design-system

设计系统

当核心问题是**“在设计或重构单个界面之前，哪些共享 UI 规则应当适用于这个产品或产品系列？”**时，请使用此技能。

这是本仓库规范的前端 UI 系统锚点。 它应当：

1. 对系统问题进行分类，
2. 选择合适的设计系统模式，
3. 尽早将相邻的前端工作转交给其他技能，
4. 定义一份精简的系统方案包，供其他人员或 Agent 执行。

选择方法前，请阅读 references/system-modes.md。 更改共享令牌、基元或命名规则前，请阅读 references/token-and-governance-checklist.md。 判断工作应归属此处、responsive-design 还是 web-accessibility 时，请阅读 references/scope-boundaries.md。 编写最终交接内容前，请阅读 references/design-system-packet-template.md。

何时使用此技能

• 为产品、产品套件或应用 + 营销页面定义或重构共享设计系统
• 制定颜色、排版、间距、圆角、层级、动效和断点尺度的令牌策略
• 选择基元命名规则、贡献边界和可复用的视觉语言规范
• 为需要保持一致感的落地页、仪表板、表单和组件库打造连贯的系统方向
• 将“我们的 UI 感觉不一致”之类的模糊请求转化为系统级方向方案包，而非一次性的页面重设计
• 评估团队是否需要先确定系统规范，再开始组件、无障碍或响应式实现
• 设计可复用的基元 / 插槽 / 变体 API，并从临时搭建的 UI 中提取组件系列
• 准备设计系统交接内容，供 Figma、代码令牌、基元和后续前端工作使用

何时不使用此技能

• 核心任务是视口适配、容器查询策略、溢出或移动端布局验证 → 使用 responsive-design
• 核心任务是键盘 / 焦点行为、WCAG 修复、标签、语义、对比度或手动无障碍验证 → 使用 web-accessibility
• 核心任务是针对页面层级、CTA 清晰度、精致度和上线准备情况，对整个页面或流程进行评审 → 使用 web-accessibility
• 任务仅涉及实现，且系统规则已经明确；直接实现，不要重新讨论系统治理

核心理念

优秀的设计系统不是随意拼凑的调色板加上一个首屏区块的样稿。 它是一个共享决策层，用于定义：

• 哪些内容保持一致，
• 哪些内容可因页面类型而异，
• 哪个相邻技能负责下一步实现，
• 以及下游团队应遵循什么交付物。

不要让此技能成为涵盖所有前端问题的万能技能。 系统治理由此处负责；专业问题应转交给相应技能。

说明

步骤 1：生成示例前，先对设计系统请求进行分类

选择一个主要模式，让回答保持明确的范围。

模式：

• 基础模式 — 令牌、尺度、命名、动效、密度和断点策略
• 跨页面类型对齐模式 — 落地页 + 仪表板 + 应用外壳的一致性、共享层级、共享品牌 / 系统语言
• 基元治理模式 — 团队需要基元命名、所有权、贡献边界，以及将产品专属 UI 提升为共享基元的规则
• 系统交接模式 — 将已确定的系统规则整理成简明交付物，供设计 / 开发执行
• 系统评审模式 — 评估不一致是否确实属于设计系统问题，或应转交给相邻技能

快速框架：

Design-system request:
- Surface: marketing site + logged-in dashboard
- Primary mode: cross-surface alignment
- System question: shared tokens and hierarchy, separate page-specific layouts
- Likely route-outs: responsive verification to responsive-design, a11y remediation to web-accessibility

第 2 步：定义共享系统边界

在更改令牌或页面方向之前，先确定系统实际负责什么。

以下工作应保留在 design-system 中：

• 令牌层级和命名规则
• 基础组件的命名和贡献政策
• 应适用于多个屏幕的视觉语言原则
• 多个界面应继承的断点或密度政策
• 许多组件所依赖的动效原则和无障碍基线

遇到以下问题时，不要在此处处理：

• 单个页面的布局故障 → responsive-design
• 单项无障碍问题或修复方案 → web-accessibility
• 范围较广的 UX/UI 评审 → web-accessibility

第 3 步：先做最少的共享决策

不要一开始就罗列几十个示例令牌。

对于每项系统请求，先确定以下共享层：

1. 基础规范 — 颜色、字体、间距、圆角、层级、动效、密度、断点
2. 基础组件政策 — 有哪些基础组件、如何命名、哪些是共享的，哪些仅属于产品
3. 界面规则 — 落地页、仪表板、表单、导航和数据密集型界面应如何区分，同时保持一致
4. 无障碍基线 — 对比度要求、焦点可见性、减少动效的处理方式、语义要求
5. 治理 — 谁可以添加或更改令牌或基础组件、哪些内容必须经过审核，以及何时应将工作转交给其他技能

如果某一层尚不明确，请明确说明，并将其记录为待决事项，不要凭空编造细节。

第 4 步：让示例从属于规则

只有在明确了共享规则后，示例才有用。

适当的示例用法：

• 展示一种令牌命名模式
• 展示落地页和仪表板界面之间的一种页面系统对比
• 展示一种基础组件升级规则
• 展示一种动效基线或无障碍基线

不恰当的示例用法：

• 在说明系统要解决什么问题之前，就罗列完整调色板、TS 令牌文件、CSS 动画表和 JSX 屏幕样稿

遵循以下顺序：

• 先写规则，
• 再给一两个示例，
• 最后提供交接材料。

第 5 步：尽早将相邻的前端工作转交出去

混合请求很常见。请明确拆分。

示例：

• 如果团队询问按钮变体、插槽结构以及受控/非受控行为，请在此处结合系统命名和令牌定义该基础组件 API
• 如果团队询问卡片在移动端如何折叠，请在此处保留共享断点政策，但将布局适配转交给 responsive-design
• 如果团队询问仅含图标的按钮是否满足键盘、焦点和标签要求，请在此处保留无障碍基线要求，但将修复工作转交给 web-accessibility
• 如果请求是“审查这个仪表板并告诉我们哪些地方感觉不对”，请将广泛评审转交给 web-accessibility

不要把所有工作都称为“design-system 工作”，以此掩盖职责不清的问题。

第 6 步：生成 design-system 交接材料

最后提供一份简洁的交付材料，供后续设计和开发工作遵循。

建议格式：

# Design System Packet

## Scope
- Products / surfaces covered:
- Primary mode:
- Shared system goal:

## Foundations
- Color / semantic token rules:
- Typography / spacing / radius / elevation:
- Motion / density / breakpoint policy:

## Primitive policy
- Shared primitives:
- Naming rules:
- What stays product-local:

## Surface guidance
- Landing / marketing:
- Dashboard / app shell:
- Forms / workflows:

## Accessibility baseline
- Contrast / focus / reduced motion / semantics:

## Route-outs
- `responsive-design`:
- `web-accessibility`:

## Open decisions
- ...

如果用户要求简短回答，保留相同的章节，但将内容精简为项目符号。

第 7 步：仅在需要时添加一个简短示例

最多使用一两个示例，并明确让它们从属于交接材料。

合适的示例形式：

• 使用语义化颜色令牌（surface/default、surface/emphasis、text/muted），而不是庞大的固定调色板
• 对比落地页主视觉区与仪表板页眉，展示层级一致而密度不同
• 基础组件升级规则，例如“共享按钮保留为基础组件；账单升级横幅仅属于产品”

步骤 8：以边界说明收尾

最后用一句话说明边界，防止职责范围逐渐重叠。

示例：

• “本方案包定义共享 UI 系统及其基础 API；各功能的产品组件仍由各产品自行维护。”
• “本方案包制定断点和密度策略；页面级布局调整应归入 responsive-design。”
• “本方案包制定无障碍基线要求；整改和验证应归入 web-accessibility。”

示例

示例 1：共享落地页 + 仪表盘系统

输入：“我们希望营销网站和 B2B 仪表盘共用一套设计系统，让设计令牌、排版和动效相互协调，同时又不让两个界面变得完全相同。”

理想的回复形式：

• 选择跨界面对齐模式
• 定义共享基础和界面特定差异
• 产出一份精简的设计系统方案包
• 在共享基础旁定义组件系列 API

示例 2：令牌和基础元素治理

输入：“团队总在随意添加颜色和间距值。我们需要共享基础元素的命名规则和审核政策。”

理想的回复形式：

• 选择基础规范或基础元素治理模式
• 定义令牌／命名规则和审核门槛
• 只保留一两个命名示例
• 避免把回复写成完整的页面样稿

示例 3：系统 + 响应式混合需求

输入：“仪表盘和移动 Web 应用是否应该共用一套断点策略？小屏幕上应如何折叠布局？”

理想的回复形式：

• 在 design-system 中保留共享的断点／密度策略
• 将实际的折叠方案和验证工作交由 responsive-design
• 在方案包中明确说明职责划分

示例 4：以无障碍为重点的后续需求

输入：“我们已经有设计令牌，但表单在焦点可见性和错误状态无障碍方面仍不符合要求。”

理想的回复形式：

• 简要说明设计系统基线
• 将实际整改和手动验证交由 web-accessibility
• 不要把完整的无障碍修复工作纳入此技能

最佳实践

1. 先确定模式，确保技能的职责范围明确。
2. 先定义共享规则，再给出示例，避免过度适配单个样稿。
3. 明确治理规则：令牌变更、基础元素晋升和所有权规则都是系统的一部分。
4. 尽早转交其他职责，避免 design-system 涉足布局、无障碍或广泛审计工作。
5. 产出精简的方案包，让其他人员或 Agent 可以据此开展工作。

参考资料

• 系统模式
• 令牌和治理检查清单
• 范围边界
• 设计系统方案包模板
• 响应式布局相关技能
• 无障碍相关技能