用途
tokens 是 ui-craft 技能下的一个子技能（lens）。它的目标是对项目的设计令牌（design tokens）进行审计，或在项目尚无令牌时建立一套三层令牌主干。当用户要求为 UI 建立令牌，或在设计、UI、前端语境中提到 tokens 时触发。
如果 ui-craft 主技能也已安装，应先阅读其 SKILL.md 中的 Discovery、Anti-Slop 与 Craft Test 内容，再应用本子技能。
主要能力
- 检测项目中已有的令牌定义，来源包括：: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 个类别（颜色 / 间距 / 字体 / 圆角 / 阴影 / 动效 / z-index）中哪些存在，三层（原始值 primitive / 语义 semantic / 组件 component）中哪些存在，以及明暗两套主题是否都已定义。
- 按参数路由：audit 只运行审计；establish 跳过审计直接建立；color / spacing / type / radii / shadows / motion / z-index 将审计与建议聚焦到单一类别；参数为空时，若存在令牌则审计，若未找到则建立。
- 审计时依据 references/tokens.md 中的契约评估，输出按严重程度排序的缺口清单，不主动提出代码。
- 建立时提出最小主干，覆盖全部 7 个类别，并始终同时包含明暗两套主题。
使用方式
审计（令牌已存在）时检查以下方面：
- 三层覆盖：原始值、语义、组件三层是否齐全。缺少语义层是最常见的缺口——原始值存在，但没有任何东西为暗色模式切换，也没有定义表面层级栈。
- 7 类别覆盖：颜色 / 间距 / 字体 / 圆角 / 阴影 / 动效 / z-index 中是否有缺失，逐一标记。
- 有意的暗色模式：运行 intentional-dark 测试——暗色模式是否只是反转 --text-primary？--surface-canvas 是否为带色调的近黑（而非 #000）？强调色饱和度是否降低 10-15%？阴影是否替换为边框环？
- 命名规范：原始值是否按值命名（--gray-500）而非按角色命名（--button-bg）？语义是否按角色命名（--text-primary）而非按值命名（--gray-900-text）？
- 无任意值：是否存在绕过令牌系统的内联颜色、间距或 z-index 值。
审计输出格式为：严重程度 / 类别 / 发现。例如：Critical / Dark mode / --surface-canvas 为 #000，未通过 intentional-dark 测试；High / Semantics / 无表面层级栈，组件使用原始值；Medium / Shadows / 单层阴影，缺少环境层；Low / Z-index / 3 个组件中存在任意值（z-index: 999）。审计期间只展示缺失内容，除非用户要求，否则不提出代码。
收敛模式（需显式选择加入）：加载 skills/ui-craft/references/loops.md 中的 token-consistency 预设（预算为 loops.md 中定义的默认循环预算），发出预检成本提示。在修复最严重的系统外值（原始十六进制颜色、任意圆角或魔法间距）后，重新扫描，直到系统外值为零或预算耗尽。
建立（未找到令牌）时提出最小主干，覆盖全部 7 个类别，并始终包含明暗两套主题。最小主干顺序为：
- 原始值——中性色阶（gray-50 到 gray-950）、一条强调色阶、语义色基、间距刻度、字体刻度、圆角、阴影、动效、z-index。
- 语义——表面层级栈（5 级）、文本角色、边框角色、强调色角色、状态角色（成功 / 警告 / 错误 / 信息）。
- 组件令牌——除非已有具体组件正在构建，否则推迟。
颜色使用 OKLCH，除非项目整体使用 sRGB——此时标记该缺口，建议迁移到 OKLCH，但不自动转换。
写入文件前先询问写入哪个文件，并根据项目结构建议：Tailwind 项目 → globals.css（:root 内的 CSS 变量）；CSS-in-JS → theme.ts（导出的主题对象）；原生 CSS → tokens.css（独立变量文件）；跨平台 / 多消费方 → design-tokens.json（Style Dictionary 格式）。写入前需与用户确认。
从不覆盖：如果项目已有令牌文件，以补丁形式提出新增内容，用 diff 块展示将发生的变化，由用户应用。除非用户批准，否则不直接写入。
适用场景
- 需要评估现有 UI 设计令牌体系是否完整、命名是否规范、暗色模式是否经过有意设计。
- 新项目需要从零建立一套覆盖 7 个类别、包含明暗两套主题的令牌主干。
- 希望聚焦某一类别（如颜色、间距、字体、圆角、阴影、动效、z-index）进行审计或补充。
限制
- 不将 Tailwind 强加于原生 CSS 项目，需匹配项目现有语法。
- 若项目一致使用 sRGB，不强制推行 OKLCH，只标记并建议迁移。
- 尊重现有命名约定——若项目使用 --color-primary 而非 --accent-500，应扩展该模式，而非引入并行命名方案。
- 审计阶段不主动提出代码，除非用户要求。
- 不覆盖已有令牌文件，改动以补丁形式呈现，需用户批准。
- 收敛模式需显式选择加入，并受 loops.md 中默认循环预算限制。
下一步：/craft——在刚建立的主干上继续构建（第 1 级）。