design-system

design-system

将提供的设计系统构建为命名令牌、符合目标技术栈惯例的 UI 库、可验证的预览页面，以及三项注册（文档、AGENTS.md 参考、项目 UI 技能）——确保之后的每次 UI 更改都复用该库，而不是内联一次性标记。每个 UI 项目在依次运行 /agents-md → /setup-matt-pocock-skills → 填写占位符后运行一次；触发条件满足时重新运行 extend。

不属于此技能的范围。 要让单个页面与设计像素级匹配，请使用 /pixel-audit；要处理外观 QA 收尾，请使用 /polish-batch；要从参考技术栈移植 UI，请使用 /port-feature；要追踪现有 UI，请使用 /feature-discovery。

输入

根据请求和低成本的代码库证据推断；仅在信息缺失时进行访谈：

• TARGET PROJECT-CODE — 完整的 Project Matrix 代码；它决定输出惯例。若缺少 Project Matrix → 停止并先转到 /agents-md。从矩阵 / AGENTS.md 读取目标技术栈，切勿猜测。
• DESIGN-SYSTEM SOURCE（必需） — 指定的来源优先。未指定来源时，加载 references/source-selection.md，并按其中的顺序进行发现。若来源包含令牌，则它们仍是唯一事实来源。没有来源或明确批准的引导式定义 → 停止并询问；切勿编造设计系统。

规则

• 不作任何署名：切勿在提交、PR、问题评论、发行说明、生成的文档、设置或代码注释中添加或保留共同作者、AI 或工具署名。每个生成或更新的指令文件中都要包含此规则。
• 在所有地方使用 Project Matrix 中完整的 PROJECT-CODE；切勿将一个项目的惯例、令牌或组件混入另一个项目。
• 决策是产物——每项输出都必须写入磁盘，而不是留在聊天中。
• 切勿硬编码位置——根据目标技术栈惯例和设置决策解析路径；在文档、参考文件和技能中记录实际路径。
• 子 Agent：对独立工作自动分派本地任务通道——切勿使用云端 Agent；分派时告知通道数量，并在每个通道完成时报告。通道仅负责提取和调研；综合工作由主 Agent 负责。
• 每次阶段转换时输出 Stage / Found / Next / Needs user——每个字段各占一行。
• 只建议，不自动串联。 推荐下一步并停止；不要在此处开始功能开发。

适配技术栈的输出

采用目标技术栈的惯例输出，切勿固定使用某个框架：框架 Web（Laravel/Livewire、Rails、Django 等）→ 框架组件 + 服务端渲染的预览路由（例如 /ui/preview/all）；React Native → 库 + 预览屏幕；静态 HTML/PHP → HTML/CSS 组件 + 静态预览文件；其他情况 → 选择最接近其 UI 渲染方式的方案。

模式

bootstrap（默认）

完整首次运行；如果已有设计系统文档或组件库，请切换到 extend。按以下顺序执行：

1. 提取源中的设计令牌和基础组件列表及其状态。
2. 设计令牌 — 在项目现有机制中将颜色、字体、间距、圆角、阴影定义为命名令牌，并根据项目安装的框架版本进行检查；切勿在每次使用时硬编码。源定义了浅色和深色模式 → 令牌须同时包含两者，预览须渲染两种模式。
   • 对比度： 检查每组文本/背景令牌组合是否符合 WCAG AA — 正文为 4.5:1，大号文本为 3:1；还要检查焦点指示器和控件边界。源中的组合若不达标，须列在 Deviations 和 Needs user 下；不得悄悄调整源颜色。
   • 字体： 字体令牌须指定项目能够加载的字体；无法加载的字体须列为 Deviation，不得悄悄回退到其他字体。
3. UI 组件库 — 根据令牌构建基础组件（按钮、输入框、选择框、开关、卡片、警告框、徽章等），忠实还原源内容。
4. 预览页面 — 用一个页面/路由/屏幕渲染每个组件及其各个状态（默认/悬停/焦点/禁用/激活；适用时包括空状态/加载中/错误；响应式）— 分为两个部分的验证关卡：
   • Agent 部分 — 证据优先。 构建/启动目标项目，加载预览，并检查每个提取的组件均已显示且无错误输出。渲染截图是最低证据要求；仅当输出为服务器端渲染的 Web 内容时，才能用已提供的 HTML 替代。仅客户端渲染的 Web 项目和原生项目必须提供本地浏览器或模拟器中的截图或渲染后的 DOM/树快照。引用证据：URL/文件、状态、截图路径或明确说明采用的替代方案，以及对照提取清单逐项核对后的已检查组件列表。仅提供一个总数不算证据。
   • 人工部分 — 验收关卡。 如果工作区策略要求先运行 /agentic-qa，但缺少相应证明，则标记为待人工检查并建议执行该 QA 步骤；不要自动调用。后续收到 preview 请求或进行下一次 extend 时，只要该证明已具备，就从这部分继续。所有适用的 QA 关卡通过后，展示预览位置并请用户检查。如果用户暂时不在，请说明预览位置和 Agent 部分的证据，在阶段更新中记录待检查，并继续提供建议 — 在用户检查之前，绝不能声称设计系统已通过验证。 如果存在快照测试框架，为每个基础组件添加一个最简渲染/快照测试。
5. 注册 — 编写文档、AGENTS.md 参考和项目 UI 技能（见下文）。

extend（重新运行）

触发条件：设计系统扩展了（新增 Figma 组件）；UI 更改需要一个缺失组件；反馈循环 — 已发布页面的 UI 反哺组件库。

• 缺失组件： 先检查组件库。若已存在 → 无需构建；停止并说明原因。若缺失 → 根据设计系统源构建；若没有可参照的资料 → 先向用户索要，不要自行臆造。
• 反馈循环： 检查已发布页面的差异，并将每个可复用部分纳入组件库，基于已发布的 UI 和源内容构建；只有在说明原因后，才可将页面专用的一次性组件留在库外。
• 待人工检查： 如果 bootstrap 留下了待人工检查的部分，在同步前展示预览位置并请用户检查。
• 同步： 一次性更新组件库、预览、文档、AGENTS.md 参考和项目 UI 技能。
• 边界 — 仅限设计系统。 extend 只更新设计系统，不做其他事情。它不会提交、更不会推送，不会编写 ADR，也不会生成交接文档；这些工作应交由 /grill-with-field 和 /commit-push-*，按照「建议但绝不自动串联」的原则分别调用。

注册

specs/design-system/ 文档

将完整文档写入 <docs-root>/design-system/<TARGET-PROJECT-CODE>-design-system.md，其中 <docs-root> 为设置文档所在位置；若未作出设置决策，则使用 <artifacts-root>/specs/。解析 <artifacts-root>：如果存在 *.code-workspace 目录，则使用该目录；否则使用各上下文的根目录（仓库根目录中的 GLOSSARY-MAP.md；旧版 CONTEXT-MAP.md）；再否则使用仓库根目录。填写 references/registration-templates.md §1 中的文档骨架。

AGENTS.md 参考

仅在 /agents-md 规定的位置添加一条以 PROJECT-CODE 为键的简短参考；在 extend 时原位更新，切勿重复添加。完整设计系统不得写入 AGENTS.md——其中只需指向该文档。填写 references/registration-templates.md §2。

项目 UI 技能

这是实际 UI 工作的深入参考；所有项目特定的 UI 规则都应放在该技能和文档中，绝不能放在 /design-system 中。

• 先检测是否已有 UI 技能： 检查 <project>/.agents/skills/ 和运行时目录（.claude/skills/、.cursor/skills/ 等），查找是否已有技能负责该项目的 UI 工作。
• 找到后 → 原位采用并扩展；切勿在其旁边新建并行技能——两个 UI 技能会争抢路由。将实际路径、组件清单及状态、优先复用而非新建的规范、缺少组件时的处理流程，以及使用组件库的规则纳入其中；完善其描述，确保 UI 工作仍会路由到该技能。
• 保留其长期积累的约定和风格：展示差异；若现有规则与设计系统相矛盾，应向用户指出冲突，不得擅自改写任一方。
• 在文档的 Project skill: 行和 AGENTS.md 参考中，记录所采用技能的实际名称。
• 仅当任何位置都不存在 UI 技能时：新建项目本地 <project-slug>-ui-coding（kebab-case，遵循目标命名规则）；加载 references/fresh-ui-skill.md，了解其位置、各运行时副本和内容。

输出

输出阶段更新并停止：

Stage: design-system (<bootstrap|extend>) — tokens+library+preview for <TARGET-PROJECT-CODE>; doc <docs-root>/design-system/<TARGET-PROJECT-CODE>-design-system.md; AGENTS.md reference added; <ui-skill name> seeded/extended.
Found: <N> tokens, <M> components (<states covered>); source = <DESIGN.md|project UI skill/library|Figma|spec|reference|guided(approved)>; contrast <all AA | N failing pairs>; stack = <from matrix>.
Next: <required agent QA pending: run /agentic-qa; otherwise open preview and inspect every component/state>. Then /feature-prompt for the first feature.
Needs user: <agent QA pending: start the required QA; otherwise verify the preview>; confirm guided choices, failing contrast pairs, or DS/stack deviations.

Suggested next skills (optional):
- /feature-prompt: begin the first feature — it consumes this library.
- /pixel-audit: per-page conformance during that feature work (not here).

不得继续执行建议之后的内容。

完成标准

• Token、组件库和预览均存在于文档记录的路径
• 按 Agent 部分的要求引用预览证据；如存在测试框架，渲染／快照测试通过
• <docs-root>/design-system/<TARGET-PROJECT-CODE>-design-system.md 已存在，且包含 Project skill: 行，所命名的技能在磁盘上存在
• AGENTS.md 中恰有一条针对 TARGET PROJECT-CODE 的设计系统参考
• 阶段更新记录了人工检查已完成或待处理；之后未运行任何操作
• extend 运行：git log 显示本次运行未产生新提交