激活契约
每当用户用自然语言提出 UI 设计、原型图、屏幕、登录页或视觉方向的需求，或对 design/ 下的画板进行迭代时，默认使用此技能。不要用它来实现项目栈中的生产代码。
/gentle:design 命令是可选的快捷方式：每个操作也可以通过普通请求，经由本技能和 gentle_design 工具（list、open、stop、implement、handoff）执行。
硬性规则
- 每个画板是一个自包含的 HTML 文件：内联 CSS、JS 和 SVG；仅使用系统字体栈。绝不引用外部 URL、CDN、远程字体、图像或脚本。
- 为目标受众使用真实内容；不使用 lorem ipsum 或占位符名称。
- 可访问的标记：语义化元素和地标、WCAG AA 对比度、可见的焦点样式、尊重
prefers-reduced-motion（如果有任何动效）。 - 当
design/system.md存在时，先读取它，并且只使用其中的令牌和组件规则；在完成任何画板之前，运行“设计系统同步”中的自查。 - 最多问一个澄清性问题，并且仅在需求缺乏目标或内容时提问。
- 迭代时只编辑目标画板。绝不重写其他画板。
决策门
| 情况 | 操作 |
|---|---|
| 新需求 | 为新的 design/<slug>/ 编写 N 个明显不同的方向（默认 3 个，或用户指定的数量） |
| 对某个画板的反馈 | 仅编辑该文件；保留其清单条目，如果权衡改变则更新 tradeoff |
| “保存并尝试不同方法” | 添加一个新的画板，编号为下一个 NN；保留之前的画板；将其追加到清单中 |
| 用户想要调整值（间距、颜色、字号比例） | 在画板中添加滑块或控件，以及一个“复制为提示”按钮，将所选值复制为提示文本 |
新需求对应的 design/<slug>/ 已存在 | 选择一个新的 slug；永远不要覆盖另一个设计 |
| 消息中带有设计评论，或用户要求应用评论 | 遵循下面的“画布评论” |
/gentle:design sync，或用户要求捕获项目的设计系统 | 遵循下面的“设计系统同步” |
| 用户要求显示、停止或列出设计，或实现一个画板 | 调用 gentle_design 工具（open、stop、list 或 implement 并带上 <slug>/<artboard>）；遵循 implement 返回的交接文本，并用 action "handoff" 报告进度：开始时 status: "in_progress"，完成时 status: "implemented"，当有正在运行的应用时，将 previewUrl 设置为该应用的回环 URL |
设计之前
在每个新需求之前运行此门：调用 gentle_design 工具，action: "list"，然后：
list 报告的内容 | 操作 |
|---|---|
system.exists 为 false 且 designSources 存在 | 先运行“设计系统同步”，用一句话告诉用户你同步了项目的设计系统，然后用它进行设计 |
没有 designSources | 跳过同步并自由设计 |
system.staleSources 存在 | 列出这些源，说明 design/system.md 可能已过时，并提供在进行设计前再次同步的选项；只在用户同意后才重新同步，永远不要静默地使用过时的令牌 |
执行步骤
- 获取需求：目标、布局、内容、受众。
- 加载
gentle-ui-design：阅读其SKILL.md，以及仅与需求的受众、主要工作及成功条件相匹配的参考资料。本技能负责交付，gentle-ui-design负责 UX 质量。 - 从需求中选择一个短横线命名（kebab-case）的 slug。
- 使各方向在结构或视觉策略上有所不同，而不仅仅是颜色。为每个方向标注其做出的权衡。
- 按画板编写
design/<slug>/NN-<name>.html（01-…、02-…；短横线命名）。 - 编写
design/<slug>/design.json：
{
"title": "定价页面",
"brief": "面向学生的笔记应用的定价页面",
"feature": "odd/tasks/pricing-page.md",
"artboards": [
{ "file": "01-comparison-table.html", "title": "对比表格", "tradeoff": "密集且可快速浏览；情感吸引力较弱", "width": 1440, "height": 900 },
{ "file": "02-single-plan-hero.html", "title": "单一计划主视觉", "tradeoff": "焦点突出；隐藏了计划差异", "width": 1440, "height": 900 }
]
}
- 将
width/height设置为画板预期的视口大小（CSS 像素）；每次更改后保持清单与文件同步。字段：title、brief、可选的feature、以及包含file、title、tradeoff、width、height的artboards[]。 - ODD 链接：当设计来自一个已跟踪的 ODD 特性（当前工作中已存在的
odd/tasks/<feature>.md）时，将feature设置为该路径，并在该文档的## Log中追加一个条目，记录design/<slug>/及其画板。当该设计的某个画板被移交实现时，Log 条目还指定被选中的画板（被移交的那个；list会将其报告为Chosen），并说明其他画板是备选方案。对于小的未跟踪工作，省略feature并让设计独立存在；永远不要仅仅为了链接而创建一个特性文档。 - UX 自查，针对你完成的每个画板：对照
gentle-ui-design的构图与反馈（层级、密度、反馈）以及自适应界面（窄屏、输入访问、状态）的指导进行检查，并在报告前修复所有差距。 - 在编写或更改画板后，调用
gentle_design工具，action: "open"并带上 slug，除非用户要求不打开。当画布标签页已打开时，它会刷新该标签页而不是打开新标签页，因此每次更改后都要调用它。报告其返回的 URL。
设计系统同步
- 只读取，绝不编辑项目源代码。来源：CSS 自定义属性（
:root、@theme、[data-theme]）、Tailwind 配置或 v4@theme、组件库文件夹、现有令牌文件及其声明的字体。 - 编写
design/system.md：颜色（令牌名称、值、用途）、排版、间距、圆角、阴影和组件规则。每个条目都标明其来源path。仅记录在源中找到的值。 - 编写
design/system.html：一个自包含的画板，宽 1440 像素，渲染这些令牌（色板、字号比例、间距、圆角、阴影）以及核心组件，遵循相同的不引用外部 URL 规则。画布将其显示为每个设计的第一个板面。 - 当没有设计来源存在时，说明这一点并提出一个最小的入门系统供用户接受；永远不要将虚构的值呈现为项目令牌。
- 自查，对于你在
design/system.md存在期间完成的每个画板：列出该画板使用的颜色和字体家族，与系统令牌进行比较，并在报告前修复所有偏差。
画布评论
来自画布的评论存储在 design/<slug>/comments.json 中；会话也会将它们作为命名每条评论 ID 的消息接收。
- 使用
gentle_design_comments工具（action: "list"，可选的slug和file）读取开放的评论。如果没有该工具，读取design/<slug>/comments.json并使用其中status为"open"的条目。 - 通过仅编辑其
file指定的画板来应用每条评论；使用selector和excerpt定位元素。当评论有screenshot时，先查看它：它作为评论消息的附件到达，或者使用读取工具打开design/<slug>/<screenshot>。它显示用户所看到的内容，通常是静态画板未显示的瞬时动画或过渡状态。 - 将每条已应用的评论用工具标记为已解决（
action: "resolve"，slug，ids）。如果没有该工具，将其status设置为"resolved"，resolvedAt设置为当前 ISO 时间，保持其他所有条目和字段不变。未应用的评论保持开放，并说明原因。
文件格式（仅供只有文件访问权限的代理使用）：
{
"version": 1,
"comments": [
{ "id": "k3x9p2ab", "file": "02-bold.html", "selector": "body > header > h1", "excerpt": "Ship faster", "comment": "让标题更短。", "createdAt": "2026-10-26T10:00:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null },
{ "id": "m7q2w9cd", "file": "02-bold.html", "selector": "#cta", "excerpt": "Start", "comment": "按钮在悬停过渡期间会跳动。", "screenshot": ".screenshots/m7q2w9cd.png", "createdAt": "2026-10-26T10:05:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null }
]
}
screenshot 是可选的：相对于设计文件夹的路径，位于 .screenshots/ 下，仅当用户附加了图像时才存在。
永远不要删除或重新排序条目，并保持文件为有效的 JSON：画布拒绝覆盖它无法解析的文件。
输出契约
返回：slug、每个画板文件及其标题和权衡、本轮更改的文件、本轮解决的评论 ID 以及任何未解决的问题。给出步骤 10 中的画布 URL，或者说明当你没有打开画布时使用 /gentle:design open <slug> 显示画布。对于同步，返回读取的源路径、每个组的令牌数量以及系统是否是建议的入门系统；在从“设计之前”自动同步后，说明它已运行并以相同方式报告。
参考资料
- 项目中的
design/system.md（如果存在）—— 要遵循的设计令牌。 gentle-ui-design技能 —— 与每个画板配对的 UX 质量指导。