OpenDesign 设计系统 2.0 的 Token 契约与来源证据机制：以 Replicate 品牌包为范例
【免费下载链接】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
本篇技术指南围绕 OpenDesign 仓库中 design-systems/replicate/source/evidence.md 这一来源证据文档展开，系统讲解 Design System 2.0 品牌包中“来源证据（Source Evidence）— Token 契约（Token Contract）— 派生产物（Derived Outputs）”三层数据管线的工作原理。读者读完将掌握：token-contract.report.json 的报告结构与打分机制、tokens.css 的四个分层语义、design-tokens.json 与 tailwind-v4.css 为何必须“从报告再生成”而非手工编辑，以及 Agent 在使用该设计系统时应遵循的证据边界。
一、背景：什么是 Design System 2.0 Backfill 与来源证据
OpenDesign 的design-systems/目录收录了 150+ 个品牌设计系统包（airbnb、vercel、stripe、openai、replicate 等），每个包都遵循一套统一约定：以DESIGN.md描述视觉意图、以tokens.css声明结构化 token、以components.html承载参考组件、以manifest.json声明包元数据。
Replicate 包的 evidence.md 正是这套约定中的“来源证据”文件——它记录的是该包“数据从哪里来、契约如何建立、哪些文件可派生、哪些文件不可手改”的审计信息。对于任何想基于该设计系统做二次开发、或想理解 OpenDesign 如何批量生成品牌包的开发者，这份证据文档是入口级文件。
二、Source Scope：基于内置 Fixture 的回填，而非上游重爬
evidence.md 开篇即声明了本包的数据边界：
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.
这句话定义了 Replicate 包的证据性质：本包是 OpenDesign 内置、经过人工策展（curated）的 fixture 派生物，并不声称对 Replicate 官方品牌仓库或官网做过全新爬取。这一声明的意义在于：
- 它划定了证据可信度的上限——包内所有 token 的置信度都基于“bundled fixture”，而不是“上游一手数据”；
- 它直接决定了 token-contract.report.json 中每条记录的
reason字段内容，例如--bg的 reason 即写明 "Bundled tokens.css declares --bg; no upstream recrawl was performed for this backfill"； - 它与 manifest.json 中的
source.type: "bundled"、source.origin: "OpenDesign curated bundled fixture"字段相互印证，构成完整的数据溯源链。
同时，evidence.md 的标题"Source Scope"也对应仓库内多个校验脚本的审计目标，例如 scripts/check-design-system-manifests.ts 会检查各包 manifest 与证据文件的字段一致性，防止包元数据与真实来源脱节。
三、Included Fixture Files：三个来源文件的分工
evidence.md 明确列出了本包回填所依据的三个 fixture 文件，它们共同构成“设计意图 → 可执行 token → 参考实现”的完整链条：
| 文件 | 角色 | 内容概要 |
|---|---|---|
| DESIGN.md | 视觉意图与约束 | 色彩体系、字体层级表、组件样式、布局原则、Do's and Don'ts、Agent Prompt Guide |
| tokens.css | Token 单一事实源 | 125 行:root声明，覆盖 surface/foreground/border/accent/semantic/typography/spacing/radius/elevation/motion/layout 全部类别 |
| components.html | 参考组件实现 | 依据 components.manifest.json 的统计，包含 1 个 style 块、49 个选择器、25 个 class、25 个元素 |
三个文件的职责边界非常清晰：DESIGN.md 回答“为什么这么设计”，tokens.css 回答“用什么值表达设计”，components.html 回答“组件长什么样”。Agent 或开发者做二次开发时，按 USAGE.md 推荐的读序依次消费这三个文件即可。
3.1 以 DESIGN.md 为例：设计意图如何转化为 token 命名
DESIGN.md 第 2 节定义了核心色彩角色，它们与 tokens.css 中的变量一一对应：
Replicate Dark (#202020)→--fg、--border（文本与边框锚点色，比纯黑更暖）Replicate Red (#ea2804)→--accent（品牌色，仅用于渐变与强调边框，禁止作大面积填充）Status Green (#2b9a66)→--success（运行/在线状态徽章）Medium Gray (#646464)→--muted（次要正文）Mid Silver (#8d8d8d)→--meta（三级文本、脚注）
DESIGN.md 第 3 节的字体层级表（Display Mega 128px / Hero 72px / Section 48px / Sub-heading 30px……）同样被 tokens.css 的--text-xs到--text-4xl八个字号 token 逐一承接，其中--text-4xl: 128px正是 DESIGN.md 中“closing manifesto（'Imagine what you can build.' 宣言段）”的字号——tokens.css 第 63-64 行注释甚至直接引用 DESIGN.md 章节号（DESIGN.md §3）作为溯源依据。这种“文档章节号 ↔ token 声明行”的双向引用，正是整个 evidence 体系的微观体现。
四、Token Contract：token-contract.report.json 的结构与语义
evidence.md 的核心段落是 Token Contract 一节：
source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.design-tokens.jsonandtailwind-v4.cssare derived outputs and should be regenerated from the report and token stylesheet rather than edited by hand.
它确立了三个规则：① 每一条 TOKEN_SCHEMA 绑定都必须能映射回 tokens.css 的具体声明行；② design-tokens.json 与 tailwind-v4.css 是派生产物；③ 派生产物禁止手工编辑，必须从报告与 token 样式表重新生成。这是保证 150+ 品牌包 token 体系一致性的关键机制——TOKEN_SCHEMA 契约定义于 packages/contracts/src/design-systems/token-schema.ts，并经 design-systems/_schema/tokens.schema.ts 导出供全仓库校验使用。
4.1 报告头部：summary 聚合指标
token-contract.report.json 的 summary 区块给出了整包 token 健康度的量化画像：
{ "schemaVersion": 1, "contract": "TOKEN_SCHEMA", "generatedAt": "2026-06-06T00:00:00.000Z", "sourceScope": "open-design-bundled-fixture", "summary": { "totalTokens": 56, "declaredTokens": 56, "sourceBackedTokens": 56, "sourceBackedA1": 26, "fallbackTokens": 26, "aliasTokens": 1, "layerCounts": { "A1-identity": 8, "B-slot": 4, "A2": 26, "A1-structure": 18 }, "score": 100, "grade": "excellent", "recommendRebuild": false } }关键字段解读：
| 字段 | 值 | 含义 |
|---|---|---|
totalTokens/declaredTokens | 56 / 56 | 契约要求 56 个 token，tokens.css 全部声明 |
sourceBackedTokens | 56 | 56 个 token 全部有源码行支撑，覆盖率 100% |
sourceBackedA1/fallbackTokens | 26 / 26 | A1 层 26 个 token 有源码直接背书，恰好对应 26 个回退 token（即 tokens.css 中全部实际声明值） |
aliasTokens | 1 | 存在 1 个别名 token（--surface-warm: var(--surface)，见 tokens.css 第 24 行） |
score/grade | 100 / excellent | 契约健康度满分 |
recommendRebuild | false | 无需重建派生产物 |
4.2 分层模型：A1-identity / B-slot / A2 / A1-structure
报告的layerCounts展示了 TOKEN_SCHEMA 的四层归类（合计 56 = 8 + 4 + 26 + 18）：
- A1-identity（8 个）：品牌身份层，如
--bg（tokens.css:22）、--surface（:23）、--fg（:29）、--muted（:31）、--border（:37）、--accent（:43）、--font-display（:59）、--font-body（:60）——这些是品牌不可协商的核心变量； - B-slot（4 个）：品牌槽位层，如
--surface-warm（别名，:24）、--fg-2（:30）、--meta（:32）、--border-soft（:38）——用于承接各品牌差异化的次级语义； - A2（26 个）：派生/语义层，如
--accent-on、--accent-hover、--accent-active、--success、--warn、--danger、--font-mono及全套字号/行高/字距 token，大多直接声明或通过color-mix()派生； - A1-structure（18 个）：结构层，如
--text-xs至--text-4xl、--space-1至--space-12、--radius-*、--elev-*等。
这一分层与 26 个sourceBackedA1的统计相互印证：A1-identity 与 A1-structure 共 26 个 token 拥有源码直接背书，B-slot 与 A2 中的 30 个则通过声明值/别名/派生表达式间接落地。
4.3 单条记录的字段结构
报告主体每条记录包含 6 个字段，例如：
{ "name": "--accent", "layer": "A1-identity", "value": "#ea2804", "confidence": "high", "reason": "Bundled tokens.css declares --accent; no upstream recrawl was performed for this backfill.", "sources": ["tokens.css:43"], "sourceName": "--accent" }sources数组直接给出tokens.css:43这类行级引用，实现了 evidence.md 承诺的“每一条绑定映射回声明行”；confidence: "high"表示该值可高置信度信任（当前报告全部 56 条均为 high）；reason统一声明证据来源为 bundled fixture，维持了第 2 节所述的数据边界诚实性。
五、派生产物管线：design-tokens.json 与 tailwind-v4.css
evidence.md 明确将 design-tokens.json 与 tailwind-v4.css 标记为派生输出（derived outputs），并给出两条铁律：
- 只能从 report + token 样式表重新生成，即修改流程必须是“改 tokens.css → 重跑生成器 → 产出新 report/派生文件”；
- 禁止手工编辑派生文件，否则下次再生成时差异将被覆盖，且可能绕过契约校验。
以 tailwind-v4.css 为例，其头部注释即声明 "Derived from tokens.css. Keep tokens.css as the source of truth."，正文通过@import "./tokens.css"加@theme块把 CSS 变量桥接为 Tailwind v4 的 design token：
@import "tailwindcss"; @import "./tokens.css"; @theme { --color-bg: var(--bg); --color-accent: var(--accent); --color-success: var(--success); --font-display: var(--font-display); --font-sans: var(--font-body); --text-4xl: var(--text-4xl); --radius-pill: var(--radius-pill); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); /* ... 其余桥接见文件全文 */ }可见每个@theme变量都只是tokens.css中同名变量的透传引用，没有任何独立取值——这正是“tokens.css 是唯一事实源、派生文件零增改”的工程体现。同理，design-tokens.json 是面向工具链的 JSON 化输出，同样应当通过生成器从 report 再生成。
六、消费方视角：Agent 如何正确使用该包
证据体系最终服务于“Agent 拿到品牌包后能生成符合品牌约束的产物”。依据 USAGE.md，正确使用流程为：
- 先读 USAGE.md 理解包契约（Read Order 第 1 步）；
- 再读 DESIGN.md 获取视觉意图与反模式清单（第 2 步）；
- 将 tokens.css 的
:root块整体粘贴到产物第一个<style>块中，再写组件样式（第 3 步）； - 依据 components.manifest.json 复用已有组件配方，仅当需要精确选择器/状态时才打开 components.html（第 4 步）；
- 需要视觉 sanity check 时查看 preview/colors.html、preview/typography.html、preview/spacing.html 三个预览页（第 5 步）。
USAGE.md 同时给出了明确的约束清单，与 evidence.md 的证据边界完全一致：
- Do：保持 schema token 名称不变，保证跨品牌切换（cross-brand switching）可靠；用
--accent承载主操作、链接、焦点态；把source/目录当作回填审计证据； - Avoid：禁止在
:roottoken 块之外散落裸 hex 值；禁止脱离 tokens.css 独立重定义 Tailwind/design-token 值；禁止宣称拥有上游原始来源证据；禁止新增 components.html 与 DESIGN.md 之外的组件配方。
七、来源文件的证据协同：manifest.json 与 tokens.source.json
包级元数据 manifest.json 在sourceFiles字段中显式登记了证据三件套：
"sourceFiles": { "evidence": "source/evidence.md", "tokens": "source/tokens.source.json", "report": "source/token-contract.report.json" }其中 source/tokens.source.json 保存 token 的源态快照，与 evidence.md、token-contract.report.json 共同构成“文档声明 + 原始值 + 契约映射”的完整审计档案；manifest 的files字段则指向 DESIGN.md / tokens.css / design-tokens.json / tailwind-v4.css / components.html 五个可消费文件，craft.suggested字段建议叠加 craft/color.md 与 craft/accessibility-baseline.md 两个 craft 规范做进一步打磨。
八、校验闭环：从 evidence 到全仓库一致性
evidence 机制并非孤立存在。仓库的 scripts/ 目录部署了多层校验脚本，例如 check-design-system-manifests.ts 会遍历全部品牌包核对 manifest 字段，check-design-system-flag-parity.ts 校验包间能力对齐——这些脚本与 token-contract.report.json 的score: 100、recommendRebuild: false共同构成“生成 → 校验 → 审计”的自动化闭环。对 Replicate 包而言，当前报告的满分成绩意味着：56 个 token 全部有 tokens.css 行级来源支撑、分层统计自洽、派生产物无需重建，Agent 可以放心消费该包产出符合品牌约束的前端产物。
小结
Replicate 包的来源证据体系展示了 OpenDesign 设计系统 2.0 的工程化底线：用 evidence.md 声明数据边界，用 token-contract.report.json 建立可追溯的 token 契约，用“tokens.css 唯一事实源 + 派生产物只可再生成”保证多品牌包的一致性与可维护性。无论你是想为 OpenDesign 贡献新品牌包、基于现有品牌做定制开发，还是研究大规模设计 token 治理方案，这套“来源证据 + 契约报告 + 派生管线”的模式都值得作为参考起点——仓库根目录的 design-systems/README.md 与 design-system-tracking-spec.md 提供了更宏观的目录级规范说明。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
