OpenDesign 设计系统 2.0 证据链解析Perspective 包的 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本篇文章围绕 OpenDesign 仓库中design-systems/perspective/source/evidence.md这份「来源证据」文档展开解读 Design System 2.0 回填backfill包的数据血缘模型bundled fixture 的取证边界、TOKEN_SCHEMA契约报告如何把每一个 token 绑定回tokens.css声明行以及design-tokens.json与tailwind-v4.css两条衍生产物为什么必须「从报告和样式表再生、而非手工编辑」。读完你将掌握这套设计系统包的完整文件契约、56 个 token 的分层结构与落地使用规范并能在自己的设计系统包中复刻同样的可审计、可再生的流水线。1. 背景什么是 Design System 2.0 回填包与 source/evidence.mdOpenDesign 的design-systems/目录下沉淀了上百个设计系统包perspective、stripe、notion、vercel、github 等每个包都被归一化normalized为一套约定文件DESIGN.md视觉意图、tokens.css结构化 token、components.html参考组件等。perspective 包属于其中的「Layout Structure」类别视觉语言是「等距视图、消失点、分层元素营造的 3D 空间纵深感」。source/evidence.md是这套机制中专门负责溯源取证的文档全文围绕三个问题来源边界Source Scope这套 Design System 2.0 回填内容派生自 OpenDesign 官方精编的 bundled fixture随仓库打包的样例资产并不声称对上游品牌仓库或官网做过全新抓取fresh crawl。这是刻意保守的取证声明——它划定了哪些证据可信、哪些不可信。纳入的 fixture 文件Included Fixture Files明确列出三个证据源头文件即 DESIGN.md、tokens.css、components.html。Token 契约Token Contractsource/token-contract.report.json把每一个TOKEN_SCHEMA绑定映射回已提交的tokens.css声明行而design-tokens.json与tailwind-v4.css是衍生输出必须从报告和 token 样式表重新生成而不是手工直接编辑。这份文档的价值在于它把「设计 token 从哪里来、如何被验证、如何被派生」变成了一条可审计的机器可读证据链而不仅是人的口头承诺。2. 包结构总览证据文件、fixture 与衍生产物如何分层perspective 包的文件布局相对仓库根目录清晰地体现了「源 → 契约 → 衍生」三层结构design-systems/perspective/ ├── DESIGN.md # fixture视觉意图、约束、反模式 ├── tokens.css # fixture唯一的 token 事实源:root 变量块 ├── components.html # fixture参考组件48 个选择器、26 个类 ├── components.manifest.json # 派生清单组件分组 token 引用审计 ├── design-tokens.json # 衍生产物TOKEN_SCHEMA 归一化 JSON带类型 ├── tailwind-v4.css # 衍生产物Tailwind v4 theme 映射 ├── manifest.json # 包清单schemaVersion od-design-system-project/v1 ├── USAGE.md # 使用指南读序、Do / Avoid ├── source/ │ ├── evidence.md # ← 本篇文章主体来源证据与契约声明 │ ├── token-contract.report.json # 契约报告token ↔ tokens.css 行号映射 │ └── tokens.source.json # token 原始快照 ├── preview/ # 视觉抽查页colors / typography / spacing └── system/ # 系统级渲染产物index / kit / kit.dark其中 manifest.json 是机器读取包结构的入口关键字段如下schemaVersion: od-design-system-project/v1——OpenDesign 设计系统项目的版本化模式标识id: perspective、category: Layout Structuresource.type: bundled、source.origin: OpenDesign curated bundled fixture——与 evidence.md 的取证声明完全一致files指向 DESIGN.md / tokens.css / design-tokens.json / tailwind-v4.css / components.html 五个主文件sourceFiles指向source/evidence.md、source/tokens.source.json、source/token-contract.report.json三个证据文件craft.suggested建议在设计评审时叠加color与accessibility-baseline两条 craft 规范。从源码结构看manifest.json就是整个包的「目录页」而source/evidence.md是它的「审计声明」。3. TOKEN_SCHEMA 契约报告逐字段解读 token-contract.report.jsontoken-contract.report.json 是证据链的核心产物。它声明契约contract: TOKEN_SCHEMA、来源范围sourceScope: open-design-bundled-fixture并给出一个可量化的健康度评分。3.1 summary 指标与评分模型{ totalTokens: 56, declaredTokens: 56, sourceBackedTokens: 56, sourceBackedA1: 26, fallbackTokens: 26, aliasTokens: 0, layerCounts: { A1-identity: 8, A1-structure: 18, B-slot: 4, A2: 26 }, score: 100, grade: excellent, recommendRebuild: false }各指标含义字段值含义totalTokens/declaredTokens56 / 56报告登记数与 tokens.css 实际声明数完全一致sourceBackedTokens56每个 token 都能映射回源码声明行无孤儿 tokensourceBackedA126属于 A1 层身份/结构层且由源码背书的 token 数fallbackTokens26需要回退兜底的 token 数即 A2 层数量见下文分层说明aliasTokens0当前包未使用别名 tokenscore/grade100 / excellent契约完整度评分与评级recommendRebuildfalse无需重建派生产物与源保持一致3.2 单条 token 记录的结构报告内每个 token 条目都携带 7 个字段把「值」与「证据」绑定在一起{ 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 }layer所属层级见第 4 节confidence: high全部 56 个 token 均为 high因为证据直接来自仓库内 bundled 的 tokens.csssources指向 tokens.css 的具体声明行例如tokens.css:16即--accent: #2563eb;reason统一注明「由 bundled tokens.css 声明未执行上游重新抓取」——反复强调取证边界避免读者误以为该包代表上游品牌官方的最新设计。这正是 evidence.md 所述「把每一个 TOKEN_SCHEMA 绑定映射回已提交的 tokens.css 声明行」的机器可读实现。4. 分层模型A1 / B-slot / A2 的语义与 56 个 token 全量清单报告与衍生文件共同使用一套四层模型从「身份」到「结构」再到「派生值」逐级展开A1-identity8 个品牌的身份级颜色与字体跨品牌切换时的锚点A1-structure18 个排版、间距节奏、版心与断点等结构性常量B-slot4 个语义槽位slot把身份值映射为具体用途A226 个由 A1/B-slot 派生的具体可用值hover、active、状态色、阴影、动效等。4.1 A1-identity身份锚点8 个Token值类型声明行--bg#f5f8ffcolortokens.css:7--surface#ffffffcolortokens.css:8--fg#101828colortokens.css:10--muted#667085colortokens.css:12--border#d7e0efcolortokens.css:14--accent#2563ebcolortokens.css:16--font-displayInter, system-ui, sans-seriffontFamilytokens.css:23--font-bodyInter, system-ui, sans-seriffontFamilytokens.css:244.2 B-slot语义槽位4 个Token值类型声明行--surface-warm#eaf1ffcolortokens.css:9--fg-2#344054colortokens.css:11--meta#2563ebcolortokens.css:13--border-soft#edf2f8colortokens.css:15从分层语义看B-slot 是把 A1 身份色「配位」到界面角色次要前景、元信息、暖色面、软边框的中间层避免组件直接裸引用身份值。4.3 A1-structure结构常量18 个字号9 个--text-xs12px、--text-sm14px、--text-base16px、--text-lg18px、--text-xl24px、--text-2xl36px、--text-3xl54px、--text-4xl76pxtokens.css:26–33行高/字距3 个--leading-body1.52、--leading-tight1.06、--tracking-display-0.025emtokens.css:34–36章节纵向节奏3 个--section-y-desktop96px、--section-y-tablet68px、--section-y-phone48pxtokens.css:45–47版心3 个--container-max1180px、--container-gutter-desktop36px、--container-gutter-tablet24px、--container-gutter-phone16pxtokens.css:59–62共 4 个 gutter/容器字段。值得留意的是 76px 的--text-4xl与 -0.025em 的--tracking-display大标题刻意收紧字距是「现代、高对比、清晰」风格在排版上的具体体现。4.4 A2派生实现值26 个派生色6 个--accent-on#ffffff、--accent-hoveroklab 混合黑色 8%、--accent-active混合黑色 14%、--success#16a34a、--warn#f59e0b、--danger#ef4444等宽字体1 个--font-monoSF Mono, ui-monospace, Menlo, monospace间距8 个--space-14px 至--space-1248px4/8/12/16/20/24/32/48圆角4 个--radius-sm10px、--radius-md16px、--radius-lg24px、--radius-pill9999px层级阴影4 个--elev-flatnone、--elev-ring1px 描边、--elev-raised大投影、--focus-ring4px 焦点环动效3 个--motion-fast150ms、--motion-base240ms、--ease-standardcubic-bezier(0.2, 0, 0, 1)。其中--accent-hover/--accent-active使用现代 CSScolor-mix(in oklab, ...)语法意味着运行环境需支持 oklab 色彩空间的color-mix()这是应用本包时需要注意的浏览器兼容前提。5. 衍生产物design-tokens.json 与 tailwind-v4.css 的再生规则evidence.md 明确指出design-tokens.json和tailwind-v4.css是派生输出「应从报告和 token 样式表重新生成regenerated from the report and token stylesheet而不是手工编辑」。这是本包最重要的工程纪律tokens.css是唯一事实源source of truth。5.1 design-tokens.json归一化的 TOKEN_SCHEMA 视图design-tokens.json 复用报告中的 summary 与全部 56 个 token但每个条目额外补充了type字段形成可供其他工具消费的类型化清单color全部颜色 tokenfontFamily--font-display、--font-body、--font-monodimension字号、间距、圆角、版心等像素值number--leading-body、--leading-tightshadow--elev-*与--focus-ringduration--motion-fast、--motion-basecubicBezier--ease-standard。summary中的sourceBackedA1: 26与fallbackTokens: 26相等并非巧合A1 两层8 18与 B-slot4合计 26 个是「源生锚点」而 A2 的 26 个被视为可回退兜底的派生值——两者的对称关系在报告中是强一致的score 100。5.2 tailwind-v4.css把 token 桥接进 Tailwind v4 的 themetailwind-v4.css 文件头注释同样声明「Derived from tokens.css. Keep tokens.css as the source of truth.」随后通过import ./tokens.css与theme块做命名映射--color-*bg/surface/surface-warm/fg/fg-2/muted/meta/border/border-soft/accent/accent-on/accent-hover/accent-active/success/warn/danger--font-*display/body/sans/mono--text-*与--leading-*、--tracking-*完整继承排版量表--spacing-*把--space-N重命名为 Tailwind 惯用的--spacing-N并追加--spacing-section-*、--spacing-container-*--radius-*、--shadow-*、--duration-*、--ease-standard、--container-max一一映射。这样项目里即可直接写bg-accent、text-sm、rounded-md、shadow-raised、duration-base等 Tailwind 工具类而它们的值仍然回流到tokens.css这个唯一事实源。6. 组件清单佐证token 引用审计与未使用声明components.manifest.json 提供了证据链的第三层组件与 token 的交叉引用审计。fixture 摘要显示components.html包含 1 个style块、48 个选择器、26 个类与 19 个元素并按 8 个组件分组登记分组覆盖的类/选择器引用的代表 tokenbuttons.btn、.btn-primary、.btn-secondary及 hover/focus 态--accent、--accent-on、--motion-fast、--ease-standard、--radius-mdinputs.field、input、input:focus、label--border、--radius-sm、--space-4cards.card-row、.panel、.panel-head、.tile--elev-raised、--radius-lg、--surfacebadges.status无独立引用linksa无独立引用typographyh1/h2/h3、.eyebrow、.lead--text-4xl、--text-xl、--fg-2layout.container、section--container-gutter-*、--section-y-desktop该清单还报告了 7 个「已声明但未在组件中引用」的 token--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn以及undeclaredReferenced: []无未声明却被引用的 token。这种双向审计保证了组件不会偷偷绕过 token 层使用硬编码值与 evidence.md「禁止在 token 块外使用裸十六进制值」的纪律互为表里。7. 落地使用规范按 USAGE.md 读序消费本包USAGE.md 给出 Agent 与评审者消费本包的推荐顺序与证据链的文件依赖方向完全一致先读 USAGE.md 理解包契约读 DESIGN.md 掌握视觉意图、约束与反模式将 tokens.css 粘贴进产物第一个style块作为组件 CSS 的基底用components.manifest.json快速盘点组件需要精确选择器或状态时再打开components.html需要视觉抽查时打开preview/下的 colors.html、typography.html、spacing.html。7.1 Do应做保持 schema token 名称原样跨品牌切换cross-brand switching才可靠用--accent承载主行动、链接、焦点态与唯一视觉焦点优先复用components.manifest.json中的组件分组而不是发明新控件把source/文件视为 bundled fixture 回填的审计证据。7.2 Avoid避免在复制的:roottoken 块之外使用裸十六进制值独立于tokens.css重新定义 Tailwind 或 design-token 的值应走再生流程声称拥有上游原始来源证据——本包基于精编 bundled fixture证据边界见第 1 节添加components.html与DESIGN.md之外的新组件配方。8. 视觉与交互约束速览DESIGN.md 摘要DESIGN.md 从 9 个维度约束生成结果的可识别度色板主色#00BD7D设计意图层面与 token 层--accent#2563eb形成「身份描述 vs 实现值」两层成功#16A34A、警告#D97706、危险#DC2626、Surface#FFFFFF、正文#111827字体display 用 Oswald、正文用 Poppins、等宽 JetBrains Mono字重 100–900 全梯度间距4/8/12/16/24/32 的节奏刻度与 tokens.css 的--space-*对齐动效150–250ms 短促过渡、稳定缓动hover/focus-visible/active/disabled/loading 状态必须显式反模式不得引入调色板外颜色、不得用同字号同字重压平层级、不得以装饰牺牲可读性、不得在同一界面混用无关视觉隐喻。从源码结构看DESIGN.md 属于「人读的意图层」tokens.css 属于「机读的实现层」evidence.md 则把两者之间的映射关系钉死为可审计契约——这正是 Design System 2.0 包与纯设计文档的本质区别。9. 结语可复用的设计系统取证与再生方法论perspective 包的 evidence 机制给出了一条清晰可复用的流水线适用于 OpenDesign 中任意设计系统包固定事实源tokens.css的:root块是唯一真相fixtureDESIGN.md、components.html说明意图与形态生成契约报告source/token-contract.report.json逐 token 登记「层、值、置信度、来源行号」产出 score/grade 与recommendRebuild信号派生归一化产物design-tokens.json补充类型信息tailwind-v4.css完成 Tailwind v4 桥接两者一律由报告 样式表再生成杜绝手工编辑造成的漂移组件交叉审计components.manifest.json校验「声明即引用、引用即声明」杜绝硬编码逃逸明确取证边界如实声明「bundled fixture 回填非上游重新抓取」防止把派生包误当作品牌官方当前设计。对于要在自己的项目中消费该包的开发者只需记住直接复制tokens.css进产物style块、按 USAGE.md 读序走、绝不绕过tokens.css改衍生文件即可在保持 perspective 视觉家族辨识度的同时获得一条完整、可审计、可再生的设计 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考