企业官网建设流程全解析

OpenDesign 设计系统溯源与 Token 契约：Expo 包 source/evidence 机制全解析

【免费下载链接】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/expo/source/evidence.md展开，讲解 OpenDesign 仓库中 Design System 2.0 包的“来源证据（source evidence）”与“Token 契约（token contract）”机制。你会掌握：bundled fixture 包的溯源边界如何声明、source/目录下证据文件如何与tokens.css逐行绑定、design-tokens.json与tailwind-v4.css为何必须派生生成而非手改，以及如何按USAGE.md的阅读顺序消费整个 Expo 设计系统包。

1. 什么是 Source Evidence：为“Backfill 包”建立审计证据

OpenDesign 仓库在 design-systems/ 下以子目录形式组织了一套可移植的设计系统包。每个包都有最小机器可读结构（manifest.json+DESIGN.md+tokens.css），并可选地包含source/证据目录（见 design-systems/README.md 的 “Rich package files” 一节）。

design-systems/expo/source/evidence.md正是这一证据机制的“入口文档”。它开宗明义地声明了两点关键事实：

• 本包是Design System 2.0 backfill，来源于 OpenDesign 仓库内精选打包的 fixture（curated bundled fixture），而非对上游品牌仓库或网站的新一轮抓取（"It does not claim a fresh crawl of the original upstream brand repository or website"）。
• 包内所有内容都限定在已提交的 fixture 文件范围内，不接受外部的“新鲜爬取证据”。

这一声明的意义在于：当 Agent 或审查者评估该包的可信度时，可以明确知道每条设计结论的证据来源类型是bundled，而不是crawl。manifest.json中同样记录了这一溯源信息：

{ "schemaVersion": "od-design-system-project/v1", "id": "expo", "name": "Expo", "category": "Developer Tools", "description": "Bundled OpenDesign package for Expo, derived from curated DESIGN.md, tokens.css, and components.html fixtures.", "source": { "type": "bundled", "origin": "OpenDesign curated bundled fixture" } }

可以看到 design-systems/expo/manifest.json 的source.type为bundled，与 evidence 文档的表述完全一致——溯源声明不是孤立的注释，而是被 manifest 元数据正式记录并参与运行时发现的可信字段。

2. Included Fixture Files：证据覆盖的三个文件

evidence.md 明确列出本 backfill 的全部证据来源，共三个 fixture 文件：

这三个文件共同构成了证据的“闭合集”：设计意图看 DESIGN.md，Token 数值看 tokens.css，组件形态看 components.html。任何超出这三个文件的声明，都不属于该包的证据范围——这正是 evidence.md 约束“不越界”的体现，也是 design-systems/expo/USAGE.md 中 “Avoid claiming original upstream source evidence” 的底层原因。

3. Token Contract：从 TOKEN_SCHEMA 到 tokens.css 的逐行绑定

evidence.md 的核心技术段落是 “Token Contract”：

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

这句话定义了本包 Token 体系的数据契约：每个 Token 都必须能回溯到tokens.css中具体的声明行。打开 design-systems/expo/source/token-contract.report.json，可以看到每个 Token 记录的结构：

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

关键字段含义：

• name/sourceName：Token 变量名，必须与tokens.css声明完全一致；
• value：解析后的 Token 值；
• layer：Token 所处的架构分层（详见第 4 节）；
• confidence：可信度评级（本包全部为high，因为全部来自已提交的 tokens.css 声明）；
• sources：证据回溯的关键，形如tokens.css:8，直接指向 design-systems/expo/tokens.css 中的声明行号；
• reason：每一条都写明 “Bundled tokens.css declares …; no upstream recrawl was performed”，与 evidence.md 的溯源声明互相印证。

这种“报告 + 行号”的双向绑定，使 Token 审查变成可机械化验证的操作：任何 Token 值若无法在 tokens.css 中找到对应声明行，契约即被破坏。与之配套的 design-systems/expo/source/tokens.source.json 则提供更精简的（name/value/layer/source）四字段快照，便于程序直接消费。

4. 分层与评分：报告摘要如何量化健康度

token-contract.report.json 的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 }

这份摘要说明了 Expo 包 Token 体系的结构特征：

• 56 个 Token 全部有源码背书（sourceBackedTokens: 56），无一来自回退猜测；26 个属于 A1 层（identity + structure），26 个属于 A2 派生层，4 个属于 B-slot 插槽层；
• aliasTokens 为 0：本包不通过var(--x)别名链引用其他 Token（注意--accent-hover的color-mix()属于函数式派生值而非别名引用）；
• score 100 / grade excellent / recommendRebuild false：契约完整，无需重建；
• fallbackTokens: 26与sourceBackedA1: 26对应：A2 层 26 个 Token 走的是“由 A1 派生”的回退路径，但同样有 tokens.css 声明支撑，因此不影响评分。

从仓库结构看，可以推断这套分层对应的是 OpenDesign 的 Design Tokens 规范：A1（identity 品牌身份 / structure 结构）是源头层，A2 是语义派生层，B-slot 是品牌可替换插槽层。分层信息同时被 design-systems/expo/design-tokens.json 的layer字段和layerCounts汇总所采用，说明报告与派生产物共享同一套 TOKEN_SCHEMA 契约。

5. 派生产物规则：tokens.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.

这意味着 Expo 包的 Token 体系存在清晰的“主从关系”：

• 唯一事实源（source of truth）：design-systems/expo/tokens.css，所有 56 个 Token 在此声明；
• 派生产物 A：design-systems/expo/design-tokens.json，由 token-contract.report.json + tokens.css 重新生成，为工具链提供结构化 JSON（含type、layer、confidence、sources等字段）；
• 派生产物 B：design-systems/expo/tailwind-v4.css，头部注释明确写着 “Derived from tokens.css. Keep tokens.css as the source of truth.”，把 CSS 变量映射进 Tailwind v4 的@theme命名空间。

以 tailwind-v4.css 为例，其映射方式清晰可验证：

@import "tailwindcss"; @import "./tokens.css"; @theme { --color-bg: var(--bg); --color-accent: var(--accent); --color-accent-hover: var(--accent-hover); --color-success: var(--success); --color-danger: var(--danger); --font-sans: var(--font-body); --font-mono: var(--font-mono); --radius-sm: var(--radius-sm); --radius-pill: var(--radius-pill); --shadow-raised: var(--elev-raised); --spacing-section-desktop: var(--section-y-desktop); /* ... */ }

可见派生层覆盖了颜色、字体、字号、行高、字距、间距、圆角、阴影、动效时长与容器宽度等全部维度。修改任何 Token 的唯一正确方式是改 tokens.css，再重新生成派生文件；直接手改 design-tokens.json 或 tailwind-v4.css 会破坏与报告的行号绑定，导致契约失配。USAGE.md 的 Avoid 清单也再次强调：“Avoid raw hex values outside the copied:roottoken block” 与 “Avoid redefining Tailwind or design-token values independently oftokens.css”。

6. tokens.css 全量 Token 速查

为了便于实际引用，这里将 design-systems/expo/tokens.css 的:root块按类别整理（值均来自已提交的样式表，可直接复制使用）：

色彩与语义| Token | 值 | 用途 | |-------|-----|------| |--bg|#ffffff| 页面背景 | |--surface|#f6f7f9| 面板表面 | |--surface-warm|#eef2ff| 暖色强调面板 | |--fg|#0b0d12| 主前景文字 | |--fg-2|#353945| 次级前景文字 | |--muted|#6b7280| 弱化文本 | |--meta|#4630eb| 品牌元色（链接/焦点） | |--border|#dfe3ea| 标准边框 | |--border-soft|#edf0f5| 柔和边框 | |--accent|#000020| 主强调色（近黑） | |--accent-on|#ffffff| 强调色上的文字 | |--accent-hover|color-mix(in oklab, var(--accent), black 8%)| 悬停态 | |--accent-active|color-mix(in oklab, var(--accent), black 14%)| 按下态 | |--success/--warn/--danger|#00a36c/#f59e0b/#e5484d| 状态色 |

字体与排版| Token | 值 | |-------|-----| |--font-display/--font-body|"Inter", system-ui, sans-serif| |--font-mono|"Geist Mono", "SF Mono", ui-monospace, Menlo, monospace| |--text-xs~--text-4xl|12px / 14px / 16px / 18px / 22px / 32px / 48px / 68px| |--leading-body/--leading-tight|1.52/1.06| |--tracking-display|-0.025em|

间距、圆角、阴影、动效与容器| Token | 值 | |-------|-----| |--space-1~--space-12|4px / 8px / 12px / 16px / 20px / 24px / 32px / 48px| |--section-y-desktop/tablet/phone|96px / 68px / 48px| |--radius-sm/md/lg/pill|8px / 14px / 22px / 9999px| |--elev-flat/--elev-ring/--elev-raised|none/0 0 0 1px var(--border)/0 18px 48px rgba(0, 0, 32, 0.12)| |--focus-ring|0 0 0 4px rgba(70, 48, 235, 0.24)| |--motion-fast/--motion-base/--ease-standard|140ms/220ms/cubic-bezier(0.2, 0, 0, 1)| |--container-max/ gutter 系列 |1160px/32px / 24px / 16px|

从数值可以看出这套 Token 的“Expo 气质”：近黑 accent（#000020）承担主 CTA 与品牌锚点、Inter 独占显示与正文、--radius-pill对应 9999px 药丸形几何、--elev-raised只提供柔和的下向投影、--tracking-display为 -0.025em 的紧密字距——与 DESIGN.md 中“luminescent cool-white canvas + monochromatic + pill-shaped geometry + extreme negative letter-spacing”的设计语言一一对应。

7. 设计语言速览：证据之外的“品味契约”

虽然 evidence.md 只负责溯源与契约，但包的完整消费离不开 design-systems/expo/DESIGN.md。其中关键约束可作为生成或审查时的“反模式清单”：

• 单色纪律：界面镀铬层不引入装饰色，色彩只允许来自产品截图与内容；
• 药丸几何：交互元素圆角不低于 6px，主 CTA 用 9999px 药丸，图片/视频容器用 24px 圆角；
• 字距纪律：64px 级大标题使用 -1.6px ~ -3px 极紧字距；正文禁止宽于 -0.25px 的负字距；
• 层次即权重：Inter 以 400–900 全字重表达层次，700–900 给 Display、600 给标题、500 给强调、400 给正文；
• 留白即设计：区块纵向间距不低于 64px（推荐 96px+），画廊式节奏；
• 禁止项：不用超过 2px 的边框、不在界面加渐变、不用重阴影、不混入第二款无衬线字体。

8. 消费路径：按 USAGE.md 的阅读顺序使用本包

design-systems/expo/USAGE.md 给出了 Agent 与审查者的标准消费顺序：

1. 先读USAGE.md理解包契约；
2. 读 design-systems/expo/DESIGN.md 获取视觉意图、约束与反模式；
3. 将 design-systems/expo/tokens.css 粘贴进第一个 artifact 的<style>块，再写组件 CSS；
4. 用 design-systems/expo/components.manifest.json 做组件清单速查（其fixture段记录了styleBlockCount: 1、selectorCount: 48、classCount: 26、elementCount: 19等统计），需要精确选择器或状态时再打开 design-systems/expo/components.html；
5. 需要视觉抽查时，打开preview/下的 colors.html、typography.html、spacing.html 三个预览页。

使用纪律上，USAGE.md 强调：精确保留 schema Token 名称（保证跨品牌切换可靠）、用--accent承载主操作/链接/焦点、优先复用 components.manifest.json 中的组件组、把source/文件仅当作 bundled backfill 的审计证据。

9. 结论：evidence 机制的价值

回顾 evidence.md 的全文，它虽然短小，却定义了 Design System 2.0 包的三条核心纪律：

1. 溯源透明：明确声明 bundled fixture 边界，不冒充上游抓取证据；
2. 契约可验证：token-contract.report.json 让每个 Token 都能回溯到 tokens.css 的具体声明行，并以 score/grade 量化健康度；
3. 派生可重建：design-tokens.json 与 tailwind-v4.css 是派生产物，唯一的编辑入口是 tokens.css。

这套机制让设计系统包在 Agent 工作流中既“可信”又“可审计”：机器可以验证契约，Agent 可以消费证据，人类可以追踪来源。理解 Expo 包的 evidence 结构，也就理解了 OpenDesign 整个 bundled 设计系统目录（当前仓库包含 151 个包）的质检与溯源范式。

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