Test System

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.md

Colors

colors: primary: "#647D66"

Overview

Description 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. **Do's and Don'ts** 而 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、Do's and Don'ts 等章节全部缺失。 ## 三、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`（当前章节在规范中的序号大于后一个章节），立即产出一条 warning：

Section 'Colors' appears before 'Overview', which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts

`section-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.md）：

• version：可选，当前版本为alpha；
• colors：map<string, Color>，Color 支持 Hex、命名色、rgb()/hsl()/hwb()等函数式写法乃至oklch()宽色域写法；内部统一转 sRGB 做 WCAG 对比度校验；
• typography：map<string, Typography>，fontSize使用 Dimension（单位限px/em/rem），lineHeight可接受1.6这样的无单位倍数（推荐做法），fontWeight用数字或字符串数字均可；
• spacing：map<string, Dimension | number>，数值可表示列数、比例等无单位语义；
• rounded：map<string, Dimension>，full常用于完整圆角（如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`. ## Do's and Don'ts - Do use the primary color only for the single most important action per screen - Don't mix rounded and sharp corners in the same view - Do maintain WCAG AA contrast ratios (4.5:1 for normal text) - Don't 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 条规则，按序执行：

执行引擎与分级输出

所有规则通过纯函数式的 runner.ts 执行：runLinter()把每条规则的RuleFinding汇总为Finding[]，并按error/warning/info统计摘要；preEvaluate()则把发现的问题分级为fixes（error）/ improvements（warning）/ suggestions（info）三档编辑建议。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}）。引用深度上限为 10（max_reference_depth: 10），令牌嵌套深度上限为 20（max_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