design-system

设计系统

价值： 沟通——有文档记录的设计系统为每项视觉决策创建通用词汇。明确设计理念并为令牌命名后，贡献者无需猜测意图，就能一致地扩展系统。

目的

协助协作创建设计系统规范。生成位于 docs/design-system.pen（如果有 Pencil MCP）或 docs/design-system.html（单文件备用方案）的产物，其中记录设计理念、令牌，以及从原子到模板的完整组件层级。

实践

检测产物格式

检查 mcp__pencil__get_editor_state 工具是否可用。

• 可用： 使用 .pen 格式。遵循 references/pencil-workflow.md。
• 不可用： 使用 HTML 格式。遵循 references/html-artifact.md。

开始任何设计工作前，先确定格式。过程中不要切换格式。

遵循七阶段协作流程

你必须遵循 references/design-phases.md 中的完整方法。每个阶段完成后，才能开始下一阶段。

阶段概览：

1. 设计理念与约束——品牌、原则、无障碍、响应式策略和约束。之后的每项决策都要以此为依据。
2. 设计令牌——颜色、排版、间距、圆角、层级、动效、断点、不透明度。每个令牌都要注明对应的设计理念原则。
3. 原子——不可再分的元素（按钮、输入框、标签、图标）。每个元素都要记录状态，且只能引用令牌。
4. 分子——由原子组成的功能单元（表单字段、搜索栏）。记录组成方式和交互。
5. 有机体——由分子和原子组成的独立 UI 区块（页眉、表单、数据表格）。记录布局行为。
6. 模板——组织有机体的页面布局。定义结构、内容槽位和断点行为。
7. 产物组装——按照选定格式编译，并将设计理念置于首个章节。

引导，不要想当然

你是引导者，而非记录员。每个阶段都要提出深入的问题。对于与既定设计理念冲突的选择，要提出质疑。使用 references/facilitation-questions.md 中的问题库。

1. 不要假设用户的视觉偏好——要提问
2. 用户给出不完整的回答时，不要跳到后续阶段——要深入追问
3. 如果 docs/event_model/ 中存在事件模型线框图，用它们来确定所需组件，但仍要向用户确认
4. 根据设计理念提出令牌建议，并询问用户是否需要调整

确保设计理念可追溯

每项设计决策都必须能追溯到设计理念。

• 令牌要注明其服务于哪项设计理念原则（例如 P1）
• 原子要注明其引用的令牌
• 分子要记录由哪些原子组成
• 有机体要记录由哪些分子和原子组成
• 模板要记录其组织了哪些有机体

如果令牌无法关联到某项原则，则该令牌不必要，或设计理念不完整。继续之前必须解决这一问题。

应做：

• 在做出任何视觉决策前定义设计理念
• 组件中只使用令牌引用，不使用原始值
• 完成每个阶段后再开始下一阶段
• 在每个层级验证可追溯性
• 参考 references/token-categories.md，获取全面的令牌指导

不应做：

• 做出技术选型（CSS 框架、组件库）——这些属于架构决策
• 跳过设计理念阶段，或将其视为可选项
• 在组件中使用原始颜色代码、像素值或字体名称
• 同时设计多个阶段
• 存在未解决的问题时继续推进——如果有内容未定义，就要提问

强制执行说明

所有模式下均为建议性要求。阶段门由自身执行：Agent 必须完成每个阶段的产出，并获得用户确认后才能继续。 令牌可追溯性由自身执行：Agent 必须确认每个组件引用的是令牌，而非原始值。

硬性约束：

• 阶段顺序（完成每个阶段后再开始下一个阶段）：[RP]

约束

• “组件中不得使用原始值”：这意味着组件定义中任何位置都不得出现字面颜色代码、像素值、字号或间距值。如果组件文件中使用的是原始值，而非令牌引用，那么“我为它定义了令牌”并不足以满足要求。定义大量仅使用一次的令牌，表面上满足此规则，却破坏可复用性，同样属于违规。
• 理念阶段：理念是指足够具体、能够指导决策的命名原则。“现代、简洁”不算理念——它没有任何约束。每项原则都应可检验：面对一项设计决策时，该原则应能帮助你在多个选项中做出选择。如果它不能排除任何选项，就说明不够具体。

验证

完成此技能指导的工作后，请验证：

• 在创建任何组件之前，已记录带名称的理念原则
• 已为所有视觉类别定义令牌（颜色、字体排版、 间距、圆角、层级、动效、断点、不透明度）
• 每个令牌均注明对应的理念原则
• 原子仅引用令牌（不含原始值）
• 分子仅由目录中的原子组合而成
• 有机体仅由目录中的分子和原子组合而成
• 模板仅排列目录中的有机体
• 已记录所有组件状态（适用时包括默认、悬停、焦点、禁用、 错误）
• 如果存在事件模型，线框图字段已映射到组件
• 文件已保存至 docs/design-system.pen 或 docs/design-system.html
• 文件中的第一部分是理念

如果有任何一项未满足，请返回相关阶段并重新处理。

依赖项

此技能可独立使用。若要增强工作流，可与以下内容集成：

• event-modeling： 事件建模会话生成的线框图可明确设计系统必须包含哪些组件。为获得最佳效果，请先运行 event-modeling。
• architecture-decisions： 设计系统规范为 UI 实现的技术决策提供依据（CSS 框架、组件库、构建工具）。请先运行 design-system，再运行 architecture-decisions。
• atomic-design： 设计系统规范提供令牌定义、组件目录和层级结构，供 atomic-design 在代码中实现。
• tdd： 令牌值和组件规范可转化为可测试的契约——视觉回归测试可验证是否符合令牌要求。

缺少依赖项？使用以下命令安装：

npx skills add jwilger/agent-skills --skill event-modeling