第一个页面还不错，但从下一个页面起看起来像另一个产品
用 AI 编程代理制作第一个页面时，效果往往相当像样。问题出在增加设置、支付、搜索结果等页面时。同一个主按钮的颜色和圆角变了，加载和错误状态缺失了；到了新会话，甚至此前确定的间距也得重新说明。
这时，仅仅把“像 Toss 一样简洁”之类的风格指令写得更长还不够。你需要留下代理为何选择每个值的依据，并让它在下一个页面继续复用这些决定。
oh-my-design 有意思的地方正是在这里。它的核心不是安装大量技能，而是将设计理念连接到决策 ID、令牌、组件状态以及渲染审查。再把结果记录到 DESIGN.md 中，作为下一项工作的起点。
现在就试试：为一个页面建立共同标准
不必从一开始就重做整个产品。选择一个必须保留现有行为的页面，把安装、契约提议、批准和页面验证完整串联一次。以下流程根据公开文档整理，并非编辑部直接运行 CLI 后确认的结果。
- 从项目根目录开始安装。
准备 Node.js 18 或更高版本、Git 仓库，以及 Claude Code、Codex、OpenCode、Cursor 中任一已安装并完成认证的代理。运行npx oh-my-design-cli@latest，选择基础项目的安装范围。核心本地工作流不需要单独的 API 密钥或 MCP 服务器。 - 完全重启代理并检查安装状态。
在 Codex 中，必须信任项目，项目本地角色才能加载。重启后，在同一根目录运行npx oh-my-design-cli@latest doctor，检查与技能、代理、目录或 DESIGN.md 相关的内容是否有缺失。 - 输入包含用户与保护条件的首次请求。
例如，可以请求：“请为一款让忙碌父母记录家庭饮食的应用，提议一份项目所有者 DESIGN.md。Toss 仅作为参考资料，并且只保留已验证的事实。对于产品特有事实，请先提问再做决定；保留现有行为和 Logo；在批准前不要采纳 DESIGN.md。” - 由所有者直接批准提议文件。
要采纳与图关联的 DESIGN.md，项目所有者或预先登记的外部权限控制者必须审查并批准所提议的准确字节。生成或实现它的代理不能自行批准。 - 改进一个边界清晰的页面。
先让代理读取已采纳的 DESIGN.md，再提出类似“保留现有搜索行为和 Logo，改进搜索结果页面的层级和状态”的请求。成功标准不是让页面变得更花哨。应确认既有行为得到保留、产生可见的变更与验证摘要，并且新的令牌和状态都关联到 DESIGN.md 中的决策。
请区分批准流程的适用范围。
若只是把独立的 DESIGN.md 当作参考文档阅读，并不需要完整的采纳包。不过，如果声称由 manifest 和哈希绑定的图是当前项目的权威标准，就必须遵守所有者批准与采纳边界。Core v2 本身目前也标注为草案互操作契约。
93 不是 UI 模板数量，而是需要检查的契约数量
oh-my-design 的 93 份预设契约并不是一个用来复制 93 个成品页面的库。它由四层组成：基础元素、shadcn 与 Radix 系列的映射原语、商业与市场平台等页面类型，以及从参考资料衍生出的倾向。每份组件契约都定义了结构、状态矩阵、无障碍条件和令牌槽位。
因此，也没有理由在项目中应用全部 93 份。若是搜索页面，只需选择实际使用的元素契约，例如输入框、按钮、结果列表、空状态和错误状态。契约的价值不在数量，而在于连同要应用和不应用的状态及其理由一起记录下来。
| 工作场景 | 只有风格指令时 | 连接契约时 |
|---|---|---|
| 添加强调色 | 每个页面选择看起来合理的颜色 | 使用引用决策 ID 的令牌 |
| 实现输入框 | 容易只制作默认状态 | 检查包括聚焦、错误、禁用在内的状态矩阵 |
| 制作第二个页面 | 重新说明上一段对话中的风格 | 先读取 DESIGN.md 和现有契约 |
| 修改设计 | 通过“更精致一些”之类的感受判断 | 用决策表与相同路径的渲染结果进行比较 |
官方结构从理念出发，依次连接决策表、令牌、组件契约、布局语法、实现、渲染批评和 DESIGN.md。如果令牌或组件值不引用生成它的决策表，或者声明的原则不影响任何令牌，就可以在质量门禁中归类为失败。
即使技能数量不同也不会改变的核心
此前所知的 22 个技能和 19 个角色已不是当前规模。最新官方 Skills 页面介绍27 个产品技能和 20 个专业代理，而仓库 README 将包括渠道专用项目在内的完整套件统计为28 个技能和 20 个角色。
这种差异是因为文档统计的范围不同。Cursor 的安装数量也难以断定为一个单一数字，因为 README 内的表述并不一致。因此，在采用时，与其关注“有多少技能”，不如通过 doctor 结果确认哪些文件实际安装到了自己的代理和项目中，这样更准确。
技能负责系统生成、页面工作、审查等工作顺序；专业代理则从无障碍、内容等狭窄视角补充依据。预设契约是实现结果必须遵守的条件，DESIGN.md 则将这些条件和决策理由传递给下一次会话。即使数字变化，这种角色划分仍是产品的核心。
契约应是可观察的条件，而不是偏好
“考虑无障碍”这句话用意很好，但很难判断是否通过。相比之下，普通文本 4.5:1 的对比度、将文本放大至 200% 后内容和功能是否仍然保留、键盘焦点是否可见且没有被其他内容完全遮挡，都是可以检查的。WCAG 2.2 对这类条件作出了具体定义。
当然，在契约中写下条件，并不会自动证明实际实现符合 WCAG。Logo、大号文字、非活动内容等例外的对比度标准可能不同。因此，契约既应是固定项目选择的文档，也应是让人审查渲染结果的检查清单。
请在第二个页面判断效果。
不要只看第一个页面的美感，而要比较下一个页面是否仍保留同一按钮令牌，加载、空和错误状态是否完整，以及是否任意添加了 DESIGN.md 中没有的值。只有这三项的漂移减少，创建契约的成本才有意义。
7→3 和 47% 是可能性，而不是保证
官方变更记录中有一项自身测量：在相同夹具和简报下，首次渲染缺陷从 7 个减少到 3 个，输入令牌减少了 47%。记录还显示，最高严重程度的 P0、P1 缺陷在两种条件下均为 0。
不过，样本量、运行重复次数、所用模型、统计不确定性和外部独立评估均未公开。很难将其作为所有项目的质量或成本都会提升同样幅度的依据。在自己的项目中，比起关注首次渲染的缺陷数，更实用的是确认状态缺失、新出现的任意值以及现有行为回归，是否在下一个页面中减少。
如果想进一步深入
GitHub - kwakseongjae/oh-my-design — 可查看整体结构、93 份预设契约分类及不同安装渠道差异的官方仓库。 github.com
Getting started — oh-my-design CLI — 可查看从项目安装、代理重启到 doctor 检查的首次运行顺序。 oh-my-design.kr
DESIGN.md Core v2 — Portable Design Contract Specification — 对七个固定区域、未确定值的处理以及所有者批准边界进行规范说明的规范。 github.com
Web Content Accessibility Guidelines (WCAG) 2.2 — 关于对比度、文本放大和键盘焦点等可写入契约的无障碍标准原文。 w3.org
