Bricks Builder JSON Authoring

Generate complete Bricks designs as JSON that pastes or imports cleanly on the first try.

Default Deliverable

Produce an actual .json file in the workspace (not inline JSON) unless the user asks otherwise. Use the project's folder convention if one exists; otherwise bricks-json/{type}-{slug}.json. In the final response state: the file path, which JSON format you used, and the validation checks performed.

Workflow

1. Pick the format — clipboard paste vs template import vs programmatic insert → references/json-formats.md
2. Plan structure — semantic section → container → blocks tree; pick elements from the catalog → references/elements.md
3. Style with settings — every _ style key and its exact value shape → references/style-settings.md
4. Wire data — dynamic tags, query loops, filters as needed (see routing table)
5. Validate — checklist below, then deliver

Format Quick Reference

Clipboard (paste into builder) — the default for sections and page content:

{
  "content": [ /* flat array of element nodes */ ],
  "source": "bricksCopiedElements",
  "sourceUrl": "https://example.com",
  "version": "2.3.6",
  "globalClasses": [ /* full class objects referenced by _cssGlobalClasses */ ],
  "globalElements": []
}

Element node (every entry in content):

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

• id: unique 6-char alphanumeric. parent: parent's id, or 0 for root elements.
• The array is flat — hierarchy lives entirely in parent + children (ids must cross-reference exactly).
• Root elements are usually section; never nest a section inside anything.

Task Routing

Ready-to-paste examples (hero, grids, ACF loops, filtered archive, header/footer, popup…): patterns/ — see patterns/INDEX.md.

Non-Negotiable Rules

1. Flat tree integrity — every children id exists as a node whose parent points back. No orphans, no duplicates.
2. Verified value shapes only — colors are objects ({"hex": "#222"} or {"raw": "var(--x)"}), typography keys are CSS property names ("font-size", not fontSize), box-shadow offsets nest under values, gradients use colors: [{color, stop}]. When unsure, check style-settings.md — do not guess shapes.
3. Responsive grammar — setting:breakpoint:pseudo with colons: _padding:tablet_portrait, _background:hover, _margin:mobile_portrait:hover. Default breakpoint keys: tablet_portrait (991), mobile_landscape (767), mobile_portrait (478). Desktop is the bare key.
4. Units are strings — "3rem", "100%", "24px". Bare numbers get px appended by Bricks.
5. Spacing scale discipline — pick a scale (or the site's global variables) and stick to it across the design.
6. Real structure, no filler — semantic tag settings on sections/blocks (header, nav, article, aside, footer), one h1 per page, descending heading levels.
7. Global classes ride along — any id listed in an element's _cssGlobalClasses must have its full class object in the top-level globalClasses array.
8. Don't invent settings keys — only keys documented in the references or found in the Bricks source. Unknown keys are silently ignored and waste the user's trust.

Validation Checklist (run before delivering)

• JSON parses (python3 -m json.tool file.json or equivalent)
• Every parent/children reference resolves; ids unique, 6-char alphanumeric
• source: "bricksCopiedElements" + version present (clipboard format)
• Every _cssGlobalClasses id has a matching object in globalClasses
• Value shapes match style-settings.md (spot-check colors, typography, spacing)
• Responsive keys use valid breakpoint names
• Query loops: hasLoop: true + query.objectType present; filters point at a real query element id via filterQueryId
• Dynamic data tags exist for the stated field provider (e.g. {acf_*} matches the user's field names)