OpenDesign Bold 设计系统的来源证据与 Token Contract 审计机制解析【免费下载链接】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/bold/source/evidence.md 为骨架结合 Bold 设计系统包内的全部配套文件讲解 OpenDesign 中Design System 2.0 backfill的来源范围声明Source Scope、三类核心 fixture 文件的分工以及基于 TOKEN_SCHEMA 契约的 Token 可追溯审计机制。读完你将理解为什么tokens.css是唯一事实源、token-contract.report.json如何把每个 Token 逐行映射回声明位置、design-tokens.json与tailwind-v4.css为何必须从报告重新生成而不是手工编辑以及这套证据链如何在 Agent 生成与评审流程中保证跨品牌切换的可靠性。1. 背景Design System 2.0 与 bundled fixture backfillOpenDesign 仓库的design-systems/目录下维护着数百个风格各异的设计系统包每个包都遵循统一的项目清单manifest 设计规范DESIGN.md Token 样式表tokens.css 组件参考components.html 审计证据source/结构。BoldBold Expressive 类别就是其中之一其包级清单 manifest.json 采用od-design-system-project/v1schema声明了包的 id、名称、类别、来源类型type: bundled、文件清单、craft 建议color、accessibility-baseline与预览页面。这份source/evidence.md是包内审计证据入口文档它回答了一个关键问题这套 Bold 设计系统内容是从哪里来的答案直接关系到后续所有 Token、组件和派生文件的信任边界因此它被设计为包内所有生成类产物的出处声明。2. 来源范围Source Scopecurated bundled fixtureevidence.md 第一部分明确了 Bold 包的取证边界This 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.这句话是理解整个包的前提它包含两个事实这是 backfill回填产物Bold 包是对既有风格家族的补全包内容来自 OpenDesign 内部精选过的 bundled fixture而非从上游品牌官网或品牌仓库重新抓取recrawl。不宣称上游一手证据因此 USAGE.md 的 Avoid 清单中明确写有避免声称拥有原始上游来源证据Avoid claiming original upstream source evidence; this package is based on the curated bundled fixture。这套来源自证的设计意图在于当 Agent 或评审者拿到一个设计系统包时能立刻判断其中的颜色、字体、间距等数值属于经审核的官方打包内容还是待核验的抓取内容避免在后续生成 HTML 时把未经证实的品牌资料当作既定事实使用。这种边界意识同样体现在 token-contract.report.json 中每个 Token 的 reason 字段——每条都注明Bundled tokens.css declares ...; no upstream recrawl was performed for this backfill。3. 包内三类核心 fixture 文件evidence.md 明确列出了组成 Bold 包主体的三个 fixture 文件它们的角色各不相同文件角色内容要点DESIGN.md视觉意图与约束规范风格类别、配色立场、排版规模、间距网格、组件策略、动效时长、语气与反模式tokens.cssToken 唯一事实源56 个 CSS 自定义属性全部声明在:root块中components.html组件参考实现完整组件 HTML/CSS配套清单 components.manifest.json3.1 DESIGN.md视觉意图DESIGN.md 描述 Bold 的视觉气质为heavyweight typography, high-contrast colors, commanding layouts重型字体、高对比色、有统治力的版式并给出风格家族的推荐 TokenPrimary#0077BC、Secondary#009866、Success/Warning/Danger 语义色、Surface#111111、Text#111827。排版采用 desktop-first expressive scale展示字体建议 Archivo Black等宽字体 JetBrains Mono字重覆盖 100–900间距采用 4/8/12/16/24/32 的刻度动效建议 150–250ms 的短促过渡。需要注意的是DESIGN.md 是风格家族意图层面的描述inspired by Bold而包内实际落地的 Token 值以tokens.css为准——例如 tokens.css 中--accent: #111111、--font-display: Arial Black, Impact, sans-serif对应 manifest 中hard contrast, oversized type, and assertive actions的极简黑白表达。这正是 evidence.md 所强调的bundled fixture特性包内呈现的是经 curated 的、可用的设计语言实现而非原品牌页面的逐字复刻。3.2 tokens.css唯一事实源tokens.css 的头部注释点明了设计意图bold campaign language with hard contrast, oversized type, and assertive actions全部 56 个 Token 集中在:root中按职责可分为颜色层--bg、--surface、--surface-warm、--fg、--fg-2、--muted、--meta、--border、--border-soft、--accent、--accent-on、--accent-hover、--accent-active、--success、--warn、--danger字体层--font-display、--font-body、--font-mono字号/行高/字距层--text-xs12px到--text-4xl76px共 9 档--leading-body1.52、--leading-tight1.06、--tracking-display-0.025em间距层--space-14px到--space-1248px共 8 档以及分断点化的区块纵向间距--section-y-desktop/tablet/phone96/68/48px形状与层级--radius-sm/md/lg/pill4/8/12/9999px、--elev-flat/ring/raised、--focus-ring动效层--motion-fast150ms、--motion-base240ms、--ease-standardcubic-bezier(0.2, 0, 0, 1)容器层--container-max1180px与三档 gutter桌面 36px / 平板 24px / 手机 16px。一个值得注意的实现细节--accent-hover与--accent-active使用 CSScolor-mix(in oklab, var(--accent), black 8% / 14%)语法从基准色派生而不是硬编码新的十六进制值。这既保证了交互状态与主色永远同源也体现了能用现有 Token 解决就不引入 off-palette 颜色的设计约束见 DESIGN.md 反模式第一条。3.3 components.html组件参考与清单components.manifest.json 是对 components.html 的机器可读提炼它统计出1 个 style 块、48 个选择器、26 个类、19 个元素并将组件归纳为 9 个分组groupsbuttons按钮与 CTA.btn、.btn-primary、.btn-secondary及其 hover/focus-visible 状态引用--accent、--accent-on、--radius-md、--motion-fast等 12 个 Tokeninputs表单控件.field、input、label含input:focus状态cards卡片与面板.card-row、.panel、.panel-head、.tilebadges徽标与状态标签.status含::before指示点links链接、typography排版工具.eyebrow、.lead、h1–h3、layout布局原语.container、section、.metric-gridkeyboard键盘提示与 icons图标槽位present: false即该包未提供这两类组件。清单还做了 Token 引用审计referenced列出组件实际引用的 TokenunusedDeclared列出声明但组件未使用的 7 个 Token--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warnundeclaredReferenced为空——说明组件中不存在引用了却没声明的悬空 Token这正是可审计性的体现。该清单的literals统计3 个颜色字面量、24 个像素值、4 个硬编码字体族也为人工 review 提供了还有多少硬编码需要收敛的量化指标。4. Token Contract逐行可追溯的审计报告evidence.md 的核心落在 Token Contract 机制上source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.source/token-contract.report.json 是一份 schemaVersion 1 的契约报告它把TOKEN_SCHEMA中的每一个绑定映射回tokens.css的具体声明行。这份报告可以这样读总量totalTokens: 56、declaredTokens: 56、sourceBackedTokens: 56即全部 Token 都能在 tokens.css 中找到对应声明无一条无源 Token分层统计layerCounts将 56 个 Token 划分为四个层级——A1-identity8 个品牌身份色/字体如--bg、--fg、--accent、--font-display、B-slot4 个槽位型派生色如--surface-warm、--fg-2、A226 个语义与功能 Token如--success、--space-*、--radius-*、--elev-*、A1-structure18 个结构型 Token如--text-*、--section-y-*、--container-*置信度sourceBackedA1: 26表示 26 个 A1 层 Token 有源支撑另有fallbackTokens: 26、aliasTokens: 0评分score: 100、grade: excellent、recommendRebuild: false表示当前包的契约完整度达到满分无需重建。每个 Token 条目都携带五元组name、layer、value、confidence: high、sources如tokens.css:7对应--bg的声明行。也就是说任何人拿到这份报告都能从某个 Token 叫什么、属于哪一层、值是什么、声明在哪一行四个维度完成一次完整的溯源核对。这种报告即审计凭证的做法让机器检查脚本比对声明行与人工 review 都有了确定的锚点。5. 派生产物管线为何从报告重新生成而非手改evidence.md 最后一段给出了一条明确的工程规则design-tokens.jsonandtailwind-v4.cssare derived outputs and should be regenerated from the report and token stylesheet rather than edited by hand.仓库中的两份派生文件印证了这一规则5.1 design-tokens.json类型化的 Token 全量清单design-tokens.json 采用od-design-tokens/v1格式在契约报告的基础上为每个 Token 增加了type字段把 CSS 自定义属性归类为 7 种类型color16 个、fontFamily3 个、dimension字号/间距/圆角/容器等、number--leading-*、shadow--elev-*、--focus-ring、duration--motion-*、cubicBezier--ease-standard。这份类型化清单可以直接被设计 Token 消费方如设计工具、代码生成器读取但它与tokens.css保持严格同源——头部source字段明确记录其来源是tokens.css与source/token-contract.report.json。5.2 tailwind-v4.cssTailwind v4 的 theme 桥接层tailwind-v4.css 是给 Tailwind CSS v4 项目使用的桥接文件结构为/* 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); --font-display: var(--font-display); --text-4xl: var(--text-4xl); --spacing-6: var(--space-6); --radius-lg: var(--radius-lg); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); --ease-standard: var(--ease-standard); /* ... 共 56 个映射 */ }它通过theme块把 Tailwind 命名空间的--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*、--duration-*全部指向tokens.css中的同名变量从而让开发者可以在 Tailwind 项目中直接使用bg-accent、text-4xl、shadow-raised等工具类而值永远来自同一份 Token 事实源。文件头注释Derived from tokens.css. Keep tokens.css as the source of truth.就是这条工程规则的浓缩表达。这两份派生产物与契约报告共享同一份summary56/56/56、score 100、excellent从侧面验证了三者由同一生成管线产出。因此在使用时若需要调整任何数值正确操作顺序是修改tokens.css→ 重新运行生成管线刷新design-tokens.json与tailwind-v4.css而不是直接编辑派生文件否则下一次重新生成会把手工改动覆盖掉造成两份文件不一致的漂移。6. 在 Agent 工作流中的使用方式USAGE.md 给出了 OpenDesign Agent 与评审者读取本包的推荐顺序它也是 evidence.md 机制的落地用法先读USAGE.md理解包契约再读DESIGN.md掌握视觉意图、约束与反模式把tokens.css粘贴到产物第一个style块中再编写组件 CSS——保证组件样式直接消费 Token 变量避免出现第二个颜色体系用components.manifest.json快速核对组件清单需要精确选择器或状态时再打开components.html需要视觉检查时打开 preview/colors.html、preview/typography.html、preview/spacing.html 三个预览页。USAGE.md 的 Do 清单与 evidence.md 呼应保留 schema Token 名称的精确拼写Preserve the schema token names exactly so cross-brand switching stays reliable——这是跨品牌切换可靠性的根基因为不同风格包共享同一套 TOKEN_SCHEMA 命名--accent、--surface这些槽位名不变只是值随包变化source/目录只作为审计证据使用不作为新组件的创作素材。Avoid 清单则进一步划清边界不要在复制的:rootToken 块之外使用裸十六进制值不要脱离tokens.css单独维护 Tailwind 或 design-token 的值不要新增components.html与DESIGN.md中不存在的组件配方。7. 反模式与约束保持风格纯度DESIGN.md 第九节给出了四条反模式它们与 evidence.md 的事实源唯一原则相互印证不引入 off-palette 颜色能用现有 Token 解决就不新增色值——这与避免裸 hex的用法约束一致不扁平化层级不要对所有文本使用同一种字号/字重Bold 的价值恰恰在 oversized type 与 body text 的对比不加损害可读性的装饰效果高对比风格的底线是可读性与可达性不混用无关视觉隐喻保持风格家族的统一辨识度。8. 小结一份可审计的设计系统包长什么样从source/evidence.md出发我们可以总结 OpenDesign 设计系统包的可审计闭环出处声明evidence.md说明内容来自 curated bundled fixture不冒充上游一手资料事实源tokens.css承载全部 56 个 Token是唯一允许手工修改的文件契约报告source/token-contract.report.json把每个 Token 逐行映射回tokens.css声明位置给出层级、置信度与评分100 / excellent派生产物design-tokens.json、tailwind-v4.css由报告与 Token 样式表重新生成禁止手改组件与预览components.html、components.manifest.json、preview/提供可直接复用的实现与视觉校验入口。这种证据驱动的打包方式让 Agent 在生成界面时既能拿到开箱即用的完整设计语言又能通过契约报告快速核对每个值的出处在跨品牌切换与批量生成场景下保持稳定、可验证的输出质量。需要动手实践时直接以tokens.css为起点按 USAGE.md 的阅读顺序在产物中复用即可。【免费下载链接】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），仅供参考