对 AI 说“做得像 Toss 一样简洁”，第一屏或许看起来像模像样，但从第二屏开始，按钮、间距和状态就很容易失去一致性。oh-my-design-cli 有意思的地方，不在于承诺生成更好的设计，而在于它通过契约和验证阶段，压缩代理随意决策的空间。
22 项技能的核心是“设计决策的可追溯性”
根据当前公开仓库，oh-my-design-cli 包含 22 项产品技能、19 个专业角色、93 份预设契约，以及 440 多个质量等级参考资料。Claude Code、Codex 和 OpenCode 会安装完整的角色包，而 Cursor 会安装兼容的 21 项技能，因此不同渠道的配置略有不同。
仅看数字，它看起来像一个庞大的提示词集合，但结构并非如此。核心流程是理念 → 决策表 → 令牌 → 组件契约 → 布局语法 → 实现 → 渲染审查。例如，“强调色仅用于主要操作和焦点环”这一原则会附上决策 ID，实际的颜色令牌再引用该 ID。出现没有依据的颜色值时，系统不会将其视为单纯的审美差异，而会视为验证失败。
这里的 93 并不是可直接复制的完整 UI 组件数量，而是创建组件和页面时应遵守的预设契约数量。它们分为基础元素、shadcn/Radix 系列原语、商业和市场等页面类型，以及从参考资料衍生出的倾向。即使结构来自现有组件库，颜色、间距和状态等值也必须从项目决策表中填入。
实践中重要的区分
技能负责“做什么工作、按什么顺序做”，专业角色则从研究、无障碍和文案等聚焦视角提供依据。预设契约是实现结果必须满足的条件，而 DESIGN.md 更接近一份交接文档，将这些条件为何形成的原因保留到下一次会话。
为什么契约比提示词更有力
提示词引导一次结果，契约则让相同的决策能在下一页面复用。官方工作流也将创建新设计系统、发布新页面、改进现有页面以及记录用户偏好修正区分为不同任务。它建议同时传达目标和保护条件，而不是只说“把仪表盘做得更漂亮”，例如：“保留现有行为，检查层级、密度、动效和无障碍，然后修复影响最大的的问题。”
| 类别 | 以风格提示词为中心 | 以契约为中心的工作流 |
|---|---|---|
| 颜色和间距 | 模型为每个页面选择看似合理的值 | 复用与决策 ID 关联的令牌 |
| 组件状态 | 容易只创建默认状态，遗漏错误和加载状态 | 记录状态矩阵，以及不适用状态的原因 |
| 修改标准 | “再精致一点”之类的主观反馈 | 依据原则、契约和同一路径的渲染证据判断 |
| 下一次会话 | 对话变化后需要重新说明 | 重新阅读仓库中的 DESIGN.md 和系统文件 |
| 未知的值 | 用平均的默认值填补空白 | 省略未确定的值，只询问重要决策 |
DESIGN.md Core v2 将这些内容整理为七个领域：体验、基础、排版与资产、组件与状态、布局与平台、内容与区域设置、治理。它尤其规定，未经确认的值不应以貌似合理的默认值填充，而应保留为空。这相当于把设计文档从“情绪板说明书”变成人与代理共同阅读的可执行契约。
将令牌结构化为可在工具之间交换的形式，并非 oh-my-design 独有的想法。Design Tokens Community Group 的格式规范同样旨在将设计令牌表示为可由多个工具交换的标准文件格式，以降低集成成本。oh-my-design 可以被视为在此基础上增加了值的来源和决策理由、组件状态以及验证流程。
即使有 93 份契约，质量也不会自动得到保证
比契约数量更重要的是，是否选择了适合项目的契约，并在实际页面中进行了检查。官方的反套路文档也不会仅凭圆角卡片或一个紫色强调点就判定有问题。它说明，应先阅读用户、任务、现有行为和 DESIGN.md，再确认脱离语境的模式是否反复出现，并损害了层级或信任感。
无障碍也是同样的原理。“考虑无障碍”这一句话无法检查，但普通文本 4.5:1 的对比度、键盘焦点的可见性等可观察条件可以测试。WCAG 2.2 不仅包含文本对比度要求，也包含焦点不得被遮挡的标准。 因此，契约不应是将审美绝对化的规则，而应是区分可测量质量与项目特有选择的工具。
请将基准数字视为假设。
项目变更记录中有一项内部测量显示，在相同的夹具和简报下，首次渲染缺陷从 7 个降至 3 个，输入令牌减少了 47%。 不过，尚未公开外部独立评估或多样化项目样本。是否采用应少看这些数字，多看你们自己的页面中状态遗漏、无障碍错误和设计漂移是否确实减少。
韩国国内的实际使用介绍中反复出现的问题，并不是“第一屏的美感”，而是随着页面增多，按钮形态和颜色值发生变化所导致的一致性崩溃。将 DESIGN.md 作为项目的共同标准很适合解决这一问题，但不应将“100% 一致性”之类的表述当作已验证的保证。
在自己的项目中小规模验证的 4 个步骤
- 在真实项目根目录安装并检查状态。
运行npx oh-my-design-cli@latest后重启代理，再通过npx oh-my-design-cli@latest doctor检查技能、角色、目录和 DESIGN.md 的状态。官方文档将 Node.js 18 或更高版本列为最低要求。 - 先写产品任务，再写品牌名称。
不要止步于“Toss 风格”，而应明确用户、主要操作和需要保护的行为，例如：“一款供忙碌父母快速记录家庭饮食的应用；完成记录是主要操作；保留现有 Logo 和数据流。”要求代理在使用未经确认的产品事实前先提问。 - 用一个页面和四种状态进行测试。
与其推倒重做整个首页，不如选择搜索结果或支付完成这类边界明确的页面。创建默认、加载、空状态和错误状态，并检查是否复用现有组件，以及键盘导航、对比度和移动端重排。 - 比较漂移，而不是只看结果。
添加第二个页面后，检查是否仍使用相同的令牌和按钮状态。记录是否出现 DESIGN.md 中没有的新值、修改原因是否可通过决策 ID 追溯，以及重新渲染同一路径时是否没有回归。如果这三项没有减少，即使技能很多，采用效果也很低。
如果想进一步深入
GitHub - kwakseongjae/oh-my-design — 可查看 22 项技能、19 个角色、93 份预设契约及完整衍生结构的官方仓库。 github.com
Skills — oh-my-design CLI — 可了解技能如何划分为系统管理、页面制作、质量验证、写作和参考资料收集。 oh-my-design.kr
Workflows — oh-my-design CLI — 包含可直接用于构建新系统、制作新页面和改进现有页面的自然语言请求示例。 oh-my-design.kr
DESIGN.md Core v2 — Portable Design Contract Specification — 包含 DESIGN.md 的七个领域、权限关系、未确定值处理和符合性阶段的官方规范。 github.com
Design Tokens Format Module 2025.10 — 可查看用于在工具之间交换设计令牌的 DTCG 格式的目标和数据结构。 designtokens.org
Web Content Accessibility Guidelines (WCAG) 2.2 — 对比度、键盘焦点、重排等可写入设计契约的无障碍标准原文。 w3.org
