OpenDesign 设计系统 Token 溯源与契约机制解析Corporate 包 source/evidence 与 TOKEN_SCHEMA 绑定【免费下载链接】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/corporate/source/evidence.md 展开讲解 OpenDesign 仓库中 Design System 2.0 包的来源证据Source Evidence体系一个品牌包Brand Package如何声明自己的 token 从何而来、如何把每个 TOKEN_SCHEMA 绑定精确映射回tokens.css的声明行、以及哪些文件是唯一事实源、哪些是必须重新生成的派生输出。读完本文你将掌握 OpenDesign 设计系统的包结构契约、四层 token 模型、溯源报告token-contract.report.json的解读方法以及 Corporate 风格包 56 个 token 的完整取值与派生机制。Source Scope先声明证据边界再谈 token 来源source/evidence.md的第一节明确了整个包的证据边界Source ScopeThis 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.这句话有两层含义包的类型是 backfillCorporate 包是对既有 bundled fixture 的回填整理而不是对上游品牌官网/仓库的一次全新抓取fresh crawl证据边界诚实包内所有 token 值的出处都限定为 OpenDesign 仓库内自带的 curated bundled fixture不主张任何上游原始来源。这一声明与包清单 manifest.json 中的source字段一一对应source: { type: bundled, origin: OpenDesign curated bundled fixture }它也被写入 USAGE.md 的 Avoid 清单Avoid claiming original upstream source evidence; this package is based on the curated bundled fixture.——即使用者在引用本包时不得声称拿到了上游品牌的原始证据。这是理解整个包所有文件的前提所有 token 的可信度都锚定在仓库内 fixture 上。Included Fixture Files包的三个核心资产evidence.md 列出了本包回填所基于的三个 fixture 文件它们同时也是 design-systems/_schema/AGENTS.md 规定的 Design System Project 固定文件名契约中的核心成员文件职责DESIGN.md规范设计散文canonical design prose视觉主题、色彩立场、排版、间距网格、组件、动效、语气与反模式tokens.css规范编译后的 tokencanonical compiled tokens:root块内 56 个 CSS 自定义属性components.html独立组件 fixture按钮、表单、卡片、状态徽标、指标、色板等参考实现三者形成一条清晰的流水线DESIGN.md描述为什么这样设计tokens.css是最终值的唯一事实源components.html演示如何消费这些值。与之配套的还有四个衍生/缓存文件components.manifest.json——可由components.htmltokens.css重新派生的组件清单缓存含 48 个选择器、26 个类、19 个元素的统计design-tokens.json 与 tailwind-v4.css——派生输出详见下文source/tokens.source.json——source 侧的 token 原始清单。manifest.json的sourceFiles字段把证据链收拢到source/目录sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json }Token ContractTOKEN_SCHEMA 绑定与溯源报告evidence.md 的核心段落定义了 Token Contractsource/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.也就是说source/token-contract.report.json 是一份契约审计报告它把 schemaTOKEN_SCHEMA中每一个 token 绑定binding映射回已提交的tokens.css的具体声明行号。报告顶层结构如下{ schemaVersion: 1, contract: TOKEN_SCHEMA, generatedAt: 2026-06-06T00:00:00.000Z, sourceScope: open-design-bundled-fixture, summary: { ... }, tokens: [ ... 56 bindings ... ] }summary给出了整份契约的健康度体检结果指标值含义totalTokens56schema 中注册的 token 总数declaredTokens56在tokens.css中实际声明的 token 数sourceBackedTokens56有 source 行号背书的 token 数sourceBackedA126A1 层identity structure全部有源fallbackTokens26携带 fallback 默认值的 A2 token 数aliasTokens0以var(--sibling)别名形式绑定的 token 数layerCountsA1-identity 8 / B-slot 4 / A2 26 / A1-structure 18四层分布score / grade100 / excellent契约完备度评分recommendRebuildfalse无需重建每个 token binding 都包含完整的溯源信息例如{ name: --accent, layer: A1-identity, value: #2563eb, confidence: high, reason: Bundled tokens.css declares --accent; no upstream recrawl was performed for this backfill., sources: [tokens.css:16], sourceName: --accent }字段含义name是 token 名layer是其在 schema 中的分层value是解析值confidence表示置信度本包全部为 highreason统一说明值来自 bundled tokens.css 声明、未做上游重抓取sources精确到 tokens.css 的行号如tokens.css:16即第 16 行的--accent: #2563eb;。confidence、reason、sources的组合正是 evidence.md 所称map every TOKEN_SCHEMA binding back to the committed tokens.css declaration line的实现形态。四层 Token 模型A1-identity / A1-structure / A2 / B-slot要读懂layerCounts需要了解 design-systems/_schema/AGENTS.md 中定义的四层模型。每个共享 token 回答两个问题谁决定值品牌作者 A 层还是 schema 作者 B-slot 层品牌缺省时会发生什么required / fallback / alias。层谁决定品牌缺省时示例A1-identity品牌guard 失败必填--bg、--fg、--accent、--font-displayA1-structure品牌guard 失败必填字号刻度、--container-max、--section-y-*A2品牌带 fallback当前 guard 失败未来由派生脚本填充--motion-fast、--success、--space-4、--font-monoB-slot品牌或 schema 建议别名guard 失败——品牌必须声明--fg-2 → var(--fg)、--surface-warm → var(--surface)Corporate 包的分布为A1-identity 8 个、A1-structure 18 个、A2 26 个、B-slot 4 个。值得注意的是两个实现细节B-slot 采用了独立值而非别名折叠。schema 建议的默认写法是--fg-2: var(--fg)品牌对丰富层无意见时照抄别名但 Corporate 选择绑定独立值--fg-2: #344054、--surface-warm: #eaf1ff、--meta: #2563eb、--border-soft: #edf2f8——两种写法都满足design-system: B-slot required tokensguard但独立值意味着品牌对丰富层有明确立场A2 当前必须显式声明。因为 agent 生成的产物是把单个品牌的:root块直接粘贴进一个style没有全局样式表兜底缺少任一 A2 token 都会导致transition: var(--motion-fast)这类规则静默失效。因此在未来的 derive 脚本落地前每个品牌必须声明每个 A2 token是唯一安全的契约design-system: A2 required tokensguard 严格强制。56 个 Token 完整清单按类别组织的取值与行号以下依据 source/token-contract.report.json 与 tokens.css第 7–62 行列出全部 56 个 token 的解析值。所有 token 的confidence均为high。颜色16 个Token值层tokens.css 行--bg#f5f8ffA1-identity7--surface#ffffffA1-identity8--surface-warm#eaf1ffB-slot9--fg#101828A1-identity10--fg-2#344054B-slot11--muted#667085A1-identity12--meta#2563ebB-slot13--border#d7e0efA1-identity14--border-soft#edf2f8B-slot15--accent#2563ebA1-identity16--accent-on#ffffffA217--accent-hovercolor-mix(in oklab, var(--accent), black 8%)A218--accent-activecolor-mix(in oklab, var(--accent), black 14%)A219--success#16a34aA220--warn#f59e0bA221--danger#ef4444A222hover/active 使用 CSScolor-mix(in oklab, ...)从--accent派生避免手写近似色值——这正是 evidence.md Token Contract 精神的落地交互态也由 token 表达。字体与排版12 个Token值层行--font-displayInter, system-ui, sans-serifA1-identity23--font-bodyInter, system-ui, sans-serifA1-identity24--font-monoSF Mono, ui-monospace, Menlo, monospaceA225--text-xs12pxA1-structure26--text-sm14pxA1-structure27--text-base16pxA1-structure28--text-lg18pxA1-structure29--text-xl24pxA1-structure30--text-2xl36pxA1-structure31--text-3xl54pxA1-structure32--text-4xl76pxA1-structure33--leading-body/--leading-tight/--tracking-display1.52/1.06/-0.025emA1-structure34–36间距、区块与圆角15 个Token值层行--space-1…--space-64px8px12px16px20px24pxA237–42--space-8/--space-1232px/48pxA243–44--section-y-desktop/-tablet/-phone96px/68px/48pxA1-structure45–47--radius-sm/-md/-lg/-pill10px/16px/24px/9999pxA248–51间距遵循 8pt 基线网格4/8/12/16/20/24/32/48与 DESIGN.md 第 4 节 8pt baseline grid 的约束一致区块纵向留白按 desktop/tablet/phone 三档响应式取值。阴影、动效与容器13 个Token值层行--elev-flatnoneA252--elev-ring0 0 0 1px var(--border)A253--elev-raised0 20px 52px rgba(16, 24, 40, 0.11)A254--focus-ring0 0 0 4px rgba(37, 99, 235, 0.22)A255--motion-fast/--motion-base150ms/240msA256–57--ease-standardcubic-bezier(0.2, 0, 0, 1)A258--container-max1180pxA1-structure59--container-gutter-desktop/-tablet/-phone36px/24px/16pxA1-structure60–62动效时长落在 DESIGN.md 第 7 节建议的 150–250ms 区间缓动采用稳定的标准曲线容器最大宽度 1180px、三档 gutter 与 components.html 中的媒体查询1023px / 639px 断点配套使用。一个值得注意的文档差异DESIGN.md 第 2 节的 prose 中写 Primary 为#3B82F6而编译后的tokens.css中--accent与--meta实际取值为#2563eb。从证据链看token-contract.report.json的sources全部指向tokens.css因此以tokens.css的编译值为准这也印证了 USAGE.md 中不要把 DESIGN.md 的散文当作最终 token 值的契约设计意图。派生输出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.即tokens.css是唯一事实源而 design-tokens.jsonDesign Tokens JSON与 tailwind-v4.cssTailwind v4theme都是派生产物。这一规则在源码层面有明确实现packages/contracts/src/design-systems/derived-token-outputs.ts 提供了两个渲染函数renderDesignTokensJson(...)把 bindings report 渲染为od-design-tokens/v1格式的 JSON其中每个 token 通过inferDesignTokenType(name)按前缀推断类型--bg/--accent等为color--font-*为fontFamily--leading-*为number--motion-*为duration--elev-*/--focus-ring为shadow--text-*/--space-*/--radius-*/--container-*等为dimensionrenderTailwindV4Css(bindings)基于TAILWIND_V4_THEME_BINDINGS这张 57 条映射表生成theme块且只输出在tokens.css中实际声明过的 token。TAILWIND_V4_THEME_BINDINGS展示了命名空间的翻译规则--color-bg → var(--bg)、--color-accent-hover → var(--accent-hover)、--spacing-section-desktop → var(--section-y-desktop)、--shadow-raised → var(--elev-raised)、--duration-fast → var(--motion-fast)等。对应地tailwind-v4.css 文件头注释明确写着/* Derived from tokens.css. Keep tokens.css as the source of truth. */ import tailwindcss; import ./tokens.css;因此正确的维护方式是修改tokens.css或source/token-contract.report.json然后重新运行派生逻辑仓库中scripts/目录下存在配套的生成与校验脚本而不是直接手改两个派生文件。组件 Fixturecomponents.html 与组件清单的 token 引用关系components.html 是 Corporate 组件的参考实现其style块首部就是与tokens.css逐字一致的:root粘贴块第 9–66 行随后是 48 个选择器定义的组件样式。对应的 components.manifest.json 记录了 fixture 统计与 token 引用审计fixture 统计1 个 style 块、48 个选择器、26 个类、19 个元素token 审计56 个 declared、55 个 referenced、7 个 unusedDeclared--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn、0 个 undeclaredReferenced——即组件中引用的每个 token 都有声明反向无遗漏组件分组present 为 true 的 8 组buttons引用--accent、--accent-on、--border、--ease-standard、--elev-ring、--fg、--font-body、--motion-fast、--radius-md、--space-5、--surface、--text-sm共 12 个 token、inputs、cards、badges、links、typography、layoutkeyboard、icons 两组为present: false。组件组与 token 的引用映射是证据链的延伸components.html中的.btn-primary { background: var(--accent); color: var(--accent-on); }直接消费 A1-identity 层 token而.panel { ... box-shadow: var(--elev-raised); }消费 A2 层 token——通过这份清单可以快速确认哪些 token 真正被组件使用、哪些仍处于备用状态。实战使用USAGE 读取顺序与守则USAGE.md 为 agent 与评审者提供了推荐的读取顺序先读本文件理解包契约读DESIGN.md理解视觉意图、约束与反模式把tokens.css粘贴进第一个产物的style块再写组件 CSS用components.manifest.json做紧凑的组件盘点需要精确选择器或状态时打开components.html需要视觉 sanity check 时查看preview/页面。配套的 Do / Avoid 守则中与证据体系直接相关的两条是Do——Treatsource/files as audit evidence for the bundled fixture backfill即把source/目录视为审计证据Avoid——Avoid redefining Tailwind or design-token values independently oftokens.css即禁止绕过tokens.css单独重定义派生值。此外 manifest.json 的craft.suggested建议配套应用color与accessibility-baseline两份 craft 规范见仓库 craft/ 目录preview/目录提供 colors.html、typography.html、spacing.html 三个静态预览页。总结何时信任证据、何时重建token-contract.report.json的recommendRebuild: false与grade: excellent表示当前包内 56 个 token 全部被tokens.css声明背书、A1 层全部有源、无别名绑定、无未声明引用契约处于健康状态无需重建。需要重建的触发条件是修改了tokens.css、更新了source/tokens.source.json或 schema 本身如新增/重命名 token 时需同步更新defaults.css与各品牌tokens.css否则 drift guard 会失败。对使用 OpenDesign 设计系统的人来说source/evidence.md及其配套文件提供了一个可复用的范式每个 token 都应有明确的来源声明、精确到行的绑定证据以及唯一事实源 派生输出的文件分层。Corporate 包就是这一范式的一个完整范例——从bundled fixture backfill的证据边界声明到 56 个 token 逐条映射tokens.css行号再到design-tokens.json/tailwind-v4.css只可重新生成、不可手改的工程纪律构成了一条端到端可审计的设计系统证据链。【免费下载链接】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），仅供参考