构建系统化设计系统
brand 技能决定品牌身份；frontend-design 技能决定界面外观。而此技能决定如何结构化地组织外观，使其能够规模化扩展：三层令牌架构加上单一事实来源，涵盖所有状态的组件规范，以及防止原始值泄漏的检查机制。需要深入细节时，可加载以下参考资料：
| 主题 | 参考资料 |
|---|---|
| 层级、命名、暗黑模式、DTCG JSON、从扁平令牌迁移 | references/token-architecture.md |
| 按钮/输入/卡片/徽章/警告/对话框/表格的变体、尺寸和状态矩阵 | references/component-specs.md |
| 状态优先级、聚焦环、错误/加载模式、各状态 ARIA | references/states-and-variants.md |
架构概述
/* 原始令牌 — 原始值，无含义。很少更改。 */
--blue-600: oklch(55% 0.2 264);
/* 语义令牌 — 用途。主题分界线：浅色/深色/品牌变更仅覆盖此层。 */
--color-primary: var(--blue-600);
/* 组件令牌 — 每个组件的旋钮，引用语义令牌。 */
--button-bg: var(--color-primary);
组件应使用组件令牌或语义令牌 — 绝不要使用原始令牌或字面值。 主题（深色、高对比度、第二品牌等）只需重新指向语义令牌，其他层不变。
单一事实来源。 如果仓库使用 W3C 设计令牌社区组 (DTCG) JSON（该格式于 2025 年 10 月达到第一个稳定版本）保存令牌，那么这些文件就是事实来源：令牌包含 $value 和 $type，别名写作 {color.blue.600}，构建工具（Style Dictionary 或仓库的等效工具）会生成 CSS 变量、Tailwind 主题和原生值。编辑 JSON 并重新生成；切勿手动编辑生成的文件。如果仓库只有 CSS 自定义属性，则这些属性是事实来源。不要引入第二个事实来源。
步骤
- 了解现有情况。 使用
search_lore查找设计系统的 ADR；定位令牌文件（*.tokens.json、tokens/、theme.ts、:root块、Tailwind 配置）、生成输出的构建命令，以及两个同级组件。以现有系统的方式扩展它；绝不要添加竞争性方案。 - 先审计再添加。 统计组件样式中的字面值（命令见下文）。你处理的每个泄漏要么被现有令牌替代，要么成为新增令牌的依据。
- 将每个新令牌放入对应层级。 只有真正新的原始值才放入原始令牌；新用途放入语义令牌（
--color-surface-raised、--space-section）；仅当某个组件必须与众不同时才使用组件令牌。名称描述用途，而非外观（--color-danger，而不是--color-red）。颜色原始值使用oklch（团队惯例），字号使用clamp()流体比例，间距基于一个基础单位（4px 或 8px）。 - 在语义分界线上切换主题。 暗黑模式和其他主题在一个块中覆盖语义令牌（
[data-theme="dark"]、.dark或@media (prefers-color-scheme: dark)，根据仓库约定），并设置color-scheme，使原生控件和滚动条跟随。如果某个主题覆盖了原始令牌或组件令牌，说明分界线位置不对。 - 验证每个主题的对比度。 对于每个实际使用的前景/背景语义对（文本在表面、文本在主要色、边框在表面、聚焦环在表面），计算每个主题中的 WCAG 对比度：正文文本 4.5:1，大文本 3:1，UI 边界和焦点指示器 3:1。
oklch的明度不等同于 WCAG 对比度——请实际计算（通过脚本、仓库的检查工具或测试）。记录表格。 - 完整定义组件规范。 变体、尺寸（明确的高度、内边距、字体令牌），以及状态矩阵——默认、悬停、聚焦可见、激活、禁用、加载、错误，加上相关时的选中/复选状态——附带每个状态暴露的 ARIA。多个状态同时应用时的优先级：禁用 > 加载 > 错误 > 激活 > 聚焦 > 悬停 > 默认。焦点始终可见（
:focus-visible环使用--color-ring，绝不能只有outline: none）。详情见参考资料。 - 为新产品推荐设计系统： 从产品本身出发，而不是从工具包出发——
(a) 模式和密度（营销型、数据密集的仪表盘、事务性流程），
(b) 方向（听从
brand技能）， (c) 调色板姿态（包括成功/警告/危险/信息等语义角色；仅当用户需要时才包含暗黑模式）， (d) 无障碍和性能目标事先明确。输出简短的理由说明以及令牌和组件框架；将视觉执行交给frontend-design。 - 验证并提供证据。 如果仓库构建令牌输出，则重新生成并确认差异只包含你想要的；运行 lint、类型检查和测试；运行泄漏检查；在仓库的组件测试或截图测试中渲染每个主题中修改的组件（如果存在）。使用
record-evidence技能记录每项验收标准的证据（泄漏数前后对比、对比度表），然后停止。
泄漏检查
对修改过的组件和样式文件（不包括令牌文件本身）执行：
- 原始颜色：
grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components - 原始字号：
grep -rEn 'font-size:\s*[0-9.]+px' src/components - 组件中引用原始令牌：
grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components - 已有令牌时使用的 Tailwind 任意值：
grep -rEn '\[(#|[0-9]+px)' src/components
根据仓库情况调整路径和原始令牌名称。你的 diff 中出现的新匹配是构建者需要修复的缺陷，除非该行本身就是令牌定义；审查者将其列为 (optional)，除非某个匹配破坏了验收标准或某个主题的对比度。
完成条件
组件中没有新的字面值或原始令牌引用；每个主题只覆盖语义令牌；对比度表在每个主题中都通过；每个被修改的组件都实现了状态矩阵并带有可见焦点；生成的输出与事实来源匹配。
捕获经验
仓库的令牌架构——层级划分、命名约定、暗黑模式分界线，或“组件中绝不可引用原始令牌”规则——正是下一个代理开始工作前需要了解的事实。 这类事实即“经验”。请通过你任务简报中的 经验捕获协议 (CLAUDE.factory.md，第 11 步“记忆贡献”) 捕获它：在任务结束时调用 Memory MCP 的 suggest_lore 一次——只记录可复用的约定、陷阱、决策和边界，不记录每个任务的琐事。