OpenDesign 设计系统 2.0 溯源证据体系以 Notion 包的 source 证据目录与 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本文以 OpenDesign 仓库中 Notion 设计系统包的source/证据目录为切入点系统讲解 Design System 2.0 的回填backfill溯源模型source/evidence.md如何声明证据边界、source/token-contract.report.json如何把每一个 TOKEN_SCHEMA 语义令牌回绑到tokens.css的具体声明行以及design-tokens.json、tailwind-v4.css等派生产物为何必须由报告再生成而非手工维护。读完本文你将掌握 OpenDesign 设计系统包的标准包结构、令牌契约的分层模型A1-identity / A2 / B-slot / A1-structure、证据文件的审计用法以及如何在 Agent 工作流中正确消费这类可验证、可溯源的设计系统包。一、为什么需要source 证据Design System 2.0 回填的背景OpenDesign 将每个品牌设计语言打包为独立的设计系统包design-system package每个子目录即一个可移植的包。仓库的 design-systems/README.md 指出当前打包目录包含151 个包每个包至少具备相同的机器可读形态design-systems/slug/ ├── manifest.json ├── DESIGN.md └── tokens.css其中manifest.json负责稳定的发现元数据与来源记录provenanceDESIGN.md是面向 Agent 的设计散文design prosetokens.css是编译后的语义令牌样式表semantic-token stylesheet。Notion 包design-systems/notion/id 为notion分类 Productivity SaaS正是这批回填包中的一员。所谓回填指的是这些包的内容并非来自对上游品牌官网或代码仓库的实时抓取而是基于 OpenDesign 预先整理的 bundled fixture随仓库分发的精选固件派生而成。这一事实由 source/evidence.md 开篇明确声明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.这句话定义了整个证据体系的边界所有结论都锚定在仓库内已提交的文件上不对外宣称我们重新抓取了 Notion 官方资源。这也与 design-systems/README.md 末尾的声明一致——品牌引用包只是审美灵感aesthetic inspirations并非所引用品牌的官方资产。二、source/ 目录包内的审计证据区Notion 包在标准三件套manifest.json / DESIGN.md / tokens.css之外还声明了富文件rich files。完整目录结构如下design-systems/notion/ ├── DESIGN.md # 设计意图散文Agent 主读文件 ├── USAGE.md # Agent 与评审者的读取顺序与使用契约 ├── tokens.css # 语义令牌样式表事实源之一 ├── components.html # 独立组件 fixture43 个选择器 ├── components.manifest.json # 由 components.html tokens.css 派生的组件/令牌索引 ├── design-tokens.json # 派生产物Design Tokens JSON ├── tailwind-v4.css # 派生产物Tailwind v4 映射 ├── manifest.json # 包元数据与来源记录 ├── preview/ # 可视化预览页colors / typography / spacing └── source/ # 审计证据区 ├── evidence.md # 证据声明本文核心 ├── token-contract.report.json # TOKEN_SCHEMA 契约报告 └── tokens.source.json # 源令牌快照source/目录在包中的定位由 manifest.json 的sourceFiles字段显式声明sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json }从包的使用契约看USAGE.md 在 Do 一节中明确要求将source/文件视为本次 bundled fixture 回填的审计证据audit evidence同时在 Avoid 一节中禁止声称存在原始上游来源证据——因为本包基于精选固件而非上游抓取。换言之source/不是运行时样式输入而是供评审者、Agent 与自动化守卫校验令牌声明是否可信、是否可追溯到仓库内文件的证据层。三、三大 fixture 文件证据所覆盖的对象evidence.md 列出本次回填所依据的三个固件文件它们是证据直接覆盖的被审对象文件职责在本包中的角色design-systems/notion/DESIGN.md品牌视觉意图、约束与反模式Agent 提示词组合时的设计散文主体design-systems/notion/tokens.css语义令牌的规范化声明令牌契约的事实源报告逐行回绑到它design-systems/notion/components.html组件 fixture按钮、卡片、输入框、徽标等组件清单派生的来源校验选择器与令牌引用这三个文件共同定义了 Notion 包是什么。以 DESIGN.md 为代表其记录的 Notion 视觉语言核心特征包括暖中性色体系灰度普遍带有黄棕色调#f6f5f4暖白、#31302e暖深、#615d59暖灰 500、#a39e98暖灰 300画布纯白#ffffff文字用接近黑色的rgba(0,0,0,0.95)而非纯黑NotionInter 字体展示字号64px使用激进的字距压缩-2.125px四档字重 400/500/600/700大字号开启 OpenType 特性lnum表格数字与locl本地化字形细线哲学whisper border全系统统一使用1px solid rgba(0,0,0,0.1)的超细边框多层阴影45 层阴影叠加单层不透明度不超过 0.05营造可感知而非可见的深度Notion Blue#0075de核心 UI 中唯一的饱和强调色用于 CTA 与链接Pill 徽标9999px 圆角胶囊 蓝色调底#f2f9ff底 /#097fe8字。这些设计细节最终被压缩进tokens.css的语义令牌因此 evidence 的令牌契约报告本质上回答的是DESIGN.md 里描述的每一个视觉决策是否都能在 tokens.css 中找到对应的声明行四、TOKEN_SCHEMA 契约token-contract.report.json 逐字段解读source/token-contract.report.json 是证据体系的核心产物。它的契约名contract为TOKEN_SCHEMAschemaVersion 为 1sourceScope为open-design-bundled-fixturegeneratedAt记录生成时间本包为 2026-06-06。报告顶部 summary 给出了整体结论{ schemaVersion: 1, contract: TOKEN_SCHEMA, sourceScope: open-design-bundled-fixture, summary: { totalTokens: 56, declaredTokens: 56, sourceBackedTokens: 56, sourceBackedA1: 26, fallbackTokens: 26, aliasTokens: 1, layerCounts: { A1-identity: 8, B-slot: 4, A2: 26, A1-structure: 18 }, score: 100, grade: excellent, recommendRebuild: false } }各字段含义如下totalTokens/declaredTokens报告共登记 56 个令牌且 56 个都在 tokens.css 中有声明sourceBackedTokens56 个令牌全部有源文件支撑sourceBackedA1其中 26 个直接落在 A1 层身份/结构层即强绑定令牌fallbackTokens26 个通过回退机制fallback得到的令牌aliasTokens1 个别名令牌--surface-warm值为var(--surface)layerCounts令牌在四层语义模型中的分布score: 100/grade: excellent/recommendRebuild: false契约完整度满分无需重建。报告中每个令牌条目都带结构化证据字段例如{ name: --bg, layer: A1-identity, value: #ffffff, confidence: high, reason: Bundled tokens.css declares --bg; no upstream recrawl was performed for this backfill., sources: [tokens.css:31], sourceName: --bg }值得注意的细节sources字段精确到声明行号如tokens.css:31这正是 evidence.md 所强调的将每一个 TOKEN_SCHEMA 绑定映射回已提交 tokens.css 的声明行每个条目的reason都带着相同的溯源边界声明——基于 bundled tokens.css本次回填未执行上游重抓取避免任何来自官方的误读部分令牌使用现代 CSS 能力派生如--accent-active的值为color-mix(in oklab, var(--accent), black 14%)见 tokens.css 第 49 行由基准强调色在 oklab 色彩空间压暗 14% 得到按压态。四层令牌语义模型报告中 56 个令牌按四层分布对应 OpenDesign 的 TOKEN_SCHEMA 语义分层层数量语义本包示例A1-identity8品牌身份级基础令牌不可再拆--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-bodyA1-structure18结构/排版骨架--text-xs…--text-4xl8 档字号、--leading-body、--leading-tight、--tracking-display、--section-y-*、--container-max、--container-gutter-*A226由 A1 派生/细化的具体令牌强调态--accent-hover、--accent-active、语义色--success、--warn、--danger、间距--space-*、圆角--radius-*、阴影--elev-*、动效--motion-*等B-slot4槽位别名引用上层令牌--surface-warm: var(--surface)、--fg-2、--meta、--border-soft其中 B-slot 层正是别名令牌的所在层--surface-warm直接别名为var(--surface)这使跨品牌切换时只要保持 schema 令牌名不变替换tokens.css的:root块即可整体换肤——这也是 USAGE.md 要求严格保留 schema 令牌名以保证跨品牌切换可靠的底层原因。五、tokens.source.json与报告同构的源令牌快照source/tokens.source.json 与契约报告同构但更轻它记录brandIdnotion、sourceScope、本次回填所依据的files列表DESIGN.md / tokens.css / components.html以及 56 个令牌的精简条目——每个条目只保留name、value、layer、source行号四个字段例如{ schemaVersion: 1, sourceScope: open-design-bundled-fixture, brandId: notion, files: [DESIGN.md, tokens.css, components.html], tokens: [ { name: --fg, value: rgba(0, 0, 0, 0.95), layer: A1-identity, source: tokens.css:36 } ] }它与token-contract.report.json的关系是报告 源快照 置信度 理由 完整证据链confidence、reason、sources。两者共同构成 source 证据区供守卫脚本与评审者交叉核验。由于 56 个令牌的声明行在两份文件中完全一致任何对tokens.css的手工改动若不同步更新这两份证据都会被自动化检查捕获。六、派生产物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.这句话的意思是design-systems/notion/design-tokens.json 与 design-systems/notion/tailwind-v4.css 是缓存性质caches而非并列的事实源前者应当从 token-contract 报告生成后者应当从tokens.css生成二者都必须与tokens.css保持一致手工编辑派生文件属于反模式——一旦与报告/样式表不一致包质量守卫package-quality guard会判定为派生文件失配。这一规则与 design-systems/README.md 的派生文件定义完全一致components.manifest.json由components.htmltokens.css派生design-tokens.json由 token-contract 报告派生tailwind-v4.css由tokens.css派生。仓库的守卫脚本如 scripts/check-tokens-fixture-sync.ts、scripts/check-design-system-manifests.ts、scripts/check-design-system-package-quality.ts正是用来验证这些派生关系的写包后需运行pnpm guard与pnpm typecheck。七、证据如何下沉到组件层components.manifest.json 的交叉印证证据链并未止步于令牌。由 components.html 与 tokens.css 派生的 components.manifest.json 把令牌契约继续下沉到组件选择器规模数据fixture 包含 1 个 style 块、43 个选择器、22 个类、24 个元素组件分组buttons、inputs、cards、badges、links、icons、typography、layout 共 8 组其中键盘提示组keyboard在本包中不存在present: false其余 7 组均 present令牌引用追踪每个组件组列出其引用的令牌例如 buttons 组引用--accent-hover、--radius-sm、--space-2、--text-sm、--motion-fast、--ease-standard、--font-displaycards 组引用--elev-raisedbadges 组引用--radius-pill、--space-1、--text-xs未使用声明unusedDeclared报告诚实列出 12 个已声明但未在组件 fixture 中使用的令牌--accent-active、--border-soft、--danger、--elev-flat、--elev-ring、--fg-2、--font-mono、--radius-md、--space-8、--success、--surface-warm、--warn同时undeclaredReferenced为空——即不存在用了却没声明的令牌这说明组件样式完全收敛在令牌契约内没有游离的硬编码。这组数据让评审者可以回答三个问题组件是否齐全组件是否全部引用令牌是否存在声明冗余从而把证据从令牌有定义推进到令牌被真正使用。八、Agent 视角如何正确阅读与使用该包综合 USAGE.md 的读取顺序与 DESIGN.md 第 9 节Agent Prompt Guide一个 Agent 或人类读者消费本包的正确姿势是先读 USAGE.md理解包契约与读取顺序再读 DESIGN.md掌握视觉意图、约束与反模式其中 §9 提供了可直接复用的组件提示词例如 Hero 区提示词要求64px NotionInter weight 700、line-height 1.00、letter-spacing -2.125px、颜色 rgba(0,0,0,0.95)以及蓝色 CTA#0075de4px 圆角8px 16px padding ghost 按钮的组合把 tokens.css 粘进首个 artifact 的style块之后一律用var(--*)引用令牌禁止在组件 CSS 里出现裸 hex需要精确选择器或状态时打开 components.html需要组件清单概览时查 components.manifest.json需要视觉抽查时打开 preview/colors.html、preview/typography.html、preview/spacing.html需要审计溯源时查阅 source/evidence.md 与 source/token-contract.report.json确认某个令牌值来自 tokens.css 的哪一行使用--accent承担主操作、链接、焦点态与唯一视觉焦点manifest.json 的craft.suggested还建议叠加 craft/color.md 与 craft/accessibility-baseline.md 两条工艺约束。DESIGN.md 的迭代指南同时给出了 8 条强约束是消费本包时最容易踩坑的边界始终用暖中性色绝不用蓝灰字距随字号缩放64px 时 -2.125px16px 时 normal四档字重各司其职边框永远不重于1px solid rgba(0,0,0,0.1)阴影单层不透明度不超过 0.05暖白#f6f5f4分区背景是视觉节奏的关键Pill9999px用于状态/标签、4px 圆角用于按钮/输入框Notion Blue 是核心 UI 中唯一的饱和色须克制使用。九、总结证据模型带来的工程价值回到 source/evidence.md 这份仅十余行的声明文件它承载的其实是 OpenDesign Design System 2.0 回填体系的三条核心原则诚实边界明确声明内容来源是 curated bundled fixture而非上游重抓取避免任何官方来源的虚假背书逐行可溯token-contract.report.json把 56 个 TOKEN_SCHEMA 令牌逐一回绑到 tokens.css 的具体声明行形成令牌 → 层 → 行号的完整证据链派生收敛design-tokens.json、tailwind-v4.css乃至components.manifest.json均为派生缓存只能由报告与样式表再生成不能被手工修改以此保证整个包在 151 个包组成的目录中保持机器可校验的一致性。这套证据 契约 派生三层结构让设计系统包对 Agent、评审者和自动化守卫pnpm guard都变得可验证、可审计、可复现——这正是 Design System 2.0 区别于早期仅含 DESIGN.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），仅供参考