DESIGN.md 实战：以 Meridian「制图师图集」为例编写面向 AI Agent 的设计系统规范

DESIGN.md 实战以 Meridian「制图师图集」为例编写面向 AI Agent 的设计系统规范【免费下载链接】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导读本文以仓库中完整可用的 DESIGN.md 实例 MERIDIAN.md 为骨架系统讲解如何在 YAML frontmatter 中定义机器可读的设计令牌color / typography / spacing并在 Markdown 正文中为 AI Agent 提供人类可读的品牌叙事、排版原则与组件规范。读完本文你将掌握 DESIGN.md 的标准结构、令牌命名与引用约定、各章节Section的写法要点以及如何用仓库内置的 lint 命令与源码解析流程校验自己的 DESIGN.md 文件。一、DESIGN.md 是什么一个文档、两种语言根据格式规范 docs/spec.mdDESIGN.md 是自包含、纯文本的设计系统描述文件其核心目标是为编码代理coding agent提供持久、结构化的视觉身份理解。一个文件中同时承载两种信息层YAML frontmatter以---开始、以---结束的机器可读设计令牌块规范定义了colors、typography、rounded、spacing、components等令牌组Markdown 正文以##小节组织的人类可读设计原理与使用指南正文中可以用描述性颜色名如 Antique Gold对应系统性令牌名如tertiary。规范明确令牌是规范性取值normative values正文为应用语境提供上下文。这一点在 MERIDIAN.md 中得到完整示范——frontmatter 里的精确色值、字号、行高配合正文里 为什么用这种衬线体 的叙事共同构成 Agent 可执行的设计约束。MERIDIAN.md 是一个虚构品牌 The Cartographers Atlas制图师图集 的完整 DESIGN.md 样例也是本仓库 linter 的 fixtures 之一与其同级的还有 ALPINE_OBSERVATORY.md 等样例共同验证解析器与校验规则。二、MERIDIAN.md 的 YAML 令牌区逐字段拆解MERIDIAN.md 的 frontmatter 声明了name、colors、typography、spacing四组顶层内容完整如下节选关键结构--- name: The Cartographers Atlas colors: surface: #0f131c primary: #c3c6d7 on-primary: #2c303d secondary: #b9c8dc tertiary: #ecc246 error: #ffb4ab ... typography: display-xl: fontFamily: Newsreader fontSize: 84px fontWeight: 700 lineHeight: 1.1 letterSpacing: 0.05em ... spacing: unit: 8px gutter: 24px margin: 64px panel-padding: 120px ---2.1 name 与顶层字段name是必填字符串标记设计系统名称。规范 docs/spec.md 还允许可选的version当前为alpha、description、omitted声明有意省略的令牌组用于抑制 lint 的缺失警告可写成字符串或带reason的对象。2.2 colors 令牌Material 式表面色体系MERIDIAN.md 的colors令牌组包含 40 个令牌覆盖了surface、surface-container-*、on-surface、inverse-surface、outline、primary/secondary/tertiary及其-container、-fixed变体、error、background等是一套接近 Material 3 语义的深色表面体系。核心取值如下令牌色值设计角色surface#0f131c页面基底深色画布surface-container-lowest#0a0e16最深一级容器用于与基底形成分层surface-container#1c2028常规内容容器on-surface#dfe2ee基底上的前景文字outline#909096发丝线边框、分隔线primary#c3c6d7主强调色冷银蓝灰tertiary#ecc246金褐色点缀色Antique Gold 的令牌对应error#ffb4ab错误态规范要求colors中至少必须定义primary多调色板时推荐按primary、secondary、tertiary、neutral的次序命名MERIDIAN.md 正是按此约定组织。所有颜色值会在内部统一转换为 sRGB 用于 WCAG 对比度校验原文格式则保留用于展示与导出见 docs/spec.md 的 Color 一节。2.3 typography 令牌三层字体系统typography令牌组为每个文本层级定义fontFamily、fontSize、fontWeight、lineHeight、letterSpacing层级令牌字体字号字重行高用途display-xlNewsreader84px7001.1巨幅展示标题headline-lgNewsreader48px6001.2一级标题headline-mdNewsreader32px5001.3二级标题body-lgNoto Serif20px4001.7长文正文body-mdNoto Serif17px4001.7常规正文label-capsSpace Grotesk12px5001.5全大写标注、标签quote-editorialNewsreader28px4001.4编辑性引言注意fontWeight在 YAML 中写成带引号的700解析器会将其规范化为数字测试 fixture.test.ts 断言700解析为700lineHeight的1.1这类无单位数字被解释为相对fontSize的倍数——这是规范推荐的 CSS 写法。2.4 spacing 令牌4 级间距尺度spacing: unit: 8px gutter: 24px margin: 64px panel-padding: 120pxspacing是mapstring, Dimension | number既接受带单位的维度px/em/rem也接受无单位数字如列数、比例。MERIDIAN.md 用语义化键名unit/gutter/margin/panel-padding而非sm/md/lg刻度——规范允许任意描述性字符串作为键这印证了令牌命名的灵活性。三、正文 Section从 Brand Style 到 Components 的叙事骨架规范定义了 8 个标准小节及其顺序Overview/Brand Style→Colors→Typography→Layout→Elevation Depth→Shapes→Components→Dos and DontsMERIDIAN.md 依次实现了前七个可作为照抄的模板。3.1 Brand Style一锤定音的总体气质MERIDIAN.md 的开篇用两段话定义了品牌基调知性权威与发现感目标受众是重视长篇调查报道、历史语境与精确数据的受众美学路线是High-Contrast / Minimalist高对比 / 极简拒绝柔和阴影与圆角追求被一盏高亮度台灯照亮的幽暗图书馆般的专注情绪。规范指出该小节是 Agent 在没有明确规则或令牌时做高层级风格决策的兜底语境因此值得用明确形容词写透。3.2 Colors四色叙事的正文版正文将调色板收敛为四种核心色调与令牌一一对应Obsidian Canvas#080C14基础地面深色空洞让内容浮现Ink Navy#0A0E1A主要内容容器与标题与背景形成微妙层次Slate Structure#2C3A4A技术性色彩用于发丝线边框、网格线与功能性 UIAntique Gold#C9A227唯一的强强调色必须克制使用理想情况每屏仅出现一次充当最重要操作或数据点的灯塔。注意正文色值与 frontmatter 色值存在有意差异如正文写#C9A227令牌tertiary为#ecc246。这正是规范反复强调的令牌是规范性取值正文中的描述性色名仅提供语义参照。3.3 Typography衬线叙事 × 无衬线标注正文将字体分为三层与令牌一一对应Headlines — Newsreader高对比笔画的锐利衬线大字号下加宽字距tracking强化纪念碑式体量Body — Noto Serif长时间阅读的温暖与易读性1.7 行高是强制要求防止文本块显得密集Labels UI — Space Grotesk全大写 宽字距模仿地形图上的坐标标注。3.4 Layout Spacing全出血面板网格布局采用Full-Bleed Panel Grid全出血面板网格并配合 scroll-snap每个面板代表体验中的一个章节 / 地图页偏移文本块避免居中内容应偏置在垂直中线左侧或右侧营造编辑性节奏交替面板视觉重量在面板间轮换如文字密集的 Slate 面板之后接全屏图像 / 数据可视化边距慷慨的 64px 边距保证内容不拥挤维持图集的辽阔感。3.5 Elevation Depth扁平制图学严禁阴影与制图学的扁平性质一致阴影被严格禁止深度只通过三种手段构建色调阶梯Tonal Stepping将 Ink Navy 层叠于 Obsidian 之上发丝线边框1px 实线 Slate 定义面板或组件边界Z 轴分层固定导航、标签等元素以 100% 不透明度浮于内容之上靠色彩对比而非模糊/阴影突出。3.6 Shapes0px 圆角直角即精度形状语言定义为0px border radius所有容器、按钮与装饰元素必须使用锐利直角体现制图工具的精度与建筑制图的刚性线条。没有例外——连圆形头像与图标也应置于方形/矩形容器中。3.7 Components五个组件的精修细节Buttons主按钮用 Antique Gold 填充 Navy 文字矩形0px 圆角无 hover 阴影hover 态以 1px Slate 描边或金色轻微偏移表示Pull Quotes大字 Newsreader 斜体左侧 2px 竖向金色边框锚定常置于偏移布局区以打破正文流Lists Annotations项目符号/编号用 Label 字体Space Grotesk条目间以 Slate 水平发丝线分隔Input FieldsNavy 表面上的 1px Slate 描边聚焦时边框变金标签恒位于字段上方全大写宽字距 Space GroteskData Panels独特的Coordinate Panel坐标面板——视口角落的小型固定 UI以 Label 字体展示进度或元数据模仿地图图例。四、源码侧印证令牌如何被解析与校验4.1 解析器frontmatter 与 fenced yaml 双模式解析入口是 packages/cli/src/linter/parser/handler.ts。ParserHandler.execute()使用unifiedremark-parseremark-frontmatter构建 AST然后遍历节点收集三类信息yaml 节点---frontmatter与fenced yaml/yml 代码块均作为令牌来源##二级标题作为 Section 列表sections每个 Section 的原文切片documentSections。随后mergeCodeBlocks()会检测跨块重复的顶层键并返回DUPLICATE_SECTION错误对应规范中 Duplicate section heading → Error 的消费者行为表。toDesignSystem()将原始 YAML 映射为结构化的colors/typography/rounded/spacing/components/omitted字段。也就是说MERIDIAN.md 的 frontmatter 会先经过这一层校验性解析才能进入 lint 阶段。4.2 校验规则11 条默认规则的靶向检查解析后的设计系统状态会交给 packages/cli/src/linter/linter/runner.ts 的runLinter()它按序执行 packages/cli/src/linter/linter/rules/index.ts 中注册的 11 条默认规则brokenRef、missingPrimary、contrastCheck、orphanedTokens、tokenSummary、missingSections、missingTypography、sectionOrder、unknownKey、tokenLikeIgnored、omitted。对 MERIDIAN.md 这类规范文件最有意义的检查包括missingPrimarycolors必须含primary、sectionOrderSection 必须按规范顺序出现、contrastCheck颜色转 sRGB 后做 WCAG 对比度评估、brokenRef{path.to.token}引用是否悬空。每项 rule 都有独立测试文件如 missing-primary.test.ts、section-order.test.tsfixture 级测试则通过 fixture.test.ts 对整份 DESIGN.md 做端到端断言。4.3 CLI 实战校验你自己的 DESIGN.md仓库提供lint命令用于验证文件的结构正确性入口见 packages/cli/src/commands/lint.tsbun run cli lint path/to/DESIGN.md # JSON 输出默认 bun run cli lint path/to/DESIGN.md -f text # 纯文本输出 cat path/to/DESIGN.md | bun run cli lint - # 从 stdin 读取命令行为读取文件 → 调用lint(content)得到{ findings, summary }→ 打印报告只要存在error级别 finding进程退出码即为 1process.exitCode report.summary.errors 0 ? 1 : 0适合接入 CI 门槛。五、从样例到自己的 DESIGN.md可复用的写作清单对照 MERIDIAN.md 与仓库其他示例编写一份合格 DESIGN.md 的检查清单如下frontmatter 必填name 至少colors.primary无 YAML 时解析器返回NO_YAML_FOUND错误见 parser/handler.ts令牌优先所有正文提到的关键色值、字号都要在令牌区有对应取值正文中的命名色只作语义注释Section 顺序按 Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Dos and Donts 排列避免sectionOrder规则报警不需要的小节可省略深色 / 浅色体系都要定义on-*与container层级MERIDIAN.md 与 ALPINE_OBSERVATORY.md 都提供了完整的 Material 式表面色阶梯可当作深色主题模板直接改写无圆角 / 禁阴影等极端约束要写成禁止句式规范与正文都以明确的 strictly prohibited、No exceptions 句式约束 Agent 行为避免歧义写完立即 lint用上文 CLI 命令验证零 error再提交。如需参考浅色主题与不同字体组合可对比 examples/paws-and-paths/DESIGN.mdMaterial 风格浅色色板 Plus Jakarta Sans / Space Grotesk该文件同时被 Tailwind v4 导出测试引用见 packages/cli/src/linter/tailwind/v4/fixture.test.ts说明同一份 DESIGN.md 令牌还可流向 Tailwindtheme生成。结语MERIDIAN.md 的价值在于它完整演示了 DESIGN.md 的双轨写法机器可读的令牌区给出精确数值人类可读的正文区给出审美意图与使用边界二者互为表里。对 Agent 而言前者是可执行的规则后者是决策的语境对设计团队而言这是一份既能进 CI 校验、又能被模型消费的活的设计真源。以它为模板配合本仓库的 lint 工具与解析源码任何人都能在几小时内产出一份高质量、可验证、可被 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），仅供参考