没有设计稿时，把 DESIGN.md 写成 Agent 能执行的视觉约束

前端页面交给 AI 改样式时，最容易失控的一环是目标太模糊。

「高级一点」「像某个品牌」「不要蓝紫渐变」都能表达方向，但它们不是工程约束。Agent 真正需要的是能反复读取、能映射到代码、能验证有没有跑偏的规则：哪些颜色负责背景和边框，主按钮 hover 到什么程度，卡片要不要阴影，表格密度能不能降，移动端怎么收缩，哪些装饰明确不要出现。

DESIGN.md 刚好站在这个位置。它不用替代 Figma，也不用把一个前端项目改造成完整设计系统；它更像一份给 Agent 看的视觉契约。没有设计稿时，先把视觉偏好写成结构化 Markdown，再让 Agent 按这份契约改 UI，结果会比一轮轮口头补审美稳定得多。

DESIGN.md 解决的是风格漂移

Google Labs 在 2026 年 4 月把 Stitch 的 DESIGN.md 格式开源，定位是让设计规则可以在不同项目和工具之间迁移。Google 的介绍里强调，它让 Stitch 理解设计系统背后的意图，进而生成更匹配品牌的界面；开源规格的目标则是让 AI agent 不再猜颜色和用途，而是能按规则理解、校验和应用这些选择。

Google 的公告把重点放在跨工具使用和 WCAG 校验上；google-labs-code/design.md仓库里则把格式拆成 YAML token 和 Markdown rationale 两层。token 给出精确值，正文解释为什么这么用。

这和普通 AGENTS.md 的职责不同。AGENTS.md 更适合告诉 Agent 怎么构建项目、怎么跑测试、目录怎么放；DESIGN.md 负责告诉 Agent 页面应该长成什么样、哪些视觉选择不能漂移。

社区整理的 awesome-design-md和中文版本 awesome-design-md-cn也沿用了这个分工：把一个站点的 DESIGN.md 放进项目，再让 AI agent 按它生成一致 UI。它们还把 DESIGN.md 拆成视觉主题、调色板、字体、组件、布局、高程、禁忌、响应式和 Agent prompt 等部分，正好对应 Agent 在改前端时最容易漏的几类信息。

这类社区资料很有用，但要把边界写清楚。比如 getdesign.md 的 Tesla 分析会说明它是基于公开可观察模式的独立分析，不代表 Tesla 官方背书。用于真实项目时，可以借鉴「极简、低 UI、全屏摄影、克制控件」这样的模式，不应该复制商标、专有图片或把社区分析写成官方品牌规范。

口头偏好要先变成工程约束

一个可执行的视觉约束，至少要回答这些问题：

  • 颜色怎么分工：背景、表面、主文本、次文本、边框、强调色、危险色、成功色、hover、active、disabled、focus ring。
  • 字体怎么分层：字号、行高、字重、标题和正文的关系，是否允许全大写或负字距。
  • 空间怎么组织：页面边距、栅格、控件高度、卡片内距、列表密度和移动端收缩方式。
  • 形状和深度怎么收敛：圆角、边框、阴影、模糊、glow 和大面积渐变是否允许。
  • 组件状态怎么落地：按钮、输入框、选择器、表格、卡片、弹窗、tooltip、加载态、空态和错误态。
  • 哪些东西明确不要出现：卡片套卡片、营销式大 hero、所有 hover 都染主色、默认蓝紫渐变、过重阴影、按钮 hover 位移。

这些规则越早写清楚，Agent 越容易把它们映射到主题 token 或组件变体里。否则同一个页面会出现很多一次性颜色和局部样式：按钮像一个产品，表格像另一个产品，空态又像第三个产品。

先判断风格适不适合当前产品

DESIGN.md 不能绕过产品判断。

有些品牌风格依赖全屏图片、极少文字和极少控件，适合硬件发布页、汽车产品页或媒体叙事页。把这种风格直接套到 CRM、监控后台、运营配置页或编辑器里，通常会牺牲信息密度和操作效率。

更稳的做法是先做适配判断：

判断项 要回答的问题
产品类型 当前页面是营销页、内容站、工具面板、后台系统、编辑器、移动页面，还是一次性 demo。
主要动作 用户是在浏览、比较、输入、配置、批量处理、审核、等待，还是完成高风险动作。
资源依赖 参考风格是否依赖大图、视频、品牌字体、插画、数据密度、暗色背景或特殊动效。
可迁移特征 哪些特征可以抽象成 token 和组件规则，哪些特征会伤害当前任务。

比如 Tesla 这类极简汽车风格可以给产品展示页很强的秩序感，但它依赖高质量车图、强品牌资产和低交互密度。放到内部工具里，更值得借鉴的是「少阴影、少装饰、低圆角、单一强调色」这些可迁移规则，而不是全屏摄影和近乎没有控件的页面结构。

把这套判断封装成 Skill

因为这套流程会反复出现在 AI 前端任务里，我把它封装成了一个 Codex Skill：design-md-style-guide。

这个 Skill 的入口只放触发条件、边界和交付口径；详细流程放在 reference 里。这样日常自动触发时不会一次读太多内容，真正需要应用 DESIGN.md 时又有完整检查清单。

# codex-home/skills/design-md-style-guide/SKILL.md:1-4
---
name: design-md-style-guide
description: 当用户提到 DESIGN.md、design.md、getdesign、awesome-design-md、参考某个品牌或产品视觉风格、摆脱默认蓝紫渐变，或在没有 Figma 设计稿时需要给前端页面建立可执行视觉约束时使用；不用于已经有 Figma 节点、设计稿或截图的严格视觉还原。
---

边界比触发更重要。这个 Skill 不抢 Figma 还原任务；有 Figma node、设计稿或截图时，应该先走视觉严格还原。它也不替代前端工程规则，真实改代码时仍然要回到项目已有组件、CSS 组织、主题 token 和浏览器验证。

<!-- codex-home/skills/design-md-style-guide/SKILL.md:12-18 -->
## 使用边界

- 如果用户提供 Figma node、Figma 文件、设计截图或要求严格还原视觉，优先使用 `$figma-visual-fidelity`。本 Skill 只作为补充风格约束，不覆盖具体设计稿。
- 如果任务包含真实前端实现，同时使用 `$frontend-engineering-knowledge`，按项目现有组件、token、CSS 组织和验证规则落地。
- 如果用户只想讨论方案或评估某个风格是否适合，先给方案，不直接改项目文件。
- 如果用户已经提供 `DESIGN.md`，先完整读取该文件。不要只凭品牌名或记忆推断。
- 如果用户只给品牌、产品或网站名称，需要获取当前资料时，按全局当前文档检索规则处理，优先找官方设计系统、官方品牌资料、Google DESIGN.md 规格、公开源码或明确标注为社区分析的 `DESIGN.md`。

这也是我没有把它写进全局 AGENTS.md 的原因。视觉参考是强主观输入，误触发会很烦；让 Skill 通过 DESIGN.md、getdesign、参考品牌风格、摆脱蓝紫渐变 这些词命中，范围更干净。

完整源码可以直接在下面看。这个包是文章配套快照，真实使用时把 copy/design-md-style-guide/ 复制到自己的 Codex skills 目录，再按项目需要调整 description 和 reference。

DESIGN.md 风格约束 Skill 源码正在加载代码工作区...

校验也要进入流程

DESIGN.md 已经有官方 CLI。项目里存在 DESIGN.md 且能访问 npm 时，可以先跑结构检查：

npx -p @google/design.md designmd lint DESIGN.md

PowerShell 里推荐用 designmd 这个无点号别名。design.md 作为命令名容易和 Windows 的 Markdown 文件关联冲突；Google 仓库的 README 也专门写了这个边界。

CLI 校验只能覆盖格式、token 引用、部分章节和对比度问题。UI 最终有没有做对，还要看运行态：

  • 桌面和移动端文字是否溢出。
  • 主色是否淹没所有 hover、辅助按钮和状态。
  • danger、success、warning、disabled 是否还能分清。
  • 表格、列表、筛选、主按钮是否保持原本工作流。
  • hover、focus、loading 和异步返回是否制造布局位移。
  • 有无又滑回默认蓝紫渐变、粗阴影、卡片套卡片和大面积装饰背景。

这一步很容易被省掉。Agent 能写出符合规则的 CSS，不代表页面在真实内容、真实宽度和真实浏览器里可用。尤其是 DESIGN.md 来自品牌展示页时，运行态验证要额外看信息密度和操作路径有没有被审美牺牲。

写进 Skill 之后，经验才会复用

一次任务里临时提醒 Agent「别用蓝紫渐变」，只对当前页面有用。下一次换个项目、换个上下文、换个 Agent，问题还会回来。

Skill 要保存的是一套判断顺序，品牌样式只是输入材料：

  1. 先确认视觉来源是什么。
  2. 再判断它是否适合当前产品。
  3. 再把形容词拆成 token、组件状态和禁忌项。
  4. 再映射到项目已有样式系统。
  5. 最后用运行态验证有没有跑偏。

有了这层流程，DESIGN.md 就不只是一个放在项目根目录的参考文件，而是一次前端改造的工作协议。它让 Agent 在没有设计稿时也能先建立边界，再进入实现；也让人 review UI 时有更具体的语言，不再只剩「好像不够高级」这种难以执行的反馈。

视觉约束要落到工程和验证

  • DESIGN.md 适合解决 AI 前端生成里的风格漂移问题，尤其是没有 Figma 设计稿但需要一致视觉语言的场景。
  • 官方规格、项目内设计文件、社区品牌分析和用户口头偏好要分开处理；来源不同，可信度和可用边界也不同。
  • 风格参考要先转成工程约束，再落到 token、组件状态、布局规则和禁忌清单里。
  • 品牌风格不能越过产品判断。展示页、后台系统、工具面板和编辑器需要的密度、反馈和交互层级不一样。
  • 把这套流程封装成 Skill，比每次临时提示 Agent 更稳；真正改代码时，仍然要结合项目规则和浏览器验证。