10分钟看懂DESIGN.md让AI拥有设计系统持久记忆的格式规范【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md是一个面向 AI 编码代理的设计系统格式规范Format Specification。它用一个纯文本 Markdown 文件把你的设计系统的颜色、字体、间距、组件样式等视觉身份完整记录下来让 AI 在不同会话、不同工具之间始终理解同一套设计语言——相当于给 AI 装上了设计系统的持久记忆。本文用最通俗的方式带你 10 分钟看懂这套规范、上手官方 CLI并学会写出第一份合格的 DESIGN.md。为什么 AI 生成的界面总是风格漂移用 AI 写前端代码时你是否遇到过这种情况今天生成的按钮是圆角蓝色明天就变成了方形紫色今天用的是 Inter 字体下次会话又换成了 Roboto口头叮嘱要高端、简洁、可信结果每次生成的都是千篇一律的模板脸。根本原因在于AI 的每次对话都是失忆的它记不住你的设计决策。DESIGN.md 项目由 Google 开源解决的就是这个问题——它把设计系统固化成一个随代码库一起版本管理的文本文件AI 每次干活前先读它风格自然稳定。项目主文档README.md 一个比喻如果把 AI 当成新员工口头说明只是临时交代而 DESIGN.md 就是公司发下来的《品牌视觉手册》。DESIGN.md 的核心结构一个文件两层内容一个 DESIGN.md 文件 机器可读的设计令牌Design Tokens 人类可读的设计说明。两层各司其职层位置格式作用设计令牌文件顶部 YAML front matter---包围的 YAML给 AI 精确的数值色值、字号、圆角、间距设计说明正文 Markdown##二级标题分节告诉 AI 这些值为什么存在、怎么用完整规范定义在 docs/spec.md哲学理念为什么正文比令牌更重要写在 PHILOSOPHY.md。第一层YAML 令牌——精确数值文件开头用---围栏包裹一段 YAML里面是结构化的设计令牌官方示例 examples/atmospheric-glass/DESIGN.md 节选如下--- name: Atmospheric Glass colors: primary: #ffffff secondary: #adc9eb typography: body-md: fontFamily: Inter fontSize: 16px fontWeight: 400 ---规范的令牌分组有 5 类colors任意 CSS 颜色写法#RRGGBB、rgb()、oklch()都可以typography字体族、字号、字重、行高、字距rounded圆角尺度sm/md/lg/full 等spacing间距尺度components组件级样式支持用{colors.primary}这种令牌引用语法跨组复用值。第二层Markdown 正文——设计意图正文按 8 个标准章节组织可以缺省但不能乱序Overview品牌与风格→ 2. Colors → 3. Typography → 4. Layout → 5. Elevation Depth → 6. Shapes → 7. Components → 8. Dos and Donts关键洞察是AI 生成质量不取决于数值多精确而取决于意图描述多清晰。写1970 年代研究生讲义的克制风格比写现代、简洁、高级有效得多——前者自带一整套隐性约束不发光、不用渐变、不花哨后者只会让 AI 在语义中心生成一张平均脸。PHILOSOPHY.md 中有大量精彩案例强烈建议通读一遍。3分钟上手用官方CLI校验、对比、导出项目自带命令行工具支持lint校验、diff版本对比、export格式导出三大命令。无需安装直接用 npx 运行一键校验lint 检查你的设计令牌npx google/design.md lint DESIGN.md它会跑 11 条内置规则输出结构化 JSON例如发现主按钮文字色与背景色对比度低于 WCAG AA4.5:1这类问题。规则清单broken-ref 断链引用、contrast-ratio 对比度、missing-sections 缺失章节等完整列在 README.md 的 Linting Rules 一节。版本对比diff 检测设计回退改版设计系统时对比新旧两个文件一眼看出哪些令牌被增删改、有没有引入新的错误npx google/design.md diff DESIGN.md DESIGN-v2.md一键导出生成 Tailwind 主题与 W3C 设计令牌令牌灵感来自 W3C Design Tokens 标准DTCGexport命令可一键互转npx google/design.md export --format json-tailwind DESIGN.md # Tailwind v3 主题配置 npx google/design.md export --format css-tailwind DESIGN.md # Tailwind v4 theme 块 npx google/design.md export --format dtcg DESIGN.md # W3C tokens.json仓库里每个官方示例都附带了导出产物可以直接对照学习examples/atmospheric-glass/tailwind.config.js、examples/paws-and-paths/design_tokens.json、examples/totality-festival/design_tokens.json。格式规范核心要点速览写 DESIGN.md 前记住这 5 条硬规则即可细节见 docs/spec.md✅ 文件必须是YAML front matter Markdown 正文双层结构✅ 至少定义一个primary颜色令牌缺失会触发警告AI 只能自行补色✅ 正文章节必须按 8 节固定顺序出现重复章节名直接报错✅ 令牌引用必须用{path.to.token}花括号路径语法✅ 遇到规范未定义的章节或令牌名消费方应接受并保留保持格式开放可扩展——你可以加## Motion、## Iconography等自定义章节。CLI 的校验器、解析器、规范生成器等实现源码都在 packages/cli/src/linter/ 下想深入看规则实现可以从这里入手。学习最佳实践直接抄官方示例仓库自带 3 个风格迥异的完整示例是学习规范最好的教材示例风格特点atmospheric-glass玻璃拟态天气应用深色 白色半透明层次令牌非常完整paws-and-paths宠物友好路线规划温暖友好的品牌语气totality-festival日食音乐节大胆、戏剧化的活动视觉每个示例目录下的 README.md 都解释了 DESIGN.md、design_tokens.json、tailwind.config.js 三个文件的对应关系照着看一遍就明白令牌 → 导出的全链路。常见问题 FAQQ1AI 每次都会严格遵守 DESIGN.md 吗DESIGN.md 是强约束 软引导令牌值如色号是规范性的AI 应严格使用正文说明则是意图引导给 AI 留出创造空间。这正是官方刻意的设计取舍见 PHILOSOPHY.md。Q2没有设计师能写吗可以。规范不要求完整你可以先只写namecolors 一段 Overviewlint会列出缺失的可选章节供你逐步补全。Q3格式稳定吗当前版本为alpha规范仍在演进建议关注 docs/spec.md 的更新。核心双层结构和 8 章节骨架短期内是稳定的。Q4支持什么颜色写法所有 CSS 颜色都支持16 进制、命名色、rgb()/hsl()/hwb()、广色域oklch()/oklab()、color-mix()。校验对比度时内部会统一转 sRGB导出时保留原始写法。延伸阅读仓库关键文件索引文件说明README.md项目介绍、完整 CLI 参考、11 条 lint 规则表docs/spec.md格式规范全文令牌 Schema、章节顺序、兼容性行为PHILOSOPHY.md设计哲学为什么正文优先于令牌CONTRIBUTING.md贡献流程packages/cli/CLI 工具源码命令、lint 规则、导出器下一步行动清单打开仓库里的任一示例 DESIGN.md → 改成你自己产品的品牌色与字体 → 运行npx google/design.md lint DESIGN.md→ 把文件放进你的代码仓库根目录。至此你的 AI 就拥有了永不掉线的设计记忆。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 10分钟看懂DESIGN.md：让AI拥有设计系统持久记忆的格式规范
10分钟看懂DESIGN.md让AI拥有设计系统持久记忆的格式规范【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md是一个面向 AI 编码代理的设计系统格式规范Format Specification。它用一个纯文本 Markdown 文件把你的设计系统的颜色、字体、间距、组件样式等视觉身份完整记录下来让 AI 在不同会话、不同工具之间始终理解同一套设计语言——相当于给 AI 装上了设计系统的持久记忆。本文用最通俗的方式带你 10 分钟看懂这套规范、上手官方 CLI并学会写出第一份合格的 DESIGN.md。为什么 AI 生成的界面总是风格漂移用 AI 写前端代码时你是否遇到过这种情况今天生成的按钮是圆角蓝色明天就变成了方形紫色今天用的是 Inter 字体下次会话又换成了 Roboto口头叮嘱要高端、简洁、可信结果每次生成的都是千篇一律的模板脸。根本原因在于AI 的每次对话都是失忆的它记不住你的设计决策。DESIGN.md 项目由 Google 开源解决的就是这个问题——它把设计系统固化成一个随代码库一起版本管理的文本文件AI 每次干活前先读它风格自然稳定。项目主文档README.md 一个比喻如果把 AI 当成新员工口头说明只是临时交代而 DESIGN.md 就是公司发下来的《品牌视觉手册》。DESIGN.md 的核心结构一个文件两层内容一个 DESIGN.md 文件 机器可读的设计令牌Design Tokens 人类可读的设计说明。两层各司其职层位置格式作用设计令牌文件顶部 YAML front matter---包围的 YAML给 AI 精确的数值色值、字号、圆角、间距设计说明正文 Markdown##二级标题分节告诉 AI 这些值为什么存在、怎么用完整规范定义在 docs/spec.md哲学理念为什么正文比令牌更重要写在 PHILOSOPHY.md。第一层YAML 令牌——精确数值文件开头用---围栏包裹一段 YAML里面是结构化的设计令牌官方示例 examples/atmospheric-glass/DESIGN.md 节选如下--- name: Atmospheric Glass colors: primary: #ffffff secondary: #adc9eb typography: body-md: fontFamily: Inter fontSize: 16px fontWeight: 400 ---规范的令牌分组有 5 类colors任意 CSS 颜色写法#RRGGBB、rgb()、oklch()都可以typography字体族、字号、字重、行高、字距rounded圆角尺度sm/md/lg/full 等spacing间距尺度components组件级样式支持用{colors.primary}这种令牌引用语法跨组复用值。第二层Markdown 正文——设计意图正文按 8 个标准章节组织可以缺省但不能乱序Overview品牌与风格→ 2. Colors → 3. Typography → 4. Layout → 5. Elevation Depth → 6. Shapes → 7. Components → 8. Dos and Donts关键洞察是AI 生成质量不取决于数值多精确而取决于意图描述多清晰。写1970 年代研究生讲义的克制风格比写现代、简洁、高级有效得多——前者自带一整套隐性约束不发光、不用渐变、不花哨后者只会让 AI 在语义中心生成一张平均脸。PHILOSOPHY.md 中有大量精彩案例强烈建议通读一遍。3分钟上手用官方CLI校验、对比、导出项目自带命令行工具支持lint校验、diff版本对比、export格式导出三大命令。无需安装直接用 npx 运行一键校验lint 检查你的设计令牌npx google/design.md lint DESIGN.md它会跑 11 条内置规则输出结构化 JSON例如发现主按钮文字色与背景色对比度低于 WCAG AA4.5:1这类问题。规则清单broken-ref 断链引用、contrast-ratio 对比度、missing-sections 缺失章节等完整列在 README.md 的 Linting Rules 一节。版本对比diff 检测设计回退改版设计系统时对比新旧两个文件一眼看出哪些令牌被增删改、有没有引入新的错误npx google/design.md diff DESIGN.md DESIGN-v2.md一键导出生成 Tailwind 主题与 W3C 设计令牌令牌灵感来自 W3C Design Tokens 标准DTCGexport命令可一键互转npx google/design.md export --format json-tailwind DESIGN.md # Tailwind v3 主题配置 npx google/design.md export --format css-tailwind DESIGN.md # Tailwind v4 theme 块 npx google/design.md export --format dtcg DESIGN.md # W3C tokens.json仓库里每个官方示例都附带了导出产物可以直接对照学习examples/atmospheric-glass/tailwind.config.js、examples/paws-and-paths/design_tokens.json、examples/totality-festival/design_tokens.json。格式规范核心要点速览写 DESIGN.md 前记住这 5 条硬规则即可细节见 docs/spec.md✅ 文件必须是YAML front matter Markdown 正文双层结构✅ 至少定义一个primary颜色令牌缺失会触发警告AI 只能自行补色✅ 正文章节必须按 8 节固定顺序出现重复章节名直接报错✅ 令牌引用必须用{path.to.token}花括号路径语法✅ 遇到规范未定义的章节或令牌名消费方应接受并保留保持格式开放可扩展——你可以加## Motion、## Iconography等自定义章节。CLI 的校验器、解析器、规范生成器等实现源码都在 packages/cli/src/linter/ 下想深入看规则实现可以从这里入手。学习最佳实践直接抄官方示例仓库自带 3 个风格迥异的完整示例是学习规范最好的教材示例风格特点atmospheric-glass玻璃拟态天气应用深色 白色半透明层次令牌非常完整paws-and-paths宠物友好路线规划温暖友好的品牌语气totality-festival日食音乐节大胆、戏剧化的活动视觉每个示例目录下的 README.md 都解释了 DESIGN.md、design_tokens.json、tailwind.config.js 三个文件的对应关系照着看一遍就明白令牌 → 导出的全链路。常见问题 FAQQ1AI 每次都会严格遵守 DESIGN.md 吗DESIGN.md 是强约束 软引导令牌值如色号是规范性的AI 应严格使用正文说明则是意图引导给 AI 留出创造空间。这正是官方刻意的设计取舍见 PHILOSOPHY.md。Q2没有设计师能写吗可以。规范不要求完整你可以先只写namecolors 一段 Overviewlint会列出缺失的可选章节供你逐步补全。Q3格式稳定吗当前版本为alpha规范仍在演进建议关注 docs/spec.md 的更新。核心双层结构和 8 章节骨架短期内是稳定的。Q4支持什么颜色写法所有 CSS 颜色都支持16 进制、命名色、rgb()/hsl()/hwb()、广色域oklch()/oklab()、color-mix()。校验对比度时内部会统一转 sRGB导出时保留原始写法。延伸阅读仓库关键文件索引文件说明README.md项目介绍、完整 CLI 参考、11 条 lint 规则表docs/spec.md格式规范全文令牌 Schema、章节顺序、兼容性行为PHILOSOPHY.md设计哲学为什么正文优先于令牌CONTRIBUTING.md贡献流程packages/cli/CLI 工具源码命令、lint 规则、导出器下一步行动清单打开仓库里的任一示例 DESIGN.md → 改成你自己产品的品牌色与字体 → 运行npx google/design.md lint DESIGN.md→ 把文件放进你的代码仓库根目录。至此你的 AI 就拥有了永不掉线的设计记忆。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考