Requires: Bricks 2.4+ with the Abilities API enabled

Update check

Run first when filesystem tools are available:

bash

_BS_UPDATE_CHECK=""
for _CAND in "$HOME/.bricks/skills/bricks-skills/scripts/bricks-skills-update-check" "$PWD/scripts/bricks-skills-update-check" "$HOME/.claude/skills/bricks-skills/scripts/bricks-skills-update-check" "$HOME/.codex/skills/bricks-skills/scripts/bricks-skills-update-check"; do
  [ -f "$_CAND" ] && _BS_UPDATE_CHECK="$_CAND" && break
done
[ -n "$_BS_UPDATE_CHECK" ] && sh "$_BS_UPDATE_CHECK" || true

If it prints

BRICKS_SKILLS_UPDATE_AVAILABLE <old> <new> <tag>

, load bricks-skills-update before continuing. If it prints

BRICKS_SKILLS_JUST_UPDATED <old> <new>

, mention the new version and continue.

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:

Does a matching resource already exist? Reuse it.
Is there a convention to follow? (kebab-case classes,
```
--space-{size}
```
variable naming, t-shirt or numeric scale: match it.)
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).

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.
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.

Color palettes

Palettes are ordered arrays of colors. Each color has an id, name, raw value (hex / rgb / rgba / hsl / hsla accepted), and optional CSS variable reference.
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. When
```
save: true
```
, existing shades of the same type, parent, and mode are replaced.
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.

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
```
.

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

create-color

with

raw: "#RRGGBB"

variable: "brand-primary"

generate-color-shades

with

paletteId

colorId

shadeType: "light"

steps: 4

save: true

Repeat for
```
dark
```
(and optional
```
transparent
```
for tints).
```
list-color-palettes
```
to verify.

Add or replace a scale

Pick the naming first (t-shirt or numeric) and stick to it across typography + spacing.
```
generate-scale-variables
```
with
```
save: false
```
: review output with user.
Re-run with
```
save: true
```
once approved.
```
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.

bricks-design-systems

NPX Install

Tags

SKILL.md Content