OpenDesign Retro 设计系统包使用指南：面向 Agent 与评审者的 Design System 2.0 实践手册

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

本文档是 OpenDesign 仓库中design-systems/retro设计系统包的完整使用指南，核心基于 USAGE.md 的包契约约定，并结合 DESIGN.md、tokens.css、components.manifest.json 与 design-tokens.json 等配套文件展开。读者（尤其是接入 OpenDesign 的编码 Agent、设计系统评审者与前端开发者）读完本文后将掌握：如何按正确顺序消费 Retro 包、如何正确复制并复用 56 个设计令牌、如何引用组件清单避免发明新控件，以及如何规避该包明确列出的反模式，最终在 OpenDesign 生成产物中稳定复现高对比复古（high-contrast retro）风格。

一、包契约概览：Retro 是什么

design-systems/retro是 OpenDesign 仓库中按 Design System 2.0 规范组织的一个「捆绑式」（bundled）设计系统包，类别为Retro & Nostalgic（复古与怀旧），其 manifest.json 明确声明了包的身份与文件组成：

{ "schemaVersion": "od-design-system-project/v1", "id": "retro", "name": "Retro", "category": "Retro & Nostalgic", "description": "Bundled OpenDesign package for Retro, derived from curated DESIGN.md, tokens.css, and components.html fixtures.", "source": { "type": "bundled", "origin": "OpenDesign curated bundled fixture" }, "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": { "applies": [], "suggested": ["color", "accessibility-baseline"] }, "preview": { "dir": "preview", "pages": [] }, "sourceFiles": { "evidence": "source/evidence.md", "tokens": "source/tokens.source.json", "report": "source/token-contract.report.json" } }

值得注意的契约要点：

• source.type = "bundled"：该包基于 OpenDesign 精选的捆绑 fixture 生成，不声明对上游原始品牌仓库或网站的重新抓取（source/evidence.md 对此有专门说明）。
• importMode = "normalized"：导入模式为归一化，令牌与样式在进入产物前经过标准化处理。
• craft.suggested：manifest 建议在创作时套用 color 与 accessibility-baseline 两套 craft 规则——前者约束配色纪律，后者给出对比度、触控目标等可量化的无障碍底线（如正文常规文本需 ≥ 4.5:1 对比度、普通控件触控目标 ≥ 24×24 CSS px）。
• preview与sourceFiles：分别指向可视化预览页与审计证据文件，后文会详述。

二、推荐的阅读与使用顺序（Read Order）

USAGE.md 给出了五步消费流程，这是 Agent 与评审者接入该包的标准动作序列：

1. 先读本指南（USAGE.md），理解包契约，即当前这份文档。
2. 阅读 DESIGN.md，掌握视觉意图、约束条件与反模式（anti-patterns）清单。
3. 将 tokens.css 粘贴到首个产物的<style>块中，然后再编写组件 CSS——这是保证令牌体系不被绕过的关键动作。
4. 使用 components.manifest.json 获取紧凑的组件清单；当需要精确选择器或状态细节时，打开 components.html 查看参考实现。
5. 需要视觉抽查时，检查 preview/ 下的页面。

这套顺序的本质是「契约 → 意图 → 令牌 → 组件 → 视觉验证」的依赖链：令牌必须先于组件 CSS 就位，组件清单应先于新控件的发明被查询，预览页只用于最终的人眼/工具校验。

三、设计要点：设计系统的「身份声明」

USAGE.md 用三组关键词概括 Retro 包的设计身份，这些声明在 DESIGN.md 中有完整展开：

DESIGN.md 进一步细化了该风格的落地规则：

• 色彩：Primary#3B82F6用于 CTA 强调；Surface#FFFFFF用于大面积背景与卡片；正文保持 Text#111827以保证可读性。Secondary 为#8B5CF6，Success/Warning/Danger 分别为#16A34A/#D97706/#DC2626，Neutral 由 surface 令牌派生以兼容官方格式。
• 字体：桌面优先的表现性字阶（desktop-first expressive scale），display 与 primary 家族使用 Macondo，mono 使用 JetBrains Mono，字重覆盖 100–900；标题承载风格个性，正文优化扫读性与对比度。
• 间距与栅格：间距刻度为 4/8/12/16/24/32，保持区块间一致的纵向节奏，列与模块对齐到可预测的栅格，避免临时偏移。
• 布局与构成：偏好内部内边距一致的内容块；层级顺序保持「标题 → 支撑文案 → 主行动」；先用留白区隔内容，再考虑边框与阴影。
• 组件：按钮主行动用 Primary，次行动保持中性；输入框有强 focus-visible 状态、清晰标签与可预期的错误提示；卡片/区块统一圆角、间距与抬升策略。
• 动效与交互：以 Primary 作为交互信号，默认 150–250ms 短促过渡与稳定缓动；hover、focus-visible、active、disabled、loading 状态必须显式定义。
• 语气与品牌：文案风格贴合视觉风格——简洁、自信、产品导向；微文案行动导向，避免通用填充语。
• 反模式：不引入调色板之外的色值；不用同一字号/字重压平层级；不添加损害可读性或无障碍的装饰效果；不在同一界面混入无关的视觉隐喻。

四、设计令牌深度解析：tokens.css 的 56 个令牌

tokens.css 是该包所有派生物的事实源头（source of truth）。文件开头的注释直接点题：

/* design-systems/retro/tokens.css * Structured token bindings for Retro. * retro interface with warm colors, chunky controls, and nostalgic product cards. */

整个令牌体系定义在:root块中，共 56 个令牌，按 design-tokens.json 的分层统计可划分为四层：

4.1 色彩令牌（Color）

注意：实际捆绑令牌中的主强调色是暖橙#d24b1f（--accent/--meta），与 DESIGN.md 中提到的通用 Primary#3B82F6属于风格基座层面的参考色；以tokens.css中声明的值为准，这也是 USAGE.md「Avoid 原始 hex 出现在:root令牌块之外」的用意。--accent-hover/--accent-active使用现代 CSScolor-mix(in oklab, ...)语法动态派生，保证 hover/active 态始终与基色同源。

4.2 字体令牌（Typography）

display 与 mono 家族共享 Courier New 等宽栈，赋予标题与数据指标强烈的「复古终端」气质；正文则回落到 Inter 无衬线以保证长文可读性——这正是「标题携带风格个性、正文优化扫读与对比」意图的令牌级落地。

4.3 间距、圆角、阴影与动效（Structure / A2）

间距刻度采用 4px 基数：--space-1(4) /--space-2(8) /--space-3(12) /--space-4(16) /--space-5(20) /--space-6(24) /--space-8(32) /--space-12(48)。

圆角体系：--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))；--container-max(1180px)，gutters 桌面/平板/手机分别为 36/24/16px，--section-y-*为 96/68/48px 的区块纵向节奏。

4.4 令牌契约审计

source/token-contract.report.json 将 TOKEN_SCHEMA 的每一个绑定映射回tokens.css的具体声明行（如--bg→tokens.css:7、--accent→tokens.css:16）。审计结论为：

"summary": { "totalTokens": 56, "declaredTokens": 56, "sourceBackedTokens": 56, "aliasTokens": 0, "score": 100, "grade": "excellent", "recommendRebuild": false }

即 56 个令牌全部有源码背书、无别名令牌、无未声明引用，评分 100、等级 excellent。这意味着按 USAGE.md 第 3 步粘贴tokens.css后，组件 CSS 中引用的每一个var(--*)都有确定来源，跨品牌切换（cross-brand switching）时不会出现悬空引用。

五、组件清单：复用而非发明

components.manifest.json 是包内组件的紧凑索引。它记录了参考 fixture 的规模与结构：

"fixture": { "title": "Retro - reference components", "description": "Reference fixture for design-systems/retro: retro interface with warm colors, chunky controls, and nostalgic product cards.", "styleBlockCount": 1, "selectorCount": 48, "classCount": 26, "elementCount": 19 }

manifest 将组件划分为 9 个组，其中 7 个存在（present: true），2 个缺席（keyboard键盘提示、icons图标槽）：

对照 components.html 可见每个组的真实实现。例如按钮组：

.btn { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: 0 var(--space-5); border: 1px solid transparent; border-radius: var(--radius-md); font: 700 var(--text-sm) / 1 var(--font-body); transition: background-color var(--motion-fast) var(--ease-standard), ...; } .btn:focus-visible { outline: none; box-shadow: var(--focus-ring); } .btn-primary { background: var(--accent); color: var(--accent-on); } .btn-primary:hover { background: var(--accent-hover); transform: translateY(-1px); } .btn-secondary { background: var(--surface); color: var(--fg); border-color: var(--border); box-shadow: var(--elev-ring); }

min-height: 44px的触控目标恰好满足 accessibility-baseline 中 AAA 级 44×44 CSS px 的 craft 承诺，:focus-visible焦点环由--focus-ring统一提供——组件实现与无障碍底线形成了可验证的对应关系。

manifest 还提供令牌使用情况的统计视角：

• referenced（被引用）：--accent、--bg、--border、--fg、--motion-fast、--space-*等 52 个令牌在组件 CSS 中被实际消费；
• unusedDeclared（已声明未使用）：--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn共 7 个——它们是预留令牌，供扩展组件或状态使用；
• undeclaredReferenced（未声明却被引用）：空数组，证明组件 CSS 没有越过令牌体系使用魔法值。

六、派生产物与集成方式

Retro 包提供了多套派生物，方便不同技术栈的 Agent 直接消费：

6.1 design-tokens.json（结构化令牌）

design-tokens.json 以od-design-tokens/v1格式输出全部 56 个令牌的结构化描述，每个条目包含name、value、type（color / fontFamily / dimension / number / shadow / duration / cubicBezier）、layer、confidence与sources（精确到tokens.css行号）。例如：

{ "name": "--elev-raised", "value": "6px 6px 0 rgba(42, 24, 16, 0.26)", "type": "shadow", "layer": "A2", "confidence": "high", "sources": ["tokens.css:54"] }

适合需要以 JSON 形式驱动 Figma 插件、主题系统或自动化检测工具的场景。

6.2 tailwind-v4.css（Tailwind v4 桥接）

tailwind-v4.css 是面向 Tailwind CSS v4 项目的派生物，文件头注释明确「Derived from tokens.css. Keep tokens.css as the source of truth.」——它通过@theme块把令牌映射为 Tailwind 主题变量：

@import "tailwindcss"; @import "./tokens.css"; @theme { --color-accent: var(--accent); --color-surface-warm: var(--surface-warm); --font-display: var(--font-display); --text-4xl: var(--text-4xl); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); --spacing-section-desktop: var(--section-y-desktop); /* ... */ }

映射后即可在 Tailwind 类中直接书写bg-accent、text-fg-2、shadow-raised、duration-fast等工具类，而值仍回溯到tokens.css。注意：该文件与design-tokens.json一样属于派生输出，应通过报告与令牌样式表重新生成（见 source/evidence.md），不应手工编辑。

6.3 system/tokens.default.json（运行时最小主题）

system/tokens.default.json 提供运行时最小的默认主题参数（主色、主色背景、hover/active 派生、字号 16、圆角 8），供需要轻量主题注入的宿主环境使用：

{ "colorPrimary": "#d24b1f", "colorPrimaryBg": "#ffdca8", "colorPrimaryHover": "color-mix(in oklab, var(--accent), black 8%)", "colorPrimaryActive": "color-mix(in oklab, var(--accent), black 14%)", "fontSize": 16, "borderRadius": 8 }

七、Do 与 Avoid：Agent 的纪律红线

USAGE.md 明确列出了使用时必须遵守与必须避免的行为，这是评审者审查 Agent 产出时的核心判据：

Do（必须做）

• 精确保留 schema 令牌名，使跨品牌切换保持可靠——令牌名是包契约的一部分，改名会导致派生物与组件选择器失联；
• 用--accent承担主行动、链接、焦点态以及一个清晰的焦点元素——强调色要克制，全页只有一个视觉焦点；
• 在发明新控件之前，先复用 components.manifest.json 中的组件组；
• 将 source/ 文件视为「捆绑 fixture 回填」的审计证据，而非上游一手资料。

Avoid（必须避免）

• 在复制的:root令牌块之外使用原始 hex 值——一切颜色都必须走令牌；
• 独立于 tokens.css 重新定义 Tailwind 或设计令牌值——Tailwind 桥接文件只能做变量引用映射；
• 声称拥有原始上游来源证据——该包基于精选捆绑 fixture，证据边界见 source/evidence.md；
• 添加 components.html 或 DESIGN.md 中不存在的新组件配方。

这些红线本质上都在保护「令牌唯一事实源」：任何绕过tokens.css的值、任何超出组件清单的控件、任何未经验证的上游声明，都会破坏包的可切换性与可审计性。

八、预览与视觉验证

包内提供两套可视化资源用于产出前的检查：

1. preview/ 预览页：preview/colors.html（色彩）、preview/typography.html（字体）、preview/spacing.html（间距），对应 manifest 中preview.pages的 colors / typography / spacing 三种角色，用于逐维度抽查令牌渲染结果；
2. system/ 系统页：system/index.html、system/kit.html、system/kit.dark.html，提供组件套件（kit）级别的整体预览，kit.dark.html还覆盖暗色变体。

工作流上，Agent 应先以components.html为准核对选择器与状态，再打开预览页做人眼/工具级的视觉抽查，最终产物中不残留预览页面。

九、实战：从令牌到产物的最小工作流

将 USAGE.md 的步骤落成一个可执行的 Agent 工作流：

1. 复制 tokens.css 的完整:root块到产物<style>最顶部——逐字复制，不改名、不加值；
2. 打开 components.html，按需摘取.btn、.panel、.field、.status等选择器对应的组件 CSS，粘贴到令牌块之后；
3. 需要新 UI 时，先查 components.manifest.json 的 groups/classes 列表确认是否已有现成组件；确认没有后再参考 DESIGN.md 的组件与布局规则，仅使用已声明令牌编写新样式（例如圆角一律用--radius-sm/md/lg，抬升一律用--elev-flat/ring/raised，动效一律用--motion-fast/base加--ease-standard）；
4. 关键交互状态补全：:hover用--accent-hover，:focus-visible用--focus-ring，disabled/loading 态用--muted/--border-soft明确呈现；
5. 用 preview/ 页面或 system/kit.html 做视觉抽查，并对照 accessibility-baseline 核验对比度与触控目标（正文 ≥ 4.5:1，控件 ≥ 24×24 CSS px，焦点指示 ≥ 3:1）。

按此流程产出的界面将稳定呈现 Retro 包的高对比复古特征：奶油底色#fff4cf、暖橙强调#d24b1f、Courier New 等宽标题、硬偏移投影--elev-raised与 150ms 统一动效，同时保持与包契约完全一致、可审计、可跨品牌切换。

十、总结

design-systems/retro是一个自洽、可审计的 Design System 2.0 包：它以 USAGE.md 为契约入口，以 tokens.css 的 56 个令牌为唯一事实源，以 components.manifest.json 与 components.html 为组件边界，以 design-tokens.json 与 tailwind-v4.css 为多栈派生出口，并用 source/ 审计文件锁定证据边界。对 OpenDesign 的编码 Agent 而言，遵循「契约 → 意图 → 令牌 → 组件 → 验证」的消费顺序、严守 Do/Avoid 红线，即可在每一次产出中精确复现复古高对比风格，同时为评审者留下可追查的令牌来源与组件依据。

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