OpenDesign 设计系统来源证据与 Token 契约审计机制以 Shopify 暗色电商品牌为例【免费下载链接】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 System 2.0的来源证据Source Evidence与 Token 契约Token Contract机制展开。核心文档是 design-systems/shopify/source/evidence.md它定义了打包式回填bundled fixture backfill的来源边界、三层 fixture 文件清单以及token-contract.report.json与tokens.css之间的逐条绑定关系。读完本文你将掌握OpenDesign 每个品牌包如 shopify的 token 是如何被声明、审计、分层和派生的以及如何阅读design-tokens.json、tailwind-v4.css等派生产物而不至于误改源头。1. 什么是 Source Evidence回填包的来源边界evidence.md的第一节Source Scope给出了一个非常重要的声明该设计系统包是对 OpenDesign 内置精选夹具curated bundled fixture的二次回填backfill并不声称重新抓取过上游品牌的原始仓库或网站。这句话定义了整个包的证据边界evidence boundary包内所有视觉规范均来自 OpenDesign 自带的、经过人工筛选的 fixture 内容任何Shopify 官网就是长这样的结论都不能以本包为原始证据只能以包内 fixture 为证据这也是 design-systems/shopify/USAGE.md 中 Avoid claiming original upstream source evidence 一条的由来——它明确提醒使用者和审查者不要声称持有上游原始来源证据本包基于打包的精选夹具。在 design-systems/shopify/manifest.json 中这一边界被结构化为机器可读的字段source: { type: bundled, origin: OpenDesign curated bundled fixture }同时 manifest 还声明了importMode: normalized即导入模式为规范化并给出建议套用的 craft 规范color、accessibility-baseline。从源码结构看source/evidence.md就是这套打包回填流程的证据留存文件目的是让任何人在审计某个品牌包时能快速判断其证据等级是否来自上游实抓避免把二手规范当作一手事实。2. 包含的 Fixture 文件三层包骨架evidence.md列出回填包的三份核心 fixture文件作用design-systems/shopify/DESIGN.md视觉意图与设计规范色彩角色、排版层级、组件样式、布局原则、响应式行为、Dos Dontsdesign-systems/shopify/tokens.css结构化 Token 绑定将品牌视觉决策编码为:root下的 CSS 自定义属性design-systems/shopify/components.html组件参考夹具按钮、卡片、表单、导航等实际可用的 HTML 组件这三者形成规范 → 令牌 → 组件的完整闭环DESIGN.md是人读的规范例如Shopify 是 dark-first 的暗色数字剧场96px/weight 330 的 NeueHaasGrotesk 极细显示字体、霓虹绿#36F4A4只用于焦点环和关键强调tokens.css是机器读的令牌把上述规范逐条变成--bg、--surface、--accent等可在任意组件中引用的变量components.html是可复制的参考实现其样式引用 tokens.css 的令牌确保每个可见值都来自 tokens.css见 design-systems/shopify/components.manifest.json 的 fixture 描述。配套的还有组件清单 design-systems/shopify/components.manifest.json它统计出该夹具含 1 个style块、35 个选择器、15 个类、22 个元素并把组件归组为 buttons、inputs、cards、links、icons、typography、layout 等组每组列出其引用的 token 名称。例如 buttons 组引用了--bg、--fg、--radius-sm、--font-display、--space-2等这为组件是否越界使用裸值提供了可审计的清单。此外包内还提供 design-systems/shopify/preview/colors.html、preview/typography.html、preview/spacing.html三个预览页用于肉眼抽查颜色、排版与间距的还原度。3. Token Contract逐条可追溯的审计报告evidence.md的核心内容是 Token Contract 机制source/token-contract.report.json将每个TOKEN_SCHEMA绑定映射回已提交的tokens.css声明行。这句话对应的实际产物是 design-systems/shopify/source/token-contract.report.json。打开这份报告其summary给出了关键审计指标{ contract: TOKEN_SCHEMA, 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 } }这份摘要可以解读为56 个 token 全部在tokens.css中有声明declaredTokens sourceBackedTokens 56即声明的都来自源、源里的都被声明无孤儿、无缺口26 个 A1 级 token8 个 A1-identity 18 个 A1-structure全部有源支撑即品牌自定义部分 100% 可追溯26 个 A2 token 使用了 schema 层的 fallback 值fallbackTokens 26即这些 token 的值与_schema/defaults.css中的默认值一致0 个别名 tokenaliasTokens 0说明 Shopify 包对 B-slot 槽位如--surface-warm、--fg-2、--meta、--border-soft提供了真实独立的取值而非简单地var()别名到兄弟 token综合评分 100、评级 excellent、无需重建。每个 token 条目还带sources字段精确到tokens.css的行号例如{ name: --bg, layer: A1-identity, value: #000000, confidence: high, reason: Bundled tokens.css declares --bg; no upstream recrawl was performed for this backfill., sources: [tokens.css:36], sourceName: --bg }也就是说任何 reviewer 都可以从报告反向跳到 design-systems/shopify/tokens.css 第 36 行核对--bg: #000000的真实声明。这就是契约可追溯的工程含义报告不是一份独立的人写文档而是由工具从 tokens.css 派生出来的机器审计结果。4. Token 分层机制四层 Schema 的底层实现evidence.md提到的TOKEN_SCHEMA并非抽象概念它的权威定义在 packages/contracts/src/design-systems/token-schema.ts并由 design-systems/_schema/tokens.schema.ts 做兼容再导出。该文件把每个 token 划入四个分层区分由谁决定取值、品牌缺省时发生什么层语义品牌缺省时的行为Shopify 示例A1-identity必需。token 即品牌本身无任何默认值可替代缺省即违规必须声明--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-bodyA1-structure必需。结构性决策字号阶梯、网格、节律每个品牌自行编写无跨品牌合理默认--text-xs~--text-4xl、--leading-body、--container-max等A2最终tokens.css中必需但存在合理 fallbackderive 脚本从_schema/defaults.css内联默认值--accent-on、--accent-hover、--space-*、--radius-*、--elev-raised、--focus-ring、--motion-*B-slot可选槽位用于跨品牌一致性无更丰富层级的品牌可用var()别名到兄弟 token--surface-warm、--fg-2、--meta、--border-soft该文件在注释中解释了 A2 为什么是必须但带 fallback而非可选因为产物由 Agent 将某品牌的:root块直接粘贴进单个style生成运行时不存在来自全局默认样式表的级联。一旦粘贴的tokens.css缺少某个var()目标产物就会坏掉——例如transition: var(--motion-fast)会解析为transition:规则被丢弃。因此运行时契约是每个品牌的 tokens.css 必须声明全部 A1 A2 B-slot tokenfallback 只服务于 derive 脚本的内联不服务于运行时。同时该文件提供了辅助函数getRequiredA1Names()、getRequiredA2Names()、getBSlotNames()、getAllSchemaNames()供仓库内的 guard 脚本做一致性校验。从源码结构看这正是token-contract.report.json中contract: TOKEN_SCHEMA字段的校验依据。5. tokens.css契约的落地载体design-systems/shopify/tokens.css 是整个契约的单一事实源single source of truth。它把 Shopify 的暗色电影感品牌拆解为可复用的变量暗色表面层级不是纯黑而是森林绿底色的近黑--bg: #000000页面根背景、--surface: #02090a卡片、--surface-warm: #061a1c区块背景前景文字--fg: #ffffff是暗色表面唯一文字色--muted: #a1a1aa承载次要文本--meta: #71717a承载时间戳等三级信息霓虹绿强调--accent: #36f4a4只用于焦点环与关键强调--accent-on: #000000保证绿底黑字对比度hover 态--accent-hover: #2de097active 态用color-mix(in oklab, var(--accent), black 14%)动态混合——这是现代 CSS 色彩空间运算的典型用法排版--font-display为NeueHaasGrotesk, Helvetica Neue, Helvetica, Arial, sans-serif--font-body为 Inter Variable字号阶梯从--text-xs: 12px一路到--text-4xl: 96px药丸圆角--radius-sm: 9999px——注释明确写道full pill for all CTAs per brand identity全药丸按钮是品牌不可谈判的特征多层阴影--elev-raised是一组 1px 描边环 2px/4px/8px 递进模糊 内嵌白色高光的多层 box-shadow在暗色表面上表现为环境光遮蔽而非传统悬浮焦点环--focus-ring: 0 0 0 2px #36f4a4霓虹绿键盘焦点环是品牌签名节律与容器--section-y-desktop: 96px/--section-y-tablet: 64px/--section-y-phone: 40px定义戏剧化的区块间距--container-max: 1280px与三档 gutter 定义内容容器。design-systems/shopify/DESIGN.md 对这些变量背后的视觉逻辑给出了完整描述96px/weight 330 的极细显示字、ss03OpenType 特性、zinc 中性灰阶、以及Dont 使用纯黑做暗底文字、Dont 引入暖色等反模式清单。tokens.css 与 DESIGN.md 一一对应是规范到令牌的落地证明。6. 派生产物design-tokens.json 与 tailwind-v4.css 的生成规则evidence.md最后一条明确了派生产物的管理规则design-tokens.json和tailwind-v4.css是派生输出应从报告与 token 样式表重新生成而不是手工编辑。这与 design-systems/shopify/tailwind-v4.css 文件头的注释完全一致/* Derived from tokens.css. Keep tokens.css as the source of truth. */。也就是说手工修改这两个文件的任何一行都会被后续重建覆盖正确的改法永远是先改tokens.css与DESIGN.md再重新生成派生产物。design-systems/shopify/design-tokens.json 是 token 的结构化 JSON 视图format: od-design-tokens/v1与报告共享同一份summary并为每个 token 标注了type如color适用于需要程序化消费 token 的场景design-systems/shopify/tailwind-v4.css 通过 Tailwind v4 的theme指令把 tokens.css 的变量桥接到 Tailwind 工具类命名空间例如--color-bg: var(--bg)、--spacing-4: var(--space-4)、--shadow-raised: var(--elev-raised)、--radius-pill: var(--radius-pill)从而让bg-bg、p-4、shadow-raised这类 Tailwind 工具类直接吃到品牌 token。两份派生产物都在manifest.json的files段登记designTokens、tailwind并共同指向tokens.css与source/token-contract.report.json作为来源。7. 包内使用顺序与审计要点design-systems/shopify/USAGE.md 给出了包的标准读取顺序这也是 Agent 与 reviewer 消费该设计系统包的推荐流程先读USAGE.md理解包契约再读 design-systems/shopify/DESIGN.md 把握视觉意图、约束与反模式将 design-systems/shopify/tokens.css 粘贴进首个 artifact 的style块再编写组件 CSS用 design-systems/shopify/components.manifest.json 做组件清单速查需要精确选择器或状态时打开 design-systems/shopify/components.html需要视觉抽查时查看preview/页面。包内还给出三条审计红线保留 schema token 名称不变保证跨品牌切换cross-brand switching可靠避免在:roottoken 块之外使用裸 hex 值避免脱离tokens.css独立重定义 Tailwind 或 design-token 值不要把本包当作上游原始来源证据也不要添加components.html与DESIGN.md未涵盖的新组件配方。evidence.md本身则以极简的三节篇幅为这套流程提供了最底层的来源可信度锚点它告诉每一位读者包里的每一个值都能通过token-contract.report.json反查到 tokens.css 的声明行而这两份文件连同source/tokens.source.json一起构成了该品牌包的完整审计链。对于希望在 OpenDesign 中新增或审查设计系统包的开发者这套规范 令牌 契约报告 派生产物的分层结构就是可以复用的标准模板。【免费下载链接】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），仅供参考