用 DESIGN.md 构建 Paws Paths 宠物平台设计系统：从 YAML Token 到 Tailwind 与 DTCG 的完整实战

用 DESIGN.md 构建 Paws Paths 宠物平台设计系统从 YAML Token 到 Tailwind 与 DTCG 的完整实战【免费下载链接】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.mdPaws Paths 是 DESIGN.md 仓库中一个面向遛狗与宠物照护平台的示例设计系统它完整演示了如何用一份DESIGN.md文件同时承载机器可读的设计 TokenYAML frontmatter与人类可读的设计叙事Markdown 正文并派生出一份 Tailwind CSS v3 主题配置和一份符合 W3C Design Tokens Community Group 规范的design_tokens.json。读完本文你将掌握 DESIGN.md 文件的结构规范、Token 引用语法、组件变体定义方式以及如何把同一套设计语言导出为 Tailwind 配置与 DTCG 格式的完整工作流。示例全景三个文件构成一个设计系统examples/paws-and-paths/目录下提供了三个相互关联的文件它们共同描述并落地了 Paws Paths 的视觉身份文件说明DESIGN.md完整的 DESIGN.md 格式设计系统规范YAML frontmatter 承载结构化设计 TokenMarkdown 正文承载人类可读的风格指引tailwind.config.js从 DESIGN.md frontmatter 中的设计 Token 派生的 Tailwind CSS v3 主题配置覆盖颜色、排版、圆角与间距组件级 Token 被有意排除交由 Tailwind 的 utility-first 组合方式来表达组件样式design_tokens.json包含全部设计 Token含组件级 Token的 DTCG JSON 文件可与 Figma、Style Dictionary 及其它 Token 流水线互操作整套体系围绕两个核心颜色展开主色Golden Retriever橙#855300用于驱动行动与能量感辅色Sky Walk蓝#0058be用于管理任务与排期场景的冷静平衡排版统一使用 Plus Jakarta Sans营造亲切又不失高级感的品牌气质。DESIGN.md 格式速览一份文件两层内容在深入 Paws Paths 之前先明确 DESIGN.md 格式的基础约定完整规范见 docs/spec.mdYAML frontmatter位于文件开头、由上下两行---分隔的机器可读区块存放设计 Token。Token 是规范性数值normative values是 Agent 与工具必须遵循的精确值。Markdown 正文由##二级标题组织的人类可读章节解释为什么这些值存在、应该怎么用为 Agent 提供应用上下文。Token 引用语法采用{path.to.token}形式例如{colors.primary}、{typography.label-md}在components区块内允许引用复合值如整个{typography.label-md}排版对象而其它区块的引用必须指向原始值primitive value。规范定义了统一的章节顺序已出现的章节必须按下列顺序排列别名可互换Overview别名 Brand StyleColorsTypographyLayout别名 Layout SpacingElevation Depth别名 ElevationShapesComponentsDos and DontsPaws Paths 的 DESIGN.md 恰好是这一规范的一次完整、合规的落地示范——它没有 Dos and Donts 章节规范允许按需省略其余七个章节全部按序出现Markdown 正文中的小节标题直接对应规范别名体系。YAML Frontmatter结构化设计 Token 全解析Paws Paths 的 frontmatter 是整套系统的数据心脏按colors、typography、rounded、spacing、components五个区块组织与 docs/spec.md 中定义的 schema 一一对应。colorsMaterial 风格的全套色彩角色colors区块定义了 50 余个颜色 Token其命名结构明显借鉴了 Material Design 的色彩体系为 Agent 提供了远超主/辅/第三色的精细语义表面层级surface、surface-dim、surface-bright、surface-container-lowest/low/high/highest构成从纯白到浅灰蓝的完整表面阶梯用于实现色调分层Tonal Layers的纵深感。前景与反色on-surface#151c27深炭色正文、on-surface-variant、inverse-surface、inverse-on-surface保证任意底色上都有可达标的文字对比度。三原色系primary#855300金毛橙、secondary#0058be晴空蓝、tertiary#00658b青蓝各自附带-container、on-*、-fixed、-fixed-dim、on-*-fixed、on-*-fixed-variant全套变体。状态色与描边error系、outline#867461、outline-variant#d8c3ad、surface-tint#855300。值得注意的细节是surface-tint与primary同为#855300——这意味着表面色调提示色直接复用主色让阴影和色调带有品牌橙的暖意与 DESIGN.md 正文中阴影颜色掺入主色/辅色以杜绝脏灰色的指引完全吻合。typographyPlus Jakarta Sans 的八个层级typography区块定义了 8 个排版层级从展示级到小型标签覆盖完整的信息层级typography: display: fontFamily: Plus Jakarta Sans fontSize: 44px fontWeight: 800 lineHeight: 52px letterSpacing: -0.02em headline-lg: fontFamily: Plus Jakarta Sans fontSize: 32px fontWeight: 700 lineHeight: 40px letterSpacing: -0.01em headline-md: fontFamily: Plus Jakarta Sans fontSize: 24px fontWeight: 700 lineHeight: 32px title-lg: fontFamily: Plus Jakarta Sans fontSize: 20px fontWeight: 600 lineHeight: 28px body-lg: fontFamily: Plus Jakarta Sans fontSize: 18px fontWeight: 400 lineHeight: 28px body-md: fontFamily: Plus Jakarta Sans fontSize: 16px fontWeight: 400 lineHeight: 24px label-md: fontFamily: Plus Jakarta Sans fontSize: 14px fontWeight: 600 lineHeight: 20px letterSpacing: 0.01em label-sm: fontFamily: Plus Jakarta Sans fontSize: 12px fontWeight: 500 lineHeight: 16px各层级的分工清晰display与headline-*用 700/800 重字重建立标题层级body-*用 400 常规字重配合宽大的行高维持高级洁净感label-*用 500/600 半粗字重确保在按钮和小号元数据上依然清晰可辨。注意fontWeight在 YAML 中既可以是裸数字也可以是带引号的字符串如800两者等价这一点在规范中有明确说明。rounded 与 spacing圆角阶梯与 8px 间距系统圆角阶梯定义了 6 个级别注意 Tailwind 默认的DEFAULT语义被保留rounded: sm: 0.25rem DEFAULT: 0.5rem md: 0.75rem lg: 1rem xl: 1.5rem full: 9999px间距系统严格遵循 8px 节奏辅以 4px 半步为移动优先的固定网格提供支撑spacing: base: 8px xs: 4px sm: 12px md: 24px lg: 40px xl: 64px gutter: 16px margin: 24px正文中Spacing is strictly based on an 8px scale与这里的数值一一对应gutter16px栏间距、margin24px页边距直接服务于正文所述的 4 列固定网格布局模型。componentsToken 引用驱动组件原子components区块是 DESIGN.md 最具特色的部分——它用 Token 引用把原始设计 Token 组合成语义化的组件级 Tokencomponents: button-primary: backgroundColor: {colors.primary} textColor: {colors.on-primary} typography: {typography.label-md} rounded: {rounded.lg} padding: {spacing.md} button-primary-hover: backgroundColor: {colors.primary-container} textColor: {colors.on-primary-container} card-profile: backgroundColor: {colors.surface-container-lowest} rounded: {rounded.xl} padding: {spacing.md} card-walk-stat: backgroundColor: {colors.secondary-container} textColor: {colors.on-secondary-container} rounded: {rounded.md} padding: {spacing.sm} input-field: backgroundColor: {colors.surface-container-low} textColor: {colors.on-surface} typography: {typography.body-md} rounded: {rounded.DEFAULT} padding: {spacing.sm} list-item-walker: backgroundColor: transparent padding: {spacing.sm} rounded: {rounded.md} list-item-walker-hover: backgroundColor: {colors.surface-container-high} badge-status: backgroundColor: {colors.tertiary-container} textColor: {colors.on-tertiary-container} typography: {typography.label-sm} rounded: {rounded.full} padding: {spacing.xs}这个片段示范了 DESIGN.md 组件定义的三个关键机制跨区块引用backgroundColor: {colors.primary}、rounded: {rounded.lg}、padding: {spacing.md}分别引用颜色、圆角、间距三个独立 Token 分组typography: {typography.label-md}则直接引用整个排版对象复合引用仅 components 区块允许。变体Variants命名约定button-primary与button-primary-hover、list-item-walker与list-item-walker-hover用带后缀的相关键名表达 hover 状态。规范明确说明Agent 会考虑全部变体并做出恰当的样式决策。字面量兜底list-item-walker的backgroundColor: transparent直接使用字面量而非引用证明组件属性值既可以是 Token 引用、也可以是原始值。组件属性本身也是受约束的 Token 集合backgroundColor、textColor、typography、rounded、padding、size、height、width。Markdown 正文设计叙事如何引导 Agent 的创造性决策frontmatter 提供精确数值而正文负责讲清楚为什么。Paws Paths 的正文严格遵循规范章节顺序每一节都为 Agent 提供可执行的风格指引。Brand Style品牌人格的锚点正文开篇将品牌定义为公园散步的愉悦能量与专业高级服务的可靠性之间的平衡人格是乐观、可信、积极的。风格定调为Modern Corporate现代企业风 亲和的人本化变体干净的版式、充足的留白以降低忙碌宠物主人的认知负荷界面轻盈透气用柔和阴影与色调变化替代厚重边框营造best-in-class的数字环境。这段叙事之所以重要是因为按照 PHILOSOPHY.md 的理念生成的视觉质量更多取决于意图描述的清晰程度而非数值的精确程度——一个具体的参照Modern Corporate 的友好变体比一堆形容词更能锚定 Agent 的设计决策。Colors语义角色分配正文为颜色赋予明确的语义角色Primary主操作、激活态与高亮Secondary次级信息、信任指示与导航点缀Neutral用于背景与边框的柔和灰色系营造高级感Deep Charcoal即on-surface的#151c27所有正文文本确保高可读性与扎实专业的观感。Typography / Layout Spacing / Elevation Depth / ShapesTypographyPlus Jakarta Sans 以其友好圆润的字形端点和出色的易读性入选比标准的几何无衬线字体更亲切Headlines 用粗字重建立层级Body 用宽行高维持高级洁净感Labels 用中等/半粗字重保持小字号下的辨识度。Layout Spacing移动优先的Fixed Grid模型手持设备使用 4 列网格留白遵循慷慨哲学区块纵向分隔使用lg40px与xl64px间距大屏内容居中并设最大宽度让用户旅程Paths保持聚焦与有意图。Elevation Depth采用Ambient Shadows环境阴影与Tonal Layers色调分层定义垂直层次。主背景用最浅的中性色阶可交互卡片坐在纯白表面上阴影高度弥散柔和Blur 20–40pxOpacity 4–8%并在阴影色中混入主色橙或辅色蓝以杜绝脏灰观感元素在 hover/tap 时轻微抬升、扩大阴影以提供触觉反馈。ShapesRounded圆角语言呼应宠物柔和的特征主 CTA 按钮用12pxrounded-lg圆角宠物档案卡与遛狗人卡片用1.5remrounded-xl表单输入框用0.5rem图标采用圆头圆角以与整体结构元素和谐。Components三种组件的落地规范Buttons Inputs按钮用rounded-lg显扎实友好表单字段用更小的DEFAULT圆角保持结构对齐所有交互状态使用 150ms ease-in-out 过渡。Cards Elevationcard-profile是英雄容器rounded-xl配合带色调的环境阴影在surface背景上呈现抬升效果card-walk-stat用于蓝色辅色系中的高对比数据可视化。Lists Navigation列表项保持宽大的触控目标hover 使用surface-container-high提供清晰无噪的反馈badge-status用于宠物可用性或遛狗进度指示确保小字号排版依然清晰易读。tailwind.config.jsToken 到 Tailwind v3 主题的机械映射tailwind.config.js 是 frontmatter 的直接机械派生全部内容落在theme.extend中colors50 余个颜色 Token 原样映射为 Tailwind 颜色键surface: #f9f9ff、primary: #855300等与 DESIGN.md frontmatter 一一对应fontFamily8 个排版层级的fontFamily均映射为[Plus Jakarta Sans]fontSize每个排版层级映射为[size, { lineHeight, letterSpacing, fontWeight }]的 Tailwind v4 风格元组写法例如display: [44px, { lineHeight: 52px, letterSpacing: -0.02em, fontWeight: 800 }]borderRadius6 级圆角阶梯保留DEFAULT键DEFAULT: 0.5remspacing8 个间距键base: 8px、xs: 4px等。README 明确指出组件级 Token 被有意排除Tailwind 的 utility-first 理念主张通过基础原子颜色、字号、圆角、间距的组合来表达组件样式而非在配置中硬编码组件类。这意味着components.button-primary在 Tailwind 侧应表达为bg-primary text-on-primary rounded-lg p-md text-label-md之类的类组合。design_tokens.jsonDTCG 互操作格式design_tokens.json 是同一套 Token 的 DTCGDesign Tokens Community Group序列化与 Figma、Style Dictionary 等工具链直接兼容。与 DESIGN.md 的 YAML 简化写法不同DTCG 采用显式的类型化结构每个 Token 携带$type声明$type: color、$type: typography、$type: dimension、$type: string颜色值以$value对象同时给出 sRGBcomponents数组0–1 归一化与hex字符串例如surface为[0.976, 0.976, 1.0]与#f9f9ff尺寸dimension以{ value, unit }结构表达例如spacing.base为{ value: 8, unit: px }rounded.lg为{ value: 1, unit: rem }组件级 Token 也被完整保留且同样使用{colors.primary}形式的引用语法list-item-walker的透明背景被序列化为带alpha: 0的 sRGB 颜色对象full圆角被序列化为{ value: 9999, unit: px }。这份文件说明同一个 Token 源可以同时产出面向 Agent 的轻量 YAMLDESIGN.md frontmatter和面向设计工具的完整 DTCG JSON两者内容完全一致、不产生信息损耗。验证与落地让 Agent 和工具消费这套设计系统用 lint 校验规范一致性设计系统写好后可以用仓库提供的 CLI 校验参见 README.mdnpx google/design.md lint examples/paws-and-paths/DESIGN.mdlinter 会运行一系列规则并输出结构化 JSON。与 Paws Paths 最相关的两类检查contrast-ratiowarning检查组件backgroundColor/textColor组合的 WCAG 对比度是否低于 AA 最低 4.5:1。实现位于 contrast-ratio.ts它会遍历每个组件、解析出背景与文字颜色、调用contrastRatio()计算并比对WCAG_AA_MINIMUM 4.5。例如button-primary的白色文字on-primary落在#855300上的对比度远高于阈值可放心通过。section-orderwarning检查章节是否按规范定义的规范顺序出现。实现位于 section-order.ts它通过resolveAlias将Brand Style、Layout Spacing、Elevation等别名解析为规范章节名再按CANONICAL_ORDER逐一比对。对比度计算的前提是颜色解析。linter 的 color-parser.ts 支持解析 hex含 3/4/6/8 位、CSS 命名色、rgb()/hsl()/hwb()、lab()/lch()/oklab()/oklch()以及color-mix(in srgb, ...)混合并统一换算为 sRGB 后计算 WCAG 相对亮度。这也印证了规范中所有颜色值内部都会转换为 sRGB 进行 WCAG 对比度检查原始格式保留用于展示与导出的约定。用 export 派生 Tailwind 与 DTCG如需重新生成配套文件可使用 export 命令# 导出 Tailwind v3 theme.extend JSON npx google/design.md export --format json-tailwind examples/paws-and-paths/DESIGN.md tailwind.theme.json # 导出 DTCG tokens.json npx google/design.md export --format dtcg examples/paws-and-paths/DESIGN.md tokens.json这也解释了仓库为何同时维护三份冗余文件DESIGN.md 是唯一事实源single source of truthTailwind 配置与 DTCG JSON 是其派生产物供不同消费端前端构建、设计工具链使用。小结从一份文档到多端消费的完整闭环Paws Paths 示例展示了 DESIGN.md 格式的完整工作流YAML frontmatter 用类型化 Token 锁定精确数值 → Markdown 正文用品牌叙事锚定风格意图 → 组件 Token 用引用语法把原始 Token 组合成语义单元 → 通过导出管线派生出 Tailwind 配置与 DTCG JSON → 由 linter 校验结构顺序、引用完整性与 WCAG 对比度。对于任何希望让编码 Agent 持久、结构化地理解自身设计系统的团队这份示例都是一份可复制、可对照规范逐行研读的参考实现——可以在此基础上继续探索仓库中的 atmospheric-glass 与 totality-festival 两个风格迥异的示例观察同一格式如何承载截然不同的视觉语言。【免费下载链接】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），仅供参考