深入解析 DESIGN.md 中的 Heritage 设计系统一份面向 Coding 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.mdDESIGN.md 是一种自包含、纯文本的设计系统描述格式它用YAML frontmatter 设计令牌 Markdown 正文的组合把品牌视觉身份持久化、结构化地交付给 AI Agent。本文以仓库测试夹具 packages/cli/src/linter/fixtures/HERITAGE.md 为完整案例逐段拆解Heritage运动遗产品牌设计系统——从品牌理念、色彩策略、字体体系到组件规范与 Dos/Donts 守则——并对照 格式规范文档 与 CLI 源码、测试用例说明一份合规、可被 Agent 解析与校验的 DESIGN.md 究竟应该怎么写、每个配置项承载什么语义。一、案例背景HERITAGE.md 在仓库中的定位在 CLI 的 linter 测试体系中packages/cli/src/linter/fixtures/ 目录存放了一批真实风格的 DESIGN.md 夹具HERITAGE.md 是其中之一。它们被用于验证 lint 流水线对完整文档的处理能力frontmatter 令牌的解析、Markdown 分节的识别、规则校验与结果汇总。与 DESIGN-test.md 这类被 fixture.test.ts 直接断言属性的测试夹具不同HERITAGE.md 更接近真实世界交付物的形态——它的值未必全部经过严格校验例如正文 prose 中叙述的色值与 frontmatter 令牌存在差异这恰好是理解 DESIGN.md令牌是规范值、正文提供语境这一核心原则的最佳样本。按照 docs/spec.md 的定义DESIGN.md 只包含两个部分可选的 YAML frontmatter 与 Markdown 正文。frontmatter 存放机器可读的设计令牌正文则以##二级标题组织人类可读的设计理由与使用指引。规范要求文档遵循固定的分节顺序Overview别名 Brand StyleColorsTypographyLayout别名 Layout SpacingElevation Depth别名 ElevationShapesComponentsDos and DontsHERITAGE.md 正是按这个顺序组织的完整实现下面逐节解剖。二、Brand Style先用一句话定义品牌的情绪基调HERITAGE.md 的 Overview 章节标题写作 Brand Style这样定义系统的灵魂This design system is built upon a philosophy ofArchitectural Minimalismmixed withJournalistic Gravitas. It is designed for high-performance athletic heritage brands, marathon organizers, and prestigious sporting publications.它明确锁定了三个要素品牌哲学建筑极简 × 新闻庄重、目标受众高性能运动遗产品牌、马拉松主办方、权威体育刊物、以及期望的情绪反馈平静的权威感像高端大报或当代画廊展览。UI 呈现追求哑光高级感premium matte finish回避光泽渐变与过量阴影用结构清晰与Color Stacking色彩堆叠表达层次。对照规范 docs/spec.md 的说明Overview 是产品观感的整体描述定义品牌个性、目标受众和 UI 应唤起的情感反应当没有具体规则或令牌时它作为指导 Agent 高层级风格决策的基础上下文。因此这节不是装饰性的引言而是 Agent 在规则空白处的回退依据——例如当某元素既无组件令牌也无间距规则时Agent 应回到平静权威、编辑式留白的基调做判断。三、Colors高对比中性色 单一强调色的令牌化表达HERITAGE.md 的色彩策略一句话概括高对比中性色铺底一个富有表现力的强调色驱动交互。正文 prose 定义了五张关键调色板Primary#1A1C1EDeep Ink用于标题与核心文本的深墨色提供最大可读性与恒久感Secondary#6C7278Slate用于边框、说明文字、元数据等实用元素的高级石板灰Tertiary#B8422EBoston Clay充满活力的土红色交互的唯一驱动色只用于主要操作与关键高亮Neutral#F7F5F2Limestone暖石灰底色所有页面的地基比纯白更柔和、更有机Surface#FFFFFF纯白只留给前景卡片与内容区块在暖色画布上形成堆叠的物理感。令牌才是规范值在 frontmatter 中这些语义以colors令牌组落地。注意一个关键细节prose 与令牌并不完全一致。例如正文说 Primary 是#1A1C1E而 frontmatter 中primary: #000101、primary-container: #1a1c1e正文说 Secondary 是#6C7278frontmatter 中secondary: #595f65、secondary-container: #dde3ea正文说 Tertiary 是#B8422Efrontmatter 中tertiary-container: #400300、on-tertiary-container: #db5b45。这正是 docs/spec.md 中反复强调的规则Prose may use descriptive color names (e.g., Midnight Forest Green) that correspond to systematic token names (e.g.,primary).The tokens are the normative values; the prose provides context for how to apply them. 也就是说Agent 渲染界面时以令牌为准正文只是帮助理解这个颜色为什么存在、该用在哪里。真实的交付实践中这类不一致应由 lint 流程或人工校对消除但作为教学案例它精准地演示了令牌与正文的职责分工。HERITAGE 的colors令牌组还展示了 Material Design 3 风格的完整 surface/container 体系surface-dim、surface-container-lowest/low/high/highest、inverse-surface、surface-tint、outline、outline-variant、on-primary-container、primary-fixed(-dim)等 40 余个令牌。规范允许任意合法的 CSS 颜色字符串Hex#RGB、#RRGGBB、含透明通道的#RRGGBBAA、命名色、rgb()/hsl()/hwb()等函数式写法乃至oklch()/oklab()广色域与color-mix()混色。所有颜色在内部都会被转成 sRGB 用于 WCAG 对比度计算原始格式则保留用于展示与导出。四、Typography双字体叙事——Public Sans 讲正文Space Grotesk 报数据排版策略使用两套字体承担两种截然不同的叙事职能Headlines标题Public Sans Semi-Bold字重 600树立制度化的可信声音Body正文Public Sans Regular 16px保证现代专业感与长文可读性Labels标签Space Grotesk 承担所有技术数据、时间戳与元数据。其几何结构让人联想到数字秒表或比赛计时器标签严格大写并配以宽字距以强化技术感。对应的 frontmattertypography令牌组把上述策略精确化。以h1为例typography: h1: fontFamily: Public Sans fontSize: 48px fontWeight: 600 lineHeight: 1.1 letterSpacing: -0.02em body-md: fontFamily: Public Sans fontSize: 16px fontWeight: 400 lineHeight: 1.6 label-caps: fontFamily: Space Grotesk fontSize: 12px fontWeight: 500 lineHeight: 1.0 letterSpacing: 0.1em对照规范 docs/spec.md 的 Typography 令牌 schema每个字段的含义是fontFamilystring字体族名fontSizeDimension带单位字符串合法单位是px、em、remfontWeightnumber数字字重如 400、700。YAML 中裸数字与带引号的字符串等价——fixture.test.ts 专门断言了fontWeight: 700字符串形式会被解析为数字700lineHeightDimension | number既接受24px、1.5rem这类带单位值也接受1.6这类无单位乘数推荐 CSS 实践letterSpacingDimension如-0.02em的负字距用于大标题收紧0.1em的正字距用于小号大写标签拉开呼吸感可选的fontFeature对应font-feature-settings与fontVariation对应font-variation-settings可进一步配置 OpenType 特性与可变字体轴。HERITAGE 采用9–15 级规范中偏精简的分级h1/h2/h3 body-lg/body-md label-caps/label-numeral并命名了label-numeral这类领域化层级——规范明确说明任何描述性字符串键都是合法的这正是 docs/spec.md 中未知排版令牌名应被接受为合法排版如telemetry-data所保护的扩展性。五、Layout SpacingRelaxed Fixed Grid 与 16px 基准单位布局策略被定义为Relaxed Fixed Grid内容遵循标准 12 列栅格保持结构对齐但区块间距刻意放宽以获得呼吸感。间距纪律有三条硬规则16px 基准单位决定所有 padding 与 margin垂直节奏严格按 8px 或 16px 的倍数执行视口外缘 margin 必须充足32px以强化编辑式杂志风版式。frontmatter 的spacing令牌组将这套节奏机器可读化spacing: base: 16px xs: 4px sm: 8px md: 16px lg: 32px xl: 64px gutter: 24px margin: 32px注意xs: 4px是 8px 节奏的半步这与规范中间距可含列宽、gutter、margin 等单元以及允许无单位数字如列数或比例的说明吻合。规范 docs/spec.md 的 schema 明确spacing是mapstring, Dimension | number。这里的gutter: 24px与margin: 32px是布局级的语义化令牌Agent 可以据此直接生成栅格系统而无需从正文重新推断。Linter 的 missing-sections 规则 会提示若定义了 colors 但缺少spacing或rounded段将输出 info 级提示Layout spacing will fall back to agent defaults——也就是说不写间距令牌不会报错但 Agent 会退回默认值这在跨会话的一致性上是有损的。六、Elevation Depth用色彩堆叠与描边替代阴影HERITAGE 系统明确禁绝阴影Shadows should be avoided entirely深度完全由三层结构实现Base LayerNeutral#F7F5F2石灰底作为地面Surface Layer纯白卡片直接坐在地面上Definition每个 surface 层用 1px 实线 Secondary 边框定义边界。层级关系纯粹靠石灰底 vs 纯白前景容器的对比建立以维持哑光高级质感。这套思路在规范中属于扁平设计的典型处理——docs/spec.md 明确写道如果使用 elevation需定义其样式spread、blur、color对于扁平设计本节应说明传达视觉层级的替代方法如边框、色彩对比。HERITAGE 恰好是后者它把不用阴影从一句口号落实为可执行的Color Stacking Architectural Outlines三层模型。七、Shapes4px 圆角作为建筑学纪律形状语言定义为Architectural Sharpness所有交互元素、容器、输入框统一使用最小 4px 圆角半径。理由表述得很清楚——刚好提供足够现代感的柔和度同时保持刚性、工程化的美学呼应马拉松主题的精确性。frontmatter 的rounded令牌组给出了完整圆角刻度rounded: sm: 0.125rem DEFAULT: 0.25rem md: 0.375rem lg: 0.5rem xl: 0.75rem full: 9999pxrounded在规范中是mapstring, Dimensiondocs/spec.mdDEFAULT这类键名同样合法。full: 9999px是表示胶囊形/圆形的惯用值。Dos and Donts 中Dont use pill buttons. The 4px radius is a strict rule正是对sm/DEFAULT之外的诱惑的防御——即便令牌表里存在full品牌守则依然通过正文禁止其在按钮上使用这展示了令牌提供能力、正文约束用法的配合关系。八、Components六大组件的实现细则Components 章节把品牌哲学落实到具体的原子组件。HERITAGE 定义了六类组件这里完整保留全部规格Buttons按钮主按钮为实心 Boston Clay#B8422E 白色文字4px 圆角、16px 水平内边距无阴影hover 状态将背景色轻微加深。Inputs输入框白色背景 1px Secondary 边框聚焦时边框增至 2px 并变为 Tertiary#B8422E标签采用 Space Grotesk 标签样式、置于字段上方。Cards卡片纯白 1px Secondary 边框永远不加阴影内部留白宽松24px 或 32px以维持放松的编辑感。Chips/Badges标签/徽章透明背景 1px Secondary 边框 Space Grotesk 标签用于状态展示时边框可采用 Tertiary 色。Lists列表条目之间用 1px Secondary 水平分隔线条目间保证高垂直内边距16px避免视觉拥挤。Data Displays数据展示计时与比赛成绩使用 Primary 墨色的 Space Grotesk 数字强调钟表般的精确美学。规范对 Components 的处理是有意为之的灵活components令牌组是mapstring, mapstring, string值可以是字面量也可以是{path.to.token}形式的令牌引用同一个组件可以按状态active/hover/pressed拆成button-primary、button-primary-hover等变体键。标准属性令牌包括backgroundColor、textColor、typography、rounded、padding、size、height、widthdocs/spec.md。虽然 HERITAGE 的 frontmatter 未定义components令牌组组件规则全部在正文 prose 中表达但规范允许甚至鼓励这样做例如components: button-primary: backgroundColor: {colors.primary-60} textColor: {colors.primary-20} rounded: {rounded.md} padding: 12px button-primary-hover: backgroundColor: {colors.primary-70}一旦使用了backgroundColor/textColor这样的组件属性令牌linter 的 contrast-ratio 规则 会自动计算两者的 WCAG 对比度低于 4.5:1AA 标准时输出 warning。HERITAGE 正文里Boston Clay 白字的主按钮组合正是为了天然满足这一标准而设计的——prose 中的组件细节与 linter 的自动化检查在语义上互相印证。九、Dos and Donts给 Agent 的护栏清单最后一节是可执行的守则清单作用是为 Agent 提供护栏guardrails防止在规范未覆盖的角落做出破坏品牌一致性的决定。Do应做使用不对称 margin若左边距为16 (5.5rem)可尝试右边距24 (8.5rem)营造编辑式版面凡是数据或过程感的内容一律用Space Grotesk拥抱 Limestone 的暖意纯灰#808080太冷始终使用带蓝金色调的Slate Gray#6C7278。Dont不应做禁用 100% 纯黑始终用Deep Ink#1A1C1E禁用 pill 胶囊按钮4px 圆角是维持建筑纪律的硬性规则禁用分隔线dividers需要区隔内容时加大间距令牌如从4升到6或改变背景色阶。规范 docs/spec.md 对这节的定位是实际指导与常见陷阱并给出通用示例如每个屏幕只让 primary 色用于唯一最重要的操作同一视图中不要混用圆角与锐角。HERITAGE 的三条 Dont 全部可被具体令牌或规则回放禁纯黑对应on-surface/on-background的深墨灰值禁胶囊按钮对应 4px 圆角纪律禁分隔线对应间距令牌与背景色阶的组合方案。十、从夹具到生产这份文档如何被校验与消费HERITAGE.md 完整走完了 DESIGN.md 的标准生命周期解析CLI 的 parser 将 frontmatter 按 docs/spec.md 的 schema 解析为DesignSystemStatecolors/typography/rounded/spacing/components 令牌组分节识别正文按固定的八个##标题顺序切分可容忍 Brand Style 这类别名规则校验runner.ts 依次执行默认规则集将结果聚合为findings与summaryerrors/warnings/infos 计数并可通过 preEvaluate 把发现分级为 fixeserror、improvementswarning、suggestionsinfo三档编辑建议消费导出设计令牌可双向转换为tokens.json、Figma variables 与 Tailwind theme config仓库 examples/ 下每个示例品牌都同时提供design_tokens.json与tailwind.config.js两个导出物。从仓库的 fixture 结构可以推断HERITAGE 与 ALPINE_OBSERVATORY、CARTOGRAPHERS_ATLAS、MERIDIAN、TRACKS_OF_DC 等夹具共同构成了 linter 测试矩阵覆盖不同品牌气质与令牌密度的文档形态见 packages/cli/src/linter/fixtures/。十一、小结一份合格 DESIGN.md 的可复用清单以 HERITAGE.md 为模板可以提炼出编写面向 Agent 的设计规范时的七条经验Overview 必须回答情绪基调——它是 Agent 在规则空白处唯一的决策依据令牌是规范值prose 提供语境——两者冲突时以令牌为准docs/spec.md 原文规则色彩至少定义primary并按 primary/secondary/tertiary/neutral 的惯例命名可用 Material 风格的 surface 族令牌铺满明暗层级排版用 9–15 级语义化命名display/headline/body/labellineHeight优先用无单位乘数间距、圆角即使不强制也应提供令牌否则 Agent 会退回默认值missing-sections 规则 的提示即为此而设扁平设计用层级模型 边框/对比替代阴影并把规则写进 Elevation 章节Dos and Donts 是自动化规则的语义镜像——例如白字 Boston Clay天然满足 WCAG AA 4.5:1contrast-ratio 规则 的校验目标。HERITAGE 的价值在于它同时示范了格式的完备性八个分节 四组令牌一应俱全与风格的强约束性禁阴影、禁胶囊、禁纯黑、禁分隔线是理解 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考