tokens

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Context: this sub-skill is one lens of the broader

ui-craft

skill. If the

ui-craft

skill is also installed, read its SKILL.md first for Discovery + Anti-Slop + Craft Test, then apply the specific lens below.

Read

references/tokens.md

before proceeding. The 3-layer contract (primitive → semantic → component) and the intentional-dark test are defined there.

背景： 本子技能是更广泛的

ui-craft

技能的一个视角。如果同时安装了

ui-craft

技能，请先阅读其SKILL.md中的「发现 + 反冗余 + 工艺测试」部分，然后再应用下面的具体视角。

继续操作前请先阅读

references/tokens.md

。其中定义了三层契约（基础token → 语义token → 组件token）以及有意暗色测试（intentional-dark test）。

Step 1: Detect existing tokens

步骤1：检测现有tokens

Scan for token definitions in the project:

CSS variables in
```
:root
```
,
```
[data-theme]
```
,
```
[data-mode]
```
, or theme wrapper selectors
Tailwind config (
```
tailwind.config.js/ts
```
) under
```
theme.extend
```
or
```
theme
```

CSS-in-JS theme objects (

theme.ts

*.styles.ts

styled.d.ts

ThemeProvider

)

```
design-tokens.json
```
or
```
tokens.json
```
(Style Dictionary / Theo)
```
globals.css
```
,
```
variables.css
```
,
```
tokens.css
```

Build an inventory: which of the 7 categories exist (color / spacing / type / radii / shadows / motion / z-index), which layers are present (primitive / semantic / component), and whether both light and dark are defined.

扫描项目中的token定义：

```
:root
```
、
```
[data-theme]
```
、
```
[data-mode]
```
或主题包装器选择器中的CSS变量
```
tailwind.config.js/ts
```
中
```
theme.extend
```
或
```
theme
```
下的Tailwind配置

CSS-in-JS主题对象（

theme.ts

、

*.styles.ts

、

styled.d.ts

、

ThemeProvider

）

```
design-tokens.json
```
或
```
tokens.json
```
（Style Dictionary / Theo）
```
globals.css
```
、
```
variables.css
```
、
```
tokens.css
```

整理一份清单：7个类别（颜色/间距/排版/圆角/阴影/动效/z-index）中哪些已存在，哪些层级（基础/语义/组件）已具备，以及是否同时定义了亮色和暗色模式。

Step 2: Route based on

$ARGUMENTS

and inventory

步骤2：根据

$ARGUMENTS

和清单路由处理

"audit" → run audit only (Step 3). No proposals.
"establish" → skip audit, go to Step 4.
"color" / "spacing" / "type" / "radii" / "shadows" / "motion" / "z-index" → focus the audit and any proposal on that one category.
empty → if tokens exist: audit. If nothing found: establish.

"audit" → 仅执行审计（步骤3），不提供方案。
"establish" → 跳过审计，直接进入步骤4。
"color" / "spacing" / "type" / "radii" / "shadows" / "motion" / "z-index" → 审计和方案仅聚焦于该类别。
空 → 如果已有tokens：执行审计；如果未找到任何tokens：搭建体系。

Step 3: Audit (tokens exist)

步骤3：审计（已有tokens的情况）

Evaluate against the contract in

references/tokens.md

. Output a severity-ranked gap list — don't propose code yet.

Check:

3-layer coverage — are primitive, semantic, and component layers all present? Missing semantics is the most common gap: primitives exist but nothing switches for dark mode and no surface stack is defined.
7-category coverage — any of (color / spacing / type / radii / shadows / motion / z-index) missing? Flag each absent category.
Intentional dark mode — run the intentional-dark test: does dark mode do more than invert
```
--text-primary
```
? Is
```
--surface-canvas
```
a tinted near-black (not
```
#000
```
)? Is accent chroma reduced 10-15%? Are shadows replaced with border rings?
Naming discipline — are primitives named for values (
```
--gray-500
```
) not roles (
```
--button-bg
```
)? Are semantics named for roles (
```
--text-primary
```
) not values (
```
--gray-900-text
```
)?
No arbitrary values — inline colors, spacing, or z-index values that bypass the token system.

Output format:

Severity	Category	Finding
Critical	Dark mode	`--surface-canvas` is `#000` — runs the intentional-dark test
High	Semantics	No surface stack — components use raw primitives
Medium	Shadows	Single-layer shadows — ambient layer missing
Low	Z-index	Arbitrary values ( `z-index: 999` ) in 3 components

Show what's missing. Do not propose code during audit unless the user asks.

对照

references/tokens.md

中的契约进行评估。输出按严重程度排序的差距清单——暂不提供代码方案。

检查项：

三层覆盖度 — 基础、语义、组件层是否都存在？缺失语义层是最常见的差距：有基础token，但暗色模式没有切换逻辑，也没有定义表面层级栈（surface stack）。
七类覆盖度 — （颜色/间距/排版/圆角/阴影/动效/z-index）中是否有缺失？标记每个缺失的类别。
有意暗色模式 — 执行有意暗色测试：暗色模式是否只是简单反转
```
--text-primary
```
？
```
--surface-canvas
```
是否是带色调的近黑色（而非
```
#000
```
）？强调色的饱和度是否降低了10-15%？阴影是否替换为了边框环？
命名规范 — 基础token是否以值命名（
```
--gray-500
```
）而非以角色命名（
```
--button-bg
```
）？语义token是否以角色命名（
```
--text-primary
```
）而非以值命名（
```
--gray-900-text
```
）？
无任意值 — 不存在绕过token系统的内联颜色、间距或z-index值。

输出格式：

严重程度	类别	发现
严重	暗色模式	`--surface-canvas` 为 `#000` — 未通过有意暗色测试
高	语义层	无表面层级栈 — 组件直接使用原始基础token
中	阴影	仅单层阴影 — 缺少环境光层
低	Z-index	3个组件中存在任意值（ `z-index: 999` ）

列出所有缺失项。审计阶段不提供代码方案，除非用户明确要求。

Step 3b — Converge mode (explicit opt-in)

步骤3b — 收敛模式（需明确开启）

Load

skills/ui-craft/references/loops.md

preset

token-consistency

(budget = the default loop budget defined in loops.md). Emit the pre-flight cost notice. After fixing the top off-system value (raw hex color, arbitrary radius, or magic spacing), re-scan until zero off-system values or budget exhausted.

加载

skills/ui-craft/references/loops.md

中的

token-consistency

预设（预算 = loops.md中定义的默认循环预算）。发出前置成本通知。修复完优先级最高的脱离系统值（原始十六进制颜色、任意圆角值或魔法间距值）后，重新扫描，直到脱离系统值为零或预算耗尽。

Step 4: Establish (no tokens found)

步骤4：搭建体系（未找到tokens的情况）

Propose a minimal spine inline. Cover all 7 categories. Always include both light and dark blocks — both intentional.

Minimal spine order:

Primitives — neutral ramp (gray-50 to gray-950), one accent ramp, semantic color bases, spacing scale, type scale, radii, shadows, motion, z-index.
Semantics — surface stack (5 levels), text roles, border roles, accent roles, status roles (success / warning / error / info).
Component tokens — defer unless a specific component is already being built.

Use OKLCH for color unless the project uses sRGB across the board — in that case flag the gap, propose OKLCH, but don't auto-convert.

Before writing to a file, ask which file to write to. Detect from project structure and suggest one:

Tailwind project →
```
globals.css
```
(CSS variables inside
```
:root
```
)
CSS-in-JS →
```
theme.ts
```
(exported theme object)
Vanilla CSS →
```
tokens.css
```
(standalone variables file)
Cross-platform / multi-consumer →
```
design-tokens.json
```
(Style Dictionary format)

Confirm with the user before writing.

直接提供一套最小化的体系骨架。覆盖全部7个类别。始终同时包含亮色和暗色模块——两者均遵循有意设计原则。

最小骨架的结构顺序：

基础层 — 中性色阶（gray-50 到 gray-950）、一个强调色阶、语义色基础值、间距尺度、排版尺度、圆角、阴影、动效、z-index。
语义层 — 表面层级栈（5级）、文本角色、边框角色、强调色角色、状态角色（成功/警告/错误/信息）。
组件token — 暂不提供，除非已经在构建特定组件。

颜色使用OKLCH色彩空间，除非项目全程使用sRGB——这种情况下请标记该差距，提议改用OKLCH，但不要自动转换。

写入文件前，请询问用户要写入哪个文件。 根据项目结构检测并建议一个文件：

Tailwind项目 →
```
globals.css
```
（
```
:root
```
内的CSS变量）
CSS-in-JS →
```
theme.ts
```
（导出的主题对象）
原生CSS →
```
tokens.css
```
（独立变量文件）
跨平台/多消费端 →
```
design-tokens.json
```
（Style Dictionary格式）

写入前请与用户确认。

Step 5: Never overwrite

步骤5：绝不覆盖原有内容

If the project has an existing token file, propose additions as patches — show what would change in a diff block:

diff

  :root {
+   /* ── Semantic surface stack (new) ── */
+   --surface-canvas:  var(--gray-50);
+   --surface-raised:  var(--gray-100);
+   --surface-overlay: #fff;
+   --surface-sunken:  var(--gray-200);
+   --surface-inverse: var(--gray-900);
  }

Let the user apply. Don't write directly unless they approve.

如果项目已有token文件，以补丁形式提议新增内容——用diff代码块展示变更内容：

diff

  :root {
+   /* ── Semantic surface stack (new) ── */
+   --surface-canvas:  var(--gray-50);
+   --surface-raised:  var(--gray-100);
+   --surface-overlay: #fff;
+   --surface-sunken:  var(--gray-200);
+   --surface-inverse: var(--gray-900);
  }

让用户自行应用。除非用户批准，否则不要直接写入。

Constraints

约束条件

Don't impose Tailwind on a vanilla CSS project. Match the project's existing syntax.
Don't impose OKLCH if the project uses sRGB consistently — flag it, suggest migration, don't force it.
Respect existing naming conventions — if the project uses
```
--color-primary
```
over
```
--accent-500
```
, extend that pattern rather than introducing a parallel naming scheme.

Next step:

/craft

— build on the spine you just established (rung 1).

不要在原生CSS项目中强制使用Tailwind。匹配项目现有的语法风格。
如果项目一致使用sRGB，不要强制改用OKLCH——标记该差距，建议迁移，但不要强制执行。
尊重现有的命名规范——如果项目使用
```
--color-primary
```
而非
```
--accent-500
```
，请沿用该模式，不要引入一套并行的命名体系。

下一步：

/craft

— 在你刚搭建的体系骨架上进行构建（第1阶）。

tokens

Original

Translation

Step 1: Detect existing tokens

步骤1：检测现有tokens

Step 2: Route based on
`$ARGUMENTS`
and inventory

步骤2：根据
`$ARGUMENTS`
和清单路由处理

Step 3: Audit (tokens exist)

步骤3：审计（已有tokens的情况）

Step 3b — Converge mode (explicit opt-in)

步骤3b — 收敛模式（需明确开启）

Step 4: Establish (no tokens found)

步骤4：搭建体系（未找到tokens的情况）

Step 5: Never overwrite

步骤5：绝不覆盖原有内容

Constraints

约束条件

tokens

Original

Translation

Step 1: Detect existing tokens

步骤1：检测现有tokens

Step 2: Route based on $ARGUMENTS and inventory

步骤2：根据$ARGUMENTS和清单路由处理

Step 3: Audit (tokens exist)

步骤3：审计（已有tokens的情况）

Step 3b — Converge mode (explicit opt-in)

步骤3b — 收敛模式（需明确开启）

Step 4: Establish (no tokens found)

步骤4：搭建体系（未找到tokens的情况）

Step 5: Never overwrite

步骤5：绝不覆盖原有内容

Constraints

约束条件

Step 2: Route based on
`$ARGUMENTS`
and inventory

步骤2：根据
`$ARGUMENTS`
和清单路由处理