OpenDesign 设计系统溯源机制以 Pacman 主题包为例解读 Evidence 文档与 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/pacman/source/evidence.md是 OpenDesign 设计系统 2.0 架构中每套品牌主题都必备的溯源证据文件。它以 Pacman经典街机迷宫风主题为样本说明了当前仓库中的设计系统包不是对上游官网的全新爬取结果而是基于仓库内已精选的 bundled fixture内置夹具回填backfill而来的同时它声明了 Token 合约TOKEN_SCHEMA与tokens.css声明行之间的逐条映射关系。读完本文你将掌握Pacman 包的文件结构与证据边界、56 个设计令牌的四层分层契约A1-identity / A1-structure / A2 / B-slot、source/token-contract.report.json报告字段的语义以及为什么design-tokens.json与tailwind-v4.css必须由报告派生而非手工编辑。一、Evidence 文件在整个设计系统中的角色在 OpenDesign 仓库中每套设计系统包如design-systems/pacman/都遵循统一的包结构约定。Pacman 包的manifest.jsondesign-systems/pacman/manifest.json将包内的文件划分为三组设计意图与实现DESIGN.md、tokens.css、design-tokens.json、tailwind-v4.css、components.html使用与预览USAGE.md、components.manifest.json、preview/colors.html、typography.html、spacing.html溯源证据source/evidence.md、source/tokens.source.json、source/token-contract.report.json。source/evidence.md位于第三组其定位是审计证据audit evidence正如 design-systems/pacman/USAGE.md 中所述Treatsource/files as audit evidence for the bundled fixture backfill.二、Source Scope诚实声明数据来源边界Evidence 文件的第一节 Source Scope 做了两个关键声明数据来源是 OpenDesign 仓库内置的精选夹具curated bundled fixture而不是对上游 Pacman 品牌仓库或官网的一次全新爬取fresh crawl因此不要声称存在原始上游来源证据——这是USAGE.md中明确列出的 Avoid 项之一。这一点在manifest.json的source字段中得到印证type: bundled、origin: OpenDesign curated bundled fixture。而在报告文件的每个 token 条目中reason字段也统一写着 Bundled tokens.css declares ...; no upstream recrawl was performed for this backfill. 这种逐条声明来源边界的做法保证了设计系统包的可审计性任何人打开 evidence 文件都能立刻判断哪些结论是仓库内证据可支撑的哪些不是。三、Included Fixture FilesPacman 包的三个输入源Evidence 文件列出的三个夹具文件构成了 Pacman 包的原始输入文件相对路径内容角色设计规范design-systems/pacman/DESIGN.md视觉主题、色彩、字体、间距、组件、动效、语气与反模式令牌样式表design-systems/pacman/tokens.css56 个 CSS 自定义属性的权威声明--bg到--container-gutter-phone组件参考design-systems/pacman/components.html参考组件实现components.manifest.json据此统计出 48 个选择器、26 个类、19 个元素source/tokens.source.jsondesign-systems/pacman/source/tokens.source.json与这三者一一对应它的files数组正是DESIGN.md、tokens.css、components.html且每个 token 都带source: tokens.css:行号精确到声明行。Pacman 的设计语言结合 DESIGN.md 可以理解这三个夹具为何构成一个自洽的整体Pacman 主题的视觉核心是经典街机迷宫语言——黑色面板--bg: #050505、黄色信号--accent: #ffcc00、圆润的计分胶囊--radius-lg/--radius-pill: 9999px。tokens.css的文件头注释也复述了这一意图/* Structured token bindings for Pac-Man. * classic arcade maze language with black board, yellow signal, and rounded score capsules. */四、Token Contract56 个令牌如何被逐条映射Evidence 文件的第三节是全文的技术核心。它描述了source/token-contract.report.json的作用将 TOKEN_SCHEMA 中的每一个绑定映射回已提交的tokens.css声明行。4.1 报告文件的关键指标source/token-contract.report.json 的summary给出了这份契约的量化体检结果指标值含义totalTokens56模式中共计 56 个令牌declaredTokens56tokens.css中实际声明 56 个sourceBackedTokens56全部 56 个都被tokens.css声明行支撑sourceBackedA126A1 层identity structure26 个全部有源fallbackTokens26A2 层 26 个令牌使用了模式内 fallback 值aliasTokens0本包没有使用var()别名降级score / grade100 / excellent合约完整度满分recommendRebuildfalse无需重建派生产物4.2 四层令牌分层报告中每个 token 都带一个layer字段取值来自 TOKEN_SCHEMA 的四层契约。Pacman 包的层分布为A1-identity8 个--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-body——这些令牌本身就是品牌没有跨品牌的合理默认值任何品牌都必须亲自书写A1-structure18 个字号阶梯--text-xs到--text-4xl、行高、字距、区块节奏--section-y-*、容器--container-max、--container-gutter-*——同样是品牌必须自定的结构决策A226 个--accent-on/hover/active、语义色、间距阶梯、圆角、阴影、动效时长等——必须有值但存在跨品牌合理默认B-slot4 个--surface-warm、--fg-2、--meta、--border-soft——可选槽位品牌若无更丰富层级可别名到相邻令牌。这四层契约的定义在源码中有权威注释见 packages/contracts/src/design-systems/token-schema.ts_schema/tokens.schema.tsdesign-systems/_schema/tokens.schema.ts只是该文件的兼容性再导出。4.3 逐条映射示例以报告前几条为例映射关系一目了然{ name: --bg, layer: A1-identity, value: #050505, confidence: high, sources: [tokens.css:8], sourceName: --bg }tokens.css:8对应 tokens.css 第 8 行的--bg: #050505;。A2 令牌还额外带有 fallback 语义例如{ name: --accent-hover, layer: A2, value: color-mix(in oklab, var(--accent), black 8%), sources: [tokens.css:19] }其 fallbackcolor-mix(in oklab, var(--accent), black 8%)定义在token-schema.ts的TOKEN_SCHEMA中与_schema/defaults.cssdesign-systems/_schema/defaults.css保持字节级一致并由仓库的 design-system: A2 defaults parity guard 检查强制同步见 packages/contracts/src/design-systems/token-schema.ts 中的说明。4.4 为什么 A2 是带默认值的必填而非可选token-schema.ts的文件头注释解释了这一设计动机OpenDesign 的产物artifact由 Agent 把某个品牌的:root块粘贴进单个style生成运行时不存在全局默认样式表的级联。如果一个 Agent 粘贴的tokens.css缺少某个var()目标产物就会损坏——例如var(--motion-fast)解析为空transition: var(--motion-fast)变成transition:整条规则被浏览器丢弃。因此运行时契约是每个tokens.css必须声明全部 A1 A2 B-slot 令牌而_schema/defaults.css里的 fallback 只服务于派生脚本的内联。Pacman 的tokens.css恰好完整覆盖了全部 56 个令牌这也是报告能拿到 100 分的原因。五、派生产物design-tokens.json 与 tailwind-v4.cssEvidence 文件最后一句给出了一条明确的工程纪律design-tokens.json和tailwind-v4.css是派生输出应从报告与令牌样式表重新生成而不是手工编辑。design-tokens.json 是 TOKEN_SCHEMA 契约contract: TOKEN_SCHEMA的机器可读版本每个 token 增加了type字段如type: colorsummary与报告完全一致sources同样指向tokens.css:行号tailwind-v4.css 以import tailwindcss; import ./tokens.css;开头在theme块中将 CSS 变量桥接为 Tailwind v4 主题命名空间--color-accent→var(--accent)、--font-display→var(--font-display)、--spacing-*→var(--space-*)、--shadow-*→var(--elev-*)、--duration-*→var(--motion-*)等。因为这两个文件都标注了 Derived from tokens.css. Keep tokens.css as the source of truth.手工修改它们会导致派生链断裂正确的维护路径永远是改tokens.css→ 依据token-contract.report.json重新派生。六、组件清单Evidence 的另一层验证虽然 evidence 文件只列了三个夹具文件但包内的 components.manifest.json 从组件侧为契约提供了交叉验证fixture统计1 个style块、48 个选择器、26 个类、19 个元素tokens.declared列出全部 56 个声明令牌tokens.referenced列出组件实际引用到的令牌unusedDeclared如--accent-active、--danger、--warn、--elev-flat、--motion-base、--space-1、--space-12提醒哪些令牌已声明但组件尚未使用groups按组件族buttons / inputs / cards / badges / links / typography / layout给出每个组引用的令牌集合——例如 buttons 组引用--accent、--accent-on、--border、--ease-standard、--radius-md、--motion-fast等 12 个令牌与 DESIGN.md 中主按钮用#2A3FE5强调、次级动作保持中性的组件规范相互印证注DESIGN.md列出的#2A3FE5是样式基础层style foundations的引用值实际tokens.css中主交互信号由--accent: #ffcc00承载。七、如何在 OpenDesign 中消费这套证据体系对想要复用 Pacman 主题或研究其他设计系统包的开发者推荐按 USAGE.md 的读序操作先读USAGE.md理解包契约读DESIGN.md把握视觉意图、约束与反模式把tokens.css原样粘贴进第一个产物的style块再写组件 CSS——切勿在:root令牌块之外使用裸十六进制色值用components.manifest.json做组件清单速查需要精确选择器或状态时再打开components.html需要视觉核对时打开preview/下的colors.html、typography.html、spacing.html把source/下的三个文件当作 bundled fixture 回填的审计证据。对 Agent 和审查者而言evidence 文件 契约报告构成了一套可机读、可校验的设计系统事实层任何令牌值是否被tokens.css支撑、属于哪一层、是否使用了 fallback、是否触发重建都能通过source/token-contract.report.json直接判定无需人工翻阅样式表逐行核对。八、小结source/evidence.md虽短却定义了 OpenDesign 设计系统 2.0 回填流程的完整契约来源诚实bundled fixture 而非上游爬取 逐条映射TOKEN_SCHEMA ↔ tokens.css 行号 派生纪律design-tokens.json 与 tailwind-v4.css 只重生成不手改。Pacman 包作为 Themed Unique 类别下的一个完整样本展示了黑色面板、黄色信号、圆角胶囊的街机语言如何在四层令牌契约中落地也展示了仓库如何用token-contract.report.json的 100 分评分与excellent评级让设计系统的完整性与可审计性变得可量化、可验证。理解这套机制后你可以用同样的读法快速上手仓库中其他 100 套设计系统包如 design-systems/openai、design-systems/linear-app、design-systems/neon 等并安全地将任意一套主题注入 Agent 生成的 HTML 产物。【免费下载链接】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），仅供参考