OpenDesign Material 设计系统 2.0 包使用契约：从 tokens.css 到组件清单的接入与审计指南

• AI 应用
• 人工智能
• AI 技能
• 设计系统
• 媒体生成

本篇指南以 OpenDesign 仓库内 design-systems/material/USAGE.md 为骨架，系统讲解 Material 设计系统 2.0 包（Design System 2.0 package）的文件契约、阅读顺序、设计规范与使用守则。读者将掌握：如何按契约顺序把tokens.css注入产物<style>块、如何用components.manifest.json快速盘点组件并回查components.html选择器、如何借助source/审计证据与 token 契约报告验证包质量，以及避免破坏跨品牌切换稳定性的常见误区。

包定位与核心文件契约

Material 包是 OpenDesign 的「Design System 2.0」体系中的一个品牌包，目录 design-systems/material 内包含一组固定结构的文件，共同构成一份对 Agent 和评审者（reviewers）都有效的「包契约」。从 manifest.json 可以看到该包的自描述信息：

• id：material，name：Material，category：Professional & Corporate；
• source.type：bundled，origin：OpenDesign curated bundled fixture——即本包基于 OpenDesign 精选的内置 fixture 整理而来，并非对上游品牌仓库或官网的新鲜抓取（这一点在 USAGE.md 的 Avoid 一节中被明确要求不得混淆）；
• files：将语义角色映射到具体文件——design→DESIGN.md、tokens→tokens.css、designTokens→design-tokens.json、tailwind→tailwind-v4.css、components→components.html；
• usage：USAGE.md，即本指南所讲解的入口文档；
• componentsManifest：components.manifest.json；
• importMode：normalized；
• craft：建议配套阅读 craft/color.md 与 craft/accessibility-baseline.md；
• preview：preview/colors.html、preview/typography.html、preview/spacing.html三个视觉预览页；
• sourceFiles：source/evidence.md、source/tokens.source.json、source/token-contract.report.json三份审计证据。

整个包的文件组成可以直观列出：

design-systems/material/ ├── USAGE.md # 使用契约（本文主题） ├── DESIGN.md # 视觉意图、约束与反模式 ├── manifest.json # 包自描述清单 ├── tokens.css # 唯一 token 真源（:root 声明） ├── design-tokens.json # 派生输出：结构化 token 清单 ├── tailwind-v4.css # 派生输出：Tailwind v4 @theme 桥接 ├── components.html # 参考组件 fixture（含全部选择器与状态） ├── components.manifest.json # 组件清单（选择器/类/元素/groups 盘点） ├── source/ # 审计证据 │ ├── evidence.md │ ├── tokens.source.json │ └── token-contract.report.json ├── preview/ # 视觉抽查页 │ ├── colors.html │ ├── typography.html │ └── spacing.html └── system/ # 系统页（index.html / kit.html / kit.dark.html）

官方推荐的阅读顺序（Read Order）

USAGE.md 给出了五步阅读/使用顺序，这是任何 Agent 或评审者上手本包的必经路径：

1. 先读USAGE.md本身，理解包契约；
2. 再读 DESIGN.md，掌握视觉意图、约束与反模式；
3. 将tokens.css粘贴进第一个产物的<style>块，之后才编写组件 CSS；
4. 用components.manifest.json获取紧凑的组件清单；当需要精确选择器或状态细节时，打开 components.html；
5. 需要视觉抽查时，检查preview/页面。

这套顺序的本质是「契约 → 意图 → token → 组件 → 视觉验证」的自上而下工作流：先确立设计与技术边界，再让所有样式落在统一的 token 语义上，最后用组件 fixture 和预览页做一致性校验。

设计亮点与色彩立场

USAGE.md 用三条要点概括 Material 包的视觉身份，DESIGN.md 又对其展开为九个维度。核心立场如下：

• 视觉风格：modern, minimal, clean（现代、极简、干净）；
• 色彩立场：primary / secondary / neutral / success / warning / danger 六类语义色；
• 设计意图：让产物可被识别为该风格家族（recognizable to this style family），同时保持可用性与可读性；
• Primary 主色：#6442D6，来自 style foundations 的 token。

DESIGN.md 补充了其余语义色的取值：Secondary#C8B3FD、Success#16A34A、Warning#D97706、Danger#DC2626、Surface#FFFFFF、Text#111827、Neutral#FFFFFF（由 surface token 派生以兼容官方格式）。这些值属于 DESIGN.md 层面的「意图描述」，而实际落地到 CSS 变量时，tokens.css 采用了 Google-blue 交互色体系（accent#1a73e8等），体现了「意图文档」与「可执行 token」之间的差异——这也是理解本包时需要注意的一点：DESIGN.md 负责风格叙事，tokens.css 负责可运行的事实。

Typography 层面：字号阶梯 12/14/16/20/24/32，字体族 primary=Inter、display=Roboto、mono=Fira Code（DESIGN.md 侧）；实际 tokens.css 的字体族为"Google Sans", Roboto、Roboto, Arial、"Roboto Mono", ui-monospace, Menlo。间距刻度为 4/8/12/16/24/32。布局上强调清晰内容块、稳定内边距、headline → support text → primary action的层级，并优先用留白而非边框/阴影来切分区块。

tokens.css：56 个 token 的结构化绑定

tokens.css 是整个包唯一的 token 真源（source of truth），所有派生产物（design-tokens.json、tailwind-v4.css）都由它生成，而不是反向手改。文件头部注释明确了定位：Structured token bindings for Material. material design surface logic with soft elevation, rounded controls, and accessible blue interaction.

:root块按语义分组，可划分为以下几类（括号内为默认值）：

• 背景与表面：--bg(#f8fafd)、--surface(#ffffff)、--surface-warm(#e8f0fe)；
• 文本：--fg(#202124)、--fg-2(#3c4043)、--muted(#5f6368)；
• 交互与状态：--meta(#1a73e8)、--accent(#1a73e8)、--accent-on(#ffffff)、--accent-hover/--accent-active（用color-mix(in oklab, var(--accent), black 8%/14%)派生，而非硬编码色值）、--success(#188038)、--warn(#f9ab00)、--danger(#d93025)；
• 边框：--border(#dadce0)、--border-soft(#edf0f2)；
• 字体：--font-display、--font-body、--font-mono；
• 字号/行高/字距：--text-xs(12px) 至--text-4xl(64px) 共 8 档，--leading-body(1.5)、--leading-tight(1.12)、--tracking-display(0)；
• 间距：--space-1(4px) 至--space-12(48px) 共 8 档，另有--section-y-desktop/tablet/phone(96/68/48px)；
• 圆角：--radius-sm(4px)、--radius-md(12px)、--radius-lg(24px)、--radius-pill(9999px)；
• 阴影/焦点：--elev-flat(none)、--elev-ring(0 0 0 1px var(--border))、--elev-raised(0 3px 8px rgba(60,64,67,.18))、--focus-ring(0 0 0 4px rgba(26,115,232,.24))；
• 动效：--motion-fast(150ms)、--motion-base(250ms)、--ease-standard(cubic-bezier(0.2,0,0,1))；
• 容器：--container-max(1200px)、--container-gutter-desktop/tablet/phone(36/24/16px)。

值得注意的实现细节：hover/active 色通过color-mix()从--accent计算而来，圆角与间距全部走变量，页面内不存在游离的硬编码色值——这正是 USAGE.md「Avoid raw hex values outside the copied :root token block」规则能够成立的技术前提。

组件清单：components.manifest.json 与 components.html

USAGE.md 要求优先复用组件组，而不是发明新控件。组件的事实来源是 components.manifest.json（紧凑盘点）与 components.html（精确选择器与状态）。

manifest 的fixture汇总了参考页规模：styleBlockCount: 1、selectorCount: 48、classCount: 26、elementCount: 19。其groups字段将 48 个选择器归并为组件组：

每个组件组还记录了其消费的 token 引用（tokenReferences），例如 buttons 组引用--accent、--accent-on、--border、--ease-standard、--elev-ring、--radius-md、--motion-fast、--space-5等，从数据层面证明了「组件样式完全由 token 驱动」。

manifest 的 token 一致性分析同样值得评审者关注：tokens段列出了declared（56 个声明）、referenced（组件实际引用）与undeclaredReferenced（引用但未声明，当前为空数组，即零悬空引用）。unusedDeclared为--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn——这些 token 已声明但未被当前组件 fixture 引用，属于「为状态与语义预留」的 token，并非错误。

在 components.html 中可以实际看到这些组件如何组装：hero 区块由.eyebrow眉标 +h1标题 +.lead引导语 +.actions双按钮构成；右侧.panel面板内含.panel-head（含.status在线状态）、三列.metric-grid指标、.card-row双.mini-card（Palette 色板与 Control 输入框）；底部.lower三枚.tile分别演示 Typography / Surface / Interaction 主题。交互状态在 CSS 中均有显式表达：.btn-primary:hover上移 1px 并切换 hover 色，:focus-visible统一使用--focus-ring，input:focus同时改边框色与焦点环。

派生产物：design-tokens.json 与 tailwind-v4.css

design-tokens.json 是 token 的结构化机器可读输出，format为od-design-tokens/v1，contract为TOKEN_SCHEMA。其summary字段给出关键质量指标：totalTokens: 56、declaredTokens: 56、sourceBackedTokens: 56（全部 token 都有源码声明支撑）、aliasTokens: 0、score: 100、grade: "excellent"、recommendRebuild: false。按层分布为A1-identity: 8、B-slot: 4、A2: 26、A1-structure: 18。每个 token 条目都带有layer、confidence（本包均为high）、sources（指向tokens.css的具体声明行，如tokens.css:7）与sourceName。

tailwind-v4.css 则是 Tailwind v4 桥接层：文件头部明确「Derived from tokens.css. Keep tokens.css as the source of truth.」，通过@import "./tokens.css"引入真源，再用@theme { ... }将--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*、--duration-*、--ease-standard、--container-*等命名空间全部映射到 tokens.css 变量。这意味着在 Tailwind 项目中可以直接写bg-accent、text-fg-2、rounded-md、shadow-raised、duration-fast等工具类，且值始终与:root同步。

source/ 审计证据与 token 契约报告

USAGE.md 要求把source/文件当作「bundled fixture backfill 的审计证据」。source/evidence.md 明确了证据范围：本包派生自 OpenDesign 精选内置 fixture，不声称对上游品牌仓库/网站的新鲜抓取；包含的 fixture 文件即DESIGN.md、tokens.css、components.html三个；并规定design-tokens.json与tailwind-v4.css属于派生输出，应通过报告与 token 样式表再生成，而非手工编辑。

source/token-contract.report.json 是TOKEN_SCHEMA契约的逐条映射表：它把每个 schema 绑定映射回提交的tokens.css声明行（如tokens.css:16声明--accent）。sourceScope为open-design-bundled-fixture，与 evidence.md 的表述一致。评审者可以用它快速核验「声称的 token 是否真的存在于源码」。

底层机制：TOKEN_SCHEMA 的分层与校验

Material 包的 token 分层并非随意设计，而是受设计系统 2.0 的 schema 约束。从 design-systems/_schema/AGENTS.md 可见 token 的四层体系：

B-slot 的引入是为了保证跨品牌切换的可靠性：当共享槽位（如--surface-warm）在某个品牌包中缺失时，产物内对它的引用将静默失效；因此 B-slot 要求品牌必须声明，要么以var(--sibling)折叠到同族 token，要么给出独立值。schema 还定义了「C-extension → B-slot → A2 → A1」的晋升路径：当 ≥2 个品牌声明了同名 token 时晋升为 B-slot，当 B-slot 开始独立绑定时晋升为 A2，A2 晋升 A1 则较罕见。这正是 USAGE.md「Preserve the schema token names exactly so cross-brand switching stays reliable」的底层原因——token 名是跨品牌契约的一部分，改名即破坏契约。

仓库侧还配套了校验脚本 scripts/check-design-system-manifests.ts：它通过design-systems/_schema/manifest.schema.ts的parseDesignSystemProjectManifest解析每个包的 manifest，用TOKEN_SCHEMA校验 token，并调用 packages/contracts/src/design-systems/components-manifest.ts 提取组件清单、packages/contracts/src/design-systems/derived-token-outputs.ts 派生 token 输出。可在仓库根目录运行pnpm exec tsx scripts/check-design-system-manifests.ts做全量校验——Material 包的grade: "excellent"、score: 100、recommendRebuild: false正是这类契约检查的预期结果。

Do：接入本包时的四件必做事项

USAGE.md 的 Do 清单定义了正确用法：

1. 精确保留 schema token 名称，让跨品牌切换保持可靠——token 名属于契约而非实现细节，改名会破坏其他品牌包的复用与校验；
2. 用--accent承载主行动、链接、焦点态以及唯一视觉焦点元素——accent 是本包的交互信号中心，应避免引入第二强调色；
3. 优先复用components.manifest.json中的组件组，再考虑发明新控件——如按钮组、输入组、卡片组、徽标组都已覆盖，新增控件应先确认无法复用现有组；
4. 把source/文件当作 bundled fixture backfill 的审计证据——评审与溯源时以 source/ 下的 evidence 与契约报告为准。

Avoid：四条必须规避的陷阱

USAGE.md 的 Avoid 清单定义了负面边界：

1. 不要在被复制的:roottoken 块之外使用裸十六进制色值——所有颜色都应落在 token 上；
2. 不要脱离tokens.css单独重定义 Tailwind 或 design-token 值——tailwind-v4.css与design-tokens.json是派生产物，手改会导致与真源漂移；
3. 不要声称存在上游原始源码证据——本包基于精选内置 fixture，source/evidence.md已明确不主张新鲜抓取，对外表述必须一致；
4. 不要添加components.html或DESIGN.md中未体现的新组件配方——包契约以这两个文件为组件事实源，超出即超出契约。

实战：三步把 Material 包接进你的产物

综合 USAGE.md 的阅读顺序与 Do 清单，一次合规的接入流程如下：

第一步：注入 token 真源。将 tokens.css 中完整:root块粘贴到第一个产物的<style>块顶部（保持变量名与值完全一致），之后所有组件样式都只引用这些变量。

第二步：按组件组复用结构。打开 components.manifest.json 对照groups，需要按钮就用.btn/.btn-primary/.btn-secondary语义，需要表单就用.field+label+input结构，需要面板就用.panel/.panel-head/.metric-grid；若需精确复刻状态（hover、focus-visible、disabled、loading），以 components.html 的实现为准。

第三步：视觉抽查与自查。若部署环境支持，可打开preview/colors.html、preview/typography.html、preview/spacing.html三个预览页比对色彩、字号与间距是否与预期一致；同时对照 DESIGN.md 的 Anti-patterns 自查：不引入调色板外颜色、不扁平化层级（同一字号/字重贯穿全文）、不加损害可读性的装饰效果、不混用无关视觉隐喻。

按此流程产出的页面，将同时满足「识别为该风格家族」「token 驱动」「可跨品牌切换」三个包级要求，也就能通过 scripts/check-design-system-manifests.ts 所代表的那类契约校验。

• AI 应用
• 人工智能
• AI 技能
• 设计系统
• 媒体生成