bricks

Bricks Builder JSON 創作

產生完整的 Bricks 設計為 JSON，確保首次貼上或匯入即可正常運作。

預設交付格式

除非使用者另有要求，否則在工作區中產生物理的 .json 檔案（而非行內 JSON）。使用專案既有的資料夾慣例（若存在），否則使用 bricks-json/{type}-{slug}.json。在最終回應中需標明：檔案路徑、所使用的 JSON 格式，以及執行的驗證檢查。

工作流程

0. 先釐清輸入 — 在編寫 JSON 之前 先確認兩件事：
   • rem 基準 — 確認目標網站上 1rem 等於多少 px。詢問使用者；若未指定則預設為 16px（若網站使用 html { font-size: 62.5% } 重置，則為 10px）。所有 rem/clamp() 運算以及從參考資料進行的 px→rem 轉換都依賴於此。→ rem 基準
   • 參考 URL — 若使用者提供（或指定了資產 URL），則擷取該 URL，並以其圖像/影片/SVG/圖示的絕對 URL 作為參考。→ references/external-assets.md
1. 選擇格式 — 剪貼簿貼上 vs 模板匯入 vs 程式化插入 → references/json-formats.md
2. 規劃結構 — 語意區段 → 容器 → 區塊樹；從目錄中挑選元素 → references/elements.md
3. 使用設定進行樣式設計 — 每個 _ 樣式鍵及其精確的值形狀 → references/style-settings.md
4. 綁定資料 — 根據需要加入動態標籤、查詢迴圈、篩選器（參見路由表）
5. 驗證 — 執行下列檢查清單，然後交付

格式快速參考

剪貼簿（貼入建構器） — 區段和頁面內容的預設格式：

{
  "content": [ /* 元素節點的扁平陣列 */ ],
  "source": "bricksCopiedElements",
  "sourceUrl": "https://example.com",
  "version": "2.3.6",
  "globalClasses": [ /* `_cssGlobalClasses` 所參考的完整類別物件 */ ],
  "globalElements": []
}

元素節點（content 中的每個條目）：

{
  "id": "abc123",
  "name": "heading",
  "parent": "xyz789",
  "children": [],
  "settings": {},
  "label": "Optional structure-panel label"
}

• id：唯一的 6 字元英數字元。parent：父元素的 id，根元素則為 0。
• 陣列是扁平的 — 層次結構完全存在於 parent + children 中（id 必須精確交叉參照）。
• 根元素通常是 section；切勿將 section 巢狀放入任何元素中。

任務路由

任務	參考文件
格式選擇、剪貼簿/模板/meta 儲存、程式化插入	references/json-formats.md
元素目錄、各元素設定、可巢狀元素	references/elements.md
樣式鍵、值形狀（顏色/排版/邊框/陰影/漸層/變形）、響應式 + 懸停語法	references/style-settings.md
區段/網格/彈性盒排版、卡片、疊加、固定定位、完整設計	references/layout-recipes.md
動態資料標籤 {post_title}、引數、{echo:}	references/dynamic-data.md
ACF（含重複器、群組、彈性內容）、Meta Box、JetEngine、Pods、CMB2	references/acf-providers.md
查詢迴圈（hasLoop + query）、文章/分類/使用者查詢	references/query-loops.md
分面篩選器、AJAX 分頁、載入更多、無限捲動、即時搜尋	references/query-filters.md
顯示/隱藏條件（_conditions）	references/conditions.md
互動、動畫、捲動觸發器（_interactions）	references/interactions.md
彈出視窗（模板、觸發器、限制、AJAX）	references/popups.md
模板類型、條件、匯入/匯出、頁首/頁尾/文章存檔/404	references/templates.md
元件、全域類別、全域變數、色票	references/components-classes.md
主題樣式、斷點、CSS 產生順序	references/theme-styles.md
表單元素、動作、驗證	references/forms.md
WooCommerce 模板和元素	references/woocommerce.md
PHP：自訂元素與控制項	references/custom-elements.md
PHP：篩選器和動作	references/hooks.md
來自參考 URL 的外部資產（任何圖像/影片/SVG/圖示，直接連結 vs 重新託管）	references/external-assets.md
資產載入、建構器權限	references/assets-permissions.md

可直接貼上的範例（英雄區、網格、ACF 迴圈、篩選後的文章存檔、頁首/頁尾、彈出視窗…）：patterns/ — 請參閱 patterns/INDEX.md。

不可協商的規則

1. 扁平樹狀結構完整性 — 每個 children id 都必須有一個 parent 指向它的節點。不允許孤立節點或重複 id。
2. 僅使用經過驗證的值形狀 — 顏色是物件（{"hex": "#222"} 或 {"raw": "var(--x)"}），排版鍵是 CSS 屬性名稱（"font-size"，不是 fontSize），box-shadow 偏移巢狀於 values 下，漸層使用 colors: [{color, stop}]。若不確定，請檢查 style-settings.md — 不要猜測形狀。
3. 響應式語法 — setting:breakpoint:pseudo 使用冒號：_padding:tablet_portrait、_background:hover、_margin:mobile_portrait:hover。預設斷點鍵：tablet_portrait (991)、mobile_landscape (767)、mobile_portrait (478)。桌面為無斷點的裸鍵。
4. 單位為字串 — "3rem"、"100%"、"24px"。裸數字會由 Bricks 附加 px。
5. 間距尺度紀律 — 選擇一個尺度（或網站的全域變數），並在整個設計中保持一致。
6. 真實結構，無填充 — 在區段/區塊上使用語意化 tag 設定（header、nav、article、aside、footer），每頁一個 h1，標題層級遞減。
7. 全域類別隨附 — 任何在元素 _cssGlobalClasses 中列出的 id，都必須在頂層 globalClasses 陣列中有其完整的類別物件。
8. 不要發明設定鍵 — 只使用參考文件或 Bricks 原始碼中記錄的鍵。未知鍵會被無視並浪費使用者的信任。
9. 使用 rem 前先確認 rem 基準 — 不要默默假設 1rem = 16px。詢問使用者；只有在他們未回答時才預設為 16px。使用已確認的基準來轉換從參考資料中取得的任何 px 值。
10. 使用絕對 url 參考外部資產，而非 id — 當提供了參考 URL 或資產 URL 時，將每個資產解析為絕對 URL，並透過媒體控制項的 url/external 來參考（附件 id 無法跨站點解析）。尊重授權 — 不要將受版權保護/品牌資產的熱連結用於生產環境。→ references/external-assets.md

驗證檢查清單（交付前執行）

• JSON 可解析（python3 -m json.tool file.json 或等效指令）
• 每個 parent/children 參照皆可解析；id 唯一，6 字元英數字元
• 存在 source: "bricksCopiedElements" + version（剪貼簿格式）
• 每個 _cssGlobalClasses id 在 globalClasses 中都有匹配的物件
• 值形狀符合 style-settings.md（抽查顏色、排版、間距）
• 響應式鍵使用有效的斷點名稱
• 查詢迴圈：存在 hasLoop: true + query.objectType；篩選器透過 filterQueryId 指向實際的查詢元素 id
• 動態資料標籤存在於指定的欄位提供者（例如 {acf_*} 與使用者的欄位名稱匹配）