OpenDesign 设计系统源证据与 Token 合约Lamborghini 包的可追溯性审计机制解析【免费下载链接】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设计系统 2.0Design System 2.0为 OpenDesign 引入了可审计的源证据source evidence体系每个设计系统包不仅要交付可用的 tokens、组件与视觉规范还必须说明这些内容从何而来、可信度如何。本文以 design-systems/lamborghini 包为实例拆解其source/evidence.md声明、Token 合约报告token-contract.report.json的追溯机制、以及派生产物design-tokens.json、tailwind-v4.css与源文件之间的生成关系帮助你理解 OpenDesign 设计系统包的目录契约与审计语义并掌握在 Agent 工作流中正确使用这套包的方法。一、源证据是什么包的来源声明与边界阅读 source/evidence.md 会发现它不是一份普通的设计文档而是一份来源审计声明回答了三个关键问题包的来源范围Source Scope该包是Design System 2.0 backfill源自 OpenDesign 捆绑的精选 fixturecurated bundled fixture不声称对原始上游品牌仓库或网站进行了全新爬取It does not claim a fresh crawl of the original upstream brand repository or website。包含的 fixture 文件明确列出了三个支撑文件——DESIGN.md视觉规范、tokens.cssToken 声明、components.html参考组件。Token 合约Token Contract声明source/token-contract.report.json将每一个TOKEN_SCHEMA绑定映射回已提交的tokens.css声明行而design-tokens.json与tailwind-v4.css是派生输出应基于报告与 token 样式表重新生成而非手工编辑。这一声明的价值在于诚实性边界它明确区分了基于上游品牌观察整理的规范与对上游代码的抓取避免 Agent 或审查者误把二次整理素材当作品牌官方源码。这一点在包级元数据中也有对应体现——manifest.json 的source字段标记为{ type: bundled, origin: OpenDesign curated bundled fixture }并采用importMode: normalized的导入模式。二、包的目录契约四层文件体系整个 lamborghini 包 遵循固定的目录契约从 manifest.json 的files字段可以还原出完整映射层级文件角色视觉规范DESIGN.md品牌视觉意图、约束与反模式Dos and DontsToken 源tokens.css56 个 CSS 自定义属性的唯一事实来源参考组件components.html组件选择器与状态的精确参考组件清单components.manifest.json紧凑的组件清单26 个类、48 个选择器、19 个元素派生产物design-tokens.json、tailwind-v4.css由 tokens.css 合约报告生成禁止手改审计证据source/evidence.md、source/token-contract.report.json、source/tokens.source.json来源声明、Token 绑定报告、Token 快照视觉预览preview/colors.html、preview/typography.html、preview/spacing.html颜色、排版、间距的视觉核对页从源码结构看source/目录承载的是审计证据职责USAGE.md 明确要求Treatsource/files as audit evidence for the bundled fixture backfill——即source/下的文件用于证明捆绑 fixture 回填的可追溯性而非直接供组件引用。三、Token 合约报告从 Token 名到 CSS 声明行的双向映射Token 合约机制是这套审计体系的核心。source/token-contract.report.json 以TOKEN_SCHEMA为契约为每一个 Token 记录四个关键字段{ name: --bg, layer: A1-identity, value: #050505, confidence: high, sources: [tokens.css:8], sourceName: --bg }其中name与sourceName报告内的 Token 名与被绑定的 CSS 变量名layerToken 所属的语义分层详见下文value解析后的最终值sources以tokens.css:行号形式精确指向声明行——这是可追溯的关键证据confidence本次报告中全部为high理由统一为Bundled tokens.css declares …; no upstream recrawl was performed for this backfill捆绑 tokens.css 已声明该 Token本次回填未执行上游重新爬取。3.1 四个语义分层报告把 56 个 Token 划分为四个层级layerCounts层级数量语义A1-identity8品牌身份层--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-bodyB-slot4插槽层--surface-warm、--fg-2、--meta、--border-softA226功能/组件级 Token交互态、语义色、间距、圆角、阴影、动效等A1-structure18结构层字号阶梯、行高、字距、区块间距、容器约束从分层可以推断这套 TOKEN_SCHEMA 的设计意图A1-identity承载不可妥协的品牌识别值A1-structure承载排版与布局骨架B-slot是品牌色向组件槽位的桥接A2则是可被组件自由消费的功能 Token。跨品牌切换时正是依靠保持A1层 Token 名不变、仅替换值才能实现 USAGE.md 中所说的cross-brand switching stays reliable。3.2 统计指标与分级报告summary块给出的关键审计指标如下{ totalTokens: 56, declaredTokens: 56, sourceBackedTokens: 56, sourceBackedA1: 26, fallbackTokens: 26, aliasTokens: 0, score: 100, grade: excellent, recommendRebuild: false }totalTokens/declaredTokens均为 56说明没有缺失声明sourceBackedTokens: 56说明每个 Token 都能在tokens.css中找到声明行sourceBackedA1: 26对应A1-identity8A1-structure18即品牌身份与结构层全部有源支撑fallbackTokens: 26恰好等于A2层数量可推断A2层 Token 使用了回填值其值同样来自捆绑的tokens.css但语义上属于功能回退而非品牌识别aliasTokens: 0即没有 Token 以别名alias形式引用其他 Token综合score: 100、grade: excellent、recommendRebuild: false表示该包契约完整无需重建。四、派生产物design-tokens.json 与 tailwind-v4.css 的生成关系evidence.md 特别强调design-tokens.json与tailwind-v4.css是派生输出derived outputs应从token-contract.report.json与tokens.css重新生成而不应手工编辑。这意味着它们不是第二份事实来源而是同一份真相的两种工程化投影design-tokens.json 将 56 个 Token 投影为带type的 JSON 结构color、fontFamily、dimension、number、shadow、duration、cubicBezier供需要程序化读取 Token 的工具链消费tailwind-v4.css 文件头直接写明 Derived from tokens.css. Keep tokens.css as the source of truth.并通过 Tailwind v4 的theme指令把tokens.css的:root变量逐项映射为 Tailwind 主题变量例如--color-accent: var(--accent)、--spacing-4: var(--space-4)、--shadow-raised: var(--elev-raised)。从文件头注释与映射结构可以确认工程链路为tokens.css唯一事实来源→token-contract.report.json绑定审计→ 生成design-tokens.json与tailwind-v4.css。因此任何 Token 值调整都应落在tokens.css的:root块内再重新生成派生产物避免两处漂移。五、Token 源文件tokens.css 的 56 个绑定tokens.css 是整条链路的根。其:root块按语义分组声明了全部 56 个 Token每组与token-contract.report.json的layerCounts一一对应颜色品牌身份与插槽--bg: #050505、--surface: #141414、--surface-warm: #211b0b、--fg: #f8f4e6、--fg-2: #d8ceb0、--muted: #9b927d、--meta: #d4af37、--border: #3a321d、--border-soft: #282315、--accent: #d4af37、--accent-on: #050505。交互与语义色--accent-hover: color-mix(in oklab, var(--accent), black 8%)、--accent-active: color-mix(in oklab, var(--accent), black 14%)、--success: #39a852、--warn: #f7c948、--danger: #e63946。值得注意的是hover/active 态使用 CSScolor-mix(in oklab, …)从基准色派生而非硬编码另一组 hex——这正是单一事实来源思想的体现。字体与排版--font-display: Lamborghini, Eurostile, Arial, sans-serif、--font-body: Inter, Arial, sans-serif、--font-mono: SF Mono, ui-monospace, Menlo, monospace字号阶梯--text-xs: 12px至--text-4xl: 90px行高--leading-body: 1.48、--leading-tight: 0.96字距--tracking-display: -0.025em。间距与容器8px 基数衍生出--space-1: 4px到--space-12: 48px区块纵向留白--section-y-desktop: 112px/--section-y-tablet: 80px/--section-y-phone: 56px容器约束--container-max: 1240px与三个断点的 gutter40px / 28px / 18px。圆角、阴影与动效--radius-sm: 2px至--radius-pill: 9999px--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised: 0 28px 84px rgba(0,0,0,0.54)、--focus-ring: 0 0 0 4px rgba(212,175,55,0.32)时长--motion-fast: 120ms、--motion-base: 210ms缓动--ease-standard: cubic-bezier(0.16, 1, 0.3, 1)。components.html 第 11–69 行的style块原样内嵌了这一整套:root声明可作为Token 先于组件这一使用约束的现场印证。六、使用方式OpenDesign Agent 与审查者的阅读顺序USAGE.md 给出了明确的包消费顺序这也是 Agent 生成页面时的实操指引先读USAGE.md理解包契约再读 DESIGN.md 获取视觉意图、约束与反模式把 tokens.css 的:root块整体粘贴到第一个 artifact 的style块中再编写组件 CSS用 components.manifest.json 做组件清单速查需要精确选择器或状态时打开 components.html需要视觉核对时打开preview/下的 colors.html、typography.html、spacing.html。同时USAGE.md 划定了四条硬性约束保留 schema Token 名不变以保证跨品牌切换可靠使用--accent承担主操作、链接、焦点态与唯一视觉焦点避免在:root之外使用裸 hex 值优先复用components.manifest.json中的组件分组而不是发明新控件不得声称持有原始上游来源证据——本包基于捆绑 fixture且不得添加components.html或DESIGN.md未覆盖的新组件配方。6.1 组件清单佐证components.manifest.json 的groups数组显示该包已覆盖 8 类组件组中的 6 类buttons、inputs、cards、badges、links、typography、layoutkeyboard 与 icons 标记为present: false。其中 buttons 组引用了--accent、--accent-on、--elev-ring、--radius-md、--space-5、--text-sm等 Tokencards 组引用--elev-raised、--radius-lg、--muted等。同时报告了undeclaredReferenced: []与unusedDeclared列表含--danger、--warn、--space-1等 7 个声明但未在组件中使用的 Token——这套声明 / 引用 / 未使用 / 未声明的对照本身就是 Token 治理的一部分。6.2 视觉规范要点供 Agent 生成时对照DESIGN.md 定义了黑底 单一金色强调的极简体系可作为生成页面时的风格校验清单页面以纯黑#000000为底Token 化为--bg: #050505--accent#d4af37接近品牌 Gold仅用于主 CTA显示级标题一律大写、行高 0.92–1.19、字距收紧按钮与卡片圆角为 0Token 化为--radius-sm: 2px起档深度不靠阴影而靠表面明度分层#000000 → #181818 → #202020 → #494949对应 Token 化的--bg → --surface与--elev-*阴影族hover 交互只允许颜色/透明度变化禁止 scale 与 translate 动画。七、小结证据链、事实源与工程化的三层关系综合 source/evidence.md 与包内各文件可以归纳出 OpenDesign 设计系统 2.0 包的三层数据关系事实源source of truthtokens.css的:root声明与DESIGN.md的视觉规范审计层audit evidencesource/token-contract.report.json将 56 个 Token 逐一绑定到tokens.css:行号source/tokens.source.json提供 Token 快照source/evidence.md声明来源范围与非上游爬取的边界工程投影derived outputsdesign-tokens.json程序化 JSON与tailwind-v4.cssTailwind v4theme映射由审计层与事实源重新生成禁止手工编辑。对使用这套体系的 Agent 而言正确姿势是以USAGE.md为入口、以tokens.css为唯一事实源、以components.manifest.json为组件复用清单、以source/为可追溯性审计凭证——既拿到了可运行的视觉系统也保留了每个值从哪一行声明而来的完整证据链。【免费下载链接】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），仅供参考
