taste-design-system

taste-design-system

设计系统是一份决策清单。此技能将告诉 Agent 如何整理这份清单、构建其结构并确保其准确无误。

1. 令牌架构（三层，绝不能只有两层）

1. 原始令牌 — 原始值：--color-ink-900、--space-4、--radius-md。除了值本身，不包含其他含义。
2. 语义令牌 — 表示含义，而非值：--color-surface、--color-text-muted、--color-border、--space-inset-lg。产品只能使用语义令牌。
3. 组件令牌 — 每个组件的别名：--button-bg-primary、--button-radius、--input-border-width。组件绝不能直接引用原始令牌。

规则：组件 → 语义 → 原始 → 值。跳过任何一层，系统就会分叉。

2. 令牌格式（DTCG，而非自由格式）

将令牌写成扁平键值映射（或者在技术栈支持时使用 W3C DTCG JSON）：

--color-ink-900: #101014;
--color-ink-700: #3B3B40;
--color-accent: #E8540B;
--space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px;
--radius-sm: 2px; --radius-md: 6px; --radius-lg: 12px;
--font-display: 'Archivo', sans-serif; --font-body: 'Inter', sans-serif; --font-mono: 'JetBrains Mono', monospace;

命名规范：使用 kebab-case，以名词开头，尺度后置（--space-4、--color-ink-900、--radius-md）。名称中绝不能编码意图（例如“fancy-purple”），也绝不能在组件中直接使用十六进制颜色。

3. 盘点（构建前先审计）

开始构建前，先进行盘点：

1. 颜色 — 列出代码库中的所有十六进制颜色。标记任何不在令牌集中的值（独特的体系外颜色超过 15 种 = 系统已损坏）。
2. 间距 — 标记任何不符合 4px（或 8px）尺度的 margin/padding。
3. 字号 — 统计正在使用的不同字号和字重。单个页面上的字号超过 5 种 = 缺少层级。
4. 圆角 / 层级 / 边框 — 收集所有值，并归为 2–4 个令牌。
5. 组件 — 列出所有组件；标记那些有超过 3 种变体却做相同工作的组件，以及任何基于原始值设置自身样式的组件。

输出：令牌映射、附带计数的违规清单，以及修复顺序（先处理原始令牌，再进行语义映射，最后清理组件）。绝不能在审计的同一轮中重构系统——先审计、报告，再更改。

4. 尺度（固定参考）

• 间距： 4/8/12/16/24/32/48/64/96。小于 4px 的间距仅用于细线边框。绝不使用 5、7、10、14px——除非有记录在案的刻意视觉微调。
• 字号尺度（流式）： 响应式场景下，使用 clamp() 渲染 12/14/16/18/24/32/48/64。
• 颜色阶梯： OKLCH 中从 50→950 分为 9–11 阶（感知上均匀），包括中性色和至少一组强调色。深色模式 = 更改语义映射，而不是新增颜色。
• 层级： 最多 3 级：平面（无阴影）、抬升（细微阴影，模糊 ≥ 16px，不透明度 ≤ 0.15）、浮起（模糊 ≥ 40px，不透明度 ≤ 0.2）。其他情况都是错误。

5. 组件结构（每个组件都必须包含）

1. 一个组件只做一件事，并且名称唯一。如果组件描述中包含“以及”，就应拆分。
2. 完整状态矩阵：默认、悬停、激活/按下、焦点可见、禁用、加载、错误。如果某个状态不可能出现，应记录原因。
3. 仅在确有需要时提供尺寸变体（sm/md/lg），绝不能用颜色变体伪装状态。
4. 响应式行为及其发生变化的断点。
5. 代码中的令牌引用——组件样式中不允许出现原始值。

6. 文档与治理

• 每个组件单独一页：用途、结构图（作为代码注释）、状态矩阵、使用规则、正确/错误示例、无障碍说明。
• 变更流程：令牌变更采用增量方式（新增令牌 → 弃用旧令牌 → 一个发布周期后移除）。绝不能悄然更改令牌值。
• 归属：由一个人（或一项技能）负责令牌文件。组件决策须经其审核。
• 采用情况指标（每季度衡量）： 使用语义令牌的屏幕占比、原始颜色违规数量、超出尺度的间距值数量、有文档记录状态的组件占比。最重要的指标：违规数量持续下降。

7. 检查清单（出现以下情况时系统不合格……）

• 任意组件直接引用原始值。
• 任意 UI 使用了色值集合中不存在的十六进制颜色。
• 任意间距值不符合比例尺，且没有记录覆盖规则。
• 任意组件缺少禁用状态或焦点可见状态。
• 使用了超过 3 个层级的阴影。
• 令牌名称同时编码含义和数值（例如语义名称应为「深色」，而不是「深紫色」）。
• 存在两个用途相同但 API 不同的组件。

令牌是设计系统的记忆。如果系统无法记住，就会不断重复——你的页面也一样。