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 包中最关键的审计入口。它开门见山地声明了两件事来源范围Source Scope这个 Design System 2.0 回填包源自 OpenDesign 仓库自带的精选捆绑 fixturecurated bundled fixture并不声称对 Vodafone 原始上游品牌仓库或官网做过新的抓取It does not claim a fresh crawl of the original upstream brand repository or website。派生产物规则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 文件加上包内其余工程文件构成了完整的职责分工文件仓库根目录相对路径职责design-systems/vodafone/DESIGN.md视觉意图、约束与反模式色彩角色、字体层级、组件样式、布局、响应式、Dos and Donts、Agent Prompt Guidedesign-systems/vodafone/tokens.css单一事实来源source of truth56 个 CSS 自定义属性的结构化 token 绑定design-systems/vodafone/components.html组件参考 fixture48 个选择器、26 个 class、19 个元素的组件实现样例design-systems/vodafone/source/evidence.md本文讲解的源证据声明design-systems/vodafone/source/tokens.source.jsontoken 源映射每个 token 名 → 值 → 分层 → 声明行号design-systems/vodafone/source/token-contract.report.json契约报告把每个 TOKEN_SCHEMA 绑定映射回 tokens.css 声明行并给出总体评分design-systems/vodafone/design-tokens.json派生输出带类型的 token 清单color / dimension / fontFamily / number / shadow / duration / cubicBezierdesign-systems/vodafone/tailwind-v4.css派生输出把 token 桥接进 Tailwind v4 的themedesign-systems/vodafone/components.manifest.json组件清单选择器/class 分组、每组引用的 token、未使用声明unused declared审计design-systems/vodafone/manifest.json包级清单schemaod-design-system-project/v1声明各文件角色、预览页、craft 建议design-systems/vodafone/USAGE.mdagent 与审查者的包使用指南design-systems/vodafone/preview/可视化体检页colors.html / spacing.html / typography.html从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 都是直接声明值。layerCountsA1-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 }关键字段解读layertoken 在 TOKEN_SCHEMA 分层体系中的归属取值有四类A1-identity8 个品牌身份层如--bg、--accent、--fg、--muted、--border、--font-display、--font-bodyA1-structure18 个结构层如字号--text-xs至--text-4xl、行高--leading-body、字距--tracking-display、节距--section-y-*、容器--container-*A226 个通用功能层如--accent-on、--accent-hover、--accent-active、--success、--warn、--danger、间距--space-*、圆角--radius-*、阴影--elev-*、动效--motion-*B-slot4 个品牌槽位层如--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.css56 个 token 的分层全景tokens.css 是整个包的单一事实来源。它通过:root声明了 56 个自定义属性按语义可分为以下几组行号为该文件内声明行品牌身份A1-identity8 个--bg: #ffffffL8 画布白、--surface: #f4f4f4L9、--fg: #1f1f1fL11 近黑正文、--muted: #6f7375L13、--border: #d8d8d8L15、--accent: #e60000L17Vodafone Red、--font-display/--font-bodyL24-25品牌槽位B-slot4 个--surface-warm: #fff1f1L10 暖色面、--fg-2: #4a4d4eL12 次级正文、--meta: #a61218L14 深红 meta、--border-soft: #eeeeeeL16功能色A2 子集--accent-on: #ffffffL18、--accent-hover: color-mix(in oklab, var(--accent), black 8%)L19、--accent-active: color-mix(in oklab, var(--accent), black 14%)L20、--success: #008a00L21、--warn: #f5b400L22、--danger: #bd0000L23值得注意hover/active 状态使用现代 CSS 的color-mix(in oklab, ...)从--accent派生而非硬编码色值——这是禁止在:root之外出现裸色值规则能够成立的技术前提详见 USAGE.md 的 Avoid 条款。结构层A1-structure18 个字号--text-xs: 12px至--text-4xl: 68pxL27-34、--leading-body: 1.48、--leading-tight: 1.08、--tracking-display: -0.015em、节距--section-y-desktop: 96px/--section-y-tablet: 68px/--section-y-phone: 48pxL46-48、容器--container-max: 1200px及三档 gutterL60-63通用功能A2 余量间距--space-1: 4px至--space-12: 48pxL38-45、圆角--radius-sm: 8px/--radius-md: 16px/--radius-lg: 24px/--radius-pill: 9999pxL49-52、阴影--elev-flat: none/--elev-ring/--elev-raisedL53-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-59source/tokens.source.json 是这 56 个 token 的纯 JSON 镜像为每个 token 记录name / value / layer / source行号是契约报告与 tokens.css 之间的中间层。五、派生产物design-tokens.json 与 tailwind-v4.cssevidence.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.cssToken 到 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: 19tokens 审计declared56 个声明与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 规定了明确的操作顺序这是整个包可被机器消费的关键先读 USAGE.md理解包契约再读 DESIGN.md掌握视觉意图、约束与反模式生成代码时把 tokens.css 原样粘贴进产物第一个style块再写组件 CSS需要精确选择器/状态时查components.html需要组件清单时查components.manifest.json需要视觉体检时打开preview/三页。同时它给出了三条硬性纪律Avoid 条款避免在复制的:roottoken 块之外使用裸 hex 值——所有颜色必须走 token 引用避免脱离 tokens.css 独立重定义 Tailwind 或 design-token 值——派生产物只能由源生成避免声称存在原始上游源证据——本包基于捆绑 fixture这是 evidence.md 划定的诚实边界。而 DESIGN.md 则为 token 提供了视觉语义解释二者互为表里。例如--accent: #e60000Vodafone 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 企业字体是专有的开源替代建议用Inter400/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考