open-design 设计系统溯源证据解析Figma 包的来源边界与 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本篇文章以 open-design 仓库中 source/evidence.md 为骨架结合同一包内的DESIGN.md、tokens.css、components.html、token-contract.report.json等真实文件讲清楚三个问题这个「Figma 设计系统」的来源边界在哪里、包内各文件之间如何互相印证、以及 Token 契约报告如何保证派生产物可追溯、可再生成。读完你既能看懂 open-design 设计系统包的审计/溯源机制也能直接套用这套「证据 契约」的流程管理你自己的设计 Token。1. 这份证据文档在说什么design-systems/figma/source/evidence.md是 open-design 中 Figma 设计系统包Design System 2.0 backfill的溯源声明文件全文围绕三个问题展开Source Scope来源范围本包不是对上游品牌官网或仓库的重新抓取fresh crawl而是从 open-design 官方捆绑的精选夹具curated bundled fixture派生而来Included Fixture Files包含的夹具文件列出构成该包的三个输入文件Token ContractToken 契约说明如何用契约报告把所有 Token 绑定回源样式表的具体行以及哪些文件属于「派生产物、不可手改」。这份文件在包内的定位可以从 manifest.json 的sourceFiles字段确认sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json }也就是说source/目录被显式声明为「importer evidence导入证据」与「token reportsToken 报告」是审计证据层而不是运行时渲染层。open-design 仓库的 design-systems/README.md 同样把source/归类为「importer evidence, snippets, and token reports」并说明「Treatsource/files as audit evidence for the bundled fixture backfill」见 USAGE.md。2. 来源边界为什么是「curated bundled fixture」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.这句话在整套包结构中反复被强调形成一致的事实基线manifest.json 的source字段记录type: bundled、origin: OpenDesign curated bundled fixturesource/tokens.source.json中每个 Token 的source字段都指向tokens.css:行号sourceScope统一为open-design-bundled-fixturesource/token-contract.report.json中每个 Token 条目的reason都写明「Bundled tokens.css declares --xxx; no upstream recrawl was performed for this backfill」USAGE.md 在 Avoid 清单中明确要求「Avoid claiming original upstream source evidence; this package is based on the curated bundled fixture.」这套一致性设计的意义在于它把「品牌事实」与「实现事实」区分开来。包内的DESIGN.md描述的是「模仿 Figma 视觉语言」的设计意图属于设计参考的合理转述而证据层不伪造任何「我们抓取过上游」的声明。任何读者、Agent 或审查者在引用该包时都能从证据链上判断信息的可信等级。3. 三个夹具文件包的本体evidence.md 列出本包由三个输入夹具派生DESIGN.md —— 面向 Agent 的规范设计散文canonical design prosetokens.css —— 编译后的语义 Token 样式表canonical compiled semantic-token stylesheetcomponents.html —— 独立组件夹具standalone component fixture。这与 design-systems/README.md 定义的包最小形态manifest.json DESIGN.md tokens.css一致components.html属于「Rich package files」中的可选增强。3.1 DESIGN.md设计意图的规范散文DESIGN.md 完整刻画了「Figma 风格」的视觉系统核心要点如下。视觉主题界面外壳严格黑白二色仅#000000与#ffffff彩色只存在于产品内容Hero 渐变、产品截图、嵌入内容页面本质是「白色画廊墙上挂彩色艺术品」。几何语言是 pill50px 圆角与 circle50% 圆形的组合配合dashed 2px虚线焦点轮廓呼应 Figma 编辑器的选区手柄是整套 UI 的签名式特征。排版体系核心是自定义可变字体 figmaSans使用了罕见的字重停点 320、330、340、450、480、540、700通过「微差」而非「常规/加粗」制造层级figmaMono 用于大写技术标签。完整层级表如下RoleFontSizeWeightLine HeightLetter SpacingDisplay / HerofigmaSans86px (5.38rem)4001.00-1.72pxSection HeadingfigmaSans64px (4rem)4001.10-0.96pxSub-headingfigmaSans26px5401.35-0.26pxFeature TitlefigmaSans24px7001.45normalBody LargefigmaSans20px330–4501.30–1.40-0.1 ~ -0.14pxBody / ButtonfigmaSans16px330–4001.40–1.45-0.14px ~ normalMono LabelfigmaMono18px4001.300.54px大写Mono SmallfigmaMono12px4001.000.6px大写排版原则是正文默认比 400 更轻320–340全局启用 OpenTypekern正文字距一律为负-0.1px 至 -1.72pxmono 标签为正字距。组件与布局按钮分 Black Solid黑底白字、50% 圆角、White Pill白底黑字、8px 18px 10px非对称内边距、50px pill、Glass Darkrgba(0,0,0,0.08)、Glass Lightrgba(255,255,255,0.16)四种卡片圆角 6–8px间距基数为 8px容器最大宽度 1920px断点从 560px 到 1440–1920pxHero 标题随断点从 86px → 64px → 48px 折叠。3.2 tokens.css编译后的语义 Token 事实层tokens.css 把 DESIGN.md 的设计决策落为可机器消费的 CSS 变量并在文件头注释里用三句话总结了品牌身份。关键的 schema 决策包括--bg、--surface都是#ffffff画廊墙无表面色调--surface-warm直接别名--surface黑白系统没有暖色层--fg: #000000--muted: rgba(0,0,0,0.55)--meta: rgba(0,0,0,0.40)--accent: #000000黑白系统里黑色就是强调色--accent-on: #ffffffhover 用rgba(0,0,0,0.85)active 用rgba(0,0,0,0.08)字号轴--text-xs: 12px到--text-4xl: 86px行高--leading-tight: 1.00、--tracking-display: -0.02em--radius-sm: 50pxpill所有交互元素、--radius-md/-lg: 8px卡片、--radius-pill: 9999px阴影刻意收敛--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised: 0 4px 16px rgba(0,0,0,0.08)——深度主要靠背景对比而不是阴影焦点走虚线 outline--focus-ring只是键盘导航的兜底 shadow布局--container-max: 1920px桌面/平板/手机 gutter 分别为 40/24/16px区块纵向节奏为 96/64/40px。components.html里的:root块与 tokens.css 逐 token 一致34 个选择器、17 个类、19 个元素这正符合 components.manifest.json 的声明「Every visible value comes from tokens.css」。例如按钮与 Tab 的焦点态都写成outline: 2px dashed var(--fg); outline-offset: 2px;正文开启font-feature-settings: kernTab 激活态background: var(--fg); color: var(--accent-on)。3.3 components.html把 Token 变回界面components.html 是单文件自包含组件夹具验证 Token 是否能独立撑起一个完整的 Hero 功能卡 按钮组页面。它只依赖 token 变量与少量派生尺寸如 mono label 的0.54px字距、-0.007em的正文微缩不引入任何第三方库。配套的 components.manifest.json 提供了结构化索引tokens.declared56 个、tokens.referenced、tokens.unusedDeclared、selectors、classes、elements以及按组件分组buttons、inputs、cards、links、icons、typography、layout的 token 引用映射。从该清单可以精确看到每个组件组消费了哪些 token例如 cards 组引用--bg、--elev-raised、--radius-md、--space-6。4. Token 契约契约报告如何建立可追溯性evidence.md 的核心段落在第三部分source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.这是本包的「审计核心」。token-contract.report.json 的结构如下summarytotalTokens: 56、declaredTokens: 56、sourceBackedTokens: 56、sourceBackedA1: 26、fallbackTokens: 26、aliasTokens: 1评分score: 100、grade: excellent、recommendRebuild: falselayerCounts按 TOKEN_SCHEMA 分层统计A1-identity8 个、B-slot4 个、A226 个、A1-structure18 个tokens[]56 个 Token 条目每条包含name、layer、value、confidence、reason、sources精确到tokens.css:行号与sourceName。例如--bg条目记录layer: A1-identity、value: #ffffff、sources: [tokens.css:32]、confidence: highreason 同时注明「Bundled tokens.css declares --bg; no upstream recrawl was performed for this backfill」——契约报告不仅做映射还如实标注了证据等级。同目录的 tokens.source.json 是更精简的「导入证据」每条记录name/value/layer/sourcetokens.css:行号四元组files数组声明本包由DESIGN.md、tokens.css、components.html三个文件派生。两套文件互相印证一份做机器校验report一份做导入留痕source。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.即包内存在一条单向的「事实链」DESIGN.md设计意图 ↓ 编译 tokens.css事实层 / source of truth ↓ 契约校验 ↓ 派生 token-contract.report.json design-tokens.json / tailwind-v4.csstailwind-v4.css 开头即声明「Derived from tokens.css. Keep tokens.css as the source of truth.」通过import ./tokens.css加theme { --color-fg: var(--fg); ... }把语义 Token 映射为 Tailwind v4 的主题变量--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*等design-tokens.json 同理是 Design Tokens 规范化的派生输出。USAGE.md 的 Avoid 清单再次强调「Avoid redefining Tailwind or design-token values independently oftokens.css」。所以正确的工作流是改 DESIGN.md → 重编译 tokens.css → 重跑契约报告 → 重新生成两份派生文件而不是直接编辑派生产物。这正是 evidence.md 想传达的工程纪律单一事实源 显式契约 可重放生成。6. 如何按证据读序使用这个包结合 USAGE.md 的推荐读序一套可复制的使用流程如下先读本文件source/evidence.md理解包契约与证据边界读 DESIGN.md获取视觉意图、约束与反模式Dos and Donts把 tokens.css 粘贴进第一个 artifact 的style块再写组件 CSS——保证所有可见值来自 Token用 components.manifest.json 做组件盘点需要精确选择器或状态时再打开 components.html需要视觉抽检时打开preview/下的 colors.html、typography.html、spacing.htmlmanifest 的preview.pages声明了这三个角色页生成或审查时以 token-contract.report.json 校验每个 Token 是否都能回溯到 tokens.css 的具体行。7. 实践启示这套证据机制能迁移到你的项目从源码结构看evidence.md 所代表的不是「一页说明」而是一套可复用的设计系统质量门禁它由三层构成层文件职责意图层DESIGN.md人类与 Agent 都能读的设计散文含 Do/Dont事实层tokens.css components.html唯一事实源所有可见值必须来自 Token证据层source/evidence.md tokens.source.json token-contract.report.json声明来源边界、把 Token 逐一映射回行号、生成契约统计与评分在 open-design 的语境下这套机制让 151 个设计系统包见 design-systems/README.md可以被 Agent 稳定消费提示词组合时读USAGE.md与tokens.css做品牌切换时保留 schema Token 名即可可靠跨包切换。任何维护自有设计 Token 的团队都可以照搬「声明来源 → 单一事实源 → 契约报告 → 派生产物自动生成」这条链路用recommendRebuild与score这类字段把「Token 是否过期」变成可机器判定的指标而不是靠人肉 Review。关键文件索引证据声明 source/evidence.md · 契约报告 source/token-contract.report.json · 导入留痕 source/tokens.source.json · 设计规范 DESIGN.md · Token 事实层 tokens.css · 组件夹具 components.html · 使用指南 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），仅供参考