用 DESIGN.md 打造「制图师图鉴」深色编辑社论风设计系统：完整范例与源码级拆解

用 DESIGN.md 打造「制图师图鉴」深色编辑社论风设计系统完整范例与源码级拆解【免费下载链接】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 Cartographers Atlas制图师图鉴是本仓库packages/cli中一个完整的 DESIGN.md 示例文档它用 YAML 设计 token 与 Markdown 说明正文的双层结构完整描述了一套「18 世纪航海制图 × 21 世纪数据可视化」的高端深色编辑社论风设计系统。本文以该文档为骨架逐字段解析其 frontmatter 与八个正文章节的写法并结合解析器、模型校验、lint 规则与多格式导出源码说明这份文档从「设计描述」到「可被 Agent 执行的规范」的完整链路。读完你将掌握如何用 DESIGN.md 结构化的颜色/字体/间距 token 承载设计决策如何用 prose 传达品牌气质以及如何用lint/export命令验证并转换这套设计系统。一、这是什么一个被当作「验收样例」的完整设计系统The Cartographers Atlas位于 packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md是 linter 测试目录下的一组 fixture 之一。同目录还包含DESIGN-test.md、ALPINE_OBSERVATORY.md、HERITAGE.md等其他样例见 fixtures 目录它们共同构成了 DESIGN.md 格式的「真实世界样本集」——每份文档都必须能被 lint.ts 正常解析、建模、校验并导出。这份文档的目标很清晰建立一套连接 18 世纪海事导航与当代数据可视化的高端编辑氛围。品牌人格被定义为「权威、神秘、精确」authoritative, mysterious, precise目标受众是学者、分析师与长文数字叙事的爱好者。其风格是Minimalism极简主义与 Modern Editorial现代社论的混合体——依靠纪念碑式的排版和极端的明暗对比而非装饰性修饰。原文档用一句极富画面感的话定义了审美响应「如同在昏暗的书房里展开一张厚重的稀有纸地图安静、克制、广袤。」从格式规范docs/spec.md看任何 DESIGN.md 都由两部分组成可选的 YAML frontmatter——机器可读的设计 token---定界符包裹Markdown 正文——按规范顺序排列的##章节提供人类可读的设计理由与使用指引。token 是规范性数值normative valuesprose 则提供「为什么这样设计」的上下文。这正是「制图师图鉴」同时写好两者的原因它有 40 个颜色 token、7 个文字层级和 4 个间距 token 支撑精确实现又有 8 个章节解释每个决策背后的制图学隐喻。二、YAML Frontmatter 逐块拆解2.1 顶层结构name 与四类 token 组frontmatter 位于 CARTOGRAPHERS_ATLAS.md 第 1-99 行顶层键遵循 parser/spec.ts 中定义的 SCHEMA_KEYSversion、name、description、omitted、colors、typography、rounded、spacing、componentsname: The Cartographers Atlas colors: { ... } # 40 个颜色 token typography: { ... } # 7 个文字层级 spacing: { ... } # 4 个间距 token注意此文档没有声明version当前格式版本为alpha见 spec-config.yaml也没有rounded与components组——这不是遗漏而是与正文「Shapes 严格 0px 圆角」「组件以 prose 描述」的决策自洽。从 ModelHandler 的建模逻辑看缺失的组会以空 Map 进入模型随后由 lint 规则给出提示见下文第六节。2.2 colors一套 Material 3 风格的深色表面系统colors 组是这份文档信息密度最高的部分采用surface/on-surface/primary-container等语义化命名类似 Material Design 3 的 tonal palette 思路完整列表如下分组Token表面层级surface: #0f131c、surface-dim: #0f131c、surface-bright: #353942、surface-container-lowest: #0a0e16、surface-container-low: #181c24、surface-container: #1c2028、surface-container-high: #262a33、surface-container-highest: #31353e表面文字on-surface: #dfe2ee、on-surface-variant: #c7c6cc反转色inverse-surface: #dfe2ee、inverse-on-surface: #2c3039描边outline: #909096、outline-variant: #46464c主色系surface-tint: #c3c6d7、primary: #c3c6d7、on-primary: #2c303d、primary-container: #0a0e1a、on-primary-container: #777b8a、inverse-primary: #5a5e6d次色系secondary: #b9c8dc、on-secondary: #233241、secondary-container: #3c4a5b、on-secondary-container: #abbacd强调色tertiary: #ecc246、on-tertiary: #3d2e00、tertiary-container: #150e00、on-tertiary-container: #987700错误色error: #ffb4ab、on-error: #690005、error-container: #93000a、on-error-container: #ffdad6fixed 变体primary-fixed: #dfe2f3、primary-fixed-dim: #c3c6d7、on-primary-fixed: #171b28、on-primary-fixed-variant: #434654以及secondary-fixed*、tertiary-fixed*各四枚背景background: #0f131c、on-background: #dfe2ee、surface-variant: #31353e从实现层面看这些 token 会被 color-parser.ts 解析它支持#RGB、#RGBA、#RRGGBB、#RRGGBBAA十六进制、CSS 命名色、rgb()/rgba()/hsl()/hsla()/hwb()、宽色域oklch()/oklab()/lch()/lab()以及color-mix()并统一换算为 sRGB 计算 WCAG 相对亮度luminance用于后续对比度校验parseCssColor 入口。规范建议默认使用#RRGGBB简写本文档全部采用该格式是规范推荐写法的直接示范。与正文 Colors 章节的四角色调对照见第四节prose 中的Neutral / Primary / Secondary / Tertiary是叙事层概念而 frontmatter 中的 token 是精确数值层——两者通过一致的色相家族互相印证正文的#C9A227金色对应 token 层的tertiary: #ecc246这一「Compass Rose」强调色家族。2.3 typography三种字体的七级文字系统typography 组定义了 7 个文字层级构成「字体 × 字号 × 字重 × 行高 × 字距」的完整矩阵TokenfontFamilyfontSizefontWeightlineHeightletterSpacingdisplay-heroNewsreader84px3001.10.05emheadline-xlNewsreader48px4001.20.02emheadline-mdNewsreader32px4001.30.02embody-lgManrope18px4001.70.01embody-mdManrope16px4001.70.01emlabel-capsWork Sans12px6001.00.25emcoordinateWork Sans10px4001.00.1em这些属性均在 spec-config.yaml 的 typography_properties 中定义fontFamilystring、fontSizeDimension、fontWeightnumberYAML 中裸数字或引号字符串等价、lineHeightDimension 或 unitless 数字unitless 表示 fontSize 的倍数、letterSpacingDimension以及扩展项fontFeature/fontVariation。文档中的fontWeight: 300使用带引号字符串ModelHandler 的 parseTypography 会将其安全转为数值 300。Dimension 只允许px、em、rem三种单位spec-config.yaml 的 units非法单位会被标记为 error。这里所有字号用 px、行高用 unitless 倍数、字距用 em正是规范推荐的「CSS 实践」写法。2.4 spacing四个叙事性间距 tokenspacing: unit: 4px gutter: 24px margin: 64px section-gap: 128px与常见的xs/sm/md/lg递进刻度不同这份文档用语义命名表达制图学式的宽幅节奏unit是基础单位 4pxgutter栏间距 24pxmargin页边距 64pxsection-gap章节间距高达 128px——后者直接对应正文「用巨大的纵向间距分隔叙事节拍」的设计决策。从 ModelHandler 看spacing 接受 Dimension 或 unitless 数字且宽松处理非合法维度会以字符串存储因此未来想表达「12 列」这类纯数字刻度也是允许的。三、正文章节骨架符合规范顺序的八个决策载体格式规范在 docs/spec.md 的 Sections 一节 规定所有章节使用##标题可省略但出现时必须按规范顺序排列。The Cartographers Atlas的正文第 101 行起提供了其中七个章节的示范写法顺序与规范完全一致且每个章节都践行「token 给精确值、prose 给理由」的分工。四、正文逐章解读制图学隐喻如何落到每个设计决策4.1 Brand Style品牌人格的「总开关」「Brand Style」是规范中 Overview 章节的别名spec-config.yaml 的 sections 定义。这节的职责是给出产品整体观感品牌人格、目标受众、UI 应唤起的情感反应。文档在此明确了三层信息风格定位Minimalism × Modern Editorial 的混合审美隐喻「昏暗书房中展开的厚重纸地图」情感目标quiet安静、intentional克制、vast广袤。规范指出docs/spec.md Overview 章节当某条具体规则或 token 未定义时Agent 会依靠本节做高层风格决策——所以它是 Agent 生成 UI 时的「默认裁判」。4.2 ColorsObsidian Canvas 与四角色调正文 Colors 章节第 107-114 行把整套 token 归纳为四个叙事角色Neutral#080C14主背景 / 虚空提供无限深度Primary#0A0E1A结构面板、卡片与内嵌表面与 Neutral 的对比微妙制造深度而不产生生硬线条Secondary#2C3A4A极细分隔线或结构参考线仅在色调对比不足时使用必须极度克制Tertiary / Accent#C9A227UI 的「罗盘玫瑰」金色每个视图只允许出现一次——通常是主操作或唯一的数据焦点。这与规范对 Colors 章节的要求吻合至少定义primary可定义多套调色板并按primary → secondary → tertiary → neutral的顺序命名docs/spec.md Colors 章节。值得注意的细节是正文给每套调色板的使用约束「每视图仅一次」「极端克制」这类语义在 token 数值里表达不了正是 prose 存在的意义。4.3 Typography排版即美学载体正文 Typography 章节第 116-122 行把「Cartographer 美学」的核心压在排版上三字体分工如下Headlines → Newsreader高对比度传统衬线display 尺寸用细字重 宽松字距营造纪念碑式的轻盈感——对应display-hero84px / 300 字重 / 0.05em与headline-*层级Body → Manrope保证可读性1.7 行高是强制值以在深色背景上维持「开放」的社论感——对应body-lg/body-mdLabels Annotations → Work Sans全大写 宽字距模仿海图上的技术坐标——对应label-caps0.25em 字距与coordinate层级。三者的组合逻辑衬线叙事 无衬线正文 等宽感标签在 frontmatter 与 prose 中互为印证是「token 与 prose 双通道描述」的教科书案例。4.4 Layout SpacingFixed Grid 与稀疏节奏Layout 章节第 124-128 行采用Fixed Grid模型在 full-bleed 画布内图片与背景面板可延伸至边缘但排版内容必须落在严格的12 列网格 宽边距内。节奏被定义为「稀疏」不鼓励高密度信息用巨大的纵向间距section-gap: 128px分隔叙事节拍——「元素应像黑暗海洋中的孤岛」。对比同目录的 DESIGN-test.mdPacific Mint Dental 牙科诊所主题会发现同一种格式如何表达不同哲学那边是「1200px 容器 8px 基础单位 24px gutter 48-64px 章节间距」的现代商业节奏这边是「64px margin 128px section-gap」的宏大叙事节奏——Layout 章节 spacing token 的组合足以让 Agent 区分「信息密集的医疗界面」与「气定神闲的编辑长文」。4.5 Elevation Depth用色调分层替代阴影Elevation 章节第 130-138 行做出了一个反直觉但高度自洽的决策整个系统没有任何阴影深度完全靠 Tonal Layering色调分层与留白实现Level 0Background#080C14基础画布Level 1Panels#0A0E1A内容块或「浮动」地图片段Level 2Interactionhover 态通过背景色轻微偏移或引入 #2C3A4A 发丝线边框。并规定「避免堆叠超过两层深度」界面应像铺在桌面上的实体地图一样平坦。规范对 Elevation 章节的要求正是「说明如何基于设计风格传达视觉层级扁平设计必须解释替代手段边框、对比度等」——本节的 Level 0/1/2 分层 发丝线边框方案正是这一要求的完整回答。4.6 Shapes0px 圆角与「切纸感」Shapes 章节第 140-142 行将形状语言严格定为Sharp尖锐按钮、卡片、输入框、图片一律0px 圆角以强化制图学的精确性与档案纸的「切纸感」。这是「用 prose 定义 Shapes、而不在 YAML 里写rounded」的典型场景。运行时缺失的rounded组会触发missing-sections规则的 info 提示「No rounded section defined. Corner rounding will fall back to agent defaults.」见 missing-sections.ts。换言之如果你想让「0px」成为强制而非 Agent 默认值应通过roundedtoken 显式声明——例如rounded: { none: 0px }或像 DESIGN-test.md 那样定义完整的sm/md/lg/full刻度。若确实想声明「不采用圆角体系」规范还提供omitted机制docs/spec.md Omitted 一节例如omitted: - section: rounded reason: 0px radius enforced by prose; no rounded scale defined in brand book4.7 Components六类组件的原子规范Components 章节第 144-151 行用 prose 定义了六类组件每一类都给出可执行的视觉规则Buttons大号矩形、0px 圆角。主 CTA 是唯一允许使用金色#C9A227背景配深色文字的元素次级按钮为透明底 细 #2C3A4A 描边——与 4.2 节「金色每视图一次」的约束闭环Cards以对背景的色调变化#0A0E1A定义除非可访问性需要否则不加边框Inputs极简下边框式或纯 Primary 色块字段标题用label-caps字体Lists宽垂直内边距的干净行索引数字用coordinate风格字体如 001、002The Compass Rose定制图标 / 导航元素是构图中唯一的金色点缀用于返回「北」首页或触发主叙事流Data Points小的尖锐方块或十字准星字形Secondary 色用于地图标注。规范允许 Components 章节以 prose 或 tokencomponents:组两种方式书写。若要用 token 形式表达同一意图组件级backgroundColor/textColor/rounded/padding等属性见 docs/spec.md Component Property Tokens 一节例如把「主按钮」精确化components: button-primary: backgroundColor: {colors.tertiary} textColor: {colors.on-tertiary} padding: 16px 32px button-secondary: backgroundColor: {colors.surface} textColor: {colors.secondary}五、从文档到模型解析与建模的源码链路要理解这份 fixture 为什么是「可执行规范」需要看它被消费的完整管道核心入口是 lint.ts解析ParserParserHandler 用 unified remark 解析 Markdown识别 frontmatter 与 fenced yaml 代码块提取所有##章节标题与内容分区。它会检测「重复顶层键」如两个colors组并报DUPLICATE_SECTION错误也会收集每个 token 的源位置sourceMap建模ModelModelHandler 分三阶段构建DesignSystemState先解析原始 token颜色、排版、圆角、间距再解析链式 token 引用{colors.primary}带环检测与最大深度限制最后构建components的属性质表所有解析都遵循「Never throws」原则异常转为 findings校验LinterrunLinter 按序执行 11 条默认规则产出按 error/warning/info 聚合的 findings导出Emitter同一模型可直接生成 Tailwind v3 / v4 主题、DTCG tokens.json 与 CSS 变量。fixture 在测试中的角色可见于 fixture.test.ts它读取DESIGN-test.md断言designSystem.name、具体 token 的 hex 值与 fontSize 单位并验证非法单位 error 数量为零——这证明 fixtures 不仅用于演示还被作为端到端验收样本持续回归。六、lint 会怎么评价这份文档11 条规则逐一对照从 rules/index.ts 的 DEFAULT_RULE_DESCRIPTORS 可见 11 条默认规则我们逐一预演「制图师图鉴」会得到什么结论规则严重度对本文档的预期结论broken-referror无components组无从触发若引入组件引用需保证{colors.tertiary}等路径可解析missing-primarywarning定义了primarytoken不触发contrast-ratiowarning无组件级backgroundColor/textColor配对不触发但若把该设计实现为 token 组件on-tertiary #3d2e00与tertiary #ecc246等高对比配对可被自动核验阈值 4.5:1见 contrast-ratio.tsorphaned-tokenswarning定义了大量颜色 token 但无组件引用会提示——这正是 prose 驱动系统的预期形态可在文档中补充说明以消除疑虑token-summaryinfo输出各组的 token 数量统计missing-sectionsinfo无spacing不已定义无rounded会提示「圆角回退到 Agent 默认值」missing-typographywarning已定义 typography不触发section-orderwarning正文顺序与规范一致不触发unknown-keywarningfrontmatter 全部键名合法不触发token-like-ignoredwarning无被忽略的 token 形态未知键不触发omitted-rulesinfo未使用omitted不触发七、实操用 CLI 验证与导出这套设计系统7.1 安装与 lint 验证仓库的 README.md 说明了安装方式本地仓库安装或npx直跑Windows 下可用designmd别名规避.md后缀与文件关联的冲突。对本仓库内的样例验证npx google/design.md lint packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md输出为 JSON含findings每条含 severity / path / message与summaryerrors / warnings / infos 计数存在 error 时退出码为 1实现见 lint.ts 命令。也可从 stdin 读取cat ... | npx google/design.md lint -。7.2 多格式导出export.ts 命令 支持五种格式全部作用于同一份解析后的设计系统模型# Tailwind v3 theme.extend JSON npx google/design.md export --format json-tailwind packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md # Tailwind v4 CSS theme 块CSS 自定义属性命名空间 npx google/design.md export --format css-tailwind packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md # W3C Design TokensDTCGtokens.json npx google/design.md export --format dtcg packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md # CSS 自定义属性可加 --prefix npx google/design.md export --format css-vars --prefix atlas packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md各发射器的映射逻辑可直接阅读源码Tailwind v3 由 tailwind/handler.ts 生成theme.extendcolors → hex、fontFamily → 字体数组、fontSize →[size, {lineHeight, letterSpacing, fontWeight}]Tailwind v4 由 tailwind/v4/serialize.ts 序列化为theme块按--color-*、--font-*、--text-*、--leading-*、--tracking-*、--font-weight-*、--radius-*、--spacing-*的固定顺序输出。7.3 diff 与 spec# 对比两版设计系统的 token 级变更与回归 npx google/design.md diff packages/cli/src/linter/fixtures/CARTOGRAPHERS_ATLAS.md packages/cli/src/linter/fixtures/DESIGN-test.md # 输出格式规范全文含 --rules 附加规则表便于注入 Agent 提示词 npx google/design.md spec八、与其他 fixture 对比同一格式、两种美学谱系将「制图师图鉴」与 DESIGN-test.mdPacific Mint Dental对照可以直观看到 DESIGN.md 的「表达带宽」维度The Cartographers AtlasPacific Mint Dental美学深色编辑社论 / 航海制图临床宁静 / 现代公司表面色#0f131c系近黑#f9f9ff系近白圆角prose 规定 0px无 rounded tokensm: 0.25rem到full: 9999px完整刻度容器12 列全出血 64px margin1200px 固定容器 8px 基础单位排版Newsreader/Manrope/Work SansManrope/Inter组件prose 描述 6 类prose 描述 5 类含签名组件 Calendar Widget两份文档均能被同一管道解析、校验、导出说明格式的「token 给数值、prose 给理由」约定不绑定任何特定设计哲学——深色扁平与浅色圆角只是同一格式的两个合法实例。九、把这份范例用于你的项目的建议先写 Brand Style再写 token品牌人格决定后续所有决策「每视图一次金色」「无阴影」「0px 圆角」这类约束必须落在 prose 里才不会被 Agent 忽略用语义化 token 名而非色板名surface-container-high比darkgray-3更能驱动实现规范在 docs/spec.md Recommended Token Names 一节 给出了非强制性的推荐命名集primary/secondary/tertiary/neutral/surface/on-surface/error等prose 约束与 token 数值双通道对齐若 prose 规定「1.7 行高是强制值」务必同步在typography.body-md.lineHeight写入1.7让 lint 与导出都拿到同一事实对「故意缺失」的组显式声明不打算定义圆角刻度或间距刻度时用omittedreason记录原因既消除missing-sections提示也让 Agent 理解这是决策而非疏漏把 fixture 当模板需要快速生成新设计系统时可以基于本文件的结构colors 全量语义组 typography 分级 spacing 语义键 章节骨架替换数值再用lint回归验证、用export落入工程配置。这份CARTOGRAPHERS_ATLAS.md完整展示了 DESIGN.md 的核心价值让一个「昏暗书房里的制图师」级审美变成 Agent 能够精确复现的持久化、结构化规范。文档在 fixtures 目录 中与解析器、模型、lint 规则、发射器共同演进既是演示样本也是格式规范的活体测试。若想深入格式本身的细节可直接阅读 docs/spec.md 与 spec-config.yaml——后者是规范生成器与 linter 共同读取的单一事实来源。【免费下载链接】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），仅供参考