bricks-design-systems

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Requires: Bricks 2.4+ with the Abilities API enabled

要求： Bricks 2.4+ 且已启用 Abilities API

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.

当文件系统工具可用时，首先运行以下命令：

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

如果输出

BRICKS_SKILLS_UPDATE_AVAILABLE <old> <new> <tag>

，请先加载 bricks-skills-update 再继续。如果输出

BRICKS_SKILLS_JUST_UPDATED <old> <new>

，请提及新版本后继续。

Bricks: design system authoring

Bricks：设计系统创作

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.

如果无法直接使用
bricks/*
能力：首先检查它是否在快速路径之外，若不在则通过
mcp-adapter-execute-ability
调用，参数
ability_name: "bricks/<name>"
。若调度器也拒绝调用，请调用
bricks-list-ability-status
检查站点管理员是否在 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).

调用

bricks/get-design-context

。你需要获取三个答案：

是否已存在匹配的资源？若存在则复用。
是否有需要遵循的约定？（短横线分隔的类名、
```
--space-{size}
```
变量命名规则、T恤尺码式或数值式比例：请遵循对应约定。）
是否有空缺的位置？（调色板已存在但缺少某个颜色，比例已存在但缺少某个层级：请填补空缺，而非创建新的并行资源。）

同时检查

variableCategories

。如果某个分类已有

scale

配置，请使用该分类ID和前缀。当排版分类的前缀是

text-

时，不要创建

fs-*

变量；当存在比例分类时，不要手动编写静态间距/字体数值。

全新安装的 Bricks 可能没有已保存的设计系统资源：无自定义主题样式、类、组件或已保存的变量。但 Bricks 在编辑器和

list-color-palettes

中仍提供内置的默认调色板回退；不要告知用户 Bricks 没有默认调色板。若

get-design-context

返回空值，则将可编辑的设计系统视为全新项目，有意地初始化它（请参见 bricks-seed-design-system 技能）。

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.

名称必须在所有类中唯一。若名称已被占用，写入操作会因
```
bricks_conflict_duplicate_global_class_name
```
终止。重试前请先查看已存在的类。
名称请保持**kebab-case（短横线分隔小写）**格式，不要使用供应商前缀。例如
```
.button
```
、
```
.card
```
、
```
.hero-text
```
，而非
```
btn_v2
```
、
```
Button
```
、
```
--hero-text
```
。
不要创建类似
```
.button-red
```
的修饰类：请创建一个基础类和仅设置颜色的修饰类。Bricks 原生支持类组合。
类设置与元素设置的结构一致：在通过编程方式提交设置前，请调用
```
bricks/render-elements
```
对使用该类的最小元素进行渲染，以验证CSS输出。

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.

请使用比例生成器（
```
bricks/generate-scale-variables
```
）处理排版和间距。不要手动编写与已配置比例前缀匹配的静态间距或字体变量。同一个生成器可同时处理排版和间距：它是由分类配置驱动的单一数学模型（带斜率的流体
```
clamp()
```
函数）。没有单独的排版比例工具。
当
```
get-design-context.variableCategories
```
包含带有
```
scale
```
的间距或排版分类时，请将已有的
```
categoryId
```
传入
```
generate-scale-variables
```
。生成的变量名称会继承已配置的前缀，例如
```
space-
```
或
```
text-
```
。
比例生成器会按以下优先级解析HTML基础字号：样式管理器值 -> 主题样式 -> 默认
10px
。如果你的比例输出了意外的像素值，原因就在此优先级顺序。
变量名称在保存时必须唯一，但编辑器UI在创建时不会验证这一点：请先调用
```
list-global-variables
```
，在写入前避免重复。保存时若存在冲突会返回
```
bricks_conflict_duplicate_global_variable_name
```
。
在CSS中引用变量时使用
```
var(--{name})
```
。创建变量时请使用裸名称（例如
```
space-m
```
，而非
```
--space-m
```
）：Bricks 在生成CSS时会自动添加
```
--
```
前缀。
创建流体比例时，请使用 Bricks 比例结构。
```
category.scale
```
包含编辑器必须的四个关键属性，以及数学控制项：
- ```
scaleScope
```
  ：只能是
  "typography"
  或
  "spacing"
  。样式管理器每个范围对应一个固定标签页，仅当
```
scale.scaleScope
```
  与当前打开的标签页匹配时才会列出该分类。若省略该属性，比例仍会在变量管理器中显示“比例”标识，仍会阻止手动编写其前缀的数值，仍会随分类一起被级联删除，但样式管理器 > 排版/间距标签页会为空，用户无法编辑或重新生成该比例。
- ```
scaleNames
```
  ：有序的层级名称，例如
```
["2xs","xs","s","m","l","xl","2xl"]
```
  。此列表定义了比例的范围。
```
regenerateVariables()
```
  （当HTML字号、最小/最大屏幕宽度变化或导入时触发）会根据变量在该列表中的索引推导其层级。若省略该属性，基线索引会默认为
```
0
```
  ，导致所有变量的层级被错误改写。
- ```
baseline
```
  ：必须是
```
scaleNames
```
  中的一个条目。默认T恤尺码式比例的基线是
```
m
```
  。
- ```
prefix
```
  ：例如
```
text-
```
  、
```
space-
```
  。
- 数学控制项：
```
scaleType
```
  （
```
tshirt
```
  |
```
numeric
```
  |
```
custom
```
  ）、
```
minFontSize
```
  、
```
maxFontSize
```
  、
```
minScaleRatio
```
  /
```
minScaleRatioSelect
```
  、
```
maxScaleRatio
```
  /
```
maxScaleRatioSelect
```
  。注意：
```
*ScaleRatioSelect
```
  优先级更高，除非其值为字符串
```
"custom"
```
  ，此时会使用
```
*ScaleRatio
```
  。
请保持
scaleRange
和
scaleNames
一致。编辑器会为每个
```
scaleNames
```
条目生成一个变量。而
```
generate-scale-variables
```
接受
```
scaleRange: { from, to }
```
参数，因此可能会针对7个条目的
```
scaleNames
```
生成11个变量——这会导致样式管理器预览和
```
regenerateVariables()
```
都将变量映射到错误的层级。
```
scaleRange: { from: -2, to: 4 }
```
与基线索引为2的7个名称列表匹配。
调用
```
generate-scale-variables
```
时设置
```
save: false
```
会返回生成的变量供审核；请将这些变量展示给用户，获得批准后再保存。
全局变量存储在全局选项中，而非文章修订版。请使用
```
delete-global-variable
```
清理单个变量；该操作会返回
```
beforeDelete
```
快照。

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.

调色板是有序的颜色数组。每个颜色包含id、名称、原始值（支持十六进制 / rgb / rgba / hsl / hsla），以及可选的CSS变量引用。
格式通常可双向转换。浅色和深色阴影会保留解析后的基础格式。透明阴影会以HSL/HSLA格式输出，因为编辑器的透明阴影处理路径会直接修改透明度。
创建新调色板前，请检查现有主调色板是否已包含该颜色。碎片化的调色板是设计系统最常见的问题。
生成阴影。使用
```
bricks/generate-color-shades
```
从基础颜色生成浅色、深色或透明色阶。该能力使用Bricks的PHP颜色助手，改编自编辑器的颜色阴影弹窗，因此预览效果应与编辑器的计算结果一致。仅当基础颜色的
```
raw
```
值为
```
var(--brand-primary)
```
这类变量引用，或传入了
```
baseVariable
```
参数时，生成的阴影
```
raw
```
名称才会变为
```
var(--{base-variable}-{l|d|t}-{index})
```
。若没有该变量引用，每个生成的阴影会保留基础原始值。当设置
```
save: true
```
时，相同类型、父级和模式的现有阴影会被替换。
颜色阶分为两步：首先创建带有
```
var(--name)
```
引用的基础颜色，然后为
```
light
```
和
```
dark
```
（通常各4-5个层级）调用
```
generate-color-shades
```
。
```
transparent
```
是可选的，用于色调叠加。

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

主题样式没有条件则不会生效。条件数组为空的样式会被常规主题样式匹配器忽略。创建时请始终设置
```
conditions
```
：若要设置全站基础样式，使用
```
[{ main: "any" }]
```
；若要设置更具体的条件，可使用
```
postType
```
、
```
ids
```
、
```
terms
```
或
```
archiveType
```
。
默认情况下，Bricks 会应用匹配度最高的主题样式。更具体的条件优先级高于宽泛条件：
```
postType
```
优先级高于
```
any
```
，精确
```
ids
```
优先级高于
```
postType
```
。
若启用了“主题样式加载方式”设置，Bricks 会按分数顺序加载所有匹配的主题样式。在此模式下，宽泛样式先加载，更具体的样式后加载。
全新站点的第一个主题样式几乎总是
```
conditions: [{ main: "any" }]
```
，这样默认样式才能正常渲染。
主题样式存储在全局选项中，而非文章修订版。请使用
```
delete-theme-style
```
清理；该操作会在
```
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.

标签在所有组件中必须唯一。若存在冲突会返回
```
bricks_conflict_duplicate_component_name
```
。
组件带有自己的元素树。元素树中对全局类和CSS变量的外部引用会被保留：若组件使用了
```
.button
```
和
```
var(--space-m)
```
，这些引用会随组件实例化到任何位置。
删除使用次数（
usageCount
）非零的组件会留下孤立引用。编辑器会将缺失的组件渲染为占位符。请先替换所有引用，或明确获得用户同意后再接受孤立引用。
优先使用
```
extract-component-from-elements
```
而非复制元素树。提取操作会清晰地重写id，并在一次写入中将源子树替换为组件实例，同时生成修订快照。

关于插槽、嵌套组件和属性绑定的细节，请参见 bricks-components 技能。

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.

调用

create-color

，参数为

raw: "#RRGGBB"

variable: "brand-primary"

。

调用

generate-color-shades

，参数为

paletteId

、

colorId

、

shadeType: "light"

、

steps: 4

、

save: true

。

为
```
dark
```
（可选为
```
transparent
```
生成色调）重复步骤2。
调用
```
list-color-palettes
```
验证结果。

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.

先确定命名规则（T恤尺码式或数值式），并在排版和间距中统一使用。
调用
```
generate-scale-variables
```
并设置
```
save: false
```
：将输出结果展示给用户审核。
获得批准后，重新调用并设置
```
save: true
```
。
调用
```
list-global-variables
```
验证结果。

若要从空站点构建完整设计系统，请使用 bricks-seed-design-system 技能。若要清理现有设计系统，请使用 bricks-audit-design-system 技能。",