用途:在代码库中审计所有硬编码设计值,建立或强化三层设计令牌体系(primitive → semantic → component),并把组件中的硬编码值替换为令牌。
主要能力:
- 环境探测:定位 src/app 源根,检测 CSS-in-JS(styled-components、emotion、stitches、vanilla-extract、linaria),发现已有令牌载体(CSS 自定义属性、Tailwind config、Style Dictionary tokens.json、shadcn 模式)。
- 令牌审计:grep 查找 TSX/CSS 中十六进制、rgb/hsl、任意 Tailwind 值、命名调色板类;离网间距、任意间距、内联 px;硬编码字号、字重、行高;阴影、圆角、魔法 z-index;并按出现频次归并重复/不一致值。
- 视觉基线:用 Playwright 截取 3–5 个主要屏幕的桌面(1280×900)与移动(375×812)前后对比图,以像素级一致作为回归依据。
- 令牌映射:产出“硬编码值 | 出现次数 | 建议令牌名 | 层级”表,命名遵循 primitive(--color-{hue}-{shade}、--space-{n}、--radius-{size})与 semantic(--color-primary、--color-surface、--color-text、--color-border)约定,按角色而非外观命名。
- 递归替换:按颜色→间距→排版→阴影→圆角→z-index 顺序逐类替换,每类最多 3 次迭代,每类后截图核对桌面与移动端视觉一致。
- 暗色模式:用同名语义令牌在 .dark 下覆写,验证无需改组件即可正确换色。
- 清理与报告:删除临时截图脚本,输出分类汇总表和令牌清单,并列出无法处理的硬编码值及原因。
必要用法:按 Phase 0–4 顺序执行;先定义令牌再替换,primitive 先于 semantic;不改逻辑、布局或组件结构,只改设计值;截图前后必须视觉一致,不一致说明令牌值有误;每类最多 3 次迭代,超限标记后前进。若项目根存在 DESIGN-BRIEF.md,先读取其 Color System 与 Typography 作为 primitive 起点;令牌架构与命名详见 SYSTEMS.md。
限制:1px 边框等无需令牌化;仅应令牌化跨主题变化或多处出现的值;认证保护的页面需复用已有 auth state 文件传入 --auth;未提供与具体框架、收费或平台相关的更多信息。