DESIGN.md spec-config.yaml：spec-as-code如何生成官方规范文档

DESIGN.md spec-config.yamlspec-as-code如何生成官方规范文档【免费下载链接】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 是一个面向编码智能体的视觉设计规范格式。它的官方规范文档 docs/spec.md 并不是手写维护的而是由 spec-config.yaml 这份唯一事实来源配置文件通过 spec-as-code 流水线自动生成的。这篇文章带你读懂这套机制。为什么需要 spec-as-code DESIGN.md 规范本身定义了一套描述设计系统的格式YAML 前置元数据里放机器可读的设计令牌颜色、字体、间距正文用 Markdown 写设计理由。规范里有一批容易变化的内容章节的合法顺序与别名如Overview也叫Brand Style字体的合法属性fontFamily、fontSize等 7 项组件子令牌的合法键backgroundColor、rounded等 8 项颜色角色、推荐令牌名、示例值如果这些内容一边写在文档里、一边写在校验代码里两边迟早不一致。spec-as-code 的思路是把规范本身也变成代码让文档从数据中生成。唯一事实来源spec-config.yaml spec-config.yaml 位于packages/cli/src/linter/目录文件开头就写着This file is thesingle source of truthfor the DESIGN.md format specification.它用纯 YAML 声明了规范的全部参数新手也能一眼读懂version: alpha units: - px - em - rem sections: - canonical: Overview aliases: - Brand Style - canonical: Colors - canonical: Typography # ... 共 8 个章节 color_roles: - primary - secondary - tertiary - neutral想改规范官方流程只有三步见 spec-config.ts 头部注释编辑spec-config.yaml运行bun run spec:gen重新生成 docs/spec.md运行bun test验证 linter 与新配置对齐加载逻辑在 spec-config.ts 中用 zod 对 YAML 做严格校验并做懒加载缓存保证配置文件只被读取一次。生成流程spec.mdx 模板 配置 官方文档 真正执行生成的是 spec-gen 模块由三个文件协作文件角色spec.mdx规范文档的 MDX 模板负责骨架与叙述spec-config.yaml规范参数数据负责事实generate.ts编译器入口把两者合成 docs/spec.md流程非常直接spec-config.yaml ──► spec-config.ts校验 缓存 │ spec.mdx模板───────────► generate.ts 编译 MDX │ ▼ docs/spec.md官方规范模板里不写死任何数据而是调用注入的渲染函数。比如 spec.mdx 中的{sectionOrderList()}、{colorsExample()}、{typographyPropertyList()}等占位调用。这些函数定义在 renderers.ts 里本质是配置数据 → Markdown 片段的纯函数例如colorsExample()就是把examples.colors渲染成一段 YAML 代码块。生成结果 docs/spec.md 的开头带有自动生成标记防止有人误改!-- Generated from spec.mdx spec-config.ts | version: alpha -- !-- Do not edit directly. Run bun run spec:gen to regenerate. --最快运行与校验方法 在 packages/cli 目录下只需一条命令即可重新生成bun run spec:gen如果想验证文档是否过期比如 CI 场景加--check参数bun run src/linter/spec-gen/generate.ts --check--check模式不写文件而是把现有文档与重新生成的内容逐行比对一致则打印docs/spec.md is up to date.不一致则报告第一处差异的行号并以非零码退出——这对文档忘记重新生成的提交非常友好。另外CLI 的spec命令实现见 commands/spec.ts也能直接输出这份规范npx google/design.md spec支持--rules追加 lint 规则表、--format json输出 JSON方便把规范上下文注入 AI 智能体的提示词。一份配置两处消费linter 也读同一份数据 ✅这套机制最妙的地方在于linter 不是照着文档实现而是和文档读同一份配置。spec-config.ts 把 YAML 展开为一组常量导出供两条管线共享文档管线SPEC_VERSION、EXAMPLES、PRIMITIVE_TYPES等渲染进 spec.md校验管线CANONICAL_ORDER章节顺序检查、SECTION_ALIASES别名解析、VALID_TYPOGRAPHY_PROPS、VALID_COMPONENT_SUB_TOKENS等驱动 linter 规则也就是说你在 spec-config.yaml 里把某个新属性加进typography_propertieslinter 的合法性校验和官方文档的表格会同步更新不存在文档说了但校验没跟上的分裂状态。测试文件 spec-config.test.ts 与 compiler.test.ts 则守护着这条管线的稳定性。总结 spec-config.yaml是 DESIGN.md 规范的唯一事实来源用纯 YAML 声明章节、类型、令牌与示例spec.mdx renderers generate.ts构成 spec-as-code 生成器一键产出官方文档 docs/spec.mdbun run spec:gen重新生成--check校验新鲜度linter 与文档共用同一份配置天然保持一致这就是 spec-as-code 的核心价值规范不再是写完就漂移的文档而是可生成、可校验、可测试的代码资产。【免费下载链接】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），仅供参考