Test System【免费下载链接】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.mdColorscolors: primary: #647D66OverviewDescription here.它暴露了四个典型问题几乎覆盖了新手编写 DESIGN.md 的全部常见误区。 ### 1. 章节顺序颠倒核心问题 按照 [docs/spec.md](https://link.gitcode.com/i/c626a9da39696b912884e01fc360068a) 定义的 Section Order规范顺序为 1. **Overview**亦写作 Brand Style 2. **Colors** 3. **Typography** 4. **Layout**亦写作 Layout Spacing 5. **Elevation Depth**亦写作 Elevation 6. **Shapes** 7. **Components** 8. **Dos and Donts** 而 OUT_OF_ORDER.md 把 **Colors** 放在了 **Overview** 之前构成典型的顺序违规。 ### 2. H1 标题不参与章节解析 文件第一行是 # Test System。规范明确说明h1 标题仅用于文档标题**不会被解析为章节**。被识别的章节一律使用 h2##。所以 # Test System 不会产生任何顺序问题但也不会给 linter 提供任何有用信息——文件名 OUT_OF_ORDER.md 本身就是作者给这张考卷的注脚。 ### 3. 正文内容缺失 ## Overview 下只有一行占位文字 Description here.完全不符合 Overview 章节整体描述产品观感、品牌个性、目标受众与情感响应的定位详见 [docs/spec.md](https://link.gitcode.com/i/9e56c7c37a954ca362812b8911458c78)。 ### 4. 色板只有 primary且缺少其余规范章节 colors 只定义了 primary: #647D66虽然满足至少定义 primary的硬性要求但 [docs/spec.md](https://link.gitcode.com/i/82a77660449e31fffdf677076660593e) 建议按 primary、secondary、tertiary、neutral 的惯例命名多套色板以承担不同语义角色。同时Typography、Layout、Elevation Depth、Shapes、Components、Dos and Donts 等章节全部缺失。 ## 三、linter 如何识别顺序错误源码级原理 顺序检查由 section-order 规则实现位于 [section-order.ts](https://link.gitcode.com/i/7e2e9012c233feabde8fa9e00985bcde)。核心逻辑只有三步 1. **别名归一化**对每个已解析的章节标题调用 resolveAlias()把 Brand Style 归一为 Overview、Layout Spacing 归一为 Layout、Elevation 归一为 Elevation Depth。别名表定义在 [spec-config.yaml](https://link.gitcode.com/i/2cc69422d764a45798d9876cc4177340)并在 [spec-config.ts](https://link.gitcode.com/i/97355696353a619a41ef7f79dc24bbf6) 中被构建为 SECTION_ALIASES 映射 2. **过滤未知章节**用 ORDER_MAP由 CANONICAL_ORDER 生成的 章节名 → 序号 映射过滤掉未知章节——未知标题如 ## Iconography 会被保留但**不参与**顺序判定这与 [docs/spec.md](https://link.gitcode.com/i/58561875e1d1d0bc703c979fef0c5dcc) 中Unknown section heading → Preserve; do not error的消费者行为一致 3. **扫描相邻逆序对**遍历归一化后的已知章节序列一旦发现 currentIdx nextIdx当前章节在规范中的序号大于后一个章节立即产出一条 warningSection Colors appears before Overview, which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation Depth, Shapes, Components, Dos and Dontssection-order 的严重级别是 **warning**见 [section-order.ts](https://link.gitcode.com/i/d36de9739805ecd83e401fa6ac963459)意味着它不会阻断流程但会明确提示作者修正。 该规则的测试用例 [section-order.test.ts](https://link.gitcode.com/i/9a0199c2be99e1e6bba558f309724abe) 覆盖了多种场景其中与我们这个反面教材完全对应的是 ts it(should warn when sections are out of order, () { const state { sections: [Colors, Overview], // Out of order! } as unknown as DesignSystemState; const findings sectionOrder(state); expect(findings.length).toBe(1); expect(findings[0]!.message).toContain(out of order); });其它关键行为同样有测试背书未知章节被忽略[Overview, Unknown, Colors]不告警、别名章节正确归一、别名与规范名混用[Brand Style, Colors, Typography, Layout Spacing, ...]不告警。换言之OUT_OF_ORDER.md 就是[Colors, Overview]这个最小复现案例的真实文件版。四、修复示范把 OUT_OF_ORDER.md 改写成合规文档现在我们把反面教材改造成一份合规的 DESIGN.md。改造要点章节顺序归位、补全 Overview 正文、按需补充令牌与章节。步骤 1修正章节顺序把## Overview移到最前## Colors紧随其后。步骤 2补全 frontmatter--- version: alpha name: Test System colors: primary: #647D66 secondary: #A8B5A2 tertiary: #B8422E neutral: #F7F5F2 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 spacing: base: 16px sm: 8px md: 16px lg: 32px rounded: sm: 4px md: 8px full: 9999px ---字段说明依据 docs/spec.mdversion可选当前版本为alphacolorsmapstring, ColorColor 支持 Hex、命名色、rgb()/hsl()/hwb()等函数式写法乃至oklch()宽色域写法内部统一转 sRGB 做 WCAG 对比度校验typographymapstring, TypographyfontSize使用 Dimension单位限px/em/remlineHeight可接受1.6这样的无单位倍数推荐做法fontWeight用数字或字符串数字均可spacingmapstring, Dimension | number数值可表示列数、比例等无单位语义roundedmapstring, Dimensionfull常用于完整圆角如9999px。步骤 3补全正文章节# Test System ## Overview A test design system that prioritizes legibility and calm. It pairs a deep forest green with warm neutrals to feel grounded, professional, and approachable — suitable for documentation-heavy products. ## Colors The palette is rooted in a single evocative accent. - **Primary (#647D66):** A muted forest green used for headlines, primary actions, and key highlights. - **Secondary (#A8B5A2):** A sage tone for borders, captions, and metadata. - **Tertiary (#B8422E):** A restrained earthy red reserved for critical alerts. - **Neutral (#F7F5F2):** A warm limestone foundation for page backgrounds. ## Typography Headlines use **Public Sans** Semi-Bold (600) at 48px for an institutional, trustworthy voice; body copy uses Public Sans Regular (400) at 16px with a 1.6 line height for long-form readability. ## Layout A strict 8px spacing scale maintains a consistent rhythm, with 16px as the base unit. Components are grouped in cards with 24px internal padding. ## Elevation Depth Depth is achieved through tonal layering rather than heavy shadows: content sits on white cards against the warm limestone background. ## Shapes Interactive elements and containers use a minimal **4px corner radius** for a modern yet restrained feel; pills and tags may use full rounding. ## Components - **Buttons:** button-primary uses the primary green background with rounded.md, 12px padding, and hover state referencing colors.primary at a lighter step. - **Lists:** 1px dividers in secondary. ## Dos and Donts - Do use the primary color only for the single most important action per screen - Dont mix rounded and sharp corners in the same view - Do maintain WCAG AA contrast ratios (4.5:1 for normal text) - Dont use more than two font weights on a single screen修正后8 个章节全部就位且顺序合规frontmatter 令牌与正文散文一一呼应正是 docs/spec.md 所描述的令牌是规范值、散文提供应用上下文的理想形态。五、linter 相关机制不止于顺序检查OUT_OF_ORDER.md 还关联到 linter 的其它规则。了解这些机制能让你在撰写 DESIGN.md 时主动避开更多雷区。完整规则集linter 的默认规则集定义在 rules/index.ts共 11 条规则按序执行规则严重级别职责broken-referror校验{path.to.token}引用是否指向存在的令牌missing-primaryerror强制要求定义colors.primarycontrast-checkerror基于 sRGB 计算 WCAG 对比度orphaned-tokensinfo/warning发现未被正文散文引用的令牌token-summaryinfo生成令牌汇总missing-sectionsinfo提示可选章节spacing/rounded缺失会回退到 Agent 默认值missing-typographywarning提示缺少排版定义section-orderwarning章节顺序检查本文主角unknown-keywarning校验未知令牌键token-like-ignoredwarning发现形似令牌但未被解析的内容omittedinfo/warning校验omitted声明是否冗余或包含未知章节名执行引擎与分级输出所有规则通过纯函数式的 runner.ts 执行runLinter()把每条规则的RuleFinding汇总为Finding[]并按error/warning/info统计摘要preEvaluate()则把发现的问题分级为fixeserror/ improvementswarning/ suggestionsinfo三档编辑建议。OUT_OF_ORDER.md 的顺序问题会落入improvements档——它不阻塞但明确提示作者这里该修。构建管线一份配置、两处生成顺序规则的依据CANONICAL_ORDER与别名表并非硬编码而是来自 spec-config.yaml经 spec-config.ts 用 Zod 校验后惰性加载。官方文档 docs/spec.md 顶部注明其由spec.mdx spec-config.ts生成改动配置后需运行bun run spec:gen重新生成并用bun test验证 linter 与规范保持一致。六、扩展应用frontmatter 高级能力速览结合 docs/spec.md 与 spec-config.yaml以下是撰写 DESIGN.md 时值得掌握的高级能力令牌引用Token References跨令牌引用使用{path.to.token}语法例如组件令牌components: button-primary: backgroundColor: {colors.primary-60} textColor: {colors.primary-20} rounded: {rounded.md} padding: 12px button-primary-hover: backgroundColor: {colors.primary-70}多数令牌组的引用必须指向原始值如colors.primary-60不能指向组如colors但在components内允许引用复合值如{typography.label-md}。引用深度上限为 10max_reference_depth: 10令牌嵌套深度上限为 20max_token_nesting_depth: 20。显式省略omitted若某个章节如 spacing、rounded在设计体系中刻意不定义可通过omitted声明抑制缺失章节类告警并附带理由omitted: - spacing - section: rounded reason: No rounded corners defined in brand book【免费下载链接】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），仅供参考