OpenDesign 设计系统 2.0 溯源与 Token 契约解析以 Retro 包的 Source Evidence 为例【免费下载链接】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-designRetro复古怀旧风是 OpenDesign 仓库中随包内置bundled的设计系统之一其设计语言由一份来源证据Source Evidence文档约束着整套资产的边界与可信度。本文以 design-systems/retro/source/evidence.md 为核心骨架拆解 OpenDesign 设计系统 2.0 的夹具回填fixture backfill机制它定义了哪些文件构成证据、56 个设计令牌如何与tokens.css的声明行一一绑定、派生产物Design Tokens JSON 与 Tailwind v4 主题为什么必须由契约报告再生成而非手工编辑。读完本文你将掌握 OpenDesign 设计系统包内source/目录的审计语义、TOKEN_SCHEMA四层令牌模型以及如何在消费端验证一个品牌包是否契约完整。1. 为什么设计系统包需要来源证据evidence.md开篇即声明了两条关键事实本套 Retro 设计系统是Design System 2.0 backfill回填产物它派生自OpenDesign 仓库内置的 curated bundled fixture精选内置夹具并未对上游品牌仓库或网站进行新的爬取It does not claim a fresh crawl of the original upstream brand repository or website。这句话定义了整份文档的定位它不是一份品牌溯源报告而是一份诚实标注数据来源边界的审计声明。在 OpenDesign 的体系里设计系统包既可以来自对真实品牌站点的抓取github/local/shadcn等 source 类型也可以来自仓库自带的精选夹具bundled。Retro 属于后者因此在引用其令牌时不能声称取自某品牌官方网站——这正是 USAGE.md 中Avoid claiming original upstream source evidence这一条约束的来源见 design-systems/retro/USAGE.md。这种来源类型被结构化地记录在包的 manifest.json 中{ schemaVersion: od-design-system-project/v1, id: retro, name: Retro, category: Retro Nostalgic, source: { type: bundled, origin: OpenDesign curated bundled fixture }, sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json } }而source.type的合法取值bundled/local/github/shadcn以及sourceFiles字段的路径校验规则均定义在契约层 design-systems/_schema/manifest.schema.ts 中由validateSource与validateSourceFiles强制校验防止包内写入绝对路径或../越界路径。2. 证据清单一个包由哪些文件构成evidence.md列出的 Included Fixture Files 共三个它们分别承担设计意图、令牌实现、组件表现三种角色文件角色说明design-systems/retro/DESIGN.md设计散文proseAgent 提示词读取的规范文本描述视觉风格、色彩立场、排版、间距、组件、动效、语气与反模式design-systems/retro/tokens.css令牌实现source of truth在:root中声明全部 56 个 CSS 自定义属性是契约的最终裁决者design-systems/retro/components.html组件夹具fixture独立的组件示例配合 design-systems/retro/components.manifest.json 提供精确选择器与状态这三个文件的路径在 manifest.json 的files字段中也被硬编码为固定字面量design: DESIGN.md、tokens: tokens.css、components: components.html这一约束来自 design-systems/_schema/manifest.schema.ts 的DesignSystemProjectFiles类型与validateFiles校验函数——任何包都不能把设计散文改名或换路径从而保证 daemon / picker / importer 等消费方无需猜测目录结构即可发现规范文本与令牌样式表。此外design-systems/retro/USAGE.md 给出了推荐的阅读顺序Read Order本质上是证据链的消费流程先读 USAGE.md 理解包契约再读 DESIGN.md 理解视觉意图、约束与反模式将tokens.css粘贴到第一个 artifact 的style块中再写组件 CSS用components.manifest.json做组件清单速查需要精确选择器或状态时打开components.html需要视觉抽查时查看preview/目录下的 colors.html、typography.html、spacing.html。3. Token 契约报告每一个令牌都有行号级出处evidence.md的 Token Contract 一节是全篇的技术核心source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.也就是说design-systems/retro/source/token-contract.report.json 是一份逐令牌的可追溯性清单对于 TOKEN_SCHEMA 中定义的每一个令牌报告都记录了它对应的 CSS 变量名、所属层layer、取值、置信度、来源文件与行号。其summary字段给出了整包的契约健康度快照{ schemaVersion: 1, contract: TOKEN_SCHEMA, generatedAt: 2026-06-06T00:00:00.000Z, sourceScope: open-design-bundled-fixture, summary: { totalTokens: 56, declaredTokens: 56, sourceBackedTokens: 56, sourceBackedA1: 26, fallbackTokens: 26, aliasTokens: 0, layerCounts: { A1-identity: 8, B-slot: 4, A2: 26, A1-structure: 18 }, score: 100, grade: excellent, recommendRebuild: false } }这些指标的含义可以解读为totalTokens 56TOKEN_SCHEMA 中共享令牌的总数与packages/contracts/src/design-systems/token-schema.ts中TOKEN_SCHEMA数组的实际条目数一致declaredTokens 56 / sourceBackedTokens 56Retro 的tokens.css全部声明了这 56 个令牌且每个都能映射回 CSS 声明行无缺失、无悬空sourceBackedA1 26A1 层A1-identity 8 个 A1-structure 18 个全部由品牌自身声明因为 A1 没有跨品牌的默认值可回退fallbackTokens 26恰与 A2 层数量相等——这 26 个 A2 令牌使用了模式层提供的默认回退值例如--accent-hover、--space-1、--radius-sm等aliasTokens 0B-slot 层 4 个令牌--surface-warm、--fg-2、--meta、--border-soft在 Retro 中都给出了独立值而非var()别名score 100 / grade excellent / recommendRebuild false契约 100% 满足无需重建派生产物。报告正文中的每个条目形如{ name: --bg, layer: A1-identity, value: #fff4cf, confidence: high, reason: Bundled tokens.css declares --bg; no upstream recrawl was performed for this backfill., sources: [tokens.css:7], sourceName: --bg }其中sources字段把令牌绑定精确到 tokens.css 的声明行号而reason字段统一标注no upstream recrawl——这是回填夹具与真实抓取包在证据强度上的本质区别。4. TOKEN_SCHEMA 四层模型令牌归属由谁决定值划分要理解报告中的layer字段必须回到契约源文件 packages/contracts/src/design-systems/token-schema.ts。该文件明确定义了每个令牌只属于以下四层之一划分依据是谁来决定取值、以及品牌省略令牌时会发生什么层是否必需语义回退行为A1-identity必需令牌即品牌本体--bg、--fg、--accent、字体栈等无回退可替代无回退A1-structure必需结构性决策字号刻度、布局网格、区块节奏每个品牌自行撰写无跨品牌默认值A2最终tokens.css中必需存在合理默认值的令牌--space-*、--radius-*、--motion-*等由_schema/defaults.css提供 fallbackderive 脚本可内联B-slot可选槽位为跨品牌一致性保留如三级 surface / fg 层级品牌可别名到兄弟令牌通过aliasTo如var(--surface)解析该文件还用注释解释了 A2 为什么是required-with-fallback而非optionalAgent 生成的 artifact 会把单个品牌的:root块粘贴进一个style运行时没有全局 defaults 样式表级联。若某个tokens.css缺失var()目标例如漏掉--motion-fasttransition: var(--motion-fast)会退化成transition:规则被整条丢弃artifact 直接损坏。因此运行时契约是每个tokens.css必须声明全部 A1 A2 B-slot 令牌fallback 只存在于_schema/defaults.cssdesign-systems/_schema/defaults.css供 derive 脚本内联。同时token-schema.ts还导出了BRAND_EXTENSIONS品牌专属的 C-extension 白名单与BRAND_EXTENSIONS前缀机制以及getRequiredA1Names()、getRequiredA2Names()、getBSlotNames()、getAllSchemaNames()、isAllowedExtension()等辅助函数——这些正是守护脚本guard checks用来核验每个品牌包是否满足契约的运行时 API。design-systems/_schema/tokens.schema.ts只是对该文件的兼容再导出。5. Retro 完整令牌图谱56 个令牌按层归类Retro 的 tokens.css 是:root内逐行声明的最终裁决者。下面按报告中的layerCounts分层列出全部 56 个令牌便于对照使用A1-identity8 个——品牌本体--bg: #fff4cf、--surface: #fffaf0、--fg: #2a1810、--muted: #8a6652、--border: #d9aa7a、--accent: #d24b1f、--font-display: Courier New, ui-monospace, monospace、--font-body: Inter, system-ui, sans-serifA1-structure18 个——结构决策字号刻度 8 档--text-xs: 12px、--text-sm: 14px、--text-base: 16px、--text-lg: 18px、--text-xl: 24px、--text-2xl: 36px、--text-3xl: 54px、--text-4xl: 76px 行高与字距--leading-body: 1.52、--leading-tight: 1.06、--tracking-display: 0 区块节奏--section-y-desktop: 96px、--section-y-tablet: 68px、--section-y-phone: 48px 布局--container-max: 1180px、--container-gutter-desktop: 36px、--container-gutter-tablet: 24px、--container-gutter-phone: 16pxA226 个——带默认值的通用令牌accent 派生态--accent-on: #ffffff、--accent-hover: color-mix(in oklab, var(--accent), black 8%)、--accent-active: color-mix(in oklab, var(--accent), black 14%) 语义色--success: #3d8f4f、--warn: #f2a93b、--danger: #b83a2f 等宽字体--font-mono: Courier New, ui-monospace, monospace 间距 8 档--space-1: 4px、--space-2: 8px、--space-3: 12px、--space-4: 16px、--space-5: 20px、--space-6: 24px、--space-8: 32px、--space-12: 48px 圆角--radius-sm: 4px、--radius-md: 8px、--radius-lg: 12px、--radius-pill: 9999px 投影与焦点--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised: 6px 6px 0 rgba(42, 24, 16, 0.26)、--focus-ring: 0 0 0 4px rgba(210, 75, 31, 0.28) 动效--motion-fast: 150ms、--motion-base: 240ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)B-slot4 个——可选槽位Retro 均给出独立值--surface-warm: #ffdca8、--fg-2: #593625、--meta: #d24b1f、--border-soft: #efd0ab值得注意的两处 Retro 特色其一Retro 的投影--elev-raised采用6px 6px 0的硬偏移阴影无模糊配合--radius-*的小圆角与--font-display/--font-mono的等宽字体栈共同构成其chunky controls nostalgic product cards的复古界面气质见 tokens.css 的注释其二DESIGN.md 中列出的 Primary#3B82F6等style foundations色彩是设计意图层面的描述而令牌层面的实际强调色是--accent: #d24b1f暖橙红这与 DESIGN.md 第 2 节Favor Primary for CTA emphasis的指引在使用时需以最终令牌为准。6. 派生产物design-tokens.json 与 tailwind-v4.css 的生成纪律evidence.md的 Token Contract 一节还给出了全篇最重要的工程约束design-tokens.jsonandtailwind-v4.cssare derived outputs and should be regenerated from the report and token stylesheet rather than edited by hand.即 design-systems/retro/design-tokens.json 与 design-systems/retro/tailwind-v4.css 都是派生输出唯一合法的更新方式是从source/token-contract.report.json和tokens.css重新生成绝不手工编辑。这与 USAGE.md 中Avoid redefining Tailwind or design-token values independently oftokens.css的禁令相互印证。从实际文件可以看出派生关系的具体形态design-tokens.json 在source字段中显式声明其上游为tokensCss: tokens.css与tokenContractReport: source/token-contract.report.jsonsummary与报告完全一致56/56/56score 100每个令牌条目在报告字段之外增加了type如color并把sources指向tokens.css的行号tailwind-v4.css 头部注释写明 Derived from tokens.css. Keep tokens.css as the source of truth.随后import ./tokens.css并在theme块中把每个令牌映射为 Tailwind 主题变量例如--color-bg: var(--bg)、--text-4xl: var(--text-4xl)、--shadow-raised: var(--elev-raised)、--spacing-section-desktop: var(--section-y-desktop)等从而让bg-bg、text-4xl、shadow-raised这类 Tailwind 工具类直接消费 Retro 令牌。由此可以推断OpenDesign 的 derive 流程是单向的tokens.css report→ 派生 JSON 与 Tailwind 主题任何对派生产物的手工改动都会在下一次生成时被覆盖因此契约报告中的recommendRebuild: false意味着当前两个派生产物仍与源同步无需重建。7. 如何在消费端核验一个品牌包是否契约完整将证据文档与契约源码结合起来可以总结出一套可落地的核验步骤对任何 OpenDesign 设计系统包均适用查 manifest确认 manifest.json 中source.type与sourceFiles齐全路径均为合法的仓库内相对路径校验逻辑见 design-systems/_schema/manifest.schema.ts对层数将source/token-contract.report.json的layerCounts相加8 4 26 18 56并核对A1-identity A1-structure sourceBackedA126查声明确认declaredTokens totalTokens且recommendRebuild为false否则应基于tokens.css与报告重新生成派生产物读证据边界若source.type bundled引用令牌时应使用 tokens.css 与 DESIGN.md 作为依据而不要声称品牌官网实测值复用组件优先复用 components.manifest.json 中的组件组新增组件配方必须能在 components.html 或 DESIGN.md 中找到依据保持令牌名精确跨品牌切换的可靠性依赖令牌名不擅自改动——这正是TOKEN_SCHEMA与BRAND_EXTENSIONS白名单机制见 token-schema.ts存在的意义品牌专属名必须显式列入白名单当第二个品牌采用同名令牌时再提升为共享槽位。8. 边界与反模式哪些话不能说、哪些事不能做最后基于evidence.md与配套文档梳理使用 Retro 包时的边界不声称上游证据Retro 派生自 OpenDesign 内置夹具未对原品牌站点重新爬取任何取自品牌官网的表述都属于越界不绕开源文件design-tokens.json与tailwind-v4.css是生成物修改它们而非tokens.css会在下次生成时丢失不引入离题令牌当现有令牌能解决问题时不要在组件中硬编码偏离色板的十六进制值DESIGN.md 反模式第 1 条不扁平化层级避免全文同一字号字重、避免用装饰性效果降低可读性对应 DESIGN.md 第 9 节的反模式清单。综上design-systems/retro/source/evidence.md虽短却完整定义了 OpenDesign 设计系统 2.0 的审计语义来源类型决定证据强度契约报告保证行号级可追溯派生产物必须单向再生。这套机制让 Retro 这样的 bundled 包既能被 Agent 可靠消费又不会让夹具回填被误当成官方品牌数据。【免费下载链接】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），仅供参考