DESIGN.md的8个标准章节与别名全解从Overview到Dos and Donts【免费下载链接】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 编码代理讲清楚视觉身份的设计系统格式规范。它把设计决策拆成两层机器可读的 YAML 设计令牌design tokens 人类可读的 Markdown 设计说明。而这份文档里组织说明内容的核心骨架就是8 个标准章节——用对了AI 生成的 UI 才能稳定还原你的品牌风格。本文将带你一次性读懂每个章节的用途和官方别名。一、DESIGN.md 文件结构速览两层结构一个骨架 一个 DESIGN.md 文件由两部分组成层级位置作用YAML Front Matter文件顶部---围栏内机器可读的设计令牌颜色、字体、圆角、间距等精确值Markdown 正文围栏之后的##章节人类可读的设计理由告诉 AI 为什么用这些值Front Matter 负责给精确值正文 8 个章节负责给判断依据。两者缺一不可只有令牌AI 不知道场景只有文字AI 拿不到具体数值。二、8 个标准章节顺序与别名称全表 规范中章节使用##H2标题。它们可以省略但只要出现就必须按下表顺序排列。其中 3 个章节拥有官方认可的别名#标准章节官方别名写什么1OverviewBrand Style品牌个性、目标用户、UI 应唤起的情绪活泼/专业、紧凑/留白2Colors—色板定义primary必选惯用命名顺序 primary → secondary → tertiary → neutral3Typography—字体层级策略通常 9–15 级如 headline / body / label4LayoutLayout Spacing布局与间距策略网格模型、8px 节奏、留白哲学5Elevation DepthElevation视觉层次如何表达阴影、Tonal Layers或扁平设计的替代方案6Shapes—形状语言圆角风格、图标形态等7Components—组件级风格指引按钮、输入框、卡片、列表等原子组件8Dos and Donts—实用守则与常见坑作为 AI 生成设计时的护栏这张表的唯一事实源single source of truth维护在 spec-config.yaml官方完整规范见 docs/spec.md。三、别名机制详解为什么官方允许换名不换位 别名如何生效别名与标准名完全等价。校验器内部通过 resolveAlias 函数把别名解析回标准名后再做一切判断因此用## Brand Style开头 用## Overview开头顺序校验一视同仁别名不能乱序写了## Layout Spacing就仍必须排在 Typography 之后官方示例 paws-and-paths/DESIGN.md 就真实使用了## Brand Style和## Layout Spacing两个别名可对照 totality-festival/DESIGN.md 看不同风格的完整写法别名 vs 未知章节区别很大 ⚠️场景校验器行为举例使用官方别名正常识别等价标准章节## Brand Style使用未知章节标题保留、不报错## Iconography同一章节标题出现两次报错拒绝整个文件两个## Colors也就是说别名是官方翻译未知标题是自定义扩展——前者参与顺序校验后者被原样放行。四、章节顺序与 lint 校验三条规则帮你避坑 ✅跑一次npx google/design.md lint DESIGN.md命令详见 README.md与章节相关的检查有section-orderwarning章节出现顺序不符合标准顺序时告警提示期望顺序为 Overview, Colors, Typography, Layout, Elevation Depth, Shapes, Components, Dos and Donts。规则实现见 section-order.tsmissing-sectionsinfo定义了颜色但没有spacing、rounded令牌时提示将回退到 AI 默认值。见 missing-sections.tsomitted-rulesinfo/warning在 Front Matter 中声明omitted键可有意跳过某些部分并抑制告警例如品牌手册明确不用圆角时声明rounded。声明与已定义令牌矛盾时反而会收到 redundant-omission 警告逻辑见 omitted.ts五、新手实操清单照着写不踩坑 ✍️顺序优先先按 1→8 排好章节骨架再填充内容不需要的章节直接删掉不要留空标题令牌必写colors至少定义primary正文提到的色板如 Boston Clay应与令牌名如tertiary建立清晰对应变体独立成条组件状态hover/active作为独立条目写在 Components 令牌里如button-primary与button-primary-hoverDos and Donts 写具体像每屏只用一次 primary 色单屏不超过两种字重这种可执行的短句最有效最后跑一次 lint确认无 error、章节顺序无 warning文件即可交给 AI 代理使用掌握这 8 个章节与别名规则你就拥有了 DESIGN.md 格式的完整地图——下一章可以看看如何把令牌导出为 Tailwind 主题让设计系统真正落地到代码里 【免费下载链接】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），仅供参考
