OpenDesign 设计系统 2.0 的 Token 契约与溯源机制：以 Supabase 包 `source/evidence.md` 为例

AI 应用人工智能AI 技能设计系统媒体生成【免费下载链接】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 包的审计证据体系以design-systems/supabase/source/evidence.md为入口说明source/目录如何记录设计系统包的来源范围Source Scope、fixture 清单以及如何通过token-contract.report.json将每一枚 TOKEN_SCHEMA 绑定映射回tokens.css的具体声明行从而让设计 Token 的出处可查、可复核、可再生成。读完本文你将掌握阅读任何 OpenDesign 设计系统包的source/证据文件、核验 Token 契约一致性并理解为何派生产物应通过报告与样式表重新生成而不是手工编辑。1.source/目录在 Design System 2.0 包中的角色在 OpenDesign 仓库中每个品牌设计系统包如 Supabase的目录结构遵循统一的 Design System 2.0 约定。以design-systems/supabase/为例包内除了面向生成器与审查者的DESIGN.md、tokens.css、components.html、manifest.json、tailwind-v4.css等文件之外还有一个专门的source/子目录存放三类审计证据文件文件角色source/evidence.md来源范围声明Source Scope与契约说明的入口文档source/tokens.source.json结构化登记的 Token 源清单逐条记录 token 名称、取值与在tokens.css中的行号source/token-contract.report.jsonToken 契约报告将每个 TOKEN_SCHEMA 绑定映射回声明行并输出完整度评分source/目录的意义在于它把这个设计系统包从哪里来、每个值由哪一行代码声明、派生产物应当如何再生成这三件事显式记录成机器可读的证据而不是让审查者靠猜。manifest.json中通过sourceFiles字段显式登记了这三份文件evidence、tokens、report说明它们是包契约的一部分而不是随手放置的杂项sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json }对应的完整声明见 design-systems/supabase/manifest.json。2. Source Scopebundled fixture 而非上游重新抓取evidence.md开篇即对证据范围做了最关键的限定——这是 Design System 2.0 回填backfill包来源于 OpenDesign 内置的精选 fixturecurated bundled fixture并不声称对上游品牌仓库或网站做过重新抓取fresh crawlThis 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.这是一条非常重要的边界声明在全文其他地方也被反复强调报告中每个 token 条目的reason字段都写着Bundled tokens.css declares --xxx; no upstream recrawl was performed for this backfill逐条声明未执行上游重抓取USAGE.md的 Avoid 一节明确要求不要声称拥有原始上游来源证据本包基于精选内置 fixture。为什么这条边界如此重要因为在设计系统领域证据的来源类型直接决定其可信度等级。一次真实的上游抓取可以声称复刻了 Supabase 官网而 bundled fixture 只能声称依据仓库内已精选整理的素材回填。evidence.md用一句话划清了两者的界限既防止使用者高估证据强度也为后续如需最新上游证据请重新抓取留出升级路径。在引用本包任何 token 值时都应当把这一来源限定一并说明。3. 包含的 Fixture 文件清单evidence.md明确列出本回填包依赖的三份 fixture 文件它们共同构成了 Supabase 设计系统包的视觉意图与实现依据design-systems/supabase/DESIGN.md—— 视觉意图与约束文档详细记录 Supabase 的暗色原生主题、翡翠绿品牌色、Circular 字体体系、组件样式、布局原则、深浅层级Elevation以及该做什么 / 不该做什么Dos and Dontsdesign-systems/supabase/tokens.css—— 结构化 Token 绑定样式表tokens.css中的:root块是全部 Token 声明的权威来源design-systems/supabase/components.html—— 组件参考实现用于核对精确的选择器与状态搭配components.manifest.json可快速浏览组件清单。这三份 fixture 与包内其余文件design-tokens.json、tailwind-v4.css、preview/预览页等共同组成完整包结构。包内preview/目录还提供了colors.html、spacing.html、typography.html三个可视化预览页见manifest.json的preview.pages配置便于对 Token 做直观的视觉抽查。4. Token Contract把每个绑定映射回声明行evidence.md的核心段落是 Token ContractToken 契约说明source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.也就是说token-contract.report.json的职责是建立一条可验证的双向对应关系每个 Token 契约绑定TOKEN_SCHEMA→ 实际声明它的tokens.css行号。这样审查者可以从契约出发定位某个 Token 在样式表中的确切声明位置从样式表出发确认每一个声明值都有契约记录没有被遗忘或凭空新增。以报告头部见 design-systems/supabase/source/token-contract.report.json为例它包含schemaVersion、contract: TOKEN_SCHEMA、generatedAt、sourceScope: open-design-bundled-fixture等元信息以及一段机器可读的summarysummary: { 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 }这份摘要本身就是一份质量报告56 个 Token 全部被声明、全部有源支撑sourceBackedTokens: 56其中 26 个来自 A2 层的回退fallbackTokens: 261 个是别名 TokenaliasTokens: 1即--surface-warm直接别名为var(--surface)。score: 100、grade: excellent、recommendRebuild: false表明该包的 Token 契约完整且无需重建。报告主体是逐 token 的详细条目每条都包含名称、分层layer、值、置信度、原因与源位置。例如--bg与--accent两条{ name: --bg, layer: A1-identity, value: #171717, confidence: high, sources: [tokens.css:122] } { name: --accent, layer: A1-identity, value: #3ecf8e, confidence: high, sources: [tokens.css:163] }对照 design-systems/supabase/tokens.css 的:root块可以逐一核验--bg: #171717在第 122 行--accent: #3ecf8e在第 163 行——契约报告的行号与实际声明完全一致这正是该机制可审计的落地体现。4.1 Token 分层Layer体系从layerCounts可以看出Supabase 包的 Token 采用四层结构这与共享的 Token 模式design-systems/_schema/tokens.schema.ts再导出packages/contracts中的token-schema.ts保持一致层数量含义A1-identity8品牌身份 Token如--bg、--fg、--accent、--border、字体族A1-structure18结构 Token如字号阶梯--text-xs至--text-4xl、行高、段落节奏、容器宽度A226派生/回退 Token如 hover/active 状态、语义色、间距、圆角、阴影B-slot4槽位别名 Token如--surface-warm与--meta绑定到 A 层取值分层体系的直接好处是品牌切换cross-brand switching时只要 A1 层身份 Token 被替换A2 与 B-slot 层的值就能自动跟随USAGE.md中精确保留 schema token 名称以保证跨品牌切换可靠的建议正是基于这一结构。4.2 A2 回退Fallback机制fallbackTokens: 26表明 A2 层的 26 个 Token 并非都直接取值于tokens.css而是有相当一部分依赖 schema 层级的回退默认值。tokens.css的注释明确指出其回退对齐目标是design-systems/_schema/defaults.css——当某个品牌没有显式声明某个 A2 语义值时就使用共享默认值从而保证所有设计系统包在语义 Token 层面保持一致的行为边界。审查者可以在token-contract.report.json中看到每个 A2 Token 的confidence与reason判断它是品牌专属值还是 schema 回退。5.tokens.source.jsontoken 源的结构化登记与报告并存的source/tokens.source.json是更轻量的源登记清单同样由tokens.css派生。它记录了brandId: supabase、sourceScope: open-design-bundled-fixture、生成时间与三份 fixture 文件清单随后按顺序登记每个 Token 的名称、取值、层级及源位置如--text-4xl→72px→A1-structure→tokens.css:204。完整清单见 design-systems/supabase/source/tokens.source.json。两份文件的分工是tokens.source.json提供是什么、在哪一行的快速索引token-contract.report.json则进一步提供契约审计结论评分、置信度、回退来源、是否需要重建。二者共同构成source/目录的完整证据链。6. 派生输出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-tokens.json供程序化消费的 JSON 形式 Token与tailwind-v4.cssTailwind v4 主题接入层都是派生产物其正确再生成路径是以source/token-contract.report.json的绑定映射 tokens.css的:root声明为输入重新生成而不是直接手工修改这两份文件。这与USAGE.md的 Avoid 规则一脉相承避免脱离tokens.css独立重新定义 Tailwind 或 design-token 值。理由很直接手工编辑派生文件会破坏source/证据链与产物之间的一致性——一旦tokens.css更新而派生文件没有同步再生成Token 契约报告与产物之间就会出现无法解释的偏差。维护者只应修改权威源tokens.css或 DESIGN 文档再触发再生成。7. 如何结合源码验证 Token 契约tokens.css文件头的注释区块给出了完整的引用与校验链条可作为阅读任何设计系统包的导航标准 Token 名称以design-systems/_schema/tokens.schema.ts再导出 packages/contracts/src/design-systems/token-schema.ts为准A2 回退对齐以design-systems/_schema/defaults.css为准Lint 强制校验由apps/daemon的lint-artifact相关模块执行该模块在 apps/daemon/src/server.ts 中被引用。例如tokens.css注释中提到的每屏绿色使用不超过 2 处lint enforced这条规则就来自 DESIGN.md §7 不要把绿色用在背景或大面积表面上的反模式约束并由 lint 环节落地为可自动检查的规则。审查一个包时可以按如下顺序操作读source/evidence.md确认来源范围bundled fixture 还是上游抓取打开source/token-contract.report.json的summary看score/grade/recommendRebuild是否健康抽查任意 Token 条目按其sources中的行号跳到tokens.css对应行核对声明值与报告值一致对比tokens.source.json与tokens.css的:root块确认无遗漏、无多余若修改了tokens.css或DESIGN.md不要手工改design-tokens.json/tailwind-v4.css而是按契约报告与样式表再生成。8. 实践建议与证据使用边界综合evidence.md、USAGE.md与包内实现使用本包以及其他 Design System 2.0 包时有几条值得遵守的准则Do把source/文件当作回填审计证据对待引用取值时附带source/evidence.md中声明的来源限定bundled fixture未重抓上游Do使用--accent承担主操作、链接、焦点态与唯一焦点元素复用components.manifest.json中的组件组避免发明新控件Do保留 schema token 名称不变保证跨品牌切换时契约稳定Avoid在:rootToken 块之外散落裸 hex 值独立于tokens.css重新定义 Tailwind / design-token 值声称拥有原始上游来源证据添加components.html与DESIGN.md之外的组件配方。一句话总结这套机制的价值source/evidence.md用一页纸说清了这个包从哪来、基于哪些 fixture、Token 如何可追溯到具体声明行、派生文件如何再生成而token-contract.report.json用机器可读的报告把这一承诺固化为可自动审计的契约。这种来源声明 行级映射 再生成约定的组合正是 OpenDesign 设计系统包在质量与可维护性上的核心设计。赞分享AI 应用人工智能AI 技能设计系统媒体生成【免费下载链接】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 设计系统溯源与 Token 契约机制以 Warm Editorial 包的 Source Evidence 为例OpenDesign 设计系统溯源与 Token 契约机制以 Warm Editorial 包的 Source Evidence 为例 本篇技术指南围绕 OpAI 应用人工智能AI 技能设计系统媒体生成OpenDesign 设计系统 2.0 溯源证据与 Token 契约机制以 Arc Browser 包为例OpenDesign 设计系统 2.0 溯源证据与 Token 契约机制以 Arc Browser 包为例 本篇技术指南聚焦 OpenDesign 仓库中 DAI 应用人工智能AI 技能设计系统媒体生成OpenDesign 设计系统 2.0 回填溯源以 Slack 包为例的 Source Evidence 与 Token 契约链OpenDesign 设计系统 2.0 回填溯源以 Slack 包为例的 Source Evidence 与 Token 契约链 本文以 OpenDesignAI 应用人工智能AI 技能设计系统媒体生成上一篇React Native Circular Slider常见问题解决调试和故障排除终极指南下一篇CANN稀疏Flash MLA算子创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考