Bricks design systems

Requires: Bricks 2.4+ with the Abilities API enabled

Bricks: design system authoring

If a bricks/* ability is not available as a direct tool: first check whether it is outside the fast path and call it through mcp-adapter-execute-ability with ability_name: "bricks/<name>". If the dispatcher also rejects it, call bricks-list-ability-status to check whether a site admin disabled it under Bricks > AI.

Before you write anything

Call bricks/get-design-context. You are looking for three answers:

1. Does a matching resource already exist? Reuse it.
2. Is there a convention to follow? (kebab-case classes, --space-{size} variable naming, t-shirt or numeric scale: match it.)
3. Are there empty slots? (Palette exists but one color is missing, scale exists but one step is missing.) Fill the slot instead of creating a new parallel resource.

Also inspect variableCategories. If a category already has a scale config, use that category ID and prefix. Do not create fs-* variables when the typography category prefix is text-, and do not hand-author static spacing/type values when a scale category exists.

A fresh Bricks install can have no saved design-system resources: no custom theme style, classes, components, or saved variables. Bricks still exposes a built-in default color palette fallback in the builder and in list-color-palettes; do not tell users Bricks has no default palette. If get-design-context returns empty, treat the editable design system as greenfield and seed it deliberately (see bricks-seed-design-system skill).

Current write preconditions

Global design writes no longer share one coarse version precondition. Immediately before a focused write, call the matching focused read and pass its complete returned ownership data unchanged:

• Global classes: single create-global-class has no resource ownership parameter; pass expectedCategoryOwnership only when assigning a category. batch-create-global-classes requires resource expectedOwnership and category ownership when categorized. Updates/deletes require the target row's itemOwnership as expectedOwnership plus lockOwnership.
• Variables/categories: both variableOwnership and categoryOwnership; category writes replace the complete category list and must preserve opaque fields.
• Palettes/colors: resource ownership for creates and target itemOwnership for updates/deletes. Chain each successful response's new ownership into sequential palette mutations.
• Theme styles: use the target itemOwnership for update/delete. Fetch the specific style when editing settings; a summary digest still covers the complete hidden row.
• Components: update/delete still require expectedDesignSystemVersion and now also the complete current expectedComponentDigest.

Deletion acknowledgement flags (allowOrphans) are mandatory where documented and do not replace ownership. On any stale precondition, re-read and rebase; do not manufacture ownership data from get-design-context.version.

Global classes

• Names must be unique across all classes. The write aborts with bricks_conflict_duplicate_global_class_name if the name is taken. Read the existing one before retrying.
• Keep names kebab-case, lowercase, no vendor prefixes. .button, .card, .hero-text. Not btn_v2, Button, --hero-text.
• Don't create modifier classes like .button-red: create a base class and a modifier class that sets only the color. Bricks supports class combinations natively.
• Class settings follow the same shape as element settings: call bricks/render-elements on a minimal element using the class to verify CSS output before committing settings programmatically.

Global variables

• Use the scale generator (bricks/generate-scale-variables) for typography and spacing. Do not hand-author static spacing or type variables that match a configured scale prefix. The same generator handles both typography and spacing: it's one math model (fluid clamp() with slope) driven by the category config. There is no separate typography-scale tool.
• When get-design-context.variableCategories includes spacing or typography categories with scale, pass the existing categoryId to generate-scale-variables. The generated names inherit the configured prefix, such as space- or text-.
• The scale generator resolves the html base font-size from three sources in order: style manager value -> theme styles -> 10px default. If your scale outputs unexpected pixel values, that order is why.
• Variable names must be unique at save time, but the builder UI does not validate this on create: call list-global-variables first and guard against duplicates before writing. Conflict returns bricks_conflict_duplicate_global_variable_name on save.
• Variables are referenced in CSS as var(--{name}). Use the bare name (space-m, not --space-m) when creating: Bricks adds the -- prefix when emitting CSS.
• When building a fluid scale, use the Bricks scale shape. category.scale has four keys the builder cannot work without, plus the math knobs:
  • scaleScope: "typography" or "spacing", nothing else. Style Manager has one fixed tab per scope and lists a category only when scale.scaleScope matches the open tab. Omit it and the scale still shows a "scale" badge in the Variable Manager, still blocks hand-authored values for its prefix, and still gets cascade-deleted with the category — but Style Manager > Typography/Spacing will be empty and the user can never edit or regenerate it.
  • scaleNames: the ordered step names, e.g. ["2xs","xs","s","m","l","xl","2xl"]. This list is the scale's extent. regenerateVariables() (fires when the html font size or min/max screen width changes, and on import) derives each variable's step from its index in this list. Omit it and the baseline index collapses to 0, silently rewriting every variable at the wrong step.
  • baseline: must be one of the scaleNames entries. Default t-shirt baseline is m.
  • prefix: e.g. text-, space-.
  • Math knobs: scaleType (tshirt | numeric | custom), minFontSize, maxFontSize, minScaleRatio / minScaleRatioSelect, maxScaleRatio / maxScaleRatioSelect. Note: *ScaleRatioSelect wins unless it is the literal string "custom", in which case *ScaleRatio is used.
• Keep scaleRange and scaleNames in agreement. The builder generates exactly one variable per scaleNames entry. generate-scale-variables instead takes a scaleRange: { from, to }, so it is possible to generate 11 variables against a 7-entry scaleNames — after which the Style Manager preview and regenerateVariables() both map variables onto the wrong steps. scaleRange: { from: -2, to: 4 } matches a 7-name list with baseline at index 2.
• generate-scale-variables with save: false returns the generated variables for review; show these to the user and wait for approval before saving.
• generate-scale-variables does not support saving with save: true. Persist the previewed rows with set-global-variables, using one fresh list-global-variables response's variableOwnership and categoryOwnership. If the category itself must change, first send the complete preserved category list to set-global-variable-categories with both current ownership values, then re-read before saving variables.
• Global variables are stored in a global option, not post revisions. Use delete-global-variable for cleanup of individual variables; it returns a beforeDelete snapshot.
• set-global-variables is an upsert, not a full replacement. Pass both current variable/category ownership values. set-global-variable-categories is a full category replacement and also requires both current values. delete-global-variable requires the row's itemOwnership plus literal allowOrphans: true after review.

Color palettes

• Palettes are ordered arrays of colors. Each color has an id, light and optional dark value, plus a raw CSS-variable reference; individual colors do not have a separate display-name field.
• Formats usually round-trip. Light and dark shades preserve the parsed base format. Transparent shades are emitted as HSL/HSLA because the builder's transparent-shade path changes alpha directly.
• Before creating a new palette, check whether the existing primary palette has the color. Fragmented palettes are the most common design-system mess.
• Generating shades. Use bricks/generate-color-shades to produce light, dark, or transparent ramps from a base color. The ability uses Bricks' PHP color helper, ported from the builder Color Shades popup, so previews should match the builder math. Shade raw names become var(--{base-variable}-{l|d|t}-{index}) only when the base color has a raw value such as var(--brand-primary) or when baseVariable is passed. Without that variable reference, each generated shade keeps the base raw value. Preview with save: false, then pass that exact preview's saveOwnership as expectedOwnership when saving; the save replaces existing shades of the same type, parent, and mode.
• A color ramp is two-step: create the base color with a var(--name) reference, then call generate-color-shades for light and dark (typically 4-5 steps each). transparent is optional for tint overlays.
• Palette/color deletes require target item ownership. Deleting named CSS-variable colors or palettes also requires allowOrphans: true; run the reference audit but treat its bounded evidence as non-exhaustive.

Theme styles

• Theme styles do not apply without conditions. A style with an empty conditions array is ignored by the normal theme-style matcher. Always set conditions when creating: use [{ main: "any" }] for a site-wide base, or a more specific condition such as postType, ids, terms, or archiveType.
• By default, Bricks applies the highest-scoring matching theme style. More specific conditions beat broad ones: postType beats any, and exact ids beats postType.
• If the Theme styles loading method setting is enabled, Bricks loads every matching theme style in score order. In that mode, broad styles load earlier and more specific styles load later.
• The first theme style on a fresh site should almost always be conditions: [{ main: "any" }] so defaults actually render.
• Theme styles are stored in a global option, not post revisions. Use delete-theme-style for cleanup; it returns the removed style in beforeDelete.
• Updates and deletes require the target style's current itemOwnership. Fetch the exact style with get-theme-styles({ style: id }) before changing settings.
• Deleting a style that has settings or conditions additionally requires acknowledgeStyleRemoval: true after reviewing the returned bounded impact evidence. This acknowledgement belongs to delete, not update.

Components

• Labels are unique across all components. bricks_conflict_duplicate_component_name on collision.
• Components carry their own element tree. External references to global classes and CSS variables inside that tree are preserved: if a component uses .button and var(--space-m), those references follow it wherever it's instanced.
• Deleting a component with non-zero usageCount leaves orphan pointers. The builder renders missing components as a placeholder. Either replace the usages first or explicitly accept the orphans with the user.
• Prefer extract-component-from-elements over copying element trees. The extraction rewrites ids cleanly and swaps the source subtree to a component instance in one write, with a revision snapshot.

See the bricks-components skill for slots, nested components, and property binding specifics.

Workflows

Add a color ramp to an existing palette

1. list-color-palettes, then create-color with its resource ownership and the intended raw variable reference.
2. Preview generate-color-shades with save: false; re-run with save: true and the preview's saveOwnership as expectedOwnership.
3. Repeat for dark (and optional transparent for tints).
4. list-color-palettes to verify.

Add or replace a scale

1. Pick the naming first (t-shirt or numeric) and stick to it across typography + spacing.
2. generate-scale-variables with save: false: review output with user.
3. Once approved, pass the returned rows to ownership-guarded set-global-variables.
4. list-global-variables to verify.

For building a full design system from an empty site, use the bricks-seed-design-system skill. For cleanup of an existing one, use bricks-audit-design-system.