OpenDesign Sleek 设计系统包使用指南：从 tokens 到组件的 Agent 消费手册

Sleek 是 OpenDesign 仓库中 Design System 2.0 体系下的一个完整设计系统包，归类为 "Modern & Minimal"（现代极简），其核心定位是让 OpenDesign Agents 与人工审阅者在不依赖原始上游站点爬取的前提下，仅凭包内自带的 DESIGN 契约、token 样式表和组件 fixture 即可稳定产出风格统一、可读性良好的界面产物。阅读本篇后，你将掌握该包的文件契约、读取顺序、token 分层结构、组件清单的解读方式，以及 Agent 生成代码时应遵循的 Do / Avoid 边界，并理解其背后的"bundled fixture 回填"审计机制。

包的定位与文件契约

Sleek 包的入口说明位于 design-systems/sleek/USAGE.md，它将自己定义为 "Design System 2.0 package guide for OpenDesign agents and reviewers"。包内的 manifest.json 以 od-design-system-project/v1 schema 声明了完整的文件契约：

• design → DESIGN.md：视觉意图、约束与反模式
• tokens → tokens.css：token 的唯一事实来源（source of truth）
• designTokens → design-tokens.json：按 TOKEN_SCHEMA 契约导出的结构化 token 清单
• tailwind → tailwind-v4.css：Tailwind v4 派生绑定
• components → components.html：组件 fixture
• componentsManifest → components.manifest.json：组件清单与 token 引用关系
• preview → preview/colors.html、preview/typography.html、preview/spacing.html：颜色、排版、间距的视觉抽查页
• sourceFiles → source/evidence.md、source/tokens.source.json、source/token-contract.report.json：回填审计证据

manifest 中 source.type 明确标记为 bundled，origin 为 "OpenDesign curated bundled fixture"，importMode 为 normalized。这一契约的意义在于：包内的设计资产是经过 OpenDesign 策展、归一化后随仓库捆绑发布的，而非对上游品牌站点的实时抓取，因此在使用时不应声称持有原始上游源码证据。

推荐读取顺序

USAGE.md 给出了面向 Agent 的五个读取步骤，这是消费该包的标准操作流程：

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

该顺序体现了"先定 token、再写组件、最后验证"的渐进式工作流，与 DESIGN.md 中"在编写组件 CSS 之前先引入 token"的约束一致。

设计亮点与视觉基调

DESIGN.md 定义了 Sleek 的风格基调：

• 视觉风格：modern、minimal、clean（现代、极简、干净）
• 色彩立场：primary、neutral、success、warning、danger 五类语义色
• 设计意图：让输出保持该风格家族的可辨识度，同时保证可用性与可读性
• Primary：#3B82F6（来自 style foundations 的 token）

DESIGN.md 中的完整色板还包括 Secondary #8B5CF6、Success #16A34A、Warning #D97706、Danger #DC2626、Surface #FFFFFF、Text #111827，其中 Neutral 直接派生自 surface token 以兼容官方格式。需要留意的是：DESIGN.md 记录的是面向最终视觉意图的"浅色语义"，而 tokens.css 中实际承载的是深色面板语系（--bg: #090b12、--surface: #121722、--fg: #f8fafc、--accent: #60a5fa），二者共同构成了"风格家族辨识度"的完整证据链。

排版上采用 desktop-first 的 expressive 字阶，字体族为 Inter（primary/display）与 JetBrains Mono（mono），字重覆盖 100–900 全档。布局采用 8pt 基线网格，强调一致的纵向节奏与可预测的栅格对齐，避免临时偏移。组件层面要求按钮、输入框、卡片等遵循一致的圆角、间距与层级策略。

token 体系：56 个变量的分层结构

tokens.css 是 token 的唯一事实来源，共声明 56 个 CSS 自定义属性，全部集中在 :root 块中，按语义可分为七大类：

类别	代表 token	典型值
背景与表面	--bg、--surface、--surface-warm	#090b12、#121722、#1b2233
前景与文字	--fg、--fg-2、--muted、--meta	#f8fafc、#cbd5e1、#94a3b8、#60a5fa
边框	--border、--border-soft	#2a3447、#1d2636
强调与语义色	--accent、--accent-on、--accent-hover、--accent-active、--success、--warn、--danger	#60a5fa、#06101d、color-mix(...) 派生
字体与排版	--font-display、--font-body、--font-mono、--text-xs~--text-4xl、--leading-*、--tracking-display	12px–76px 字阶
间距与布局	--space-1~--space-12、--section-y-*、--container-max、--container-gutter-*	4px 起 8pt 网格
圆角 / 阴影 / 动效	--radius-*、--elev-*、--focus-ring、--motion-*、--ease-standard	如 --radius-pill: 9999px

其中 --accent-hover 与 --accent-active 使用 color-mix(in oklab, var(--accent), black 8%/14%) 从 --accent 派生，体现"单一来源派生状态色"的现代 CSS 实践。动效侧 --motion-fast: 150ms、--motion-base: 240ms 与 --ease-standard: cubic-bezier(0.2, 0, 0, 1) 对应 DESIGN.md 中"150–250ms、稳定缓动"的交互规范。

分层模型与契约审计

design-tokens.json 按 TOKEN_SCHEMA 契约对 56 个 token 做了分层标注，统计信息与 source/token-contract.report.json 完全一致：

• A1-identity（8 个）：品牌身份色与基础字体，如 --bg、--surface、--fg、--muted、--accent、--font-display、--font-body
• A1-structure（18 个）：结构类维度，如字阶 --text-*、行高、字距、章节纵向间距、容器宽度与 gutter
• B-slot（4 个）：槽位类语义色，如 --surface-warm、--fg-2、--meta、--border-soft
• A2（26 个）：派生与状态层，如 --accent-on、--accent-hover、--accent-active、语义色、--space-*、--radius-*、--elev-*、动效 token

两个文件的 summary 均给出 score: 100、grade: "excellent"、recommendRebuild: false，且 sourceBackedTokens: 56 意味着每个 token 都能回溯到 tokens.css 中的具体声明行（例如 --bg 对应 tokens.css:7、--container-gutter-phone 对应 tokens.css:62）。这正是 USAGE.md 中"将 source/ 文件视为 bundled fixture 回填的审计证据"的技术含义：token-contract.report.json 把每个 TOKEN_SCHEMA 绑定映射回提交的 tokens.css 声明行，design-tokens.json 与 tailwind-v4.css 均为派生产物，应当从报告与 token 样式表重新生成，而不是手工编辑。

Tailwind v4 派生绑定

tailwind-v4.css 头部注释明确声明"Derived from tokens.css. Keep tokens.css as the source of truth."。它通过 @import "tailwindcss" 与 @import "./tokens.css" 引入基础样式，再在 @theme 块中将 Sleek token 映射为 Tailwind 命名空间的工具类变量，例如：

• --color-accent: var(--accent)、--color-bg: var(--bg) → 可用 bg-accent、text-accent 等工具类
• --font-sans: var(--font-body)、--font-mono: var(--font-mono)
• --spacing-2: var(--space-2) → 间距工具类
• --shadow-raised: var(--elev-raised)、--duration-fast: var(--motion-fast)
• --container-max、--spacing-container-* → 布局约束

这也解释了 USAGE.md 中"避免独立于 tokens.css 重新定义 Tailwind 或 design-token 值"的约束：一旦 Tailwind 绑定与 token 样式表脱钩，跨品牌切换（cross-brand switching）时依赖 schema token 名称的可靠性就会被破坏。

组件清单：从 manifest 到 fixture

components.manifest.json 对 components.html 做了结构化盘点：fixture 包含 1 个 style 块、48 个选择器、26 个类、19 个元素。它按组件组（groups）组织清单，并标注每组引用的 token：

• buttons（按钮与 CTA）：.btn、.btn-primary、.btn-secondary 及 :hover、:focus-visible 状态，引用 --accent、--accent-on、--radius-md、--space-5、--motion-fast、--ease-standard 等 11 个 token
• inputs（表单字段）：.field、input、input:focus、label，引用 --border、--radius-sm、--space-* 等
• cards（卡片与面板）：.panel、.panel-head、.tile、.card-row，引用 --surface、--border、--radius-lg、--elev-raised
• badges（徽章/状态标签）：.status
• links（链接与行内操作）：元素 a
• typography（排版）：.eyebrow、.lead、h1–h3，引用 --text-4xl、--text-xl、--text-lg、--fg-2
• layout（布局原语）：.container、section、.metric-grid，引用 --container-gutter-*、--section-y-desktop
• keyboard / icons：present: false，即 fixture 中不含键盘提示与图标槽位

manifest 还给出了 token 使用统计：declared 56 个、referenced 约 44 个，unusedDeclared 包括 --accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn（即当前组件 fixture 尚未消费、但为语义完整性预留的 token），undeclaredReferenced 为空，说明组件引用与声明完全闭合。

从源码结构看，这套清单的作用是为 Agent 提供"先复用既有组件组、再发明新控件"的决策依据，同时在组件选择器与 token 之间建立可机检的引用链，便于后续校验。

Agent 使用边界：Do 与 Avoid

USAGE.md 最后给出了两条硬性使用纪律，是 Agent 生成代码时的合规基线：

Do（应当遵守）

• 严格保留 schema token 名称，确保跨品牌切换可靠；
• 用 --accent 承担主操作、链接、焦点态与唯一的视觉焦点元素；
• 在发明新控件之前，优先复用 components.manifest.json 中的组件组；
• 将 source/ 文件视为 bundled fixture 回填的审计证据。

Avoid（应当避免）

• 在复制的 :root token 块之外使用裸 hex 色值；
• 独立于 tokens.css 重新定义 Tailwind 或 design-token 值；
• 声称持有原始上游源码证据（本包基于策展的 bundled fixture）；
• 添加 components.html 或 DESIGN.md 中未体现的新组件配方。

与之呼应，DESIGN.md 的反模式章节还补充了四条视觉纪律：不引入 token 之外的离配色板颜色、不通过统一字号/字重压平层级、不添加损害可读性与可达性的装饰效果、不在同一界面混用无关视觉隐喻。

视觉抽查与运行方式

当需要确认生成结果是否符合 Sleek 风格时，可以直接在浏览器中打开 preview/ 目录下的三个静态页面（均为纯 HTML，无需构建）：preview/colors.html 用于抽查色板、preview/typography.html 用于抽查字阶、preview/spacing.html 用于抽查间距节奏。此外 system/kit.html 与 system/kit.dark.html 提供完整的组件套件展示（含深色变体），system/index.html 作为系统总览页，可作为 Agent 生成前后的视觉基线参照。

小结

Sleek 包的价值在于把"现代极简风格"沉淀为一套可机检、可复用的资产闭环：tokens.css 作为唯一事实来源，design-tokens.json 与 tailwind-v4.css 作为派生产物，components.manifest.json 作为组件与 token 的关联索引，token-contract.report.json 作为逐 token 可回溯的审计证据，而 USAGE.md 则把这一切组织成 Agent 可直接执行的读取顺序与使用纪律。对 OpenDesign 的 Agent 与审阅者而言，遵循这份契约即可在不引入离配色板色彩、不破坏 token 命名、不脱离组件 fixture 的前提下，稳定产出具有 Sleek 风格辨识度的界面产物，同时保持跨品牌切换的可靠性。