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视觉意图与约束色彩体系、字体层级表、组件样式、布局原则、Dos and Donts、Agent Prompt Guidetokens.cssToken 单一事实源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 manifestoImagine what you can build. 宣言段”的字号——tokens.css 第 63-64 行注释甚至直接引用 DESIGN.md 章节号DESIGN.md §3作为溯源依据。这种“文档章节号 ↔ token 声明行”的双向引用正是整个 evidence 体系的微观体现。四、Token Contracttoken-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/declaredTokens56 / 56契约要求 56 个 tokentokens.css 全部声明sourceBackedTokens5656 个 token 全部有源码行支撑覆盖率 100%sourceBackedA1/fallbackTokens26 / 26A1 层 26 个 token 有源码直接背书恰好对应 26 个回退 token即 tokens.css 中全部实际声明值aliasTokens1存在 1 个别名 token--surface-warm: var(--surface)见 tokens.css 第 24 行score/grade100 / excellent契约健康度满分recommendRebuildfalse无需重建派生产物4.2 分层模型A1-identity / B-slot / A2 / A1-structure报告的layerCounts展示了 TOKEN_SCHEMA 的四层归类合计 56 8 4 26 18A1-identity8 个品牌身份层如--bgtokens.css:22、--surface:23、--fg:29、--muted:31、--border:37、--accent:43、--font-display:59、--font-body:60——这些是品牌不可协商的核心变量B-slot4 个品牌槽位层如--surface-warm别名:24、--fg-2:30、--meta:32、--border-soft:38——用于承接各品牌差异化的次级语义A226 个派生/语义层如--accent-on、--accent-hover、--accent-active、--success、--warn、--danger、--font-mono及全套字号/行高/字距 token大多直接声明或通过color-mix()派生A1-structure18 个结构层如--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 条均为 highreason统一声明证据来源为 bundled fixture维持了第 2 节所述的数据边界诚实性。五、派生产物管线design-tokens.json 与 tailwind-v4.cssevidence.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 tokenimport 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），仅供参考