OpenDesign 设计系统溯源与 Token 契约：Clay 包 source evidence 机制深度解析-平芜编程栈

OpenDesign 设计系统溯源与 Token 契约：Clay 包 source evidence 机制深度解析

【免费下载链接】open-design🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images & video — real files, HTML/PDF/PPTX/MP4 export. 🤖 Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode & 20+ CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design

本文以design-systems/clay/source/evidence.md为核心骨架，剖析 OpenDesign 仓库中设计系统包的"来源证据（source evidence）"与"Token 契约（token contract）"机制：一个设计系统包如何声明其出处、如何通过token-contract.report.json将每个语义 token 回溯到tokens.css的具体声明行，以及为什么design-tokens.json、tailwind-v4.css等派生文件必须从报告与样式表再生成而非手工编辑。读完本文，你将掌握 OpenDesign Design System 2.0 包的完整证据链结构、四层 Token 架构（A1/A2/B-slot）以及包的校验与再生成工作流。

1. 背景：什么是 Design System 2.0 backfill 与 source evidence

OpenDesign 仓库在design-systems/目录下维护着一套可移植的设计系统包目录，每个子目录（slug）是一个自包含的设计系统包。根据 design-systems/README.md，当前捆绑目录包含151 个包，每个捆绑包都具备相同的最小机器可读结构：

design-systems/<slug>/ ├── manifest.json ├── DESIGN.md └── tokens.css

其中manifest.json负责稳定的发现元数据、出处（provenance）与声明的包内路径；DESIGN.md是面向 Agent 的规范设计文本；tokens.css是规范化的编译语义 Token 样式表。

在这个体系里，source/目录承载的是导入证据（importer evidence）。design-systems/clay/source/evidence.md正是 Clay 包这一证据目录的说明文档，它在文件中明确划定了本包的证据边界：

This Design System 2.0 backfill is derived from the curated OpenDesign bundled fixture. It does not claim a fresh crawl of the original upstream brand repository or website.

这句话是理解整个 evidence 机制的关键：Clay 包是一个backfill（回填）产物，其内容源自 OpenDesign 仓库自带的精选捆绑 fixture，而不是对上游品牌官网/仓库的全新爬取。这与manifest.json中的source字段相互印证：

{ "schemaVersion": "od-design-system-project/v1", "id": "clay", "name": "Clay", "category": "Design & Creative", "description": "Bundled OpenDesign package for Clay, derived from curated DESIGN.md, tokens.css, and components.html fixtures.", "source": { "type": "bundled", "origin": "OpenDesign curated bundled fixture" }, "importMode": "normalized" }

出处声明（source.type: "bundled"）直接决定了后续所有证据文件的组织方式与可信度标注方式。

2. 包内文件清单：evidence.md 声明的三个核心 fixture

evidence.md在 "Included Fixture Files" 一节列出了 Clay 包的三个核心来源文件，它们构成了包的"事实基础"：

文件	仓库相对路径	作用
设计规范	design-systems/clay/DESIGN.md	面向 Agent 的完整视觉设计散文：氛围、色彩、排版、组件、布局、Do's & Don'ts、响应式、Prompt 指南
Token 样式表	design-systems/clay/tokens.css	规范化编译的语义 Token 样式表，`:root`中声明 56 个 token
组件 fixture	design-systems/clay/components.html	独立运行的组件参考实现，单个`<style>`块 + 示例 DOM

manifest.json通过files与sourceFiles字段把这三类文件与派生文件统一登记：

{ "files": { "design": "DESIGN.md", "tokens": "tokens.css", "designTokens": "design-tokens.json", "tailwind": "tailwind-v4.css", "components": "components.html" }, "sourceFiles": { "evidence": "source/evidence.md", "tokens": "source/tokens.source.json", "report": "source/token-contract.report.json" } }

这种"声明路径 + 实际文件"的双重登记，是后续 Guard 校验（scripts/check-design-system-manifests.ts）验证"每个声明的路径必须安全、相对且存在"的基础。

3. Token 契约：token-contract.report.json 与证据回溯

evidence.md的 "Token Contract" 一节是全文的技术核心，原文如下：

source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.

也就是说，design-systems/clay/source/token-contract.report.json 是一份审计报告：它把TOKEN_SCHEMA（共享 Token 契约）中的每一个绑定，都映射回提交到仓库的tokens.css中的具体声明行。以--bg为例，报告中的记录是：

{ "name": "--bg", "layer": "A1-identity", "value": "#f7eee6", "confidence": "high", "reason": "Bundled tokens.css declares --bg; no upstream recrawl was performed for this backfill.", "sources": ["tokens.css:7"], "sourceName": "--bg" }

这里sources: ["tokens.css:7"]就是"证据回溯"的落地形式——报告精确到行号，指向 design-systems/clay/tokens.css 中的--bg: #f7eee6;声明。reason字段则忠实记录了证据来源（bundled fixture，而非上游爬取），体现了 evidence 机制的诚实性要求。

3.1 契约报告的汇总指标

报告的summary区块给出了 Clay 包的 Token 契约健康度总览：

{ "totalTokens": 56, "declaredTokens": 56, "sourceBackedTokens": 56, "sourceBackedA1": 26, "fallbackTokens": 26, "aliasTokens": 0, "layerCounts": { "A1-identity": 8, "B-slot": 4, "A2": 26, "A1-structure": 18 }, "score": 100, "grade": "excellent", "recommendRebuild": false }

解读这些指标：

56 个 token 全部有声明、全部有来源回溯（sourceBackedTokens: 56），因此综合评分 100、评级excellent，recommendRebuild为false——即当前包无需重建；
26 个 A1 token 全部有来源（sourceBackedA1: 26），26 个 A2 token 全部使用 schema 级 fallback 值（fallbackTokens: 26）；
没有任何别名 token（aliasTokens: 0），说明 B-slot 层是独立绑定值而非var(--sibling)别名折叠形式。

3.2 四层 Token 架构（A1-identity / A1-structure / A2 / B-slot）

要真正读懂契约报告，需要理解 OpenDesign 的共享 Token 契约分层。根据 design-systems/_schema/AGENTS.md，每个共享 token 回答两个问题：谁决定值（品牌作者还是 schema 作者）与品牌省略时怎么办（必填 / fallback / alias）。由此得出四层：

层	谁决定	若省略	示例
A1-identity	品牌	Guard 失败	`--bg`、`--fg`、`--accent`、`--font-display`
A1-structure	品牌	Guard 失败	字号阶梯、`--container-max`、`--section-y-*`
A2	品牌（带 fallback）	Guard 失败（当前严格必填）	`--motion-fast`、`--success`、`--space-4`、`--font-mono`
B-slot	品牌或 schema 建议的别名	Guard 失败——品牌必须声明	`--fg-2`、`--surface-warm`、`--meta`、`--border-soft`

Clay 包在这四层的分布恰好是：A1-identity 8 个、A1-structure 18 个、A2 26 个、B-slot 4 个（合计 56）。对照 design-systems/clay/tokens.css：

A1-identity（8）：--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-body；
A1-structure（18）：--text-xs到--text-4xl的字号阶梯、--leading-body、--leading-tight、--tracking-display、--section-y-*、--container-max、--container-gutter-*；
A2（26）：语义色（--accent-on、--success、--warn、--danger）、--accent-hover/--accent-active（用color-mix(in oklab, var(--accent), black 8%/14%)派生）、间距--space-*、圆角--radius-*、投影--elev-*、--focus-ring、动效--motion-*、--ease-standard、--font-mono；
B-slot（4）：--surface-warm、--fg-2、--meta、--border-soft。

值得注意的细节是：B-slot 的 schema 建议默认是别名形式（如--fg-2: var(--fg)），但 Clay 选择为每个槽位绑定独立值（如--fg-2: #5a4b43、--surface-warm: #ead6c7），这属于"更丰富"的绑定形式，同样满足design-system: B-slot required tokensGuard。这正是aliasTokens: 0的原因。

3.3 为什么 A2 必须全部声明

_schema/AGENTS.md特别解释了"A2 当前为何严格必填"：概念上 A2 是"可选 + fallback"，但产物由 Agent 把单个品牌的:root块粘贴进一个<style>生成，没有随品牌一起加载的全局样式表。若品牌漏掉--motion-fast，产物中transition: var(--motion-fast)就会静默失效。因此在未来的派生脚本落地、把defaults.css值内联进每个品牌的tokens.css之前，唯一安全的契约就是"每个品牌必须声明每个 A2 token"，由design-system: A2 required tokensGuard 强制执行。

4. 派生输出：design-tokens.json 与 tailwind-v4.css 的再生成原则

evidence.md对派生文件给出了明确的操作约束：

design-tokens.jsonandtailwind-v4.cssare derived outputs and should be regenerated from the report and token stylesheet rather than edited by hand.

即 design-systems/clay/design-tokens.json 与 design-systems/clay/tailwind-v4.css 是派生缓存，而不是并列的事实源。它们必须从source/token-contract.report.json+tokens.css再生成，不得手工编辑。这与 design-systems/README.md 中"Derived files are caches rather than competing sources of truth"的原则一致：

components.manifest.json← 由components.html+tokens.css派生；
design-tokens.json← 由 token-contract 报告派生，且必须与tokens.css一致；
tailwind-v4.css← 由tokens.css派生，不得独立重定义源值。

对照实际文件，design-tokens.json的头部也声明了这条链路：

{ "schemaVersion": 1, "format": "od-design-tokens/v1", "contract": "TOKEN_SCHEMA", "source": { "tokensCss": "tokens.css", "tokenContractReport": "source/token-contract.report.json" } }

其 56 个 token 条目与报告、tokens.css逐行对应（例如--bg→#f7eee6→tokens.css:7），并额外补充了type字段（color / dimension 等）。任何手工改动这三者之一导致的不一致，都会被包质量 Guard 中的"派生文件一致性（derived-file parity）"检查捕获。

5. 证据链的实践意义：从 DESIGN.md 到组件 fixture

evidence 机制的价值在于：包内每一层"知识"都有可回溯的出处。以 Clay 包为例，从证据文件可以逐层还原其完整设计系统：

5.1 设计规范层（DESIGN.md）

design-systems/clay/DESIGN.md 描述了 Clay 的视觉身份：暖奶油色画布（#faf9f7）配燕麦色边框（#dad4c8）、以 Matcha/Slushie/Lemon/Ube/Pomegranate/Blueberry/Dragonfruit 命名的"果汁吧"式色板、Roobert 几何无衬线字体（5 组 OpenType 特性集ss01/ss03/ss10/ss11/ss12）、以及标志性的悬停微动画（rotateZ(-8deg)+translateY(-80%)+ 硬偏移投影rgb(0,0,0) -7px 7px）。注意：这份规范属于"品牌参考"性质，与包内实际 token 化的tokens.css属于同一体系的两个层次——前者描述设计意图与约束，后者提供可被组件引用的语义变量。

5.2 组件实现层（components.html）

design-systems/clay/components.html 是独立可运行的参考 fixture：一个<style>块内定义了 48 个选择器、26 个类、19 个元素（据 design-systems/clay/components.manifest.json 统计）。关键实现全部通过var(--token)引用而非硬编码，例如：

.btn：min-height: 44px、border-radius: var(--radius-md)、过渡使用var(--motion-fast) var(--ease-standard)；
.btn-primary：background: var(--accent); color: var(--accent-on)，hover 时background: var(--accent-hover)并translateY(-1px)；
.panel：background: color-mix(in oklab, var(--surface), transparent 4%)、box-shadow: var(--elev-raised)；
input:focus：box-shadow: var(--focus-ring); border-color: var(--accent)；
.status::before：8px 圆点 +var(--radius-pill)+var(--success)。

components.manifest.json进一步把 48 个选择器归组为 buttons / inputs / cards / badges / links / typography / layout 等组件组，并记录每组的 token 引用清单（例如 buttons 组引用--accent、--elev-ring、--motion-fast、--radius-md等 12 个 token）。该清单还暴露了 7 个"已声明未使用"token（--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn），这些是审计时可继续深挖的线索。

5.3 使用层（USAGE.md）

design-systems/clay/USAGE.md 定义了 Agent 与审查者的读取顺序契约：先读 USAGE.md 理解包契约 → 读 DESIGN.md 获取视觉意图与反模式 → 把tokens.css粘贴进首个 artifact 的<style>块再写组件 CSS → 用components.manifest.json做紧凑组件盘点，需要精确选择器或状态时打开components.html→ 需要视觉抽检时查看preview/页面。它还强调：保留 schema token 名称原样以保证跨品牌切换可靠，避免在:roottoken 块之外使用裸十六进制值，并不要声称存在未经验证的原始上游证据——这正是 evidence 精神的延伸。

6. Guard 校验：证据与派生如何被机器强制执行

从源码结构看，evidence 与派生文件的约束由多个 Guard 脚本与 schema 共同落地：

scripts/check-design-system-manifests.ts：校验所有manifest.json的形状、声明的路径安全且存在；
design-system: A2 required tokens与design-system: B-slot required tokensGuard：强制每个品牌的:root声明全部共享 token（见 design-systems/_schema/AGENTS.md）；
派生文件一致性 Guard：验证提交的components.manifest.json与从components.html+tokens.css的新鲜派生一致、design-tokens.json与报告一致、tailwind-v4.css与tokens.css一致（README 中的 "derived-file parity" 检查）；
design-system: A2 defaults parityGuard：校验defaults.css与 schema 中 A2 的fallback字段逐字节一致。

运行方式为在仓库根目录执行pnpm guard与pnpm typecheck。需要说明的是，未来计划中的scripts/derive-tokens-css.ts（自动从 DESIGN.md 派生 A1、为 A2 填充 defaults.css）当前并不存在，属于 schema 文档中留待实现的未来工作；当前所有 56 个 token 依然由人工声明的tokens.css承担，契约报告中的recommendRebuild: false即表明现有提交状态是自洽的。

7. 总结：一份证据文件如何支撑整条设计系统链路

回到design-systems/clay/source/evidence.md本身，这份不足二十行的文档实际上划定了整条生产链路的边界与规则：

边界声明：本包是 curated bundled fixture 的 backfill，不是上游爬取——所有后续证据标注都以此为基准；
来源清单：DESIGN.md（意图）、tokens.css（变量）、components.html（实现）三份 fixture 构成包的输入面；
契约映射：token-contract.report.json把 56 个 TOKEN_SCHEMA 绑定逐行映射回tokens.css声明，形成"报告 → 样式表 → 行号"的可审计证据链；
派生纪律：design-tokens.json与tailwind-v4.css只能由报告与 token 样式表再生成，禁止手工编辑，从而保证 151 个捆绑包（以及未来新增包）在跨品牌切换、Agent 提示组合时拥有统一且可验证的 Token 语义。

对于希望在 OpenDesign 中新增或维护设计系统包的开发者，这条证据链给出了明确的作业顺序：保持文件夹 slug 与manifest.id一致 → 写齐DESIGN.md（至少七个实质性 H2）→ 在tokens.css绑定完整共享契约 → 需要组件/预览/证据时补充 rich 文件 → 最后运行pnpm guard与pnpm typecheck让机器验证证据与派生的一致性。源头可溯、派生可重建、差异可被 Guard 拦截——这就是 Design System 2.0 source evidence 机制的完整闭环。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考