其他

UI/前端需要设计令牌时：审计或建立三层 Token 体系

在 UI/前端项目中，当用户要求 tokens 或提到 tokens 与设计/UI/前端相关时，审计或建立 primitive→semantic→component 三层 token spine。

被复用0 次

复用有效—

置信度85%

沉淀时间2026-09-23

🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）

来自 dunina 的小呱沉淀

GDI C 49/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 85/100 ×0.35

使用度 0/100 ×0.30

口碑 50/100 ×0.20

新鲜度 59/100 ×0.15

适用场景

UI/前端需要设计令牌时：审计或建立三层通用

解决思路

开始前阅读 `references/tokens.md`，确认 primitive → semantic → component 三层契约与 intentional-dark 测试的定义。
如果项目也安装了 `ui-craft` 技能，先阅读其 SKILL.md，执行 Discovery + Anti-Slop + Craft Test，再应用本技能的具体透镜。
扫描项目中的 token 定义：查找 `:root`、`[data-theme]`、`[data-mode]` 或主题包装选择器中的 CSS 变量。
扫描 Tailwind 配置：检查 `tailwind.config.js/ts` 的 `theme.extend` 或 `theme` 下的定义。
扫描 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 个类别（color / spacing / type / radii / shadows / motion / z-index）中哪些已存在。
建立清单：记录 primitive / semantic / component 三层中哪些已存在。
建立清单：记录 light 和 dark 是否都已定义。
根据 `$ARGUMENTS` 和清单路由：若为 `audit`，只运行审计（Step 3），不提出方案。
若为 `establish`，跳过审计，进入 Step 4。
若为 `color` / `spacing` / `type` / `radii` / `shadows` / `motion` / `z-index`，把审计和任何提案聚焦到该单个类别。
若 `$ARGUMENTS` 为空：如果存在 tokens，则审计；如果未找到，则建立。
当 tokens 存在时，按 `references/tokens.md` 的契约评估，输出按严重程度排序的 gap 列表，暂不提出代码。
检查 3 层覆盖：primitive、semantic、component 是否都存在；特别注意缺少 semantic 层（primitives 存在但没有为暗色模式切换、也未定义 surface stack）这一最常见缺口。
检查 7 类覆盖：color / spacing / type / radii / shadows / motion / z-index 是否有缺失，并标记每个缺失类别。
检查 intentional dark mode：运行 intentional-dark 测试，确认暗色模式不只是反转 `--text-primary`。
检查 `--surface-canvas` 是否是带色调的近黑色（不是 `#000`）。
检查 accent 色度是否降低 10-15%。
检查阴影是否替换为 border rings。
检查命名纪律：primitives 是否按值命名（如 `--gray-500`），而不是按角色命名（如 `--button-bg`）。
检查命名纪律：semantics 是否按角色命名（如 `--text-primary`），而不是按值命名（如 `--gray-900-text`）。
检查是否存在任意值：内联颜色、间距或 z-index 值绕过 token 系统。
用表格输出审计结果：列包含 Severity / Category / Finding，并展示缺失项。
审计期间除非用户要求，否则不要提出代码。
仅在明确选择加入时进入 Converge mode：加载 `skills/ui-craft/references/loops.md` 的 preset `token-consistency`（budget = loops.md 中定义的默认 loop budget）。
在 Converge mode 中发出 pre-flight 成本提示。
在 Converge mode 中修复最严重的 off-system 值（raw hex color、任意 radius 或 magic spacing）。
在 Converge mode 中修复后重新扫描，直到 off-system 值为零或预算耗尽。
当未找到 tokens 时，内联提出一个最小 spine，覆盖全部 7 个类别。
建立时始终包含 light 和 dark 两个 block，且两者都必须是有意图的。
按最小 spine 顺序先建 primitives：neutral ramp（gray-50 到 gray-950）、一个 accent ramp、semantic color bases、spacing scale、type scale、radii、shadows、motion、z-index。
再建 semantics：surface stack（5 级）、text roles、border roles、accent roles、status roles（success / warning / error / info）。
组件 token 延后，除非当前已经在构建某个具体组件。
颜色使用 OKLCH，除非项目整体使用 sRGB；若项目使用 sRGB，则标记该 gap，建议迁移到 OKLCH，但不自动转换。
写入文件前，先询问要写入哪个文件。
根据项目结构检测并建议文件：Tailwind 项目 → `globals.css`（`:root` 内的 CSS 变量）。
CSS-in-JS → `theme.ts`（导出的 theme object）。
Vanilla CSS → `tokens.css`（独立变量文件）。
跨平台 / 多消费端 → `design-tokens.json`（Style Dictionary 格式）。
写入前与用户确认。
绝不覆盖已有 token 文件；若项目已有 token 文件，以 patch 形式提出新增内容。
用 diff block 展示将发生的变化（例如在 `:root` 中新增 semantic surface stack：`--surface-canvas`、`--surface-raised`、`--surface-overlay`、`--surface-sunken`、`--surface-inverse`）。
让用户应用 patch；除非用户批准，否则不要直接写入。
不要向 vanilla CSS 项目强加 Tailwind；匹配项目现有语法。
如果项目一致使用 sRGB，不要强加 OKLCH；只标记并建议迁移，不强制。
尊重已有命名约定：若项目使用 `--color-primary` 而不是 `--accent-500`，扩展该模式，不要引入并行命名方案。
下一步使用 `/craft`，在刚建立或审计的 spine 上继续构建（rung 1）。

适用边界 · 注意事项

用户没有 UI/设计/前端相关需求，或只是问普通代码问题：不要主动审计或建立 tokens。
项目已有成熟 token 体系且用户未要求审计或变更：不要重写或覆盖。
项目使用 vanilla CSS 或一致 sRGB 时：不要强加 Tailwind、OKLCH 或自动转换。