2026/9/11 1:40:04
FEATURED · 精选文章 
DESIGN.md 实战解析用 The Alpine Observatory 构建面向编码 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导读The Alpine Observatory高山天文台是 DESIGN.md 格式在 packages/cli/src/linter/fixtures/ALPINE_OBSERVATORY.md 中的一份完整示例文档它以 19 世纪极地科考美学为蓝本将科学登山的严谨编码为机器可读的设计令牌YAML frontmatter与人类可读的设计叙事Markdown 正文。本文以该文档为骨架结合 docs/spec.md 格式规范与 CLI 源码实现逐层拆解它的令牌 Schema、分区结构与组件规范并演示如何用lint、diff、export等命令验证、对比和导出这套设计系统——读完你将掌握撰写一份合规 DESIGN.md、让编码 Agent 稳定复现品牌视觉的完整实战方法。一、The Alpine Observatory一份完整的 DESIGN.md 是什么样1.1 双重视图层令牌是规范散文是语境根据 docs/spec.md 的定义一份 DESIGN.md 由两部分组成可选的 YAML frontmatter机器可读的设计令牌和Markdown 正文人类可读的设计依据。令牌给出精确数值散文解释为什么二者互补The tokens are the normative values; the prose provides context for how to apply them.在 ALPINE_OBSERVATORY.md 中这种双重视图层体现得非常典型frontmatter 里primary: #f6bb81是规范值正文里则用 The Instrument(Antique Brass) is used exclusively for interactive elements 告诉 Agent 这个黄铜色只能用于交互元素和关键焦点——数值负责是什么散文负责怎么用。1.2 完整的 frontmatter从颜色到排版到间距这份文档的 frontmatter 覆盖了 DESIGN.md 令牌 Schema 中的三大核心组colors、typography、spacing是理解令牌结构的绝佳标本--- name: The Alpine Observatory colors: surface: #0a1325 surface-dim: #0a1325 surface-bright: #30394d surface-container-lowest: #050e20 surface-container-low: #131b2e surface-container: #171f32 surface-container-high: #212a3d surface-container-highest: #2c3548 on-surface: #dae2fc on-surface-variant: #d5c3b6 inverse-surface: #dae2fc inverse-on-surface: #283044 outline: #9d8e81 outline-variant: #50453a surface-tint: #f6bb81 primary: #f6bb81 on-primary: #4a2800 primary-container: #c58f59 on-primary-container: #4c2a00 inverse-primary: #815524 secondary: #c9c6c1 on-secondary: #31312d secondary-container: #474743 on-secondary-container: #b7b5af tertiary: #b7c9d8 on-tertiary: #22323e tertiary-container: #8b9caa on-tertiary-container: #233440 error: #ffb4ab on-error: #690005 error-container: #93000a on-error-container: #ffdad6 primary-fixed: #ffdcbe primary-fixed-dim: #f6bb81 on-primary-fixed: #2c1600 on-primary-fixed-variant: #663d0e secondary-fixed: #e5e2dc secondary-fixed-dim: #c9c6c1 on-secondary-fixed: #1c1c18 on-secondary-fixed-variant: #474743 tertiary-fixed: #d3e5f4 tertiary-fixed-dim: #b7c9d8 on-tertiary-fixed: #0c1d28 on-tertiary-fixed-variant: #384955 background: #0a1325 on-background: #dae2fc surface-variant: #2c3548 typography: heading-display: fontFamily: Marcellus fontSize: 48px fontWeight: 400 lineHeight: 1.1 letterSpacing: 0.02em heading-section: fontFamily: Marcellus fontSize: 24px fontWeight: 400 lineHeight: 1.3 letterSpacing: 0.05em body-journal: fontFamily: newsreader fontSize: 18px fontWeight: 400 lineHeight: 1.6 letterSpacing: 0em telemetry-data: fontFamily: IBM Plex Mono fontSize: 12px fontWeight: 500 lineHeight: 1.5 letterSpacing: 0.15em telemetry-label: fontFamily: IBM Plex Mono fontSize: 10px fontWeight: 400 lineHeight: 1.2 letterSpacing: 0.2em spacing: panel-gap: 1rem margin-edge: 2rem gutter: 1rem unit: 4px ---几个值得注意的规范细节对照 docs/spec.md 的 SchemaColor 值这里全部采用#RRGGBB十六进制是规范推荐的默认写法Hex notation remains the recommended default for simplicity and broad tooling support。规范同时接受rgb()/hsl()/oklch()甚至color-mix()且所有颜色在内部都会转换为 sRGB 用于 WCAG 对比度检查原始格式仅用于展示与导出。fontWeightYAML 中400带引号字符串与裸数字400等价解析器见 parser/handler.ts会将其规范化为数值fixture.test.ts 中就验证了fontWeight: 700字符串被解析为数字700。lineHeight1.1这种无单位数字表示相对fontSize的倍率是规范推荐的 CSS 实践a unitless number represents a multiplier of the elements fontSize。spacing值是带单位的 Dimension1rem、2rem或纯数字4px也属于带单位unit: 4px则是对 4px 基础栅格的直接建模——正文里Fixed Grid章节就是它的语义化解释。1.3 正文分区严格遵循规范顺序ALPINE_OBSERVATORY.md 的正文依次是## Brand Style、## Colors、## Typography、## Layout Spacing、## Elevation Depth、## Shapes、## Components恰好命中 docs/spec.md 定义的规范分区顺序#分区别名1OverviewBrand Style2Colors3Typography4LayoutLayout Spacing5Elevation DepthElevation6Shapes7Components8Dos and Donts分区可省略但出现的分区必须按此顺序排列section-order规则warning 级会检查这一点具体规则实现见 linter/rules/ 目录。解析器只把##H2识别为分区标题可选 H1 仅作文档标题、不参与分区解析见 parser/handler.ts 中heading.depth 2的判断。二、Brand Style先定义情绪再定义像素Brand Style是全文档的定位锚点。规范的定位是它整体描述产品的外观与感受定义品牌个性、目标受众和 UI 应唤起的情感反应是 Agent 在没有显式规则或令牌时做出高层级风格决策的基础语境。ALPINE_OBSERVATORY.md 的开篇即是一个教科书级的示例——它把整套设计系统浓缩成一个可执行的概念Scientific Alpinism科学登山水准——tactile, historic materials与cold, celestial data的混合体。UI 要唤起 The Sublime敬畏与危险交织的崇高感采用Modern-Tactile路径信息被当作制图师桌上的文物、或透过黄铜六分仪看到的遥测数据明确要求avoid all modern softness。这一节的价值在于它给 Agent 提供了散文级的过滤网。当某个组件没有对应的令牌规定时Agent 可以回溯这段品牌描述自行推断这个设计不会用圆角、不会用柔光阴影——这正是 DESIGN.md 让视觉身份在 Agent 之间持久、结构化传承的核心机制。三、Colors四个隐喻撑起一整张色板Colors 分区把颜色角色提炼为四个叙事性隐喻与 frontmatter 中的令牌一一对应The Void虚空surface: #0a1325、background: #0a1325等深观测蓝作为高海拔大气的无限背景——对应整组surface-*/background令牌The Lens透镜Parchment 羊皮纸高对比阅读表面模仿早期探险的手绘地图——对应primary: #f6bb81、on-primary: #4a2800等黄铜/羊皮色系The Instrument仪器Antique Brass 古董黄铜仅用于交互元素与关键焦点代表导航的实体工具——对应surface-tint: #f6bb81与primary家族The Hardware硬件Glacial Steel 冰川钢提供结构框架是观察者与环境之间那条细而冷的线——对应secondary: #c9c6c1、outline: #9d8e81等中性金属色。正文还给出了一条关键使用规则Use parchment sparingly for primary content containers to create a magnified effect against the dark canvas——羊皮纸色要克制使用只在主要内容容器上制造放大镜效果。从实现层面看颜色值的解析与归一化由 linter/model/color-parser.ts 承担。这里 48 个颜色令牌全部是 Material Design 风格的角色命名surface-container-lowest、on-primary-fixed-variant等这也印证了规范中token 命名约定可自由选择只需保持一致的说法examples/atmospheric-glass/design_tokens.json 展示了同一套角色体系导出为 DTCG 格式后的样子。四、Typography三种字体承担三种叙事身份Typography 分区展示了字体即叙事的设计手法把排版令牌与角色绑定Primary MarkingsMarcellusheading-display48px/400/1.1/0.02em与heading-section24px/400/1.3/0.05em——古典权威感与历史永恒感The JournalNewsreaderbody-journal18px/400/1.6——作为 EB Garamond 风格的代理字体服务远征日志与高山勘察的长文阅读要求literary and intentionalThe TelemetryIBM Plex Monotelemetry-data12px/500/1.5/0.15em与telemetry-label10px/400/1.2/0.2em——机器的声音必须大写 宽字距模拟黄铜设备上的蚀刻标签或气压计打印输出用于导航、坐标和元数据。三个字体族恰好覆盖 docs/spec.md 中推荐的语义命名headline、body、label且letterSpacing从 0.02em 到 0.2em 的递进本身就是叙事权重的量化表达。规范还支持fontFeature映射font-feature-settings与fontVariation映射font-variation-settings两个高级字段本示例未使用但属于 Schema 的合法成员。五、Layout SpacingFixed Grid 与 4px 数学节奏Layout 分区定义了Fixed Grid哲学——灵感来自工程制图纸刚性面板布局由刚性面板组成面板间强制1rem gapfrontmatter 中的panel-gap: 1rem让每个模块都像套装中的独立仪器1px 冰川钢边框强化结构对应outline/secondary色系对称优先模仿望远镜的对称透镜留白不是用于呼吸感而是用于隔离数据点如同星图隔离天体对齐必须严格数学化不允许圆角破坏几何。对应到 spacing 令牌spacing: panel-gap: 1rem # 面板间距正文中强制 1rem gap的令牌化 margin-edge: 2rem # 页面边缘边距 gutter: 1rem # 栅格沟槽 unit: 4px # 基础栅格单位注意 docs/spec.md 明确 spacing 的值可以是 Dimension 或无单位数字如列数、比例所以类似grid-columns: 5这样的无单位值也在 Schema 范围内当解析器遇到非标准值时会按Consumer Behavior表格以字符串存储而不报错。六、Elevation Depth不用阴影用色调分层 结构框定Elevation 分区展示了扁平设计传达层级的标准替代方案这正是规范中for flat designs, this section explains the alternative methods所要求的Tonal Layering色调分层全局画布是最深层级The Void信息面板The Lens作为平坦、无抬升的表面置于其上十字准星交点在 1px 边框交汇处指示层级1px 内嵌inset暗示玻璃被装进镜框零环境阴影系统的光是二元的——要么被黄铜强调色照亮要么留在背景的冷钢色中。这与同仓库的另一份示例 packages/cli/src/linter/fixtures/DESIGN-test.mdPacific Mint Dental形成鲜明对比后者使用 Ambient Shadows 与 Tonal Layers 三级阴影体系。两个 fixture 放在一起恰好演示了同一格式如何承载截然不同的深度策略。七、Shapes0px 圆角不是妥协是风格声明Shapes 分区规定Linear and Sharp形状语言所有组件从按钮到大容器强制0px 圆角传达精确、危险、高海拔环境的毫不妥协。装饰元素被限制为 45 度切角chamfers与罗盘风格图标。这里有一个重要的格式事实ALPINE_OBSERVATORY.md没有定义rounded令牌组——这不是遗漏而是 DESIGN.md 格式的合法状态。若设计系统确实不需要圆角令牌可用omitted字段显式声明并附理由从而抑制missing-sections规则的提示见 docs/spec.md 的omitted定义支持字符串或{section, reason}对象两种形式omitted: - section: rounded reason: No rounded corners defined in brand book八、Components六类组件如何就地取材Components 分区把前文的颜色、排版、形状规则组装为可操作的原子组件规范也鼓励按领域自定义组件docs/spec.md 列出 Buttons、Chips、Lists、Tooltips、Checkboxes、Radio、Input fields 等常见类型Action Orreries按钮矩形 0px 圆角默认态为 1px Navy 边框 透明背景hover 时背景填充 Antique Brassprimary: #f6bb81文字转为 Navy——与 Colors 分区黄铜只用于交互的规则严格自洽The Ledger列表行间用 1px Glacial Steel 分隔线每行以 Telemetry 风格时间戳或坐标开头——直接调用 Typography 分区的等宽字体规则The Sextant输入框仅下划线或全框 Glacial Steelfocus 态边框转 Antique Brass并在右上角出现小型十字准星图标Specimen Cards羊皮纸Parchment背景容器1px Steel 边框四角常带经纬度遥测文本框定内容——呼应羊皮纸克制使用的规则Navigation顶级导航居中、IBM Plex Mono 宽字距激活链接用 1px Antique Brass 下划线Celestial Markers主区块四角使用细加号作为 UI 透镜的注册标记。从 Schema 角度看组件还可以用components令牌组精确建模docs/spec.md 的mapstring, mapstring, string通过{colors.primary}引用语法指向既有令牌并通过button-primary-hover这类关联键表达 hover/active 变体。ALPINE_OBSERVATORY.md 以散文描述组件而 README.md 中的components.button-primary示例展示了令牌化写法——两种方式都在格式覆盖范围内。九、让 Agent 读懂并验证这份文档lint / diff / export9.1 校验lint将 ALPINE_OBSERVATORY.md 交给 linter 校验会依次执行 11 条规则见 README.md 的 Linting Rules 表格核心关注点包括broken-referror{colors.primary}这类引用是否指向真实存在的令牌missing-primarywarning定义了 colors 却没有primary时Agent 会自行生成主色contrast-ratiowarning组件backgroundColor/textColor组合是否低于 WCAG AA 的 4.5:1 下限——实现见 linter/rules/contrast-ratio.ts其中const WCAG_AA_MINIMUM 4.5section-orderwarning分区是否乱序unknown-keywarningcolours:这类疑似拼错的顶层键会被捕获。npx google/design.md lint ALPINE_OBSERVATORY.md cat ALPINE_OBSERVATORY.md | npx google/design.md lint - # 支持 stdin所有命令均接受文件路径或-stdin默认输出 JSON有 error 时退出码为 1。linter 也可作为库调用见 linter/index.ts 与 linter/runner.tsimport { lint } from google/design.md/linter; const report lint(markdownString); console.log(report.findings); // Finding[] console.log(report.summary); // { errors, warnings, info } console.log(report.designSystem); // ParsedDesignSystemState9.2 对比diff追踪设计系统演进时用diff比较两版文档输出令牌级增删改与散文回归情况npx google/design.md diff ALPINE_OBSERVATORY.md ALPINE_OBSERVATORY-v2.md若after版本相比before出现了更多 error 或 warning回归退出码为 1。这非常适合在设计评审design review中自动把关。9.3 导出exportDESIGN.md 令牌可直接互操作到主流设计工程链路npx google/design.md export --format json-tailwind ALPINE_OBSERVATORY.md tailwind.theme.json # Tailwind v3 theme.extend npx google/design.md export --format css-tailwind ALPINE_OBSERVATORY.md theme.css # Tailwind v4 theme 块--color-*、--font-*、--radius-* 等命名空间 npx google/design.md export --format dtcg ALPINE_OBSERVATORY.md tokens.json # W3C Design Tokens Format Module后者的产物形态可参考仓库中的 examples/atmospheric-glass/design_tokens.jsonDTCG 输出会把颜色展开为{ $type: color, $value: { colorSpace: srgb, components: [...], hex: #0b1326 } }这样的结构化条目。十、从样板到规范以 ALPINE_OBSERVATORY 为模板撰写自己的 DESIGN.md综合全文一份可被 Agent 可靠消费的 DESIGN.md 应当具备四个特征ALPINE_OBSERVATORY.md 每一项都做了示范令牌先行散文补意frontmatter 给出精确数值primary: #f6bb81正文说明用途边界黄铜只用于交互分区守序可留可省出现的 H2 分区严格按 Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Dos and Donts 排列无关分区用omitted显式声明叙事自洽规则闭环Shapes 说0px 圆角Components 的按钮就写0px radiusColors 说羊皮纸克制Specimen Cards 就限定为主要内容容器——散文与令牌互相印证Agent 才不会产生歧义可验证、可互操作随时可过lint检查对比度、引用完整性、分区顺序可diff追踪变更可export接入 Tailwind / DTCG 工具链。对照同仓库的另一份 fixture packages/cli/src/linter/fixtures/DESIGN-test.mdPacific Mint Dental暖色系 圆角 阴影的Clinical Serenity可以更直观地看到同一套格式既能承载高山天文台的冷峻几何也能承载牙科诊所的柔和圆润——这正是 DESIGN.md human-readable, open-format 设计哲学的最好注脚。在你自己的项目中把 ALPINE_OBSERVATORY.md 当作脚手架替换为你的品牌色、字体与组件规则再用npx google/design.md lint验证一遍即可得到一份 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DESIGN.md 实战解析：用 The Alpine Observatory 构建面向编码 Agent 的高山天文台视觉系统
DESIGN.md 实战解析用 The Alpine Observatory 构建面向编码 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导读The Alpine Observatory高山天文台是 DESIGN.md 格式在 packages/cli/src/linter/fixtures/ALPINE_OBSERVATORY.md 中的一份完整示例文档它以 19 世纪极地科考美学为蓝本将科学登山的严谨编码为机器可读的设计令牌YAML frontmatter与人类可读的设计叙事Markdown 正文。本文以该文档为骨架结合 docs/spec.md 格式规范与 CLI 源码实现逐层拆解它的令牌 Schema、分区结构与组件规范并演示如何用lint、diff、export等命令验证、对比和导出这套设计系统——读完你将掌握撰写一份合规 DESIGN.md、让编码 Agent 稳定复现品牌视觉的完整实战方法。一、The Alpine Observatory一份完整的 DESIGN.md 是什么样1.1 双重视图层令牌是规范散文是语境根据 docs/spec.md 的定义一份 DESIGN.md 由两部分组成可选的 YAML frontmatter机器可读的设计令牌和Markdown 正文人类可读的设计依据。令牌给出精确数值散文解释为什么二者互补The tokens are the normative values; the prose provides context for how to apply them.在 ALPINE_OBSERVATORY.md 中这种双重视图层体现得非常典型frontmatter 里primary: #f6bb81是规范值正文里则用 The Instrument(Antique Brass) is used exclusively for interactive elements 告诉 Agent 这个黄铜色只能用于交互元素和关键焦点——数值负责是什么散文负责怎么用。1.2 完整的 frontmatter从颜色到排版到间距这份文档的 frontmatter 覆盖了 DESIGN.md 令牌 Schema 中的三大核心组colors、typography、spacing是理解令牌结构的绝佳标本--- name: The Alpine Observatory colors: surface: #0a1325 surface-dim: #0a1325 surface-bright: #30394d surface-container-lowest: #050e20 surface-container-low: #131b2e surface-container: #171f32 surface-container-high: #212a3d surface-container-highest: #2c3548 on-surface: #dae2fc on-surface-variant: #d5c3b6 inverse-surface: #dae2fc inverse-on-surface: #283044 outline: #9d8e81 outline-variant: #50453a surface-tint: #f6bb81 primary: #f6bb81 on-primary: #4a2800 primary-container: #c58f59 on-primary-container: #4c2a00 inverse-primary: #815524 secondary: #c9c6c1 on-secondary: #31312d secondary-container: #474743 on-secondary-container: #b7b5af tertiary: #b7c9d8 on-tertiary: #22323e tertiary-container: #8b9caa on-tertiary-container: #233440 error: #ffb4ab on-error: #690005 error-container: #93000a on-error-container: #ffdad6 primary-fixed: #ffdcbe primary-fixed-dim: #f6bb81 on-primary-fixed: #2c1600 on-primary-fixed-variant: #663d0e secondary-fixed: #e5e2dc secondary-fixed-dim: #c9c6c1 on-secondary-fixed: #1c1c18 on-secondary-fixed-variant: #474743 tertiary-fixed: #d3e5f4 tertiary-fixed-dim: #b7c9d8 on-tertiary-fixed: #0c1d28 on-tertiary-fixed-variant: #384955 background: #0a1325 on-background: #dae2fc surface-variant: #2c3548 typography: heading-display: fontFamily: Marcellus fontSize: 48px fontWeight: 400 lineHeight: 1.1 letterSpacing: 0.02em heading-section: fontFamily: Marcellus fontSize: 24px fontWeight: 400 lineHeight: 1.3 letterSpacing: 0.05em body-journal: fontFamily: newsreader fontSize: 18px fontWeight: 400 lineHeight: 1.6 letterSpacing: 0em telemetry-data: fontFamily: IBM Plex Mono fontSize: 12px fontWeight: 500 lineHeight: 1.5 letterSpacing: 0.15em telemetry-label: fontFamily: IBM Plex Mono fontSize: 10px fontWeight: 400 lineHeight: 1.2 letterSpacing: 0.2em spacing: panel-gap: 1rem margin-edge: 2rem gutter: 1rem unit: 4px ---几个值得注意的规范细节对照 docs/spec.md 的 SchemaColor 值这里全部采用#RRGGBB十六进制是规范推荐的默认写法Hex notation remains the recommended default for simplicity and broad tooling support。规范同时接受rgb()/hsl()/oklch()甚至color-mix()且所有颜色在内部都会转换为 sRGB 用于 WCAG 对比度检查原始格式仅用于展示与导出。fontWeightYAML 中400带引号字符串与裸数字400等价解析器见 parser/handler.ts会将其规范化为数值fixture.test.ts 中就验证了fontWeight: 700字符串被解析为数字700。lineHeight1.1这种无单位数字表示相对fontSize的倍率是规范推荐的 CSS 实践a unitless number represents a multiplier of the elements fontSize。spacing值是带单位的 Dimension1rem、2rem或纯数字4px也属于带单位unit: 4px则是对 4px 基础栅格的直接建模——正文里Fixed Grid章节就是它的语义化解释。1.3 正文分区严格遵循规范顺序ALPINE_OBSERVATORY.md 的正文依次是## Brand Style、## Colors、## Typography、## Layout Spacing、## Elevation Depth、## Shapes、## Components恰好命中 docs/spec.md 定义的规范分区顺序#分区别名1OverviewBrand Style2Colors3Typography4LayoutLayout Spacing5Elevation DepthElevation6Shapes7Components8Dos and Donts分区可省略但出现的分区必须按此顺序排列section-order规则warning 级会检查这一点具体规则实现见 linter/rules/ 目录。解析器只把##H2识别为分区标题可选 H1 仅作文档标题、不参与分区解析见 parser/handler.ts 中heading.depth 2的判断。二、Brand Style先定义情绪再定义像素Brand Style是全文档的定位锚点。规范的定位是它整体描述产品的外观与感受定义品牌个性、目标受众和 UI 应唤起的情感反应是 Agent 在没有显式规则或令牌时做出高层级风格决策的基础语境。ALPINE_OBSERVATORY.md 的开篇即是一个教科书级的示例——它把整套设计系统浓缩成一个可执行的概念Scientific Alpinism科学登山水准——tactile, historic materials与cold, celestial data的混合体。UI 要唤起 The Sublime敬畏与危险交织的崇高感采用Modern-Tactile路径信息被当作制图师桌上的文物、或透过黄铜六分仪看到的遥测数据明确要求avoid all modern softness。这一节的价值在于它给 Agent 提供了散文级的过滤网。当某个组件没有对应的令牌规定时Agent 可以回溯这段品牌描述自行推断这个设计不会用圆角、不会用柔光阴影——这正是 DESIGN.md 让视觉身份在 Agent 之间持久、结构化传承的核心机制。三、Colors四个隐喻撑起一整张色板Colors 分区把颜色角色提炼为四个叙事性隐喻与 frontmatter 中的令牌一一对应The Void虚空surface: #0a1325、background: #0a1325等深观测蓝作为高海拔大气的无限背景——对应整组surface-*/background令牌The Lens透镜Parchment 羊皮纸高对比阅读表面模仿早期探险的手绘地图——对应primary: #f6bb81、on-primary: #4a2800等黄铜/羊皮色系The Instrument仪器Antique Brass 古董黄铜仅用于交互元素与关键焦点代表导航的实体工具——对应surface-tint: #f6bb81与primary家族The Hardware硬件Glacial Steel 冰川钢提供结构框架是观察者与环境之间那条细而冷的线——对应secondary: #c9c6c1、outline: #9d8e81等中性金属色。正文还给出了一条关键使用规则Use parchment sparingly for primary content containers to create a magnified effect against the dark canvas——羊皮纸色要克制使用只在主要内容容器上制造放大镜效果。从实现层面看颜色值的解析与归一化由 linter/model/color-parser.ts 承担。这里 48 个颜色令牌全部是 Material Design 风格的角色命名surface-container-lowest、on-primary-fixed-variant等这也印证了规范中token 命名约定可自由选择只需保持一致的说法examples/atmospheric-glass/design_tokens.json 展示了同一套角色体系导出为 DTCG 格式后的样子。四、Typography三种字体承担三种叙事身份Typography 分区展示了字体即叙事的设计手法把排版令牌与角色绑定Primary MarkingsMarcellusheading-display48px/400/1.1/0.02em与heading-section24px/400/1.3/0.05em——古典权威感与历史永恒感The JournalNewsreaderbody-journal18px/400/1.6——作为 EB Garamond 风格的代理字体服务远征日志与高山勘察的长文阅读要求literary and intentionalThe TelemetryIBM Plex Monotelemetry-data12px/500/1.5/0.15em与telemetry-label10px/400/1.2/0.2em——机器的声音必须大写 宽字距模拟黄铜设备上的蚀刻标签或气压计打印输出用于导航、坐标和元数据。三个字体族恰好覆盖 docs/spec.md 中推荐的语义命名headline、body、label且letterSpacing从 0.02em 到 0.2em 的递进本身就是叙事权重的量化表达。规范还支持fontFeature映射font-feature-settings与fontVariation映射font-variation-settings两个高级字段本示例未使用但属于 Schema 的合法成员。五、Layout SpacingFixed Grid 与 4px 数学节奏Layout 分区定义了Fixed Grid哲学——灵感来自工程制图纸刚性面板布局由刚性面板组成面板间强制1rem gapfrontmatter 中的panel-gap: 1rem让每个模块都像套装中的独立仪器1px 冰川钢边框强化结构对应outline/secondary色系对称优先模仿望远镜的对称透镜留白不是用于呼吸感而是用于隔离数据点如同星图隔离天体对齐必须严格数学化不允许圆角破坏几何。对应到 spacing 令牌spacing: panel-gap: 1rem # 面板间距正文中强制 1rem gap的令牌化 margin-edge: 2rem # 页面边缘边距 gutter: 1rem # 栅格沟槽 unit: 4px # 基础栅格单位注意 docs/spec.md 明确 spacing 的值可以是 Dimension 或无单位数字如列数、比例所以类似grid-columns: 5这样的无单位值也在 Schema 范围内当解析器遇到非标准值时会按Consumer Behavior表格以字符串存储而不报错。六、Elevation Depth不用阴影用色调分层 结构框定Elevation 分区展示了扁平设计传达层级的标准替代方案这正是规范中for flat designs, this section explains the alternative methods所要求的Tonal Layering色调分层全局画布是最深层级The Void信息面板The Lens作为平坦、无抬升的表面置于其上十字准星交点在 1px 边框交汇处指示层级1px 内嵌inset暗示玻璃被装进镜框零环境阴影系统的光是二元的——要么被黄铜强调色照亮要么留在背景的冷钢色中。这与同仓库的另一份示例 packages/cli/src/linter/fixtures/DESIGN-test.mdPacific Mint Dental形成鲜明对比后者使用 Ambient Shadows 与 Tonal Layers 三级阴影体系。两个 fixture 放在一起恰好演示了同一格式如何承载截然不同的深度策略。七、Shapes0px 圆角不是妥协是风格声明Shapes 分区规定Linear and Sharp形状语言所有组件从按钮到大容器强制0px 圆角传达精确、危险、高海拔环境的毫不妥协。装饰元素被限制为 45 度切角chamfers与罗盘风格图标。这里有一个重要的格式事实ALPINE_OBSERVATORY.md没有定义rounded令牌组——这不是遗漏而是 DESIGN.md 格式的合法状态。若设计系统确实不需要圆角令牌可用omitted字段显式声明并附理由从而抑制missing-sections规则的提示见 docs/spec.md 的omitted定义支持字符串或{section, reason}对象两种形式omitted: - section: rounded reason: No rounded corners defined in brand book八、Components六类组件如何就地取材Components 分区把前文的颜色、排版、形状规则组装为可操作的原子组件规范也鼓励按领域自定义组件docs/spec.md 列出 Buttons、Chips、Lists、Tooltips、Checkboxes、Radio、Input fields 等常见类型Action Orreries按钮矩形 0px 圆角默认态为 1px Navy 边框 透明背景hover 时背景填充 Antique Brassprimary: #f6bb81文字转为 Navy——与 Colors 分区黄铜只用于交互的规则严格自洽The Ledger列表行间用 1px Glacial Steel 分隔线每行以 Telemetry 风格时间戳或坐标开头——直接调用 Typography 分区的等宽字体规则The Sextant输入框仅下划线或全框 Glacial Steelfocus 态边框转 Antique Brass并在右上角出现小型十字准星图标Specimen Cards羊皮纸Parchment背景容器1px Steel 边框四角常带经纬度遥测文本框定内容——呼应羊皮纸克制使用的规则Navigation顶级导航居中、IBM Plex Mono 宽字距激活链接用 1px Antique Brass 下划线Celestial Markers主区块四角使用细加号作为 UI 透镜的注册标记。从 Schema 角度看组件还可以用components令牌组精确建模docs/spec.md 的mapstring, mapstring, string通过{colors.primary}引用语法指向既有令牌并通过button-primary-hover这类关联键表达 hover/active 变体。ALPINE_OBSERVATORY.md 以散文描述组件而 README.md 中的components.button-primary示例展示了令牌化写法——两种方式都在格式覆盖范围内。九、让 Agent 读懂并验证这份文档lint / diff / export9.1 校验lint将 ALPINE_OBSERVATORY.md 交给 linter 校验会依次执行 11 条规则见 README.md 的 Linting Rules 表格核心关注点包括broken-referror{colors.primary}这类引用是否指向真实存在的令牌missing-primarywarning定义了 colors 却没有primary时Agent 会自行生成主色contrast-ratiowarning组件backgroundColor/textColor组合是否低于 WCAG AA 的 4.5:1 下限——实现见 linter/rules/contrast-ratio.ts其中const WCAG_AA_MINIMUM 4.5section-orderwarning分区是否乱序unknown-keywarningcolours:这类疑似拼错的顶层键会被捕获。npx google/design.md lint ALPINE_OBSERVATORY.md cat ALPINE_OBSERVATORY.md | npx google/design.md lint - # 支持 stdin所有命令均接受文件路径或-stdin默认输出 JSON有 error 时退出码为 1。linter 也可作为库调用见 linter/index.ts 与 linter/runner.tsimport { lint } from google/design.md/linter; const report lint(markdownString); console.log(report.findings); // Finding[] console.log(report.summary); // { errors, warnings, info } console.log(report.designSystem); // ParsedDesignSystemState9.2 对比diff追踪设计系统演进时用diff比较两版文档输出令牌级增删改与散文回归情况npx google/design.md diff ALPINE_OBSERVATORY.md ALPINE_OBSERVATORY-v2.md若after版本相比before出现了更多 error 或 warning回归退出码为 1。这非常适合在设计评审design review中自动把关。9.3 导出exportDESIGN.md 令牌可直接互操作到主流设计工程链路npx google/design.md export --format json-tailwind ALPINE_OBSERVATORY.md tailwind.theme.json # Tailwind v3 theme.extend npx google/design.md export --format css-tailwind ALPINE_OBSERVATORY.md theme.css # Tailwind v4 theme 块--color-*、--font-*、--radius-* 等命名空间 npx google/design.md export --format dtcg ALPINE_OBSERVATORY.md tokens.json # W3C Design Tokens Format Module后者的产物形态可参考仓库中的 examples/atmospheric-glass/design_tokens.jsonDTCG 输出会把颜色展开为{ $type: color, $value: { colorSpace: srgb, components: [...], hex: #0b1326 } }这样的结构化条目。十、从样板到规范以 ALPINE_OBSERVATORY 为模板撰写自己的 DESIGN.md综合全文一份可被 Agent 可靠消费的 DESIGN.md 应当具备四个特征ALPINE_OBSERVATORY.md 每一项都做了示范令牌先行散文补意frontmatter 给出精确数值primary: #f6bb81正文说明用途边界黄铜只用于交互分区守序可留可省出现的 H2 分区严格按 Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Dos and Donts 排列无关分区用omitted显式声明叙事自洽规则闭环Shapes 说0px 圆角Components 的按钮就写0px radiusColors 说羊皮纸克制Specimen Cards 就限定为主要内容容器——散文与令牌互相印证Agent 才不会产生歧义可验证、可互操作随时可过lint检查对比度、引用完整性、分区顺序可diff追踪变更可export接入 Tailwind / DTCG 工具链。对照同仓库的另一份 fixture packages/cli/src/linter/fixtures/DESIGN-test.mdPacific Mint Dental暖色系 圆角 阴影的Clinical Serenity可以更直观地看到同一套格式既能承载高山天文台的冷峻几何也能承载牙科诊所的柔和圆润——这正是 DESIGN.md human-readable, open-format 设计哲学的最好注脚。在你自己的项目中把 ALPINE_OBSERVATORY.md 当作脚手架替换为你的品牌色、字体与组件规则再用npx google/design.md lint验证一遍即可得到一份 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
