企业官网建设流程全解析

OpenDesign 设计系统包的 Token 契约与证据链机制——以 Vodafone 源证据文档为例

【免费下载链接】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-systems/vodafone/source/evidence.md这份"源证据文档"展开，讲解 OpenDesign Design System 2.0 包的可审计回填机制：一个设计系统包如何通过tokens.css单一事实来源、token-contract.report.json契约报告与design-tokens.json/tailwind-v4.css派生产物，形成"来源声明 → token 绑定 → 行号级溯源 → 派生输出"的完整证据链。读完本文，你将掌握 OpenDesign 设计系统包的目录契约、56 个结构化 token 的分层体系（A1-identity / A1-structure / A2 / B-slot）、契约报告的字段语义，以及 agent 在生成与审查设计系统时应遵循的读写顺序与校验纪律。

一、什么是源证据文档：回填（Backfill）的诚实声明

design-systems/vodafone/source/evidence.md全文很短，却是整个 vodafone 包中最关键的"审计入口"。它开门见山地声明了两件事：

1. 来源范围（Source Scope）：这个 Design System 2.0 回填包源自 OpenDesign 仓库自带的精选捆绑 fixture（curated bundled fixture），并不声称对 Vodafone 原始上游品牌仓库或官网做过新的抓取（"It does not claim a fresh crawl of the original upstream brand repository or website"）。
2. 派生产物规则：design-tokens.json与tailwind-v4.css是派生输出（derived outputs），必须从契约报告和 token 样式表重新生成，严禁手工编辑。

这份声明在技术上非常重要——它把"品牌视觉事实"与"工程实现证据"严格分开：视觉规格来自捆绑 fixture，而 token 的每一次绑定都必须能追溯到tokens.css中的具体声明行。这也与 manifest.json 中"source": { "type": "bundled", "origin": "OpenDesign curated bundled fixture" }的定义互相印证：该包在元数据层面就把自身标记为 bundled 类型，而非 upstream 实时抓取。

二、包结构与文件职责：一份契约化清单

evidence.md 明确列出的三个核心 fixture 文件，加上包内其余工程文件，构成了完整的职责分工：

从manifest.json可以看到包级元数据的关键约定："importMode": "normalized"（标准化导入）、"craft": { "suggested": ["color", "accessibility-baseline"] }（建议套用的 craft 规范），以及"preview"三页的角色划分。这套结构在整个design-systems/目录下是统一复用的模式——每个品牌包（vodafone、stripe、openai、github 等）都遵循"DESIGN.md + tokens.css + components.html + source/ 证据目录"的契约。

三、Token 契约报告：行号级溯源的实现

source/token-contract.report.json 是 evidence.md 所描述机制的落地实现。其顶层字段结构如下：

{ "schemaVersion": 1, "contract": "TOKEN_SCHEMA", "generatedAt": "2026-06-06T00:00:00.000Z", "sourceScope": "open-design-bundled-fixture", "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 }, "tokens": [ ] }

3.1 summary 字段语义

• totalTokens / declaredTokens / sourceBackedTokens 均为 56：声明的每个 token 都被源代码（tokens.css）覆盖，无孤儿 token。
• sourceBackedA1 = 26：属于 A1 层（identity + structure）且由源码直接支撑的 token 数量。
• fallbackTokens = 26：回退 token 数量（A2 层等非 identity 层，值取自捆绑 fixture 而非上游实时证据）。
• aliasTokens = 0：本包没有使用别名间接引用，所有 token 都是直接声明值。
• layerCounts：A1-identity 8 个、B-slot 4 个、A2 26 个、A1-structure 18 个，合计 56。
• score = 100 / grade = "excellent" / recommendRebuild = false：契约完整性满分，无需重建。

3.2 单个 token 的溯源字段

报告中的每个 token 条目都携带完整的审计信息，以--accent为例：

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

关键字段解读：

• layer：token 在 TOKEN_SCHEMA 分层体系中的归属，取值有四类：
  • A1-identity（8 个）：品牌身份层，如--bg、--accent、--fg、--muted、--border、--font-display、--font-body；
  • A1-structure（18 个）：结构层，如字号--text-xs至--text-4xl、行高--leading-body、字距--tracking-display、节距--section-y-*、容器--container-*；
  • A2（26 个）：通用功能层，如--accent-on、--accent-hover、--accent-active、--success、--warn、--danger、间距--space-*、圆角--radius-*、阴影--elev-*、动效--motion-*；
  • B-slot（4 个）：品牌槽位层，如--surface-warm、--fg-2、--meta、--border-soft。
• confidence: "high"：本包所有 token 均为 high，原因统一为捆绑 fixture 声明，未做上游重抓。
• sources：精确到文件行号的溯源（如tokens.css:17），这就是 evidence.md 所说"maps every TOKEN_SCHEMA binding back to the committed tokens.css declaration line"的机器可读实现。
• sourceName：与 CSS 中声明名一致，保证契约绑定无歧义。

四、tokens.css：56 个 token 的分层全景

tokens.css 是整个包的单一事实来源。它通过:root声明了 56 个自定义属性，按语义可分为以下几组（行号为该文件内声明行）：

品牌身份（A1-identity，8 个）

• --bg: #ffffff（L8 画布白）、--surface: #f4f4f4（L9）、--fg: #1f1f1f（L11 近黑正文）、--muted: #6f7375（L13）、--border: #d8d8d8（L15）、--accent: #e60000（L17Vodafone Red）、--font-display/--font-body（L24-25）

品牌槽位（B-slot，4 个）

• --surface-warm: #fff1f1（L10 暖色面）、--fg-2: #4a4d4e（L12 次级正文）、--meta: #a61218（L14 深红 meta）、--border-soft: #eeeeee（L16）

功能色（A2 子集）

• --accent-on: #ffffff（L18）、--accent-hover: color-mix(in oklab, var(--accent), black 8%)（L19）、--accent-active: color-mix(in oklab, var(--accent), black 14%)（L20）、--success: #008a00（L21）、--warn: #f5b400（L22）、--danger: #bd0000（L23）

值得注意：hover/active 状态使用现代 CSS 的color-mix(in oklab, ...)从--accent派生，而非硬编码色值——这是"禁止在:root之外出现裸色值"规则能够成立的技术前提（详见 USAGE.md 的 Avoid 条款）。

结构层（A1-structure，18 个）

• 字号--text-xs: 12px至--text-4xl: 68px（L27-34）、--leading-body: 1.48、--leading-tight: 1.08、--tracking-display: -0.015em、节距--section-y-desktop: 96px/--section-y-tablet: 68px/--section-y-phone: 48px（L46-48）、容器--container-max: 1200px及三档 gutter（L60-63）

通用功能（A2 余量）

• 间距--space-1: 4px至--space-12: 48px（L38-45）、圆角--radius-sm: 8px/--radius-md: 16px/--radius-lg: 24px/--radius-pill: 9999px（L49-52）、阴影--elev-flat: none/--elev-ring/--elev-raised（L53-55）、焦点环--focus-ring: 0 0 0 4px rgba(230, 0, 0, 0.22)（L56）、动效--motion-fast: 150ms/--motion-base: 220ms/--ease-standard: cubic-bezier(0.2, 0, 0, 1)（L57-59）

source/tokens.source.json 是这 56 个 token 的纯 JSON 镜像，为每个 token 记录name / value / layer / source（行号），是契约报告与 tokens.css 之间的中间层。

五、派生产物：design-tokens.json 与 tailwind-v4.css

evidence.md 强调这两份文件"should be regenerated from the report and token stylesheet rather than edited by hand"（应从报告和 token 样式表重新生成，而非手工编辑）。它们的派生关系在文件内也有明确标注：

5.1 design-tokens.json：带类型的 token 清单

design-tokens.json 采用od-design-tokens/v1格式，在 tokens.source.json 基础上为每个 token 增加了type字段（color / dimension / fontFamily / number / shadow / duration / cubicBezier），并把sources升级为数组形式（如["tokens.css:17"]）。其summary与契约报告完全一致（56/56、score 100、grade excellent），印证了"派生自报告"的声明。

5.2 tailwind-v4.css：Token 到 Tailwind 主题的桥接

tailwind-v4.css 的文件头直接写道Derived from tokens.css. Keep tokens.css as the source of truth.，结构为：

@import "tailwindcss"; @import "./tokens.css"; @theme { --color-bg: var(--bg); --color-accent: var(--accent); --color-accent-hover: var(--accent-hover); --font-display: var(--font-display); --font-sans: var(--font-body); --text-4xl: var(--text-4xl); --spacing-8: var(--space-8); --spacing-section-desktop: var(--section-y-desktop); --radius-pill: var(--radius-pill); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); /* ...其余 token 一一映射 */ }

映射规律清晰：--color-*前缀对应颜色、--font-*对应字体、--text-*对应字号、--spacing-*对应间距（含--spacing-section-desktop等语义化命名）、--radius-*对应圆角、--shadow-*对应阴影、--duration-*对应动效时长。所有值都通过var()引用 tokens.css，因此改 tokens.css 一处，Tailwind 主题自动跟随——这正是"单一事实来源"设计的目的。tailwind-v4.css中--font-sans: var(--font-body)这一行还表明：Tailwind 默认字体槽被桥接到了品牌的 body 字体上，避免出现双字体漂移。

六、组件清单：从 fixture 反推的 token 引用审计

components.manifest.json 对 components.html 做了机械化审计，为 evidence.md 的"fixture 文件"提供配套证据：

• fixture 概况：styleBlockCount: 1、selectorCount: 48、classCount: 26、elementCount: 19；
• tokens 审计：declared（56 个声明）与referenced（组件实际引用的 token）逐项比对，得出unusedDeclared（声明但未被组件引用的 7 个：--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn）与undeclaredReferenced: []（引用了但未声明的为 0，说明组件没有裸引用）；
• 组件分组：buttons（引用 12 个 token）、inputs、cards、badges、links、typography、layout 等，每组给出对应选择器与 tokenReferences。例如 buttons 组引用了--accent、--accent-on、--border、--ease-standard、--elev-ring、--fg、--radius-md、--space-5、--surface、--text-sm、--motion-fast、--font-body。

这种"组件 → token 引用"的双向审计，让审查者能快速发现：某组件是否绕过 token 体系使用了裸值（undeclaredReferenced）、某 token 是否成为死代码（unusedDeclared）。从仓库 scripts 目录的命名（如 scripts/check-design-system-manifests.ts、scripts/check-design-system-package-quality.ts、scripts/check-tokens-fixture-sync.ts）可以推断，这类审计已脚本化为 CI 可执行的批量检查，用于保证全仓库每个设计系统包都满足同样的契约。

七、使用顺序与操作纪律：agent 与审查者的共识

USAGE.md 规定了明确的操作顺序，这是整个包"可被机器消费"的关键：

1. 先读 USAGE.md，理解包契约；
2. 再读 DESIGN.md，掌握视觉意图、约束与反模式；
3. 生成代码时，把 tokens.css 原样粘贴进产物第一个<style>块，再写组件 CSS；
4. 需要精确选择器/状态时查components.html，需要组件清单时查components.manifest.json；
5. 需要视觉体检时打开preview/三页。

同时它给出了三条硬性纪律（Avoid 条款）：

• 避免在复制的:roottoken 块之外使用裸 hex 值——所有颜色必须走 token 引用；
• 避免脱离 tokens.css 独立重定义 Tailwind 或 design-token 值——派生产物只能由源生成；
• 避免声称存在原始上游源证据——本包基于捆绑 fixture，这是 evidence.md 划定的诚实边界。

而 DESIGN.md 则为 token 提供了视觉语义解释，二者互为表里。例如：--accent: #e60000（Vodafone Red）是"唯一的、不可替代的品牌身份色"，用于主 CTA、红色分隔带、speech-mark 标识；--fg: #1f1f1f是对应 DESIGN.md 中"Charcoal Headline（#25282b）绝不用纯黑"规则的工程化表达。DESIGN.md 中完整的 20+ 级字体层级（144px/800 字重大写显示字 → 12px 微标签）、双轨按钮体系（2px 直角矩形用于表单/工具，60px 全圆角 pill 用于编辑内容 CTA）、无阴影无渐变原则、以及"深色 Hero → 红带 → 白画布 → 炭黑机构面板 → 炭黑页脚"的通用页面节奏，都可以理解为这些 token 在视觉层的使用契约——token 是语法，DESIGN.md 是语义。

八、已知边界与局限

根据 DESIGN.md 末尾的 Known Gaps 与 evidence.md 的范围声明，使用本包时需注意：

• 表单控件规格为推断值：主页模板未暴露完整表单（文本框、下拉、开关），其规格从 ghost 按钮模式推断，设计真实表单时需细化；
• 品牌字体不可复刻：Vodafone 企业字体是专有的，开源替代建议用Inter（400/600/800 字重），在 80px+ 显示字号下把字距收紧 1-2%、行高设 0.85-0.95 以逼近原版大写字体的紧排效果；
• 动效时长未文档化：站点使用动效极少，静态分析无法提取精确值；tokens.css 中的--motion-fast: 150ms/--motion-base: 220ms属于包的工程默认值而非上游证据；
• 股价数字样式来自单一截图：share ticker 的数字格式（分隔符、货币符号）以投资者页截图为据，其他地区变体可能不同；
• 证据边界：所有 token 的confidence: "high"均指向捆绑 fixture 声明，而非对上游的实时抓取——审查者引用时应如实表述为"基于 OpenDesign 捆绑 fixture 的回填"。

结语

Vodafone 包展示的这套"evidence.md 声明 → tokens.css 单一事实来源 → tokens.source.json 中间映射 → token-contract.report.json 契约评分 → design-tokens.json / tailwind-v4.css 派生产物"的流水线，是 OpenDesign 设计系统 2.0 让设计资产变得可审计、可校验、可派生的核心范式。对生成式 Agent 而言，正确的工作流是：先读 USAGE.md 与 evidence.md 确认边界，再以 tokens.css 为唯一事实源生成代码，最后用契约报告与组件清单做自检——而不是凭印象引入新色值或新组件。对仓库维护者而言，scripts/下的 check-design-system-* 系列脚本构成了这一契约的机械化护栏，保证几十个品牌包长期保持一致的可信度。

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