企业官网建设流程全解析

OpenDesign 设计系统 2.0 溯源证据与 Token 契约机制：以 Arc Browser 包为例

【免费下载链接】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 System 2.0 包的溯源证据（source evidence）机制，以 Arc Browser 设计系统包（design-systems/arc/）为实例展开。你将理解：什么是 "bundled fixture backfill"、为什么设计系统包需要一份evidence.md声明其资料边界、token-contract.report.json如何把每个 TOKEN_SCHEMA 绑定逐行映射回tokens.css声明，以及design-tokens.json与tailwind-v4.css为何必须作为派生产物再生成而非手工编辑。读完即可掌握这套"来源可审计、派生可复算、守卫可校验"的设计系统资产管线。

一、什么是 Design System 2.0 backfill 与溯源证据

OpenDesign 仓库内置了大量品牌设计系统（Arc、Apple、Stripe、Notion 等上百个），供编码 Agent 在生成原型、落地页、仪表盘时直接粘贴对应品牌的tokens.css。这些包在 2.0 版本中统一升级为"项目化"结构：每个品牌目录携带manifest.json、DESIGN.md、tokens.css，并可选携带design-tokens.json、tailwind-v4.css、components.html、preview/与source/（详见 design-systems/_schema/AGENTS.md）。

其中source/目录专门存放导入器证据（importer evidence），包括scanned-files.json、evidence.md、tokens.source.json、token-contract.report.json与snippets/INDEX.json。Arc 包中的 source/evidence.md 就是这套证据机制的入口文档。

Arc 包的 evidence.md 开篇即声明其溯源范围（Source Scope）：

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.

这是整个证据机制最重要的语义：Arc 设计系统包不是对 Arc Browser 官网或上游仓库的实时爬取结果，而是基于 OpenDesign 内部策展的捆绑 fixture（即已提交的DESIGN.md、tokens.css、components.html）回填（backfill）而成。这一声明直接决定了该包的证据等级与使用边界——它可用于设计参考与组件还原，但不能被当作对上游品牌资产的"原始来源证据"。

二、证据链的组成：fixture 文件与 manifest 声明

evidence.md 明确列出了该 backfill 依赖的三个核心 fixture 文件：

这三个文件通过 design-systems/arc/manifest.json 登记为机器可读的项目条目：

{ "schemaVersion": "od-design-system-project/v1", "id": "arc", "name": "Arc Browser", "category": "Productivity & SaaS", "source": { "type": "bundled", "origin": "OpenDesign curated bundled fixture" }, "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" } }

注意 manifest 中source.type同样是bundled，与 evidence.md 的声明互相印证——"非上游爬取"的边界在证据文档与机器可读清单两个层面保持一致。

三、Token 契约：report 如何把每个绑定映射回声明行

evidence.md 对契约机制只有一句话，却是整条管线的核心：

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

即：每个共享 schema token 的绑定值，都必须能追溯到tokens.css中具体的声明行。Arc 包的 token-contract.report.json 用三个字段完成了这一映射：

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

• name/layer：token 名及其所属 schema 层级；
• value/confidence：报告期内的绑定值与置信度（该 backfill 全部为high，因为值直接来自已提交的 tokens.css）；
• sources：关键字段，指向 design-systems/arc/tokens.css 的精确行号（如tokens.css:49），即--accent: #ff5f5f;的声明行；
• reason：自动生成的取值原因说明，统一声明"来自捆绑 tokens.css，未执行上游重新爬取"。

配套的 tokens.source.json 以更紧凑的{ name, value, layer, source }结构记录了同一份行级映射（如"source": "tokens.css:26"对应--bg: #fdf3ec）。两份文件一详一略，共同构成"值 → 行号 → 声明文本"的完整证据链。

报告摘要：56 个 token 全部有据可查

report 顶部的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 }

这些数字的对应关系清晰可查：A1-identity(8) + A1-structure(18) = sourceBackedA1(26)（品牌必须亲自决定的 A1 层共 26 个）；A2(26) = fallbackTokens(26)（每个 A2 token 都带 schema 级 fallback）；B-slot(4)中有 1 个以别名实现（--meta: var(--muted)，对应aliasTokens: 1），其余 3 个（--surface-warm、--fg-2、--border-soft）绑定独立值。最终score: 100 / grade: "excellent"，表示当前 Arc 包与 TOKEN_SCHEMA 完全对齐，无需重建。

四、四层 Token 架构：报告背后的 schema 语义

要理解 report 中layerCounts的分布，必须回到权威 schema——packages/contracts/src/design-systems/token-schema.ts。它是 OpenDesign 生态中每个品牌tokens.css的结构契约，且是唯一权威来源（design-systems/_schema/tokens.schema.ts只是面向守卫脚本与仓库内导入的兼容再导出）。

每个共享 token 都属于且仅属于一个层级，由"谁决定值"与"品牌省略时怎么办"两个问题决定：

schema 中每个条目携带精确的元数据：A2 条目必须提供fallback字段（derive 脚本未来内联进品牌 tokens.css 的默认值，须与_schema/defaults.css逐字节一致）；B-slot 条目必须提供aliasTo字段（无更丰富层级时品牌照抄的别名表达式，如aliasTo: "var(--surface)"）。schema 文件顶部的注释同时解释了为何 A2 是"带 fallback 的必填"而非"可选"：artifact 由 Agent 把单个品牌的:root块粘贴进一个<style>生成，不存在随品牌并行加载的全局样式表，一旦缺少var(--motion-fast)目标，transition: var(--motion-fast)会静默失效、规则被浏览器丢弃——因此运行期契约永远是"每个 tokens.css 必须声明全部 A1 + A2 + B-slot token"。

Arc 的 tokens.css 完美体现了这套语义：例如--bg: #fdf3ec（暖桃色画布）是 A1-identity 的品牌决定；--accent: #ff5f5f（Arc Coral）保持单一可解析值，而主 CTA 的 Sunset 渐变（peach→coral）由组件内联linear-gradient(...)组合；--focus-ring: 0 0 0 4px color-mix(in oklab, var(--accent), transparent 80%)则用 schema 默认值之外的更宽更柔的聚焦环，体现 Arc 的磨砂玻璃语言。

五、派生产物的再生成原则与守卫校验

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/arc/design-tokens.json（Design Tokens JSON）与 design-systems/arc/tailwind-v4.css（Tailwind v4@themeCSS）都是派生产物：前者应由token-contract.report.json+tokens.css复算，后者必须与tokens.css同源且不得独立重定义值。手工编辑会导致与上游证据脱节，并触发仓库守卫失败。

这一原则由仓库守卫在 CI/本地强制。在 scripts/check-design-system-manifests.ts 中可以找到design-tokens.json的完整校验逻辑：

• parsed.contract必须为"TOKEN_SCHEMA"，format必须为"od-design-tokens/v1"；
• 若声明了designTokens则必须同时声明sourceFiles.report，否则报requires sourceFiles.report；
• 用renderDesignTokensJson({ bindings, report })重算期望文本，与提交文件逐字节比较（normalizeEol后），不一致则报is stale; regenerate it from <reportPath>；
• report 中的每个 token 名必须覆盖TOKEN_SCHEMA全部条目；
• 每个绑定值必须与tokens.css中实际声明值（经parseRootTokenDeclarationDetails解析）一致，且sources指向的行号必须真实存在对应声明。

同时，scripts/check-tokens-fixture-sync.ts 实现了 "Design system A2 defaults parity" 守卫：遍历TOKEN_SCHEMA中所有 A2 条目，逐一核对_schema/defaults.css的:root声明是否与 schema 的fallback字段一致（normalizeCssValue归一化后比较），并反向检查 defaults.css 中不存在非 A2 的声明——防止 schema 与 CSS 镜像之间漂移。

六、如何使用与审计这份证据

Agent 与审查者可按 design-systems/arc/USAGE.md 的既定顺序使用该包：

1. 先读USAGE.md理解包契约；
2. 读 DESIGN.md 掌握视觉意图、约束与反模式；
3. 在编写组件 CSS 之前，先把 tokens.css 粘贴进首个 artifact 的<style>块；
4. 需要精确选择器或状态时打开 components.html，紧凑清单用components.manifest.json；
5. 需要视觉抽查时打开preview/下的 colors.html、typography.html、spacing.html；
6. 审计时：把source/下的三个文件（evidence.md、tokens.source.json、token-contract.report.json）当作捆绑 fixture backfill 的审计证据。

USAGE.md 同时给出两条与证据机制直接相关的避雷提示：不要声称存在原始上游来源证据（本包基于策展捆绑 fixture）；不要独立于tokens.css重定义 Tailwind 或 design-token 值——这与 evidence.md 的派生再生成原则完全一致。

七、小结

Arc Browser 包的 source/evidence.md 虽短，却定义了 OpenDesign Design System 2.0 资产管线的三条铁律：来源有声明（bundled fixture backfill，不冒充上游爬取）、绑定可追溯（token-contract.report.json将 56 个 TOKEN_SCHEMA 绑定逐行映射回tokens.css）、派生可复算（design-tokens.json与tailwind-v4.css只能由 report + tokens.css 再生成，并由 check-design-system-manifests.ts 与 check-tokens-fixture-sync.ts 守卫强制）。理解这套机制后，你既可以把 Arc 的磨砂玻璃与渐变暖意正确粘贴进自己的 artifact，也能在引入新品牌或审计既有包时，沿着 evidence → report → tokens.css 的路径快速定位每个值的出处与边界。

【免费下载链接】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