深入 Open Design 的 Professional 设计系统：Token 契约、来源证据与派生输出

深入 Open Design 的 Professional 设计系统：Token 契约、来源证据与派生输出

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

本文以 design-systems/professional/source/evidence.md 为核心，讲解 Open Design 的 Design System 2.0 中“来源证据（Source Evidence）”模型：如何声明一套设计系统 token 的证据范围、如何通过token-contract.report.json把每个TOKEN_SCHEMA绑定回tokens.css的具体声明行，以及design-tokens.json、tailwind-v4.css等派生产物“只应再生成、不应手改”的工程约束。读完本文，你可以独立核验任意一套 Open Design 设计系统的 token 契约，理解其四层 token 分层（A1-identity / A1-structure / A2 / B-slot）的评分与重建建议机制。

一、来源证据文件的定位

在 Open Design 的设计系统目录结构中，每个品牌包都可以通过 manifest 声明自己的“来源证据”三件套。design-systems/professional/manifest.json 中的sourceFiles字段明确把三个角色映射到了具体文件：

"sourceFiles": { "evidence": "source/evidence.md", "tokens": "source/tokens.source.json", "report": "source/token-contract.report.json" }

• source/evidence.md：人类可读的证据声明（本文主角），说明本包 token 数据来自哪里、覆盖到什么程度；
• source/tokens.source.json：机器可读的 token 来源清单，记录brandId、sourceScope和每个 token 的source行号引用；
• source/token-contract.report.json：token 契约报告，把每一个TOKEN_SCHEMA绑定映射回已提交的tokens.css声明行。

manifest 同时声明了本包的基本身份信息：schemaVersion为od-design-system-project/v1，id为professional，source.type为bundled，origin为 “OpenDesign curated bundled fixture”。这些字段共同构成了阅读证据文件前的上下文。

二、Source Scope：证据范围声明

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.

翻译成工程语言：这套 Professional 设计系统的 token 数据是一次“回填（backfill）”，其权威来源是仓库内已提交的 bundled fixture 文件，而不是对上游品牌官网或品牌仓库的重新抓取。这条声明有两个直接后果：

1. 所有 token 的取值以仓库内 tokens.css 的提交内容为准；
2. 报告里每个 token 的reason字段都会明确注明这一前提，例如：

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

对应地，source/tokens.source.json 顶部同样携带了sourceScope: "open-design-bundled-fixture"字段，与报告中的sourceScope值一致。也就是说，“证据范围”不是写在散文里的口头承诺，而是被编码进了两份机器可读文件，便于脚本校验。

一个值得注意的事实差异：DESIGN.md 描述的调色板（Primary#FECE14、字体 Poppins 等）与 tokens.css 中实际声明的变量（--accent: #2563eb、--font-display: Inter, system-ui, sans-serif）并不完全一致。从源码结构看，这正是 evidence.md 强调“基于 bundled fixture、不声称上游重新抓取”的意义所在——token 契约把权威声明锚定在tokens.css的具体行上，而不是散文式的设计描述文档上。

三、Fixture 三件套：证据所依据的提交文件

evidence.md 的 Included Fixture Files 一节列出了本次回填实际引用的三个文件：

tokens.css是整份证据链的“账本”。其:root块从第 7 行到第 62 行共 56 条声明，例如：

:root { --bg: #f5f8ff; /* 第 7 行 */ --surface: #ffffff; --fg: #101828; --muted: #667085; --accent: #2563eb; --accent-hover: color-mix(in oklab, var(--accent), black 8%); --text-4xl: 76px; --leading-body: 1.52; --space-4: 16px; --radius-md: 16px; --elev-raised: 0 20px 52px rgba(16, 24, 40, 0.11); --focus-ring: 0 0 0 4px rgba(37, 99, 235, 0.22); --motion-base: 240ms; --container-max: 1180px; /* ... 共 56 条 ... */ }

这里可以看到 Professional 系统的几个实现细节：状态色与主色使用color-mix(in oklab, var(--accent), black 8%)这类派生写法而非硬编码新色值；焦点环--focus-ring使用主色 22% 透明度的 4px 外扩阴影；阴影--elev-raised用rgba(16, 24, 40, 0.11)与主文字色--fg保持同族。这些细节都可以直接在tokens.css中逐行核对。

四、Token 契约：token-contract.report.json 的字段逐项解析

evidence.md 的 Token Contract 一节指出：source/token-contract.report.json把每一个TOKEN_SCHEMA绑定都映射回已提交的tokens.css声明行。打开 token-contract.report.json 可以看到完整的契约结构。

4.1 报告头与 summary 汇总

报告头部字段：

{ "schemaVersion": 1, "contract": "TOKEN_SCHEMA", "generatedAt": "2026-06-06T00:00:00.000Z", "sourceScope": "open-design-bundled-fixture", ... }

其中contract: "TOKEN_SCHEMA"声明了本报告校验所依据的契约名，而该契约的权威定义位于 packages/contracts/src/design-systems/token-schema.ts（design-systems/_schema/tokens.schema.ts 直接 re-export 该文件）。

summary区块（报告第 6–22 行）给出了全局健康度：

"summary": { "totalTokens": 56, "declaredTokens": 56, "sourceBackedTokens": 56, "sourceBackedA1": 26, "fallbackTokens": 26, "aliasTokens": 0, "layerCounts": { "A1-identity": 8, "B-slot": 4, "A2": 26, "A1-structure": 18 }, "score": 100, "grade": "excellent", "recommendRebuild": false }

各计数器的含义（结合 token-schema.ts 的分层定义解读）：

4.2 逐 token 条目：行号级溯源

报告的tokens数组（从第 23 行开始，共 56 个条目）为每个 token 提供统一结构：name、layer、value、confidence、reason、sources、sourceName。Professional 包的 56 个条目全部满足：

• confidence为high；
• sources形如"tokens.css:N"，其中 N 从 7 递增到 62，与 tokens.css 中:root块内的 56 条声明一一对应——第一条--bg指向tokens.css:7，最后一条--container-gutter-phone指向tokens.css:62；
• sourceName与 CSS 变量名一致，说明本次回填没有做改名式的间接绑定。

这种“报告条目 → CSS 行号”的双向映射，使得任何评审者（或脚本）都能用一条grep级别的检查验证 token 声明与契约是否漂移：若有人手改了tokens.css却未重新生成报告，sources中的行号引用就会与实际声明脱节。

4.3 四层 token 分层在 Professional 包中的分布

TOKEN_SCHEMA在 packages/contracts/src/design-systems/token-schema.ts 中定义了四个层：

export type TokenLayer = "A1-identity" | "A1-structure" | "A2" | "B-slot";

各层的语义（摘自该文件头部注释与条目描述）与 Professional 包的实际分布：

按层统计：8 + 18 + 26 + 4 = 56，与totalTokens完全吻合。可以推断，score: 100的评分逻辑正是基于“声明数 == 总数、A1 层全部有源、无未解析别名”这类契约完整性指标；recommendRebuild: false则表示该包当前状态健康，无需重建。

五、派生输出：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.

也就是说，Professional 包根目录下的 design-tokens.json 与 tailwind-v4.css 属于派生产物：

• 它们的唯一合法修改方式是从契约报告与tokens.css重新生成；
• 直接手改这两个文件不会更新token-contract.report.json的行号引用，会造成“文件已改、证据未变”的不一致状态；
• 正确的变更路径是：修改tokens.css→ 重新生成报告与派生文件 → 行号引用与派生内容同步刷新。

仓库中还存在若干与 token 一致性相关的工具脚本，例如 scripts/check-tokens-fixture-sync.ts 与 scripts/generate-design-system-system-assets.ts，从脚本命名看分别承担“token 与 fixture 同步检查”和“设计系统资产生成”的职责（本文不展开其内部实现），这与 evidence.md 强调的再生成方向相互印证。

对于消费方来说，这一纪律的实际收益是：Agent 或开发者在做设计系统时，若需要 Tailwind v4 主题变量，直接引用tailwind-v4.css即可；若发现某个 token 取值异常，应顺着tailwind-v4.css → design-tokens.json → token-contract.report.json → tokens.css的链条回溯到行号级权威声明，而不是在派生文件里打补丁。

六、配套资源：预览页、Usage 与 craft 建议

manifest 还为验证证据提供了两个辅助入口：

1. 预览页：preview配置声明了三个角色页 —— preview/colors.html（色彩）、preview/typography.html（字体）、preview/spacing.html（间距）。它们与tokens.css的取值直接相关，可在浏览器中直观核对 56 个 token 的渲染效果；
2. craft 建议：craft.suggested声明了["color", "accessibility-baseline"]，对应仓库的 craft/color.md 与 craft/accessibility-baseline.md。Professional 包的--focus-ring、--muted/--fg等取值正是这类基线约束在 token 层的体现。

此外，USAGE.md 面向消费方说明该包的使用方式，与 source/ 目录下面向“证据与契约”的文件形成互补：source/回答“这些 token 凭什么成立”，USAGE.md回答“怎么用”。

七、小结：如何核验任意设计系统的 token 契约

以 Professional 包为样本，Open Design 的 Design System 2.0 给出了一套可复用的证据链模式：

1. 读 evidence.md：确认sourceScope（bundled fixture 还是上游抓取）、引用的 fixture 文件清单、派生输出纪律；
2. 对账 report 与 CSS：检查summary中declaredTokens是否等于totalTokens、sourceBackedTokens是否覆盖 A1 层、recommendRebuild是否为 false，并抽查sources行号与tokens.css实际声明是否一致；
3. 理解分层：A1-identity/A1-structure 是品牌骨架（无 fallback），A2 是可回退的通用层，B-slot 是可选槽位；
4. 只改源头：变更永远从tokens.css与报告再生成开始，design-tokens.json、tailwind-v4.css等派生文件禁止手改。

Professional 包的这份契约目前处于满分状态（score 100、grade excellent、56/56 全部行号级溯源），它既是一个具体的设计系统实例，也是理解 Open Design 整套 token 证据与契约机制的最佳入口。

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