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

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 ScopeThis 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/DESIGN.md品牌的视觉主题、色板、排版层级、组件样式、间距与动效规范Token 绑定design-systems/arc/tokens.css编译后的:roottoken 声明块是组件粘贴进 artifact 的实际来源组件夹具design-systems/arc/components.html独立的组件 fixture与 tokens.css 一同构成可复算的组件清单这三个文件通过 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/layertoken 名及其所属 schema 层级value/confidence报告期内的绑定值与置信度该 backfill 全部为high因为值直接来自已提交的 tokens.csssources关键字段指向 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 级 fallbackB-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 都属于且仅属于一个层级由谁决定值与品牌省略时怎么办两个问题决定层谁决定值省略时Arc 包中的代表A1-identity品牌必填守卫失败--bg、--surface、--fg、--accent、--font-displayA1-structure品牌必填守卫失败--text-*字号阶梯、--leading-*、--container-max、--section-y-*A2品牌带 fallback守卫失败未来 derive 脚本自动填充--motion-fast、--success、--space-4、--font-monoB-slot品牌或 schema 建议的别名守卫失败——品牌必须声明var(--sibling)或独立值--fg-2 → var(--fg)、--surface-warm、--border-softschema 中每个条目携带精确的元数据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: #ff5f5fArc 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.jsonDesign Tokens JSON与 design-systems/arc/tailwind-v4.cssTailwind v4themeCSS都是派生产物前者应由token-contract.report.jsontokens.css复算后者必须与tokens.css同源且不得独立重定义值。手工编辑会导致与上游证据脱节并触发仓库守卫失败。这一原则由仓库守卫在 CI/本地强制。在 scripts/check-design-system-manifests.ts 中可以找到design-tokens.json的完整校验逻辑parsed.contract必须为TOKEN_SCHEMAformat必须为od-design-tokens/v1若声明了designTokens则必须同时声明sourceFiles.report否则报requires sourceFiles.report用renderDesignTokensJson({ bindings, report })重算期望文本与提交文件逐字节比较normalizeEol后不一致则报is stale; regenerate it from reportPathreport 中的每个 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 的既定顺序使用该包先读USAGE.md理解包契约读 DESIGN.md 掌握视觉意图、约束与反模式在编写组件 CSS 之前先把 tokens.css 粘贴进首个 artifact 的style块需要精确选择器或状态时打开 components.html紧凑清单用components.manifest.json需要视觉抽查时打开preview/下的 colors.html、typography.html、spacing.html审计时把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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考