OpenDesign VoltAgent 设计系统包使用指南：从令牌契约到组件落地的完整实操-平芜编程栈

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

【免费下载链接】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-systems/voltagent/USAGE.md 为骨架，结合 DESIGN.md、tokens.css、components.manifest.json 与源码级证据，完整讲解 VoltAgent 这一「Design System 2.0」包的使用契约：如何按顺序阅读包内文件、如何将令牌接入 artifact、如何基于清单复用组件，以及如何在跨品牌切换与团队协作中守住设计一致性。读完本文，你将掌握 OpenDesign 设计系统包的标准消费流程、56 个设计令牌的语义用法，以及面向 Agent 与人工评审者双方的可执行规则。

1. 认识 VoltAgent 包：一份给 Agent 与评审者的包级契约

VoltAgent 是 OpenDesign 仓库design-systems/目录下众多设计系统包之一，属于「AI & LLM」类别，其定位在 manifest.json 中被描述为"Bundled OpenDesign package for VoltAgent, derived from curated DESIGN.md, tokens.css, and components.html fixtures"。它不是一个需要安装运行的 npm 包，而是一套可直接复制进 artifact 的规范化设计资产——包括视觉意图文档、令牌样式表、组件参考实现、令牌契约报告与预览页面。

USAGE.md 开篇即点明它的读者群体：

"Design System 2.0 package guide for OpenDesign agents and reviewers."

也就是说，这份文档同时服务于两条使用链路：

生成侧（Agent）：在 OpenDesign 中编写原型、落地页、仪表盘、幻灯片等 artifact 时，按包内契约消费令牌与组件，保证输出与品牌意图一致；
评审侧（Reviewer / 人）：依据同一份契约核对产物是否越界（例如是否引入了令牌之外的裸色值、是否自造了清单之外的组件配方）。

这种「一份契约、双侧共用」的机制，正是 Design System 2.0 包在 OpenDesign 中的核心价值：把设计约束从人的记忆里搬到可检索、可审计的文件契约里。

2. 包的目录结构与文件职责总览

在动手使用之前，先建立对包结构的整体认知。VoltAgent 包位于design-systems/voltagent/，各文件的职责如下：

文件/目录	角色	使用时机
USAGE.md	包级使用契约（阅读入口）	每次消费该包时先读
DESIGN.md	视觉意图、约束与反模式	需要理解"为什么这样设计"时读
tokens.css	唯一令牌事实源（`:root`块）	必须原样粘贴进首个 artifact 的`<style>`
components.manifest.json	组件清单（紧凑索引）	复用组件前查清单
components.html	组件参考实现（含完整选择器）	需要精确选择器或状态时打开
design-tokens.json	令牌结构化导出（TOKEN_SCHEMA）	需要机器可读的令牌元数据时使用
tailwind-v4.css	Tailwind v4 主题桥接	使用 Tailwind 构建时导入
manifest.json	包清单（schemaVersion: od-design-system-project/v1）	包被 OpenDesign 工具链识别时读取
`preview/`	颜色 / 排版 / 间距可视化检查页	需要视觉 sanity check 时在浏览器打开
`source/`	溯源证据（evidence.md、token-contract.report.json、tokens.source.json）	审计与回填核验时使用
`system/`	index.html、kit.html、kit.dark.html、tokens.default.json	包内参考产出物

其中manifest.json的files字段显式声明了主资产映射：design→DESIGN.md、tokens→tokens.css、designTokens→design-tokens.json、tailwind→tailwind-v4.css、components→components.html，usage指向USAGE.md，preview指向三个预览页，sourceFiles指向溯源证据三件套。包内所有「派生产物」都以 tokens.css 为唯一事实源——这一点在source/evidence.md中写得很明确：design-tokens.json与tailwind-v4.css是派生输出，应基于契约报告与令牌样式表重新生成，而非手工编辑。

3. 推荐阅读顺序：五步消费流程

USAGE.md 给出了明确的五步阅读顺序，这是消费该包的标准路径：

先读 USAGE.md，理解包级契约（即本文所依据的文档）；
再读 DESIGN.md，掌握视觉意图、约束与反模式——这是"为什么"层面的内容；
将 tokens.css 粘贴进首个 artifact 的<style>块（在编写任何组件 CSS 之前）；
用 components.manifest.json 做紧凑的组件清单检索；当精确选择器或状态（hover、focus-visible 等）重要时，打开 components.html 查看参考实现；
需要视觉 sanity check 时，在浏览器中检查preview/页面。

这套顺序的背后逻辑是分层递进：契约 → 意图 → 令牌 → 组件 → 视觉验证。其中第三步是硬性要求——令牌必须先行注入，任何组件 CSS 都建立在令牌之上，而不是在<style>里新造一套变量或裸色值。

3.1 预览页：零成本视觉核验

preview/目录下有三个自包含的 HTML 预览页，均通过../tokens.css引用令牌：

preview/colors.html：以色卡网格展示--bg、--surface、--fg、--muted、--border、--accent、--success、--warn、--danger等颜色角色的实际渲染效果；
preview/typography.html：展示字体族与字号阶梯的实际排版效果；
preview/spacing.html：展示间距令牌的实际空间关系。

这些页面无需任何构建步骤，直接打开即可核对"令牌在真实浏览器中的样子"，适合在提交 artifact 前做快速视觉验收。

4. 设计亮点：碳黑画布上的单一电光绿

USAGE.md 提炼了 VoltAgent 的四个核心设计特征，这些特征在 DESIGN.md 中有更完整的展开：

碳黑画布（#050507）+ 暖灰边框（#3d3a39）：DESIGN.md 将其称为 "Abyss Black" 与 "Warm Charcoal"，强调这种暖调灰让深色界面"不冰冷、不无菌"，形成一种驾驶舱式的暖意，这是纯蓝灰做不到的；
单一强调色：Emerald Signal Green（#00d992）：它是整个界面唯一的彩色能量源，被形容为"power-on"信号——电路板上的电流隐喻。注意 DESIGN.md 明确禁止把它用作大面积背景填充，它是强调色而非表面色；
双字体系统：system-ui 承担标题（原生权威感、零 FOIT/FOUT），Inter 承担正文与 UI（几何精确），SFMono 承担代码（开发者终端可信度）；
超紧标题行高（1.0–1.11）：制造"密集压缩的力量块"，让标题读起来像技术规格书而非营销文案。

值得留意的是：DESIGN.md 描述的是上游 VoltAgent 品牌的视觉语言，而包内实际落地的令牌值以 tokens.css 为准。例如 DESIGN.md 中的强调色是#00d992，而 tokens.css 中--accent: #7cff6b、--bg: #07110c——这是"定制打包 fixture"与"上游原始页面"之间的正常差异。source/evidence.md明确声明本包基于 OpenDesign 策展的打包 fixture，并不声称对上游品牌仓库做过新鲜抓取。因此，落地实现时永远以 tokens.css 为准，这正是 USAGE.md 在 Avoid 一节中强调"不得声称拥有上游原始源码证据"的原因。

5. 令牌系统：56 个令牌的语义与使用规则

5.1 令牌事实源：tokens.css

tokens.css 是包内唯一的令牌事实源。文件开头的注释直接点明了设计语义：

/* design-systems/voltagent/tokens.css * Structured token bindings for VoltAgent. * dark agent runtime surfaces, neon green command signals, and technical orchestration cards. */

整个令牌集定义在单个:root块中，共 56 个变量，可按用途分为几组：

色彩令牌（含语义）

令牌	值	语义角色
`--bg`	`#07110c`	页面底色（深墨绿黑）
`--surface`	`#101c16`	卡片/按钮表面
`--surface-warm`	`#14281e`	暖调面板表面
`--fg`	`#f4fff8`	主前景文本
`--fg-2`	`#c8dfd0`	次级文本
`--muted`	`#8ba493`	弱化文本/元数据
`--meta`	`#7cff6b`	眉题/状态色（电光绿）
`--border`	`#254132`	标准边框
`--border-soft`	`#1a3024`	细分隔线
`--accent`	`#7cff6b`	强调色（主行动、链接、焦点）
`--accent-on`	`#07110c`	强调色之上的文本色
`--accent-hover`	`color-mix(in oklab, var(--accent), black 8%)`	强调色悬停态
`--accent-active`	`color-mix(in oklab, var(--accent), black 14%)`	强调色按压态
`--success`	`#52e875`	成功态
`--warn`	`#facc15`	警告态
`--danger`	`#fb7185`	危险态

值得注意的实现细节：--accent-hover与--accent-active使用了color-mix(in oklab, ...)这一现代 CSS 颜色函数，从基准强调色向黑色混入 8%/14%，而不是写死两个近似色值——这让强调色的明暗变体在色相上保持完全一致。

字体令牌

令牌	值
`--font-display`	`Inter, system-ui, sans-serif`
`--font-body`	`Inter, system-ui, sans-serif`
`--font-mono`	`"JetBrains Mono", ui-monospace, Menlo, monospace`

字号阶梯（12px → 64px）：--text-xs: 12px、--text-sm: 13px、--text-base: 15px、--text-lg: 17px、--text-xl: 22px、--text-2xl: 32px、--text-3xl: 46px、--text-4xl: 64px，配合--leading-body: 1.56（正文行高）、--leading-tight: 1.07（标题行高）、--tracking-display: -0.02em（标题字距）。

间距与圆角：间距基于 4px 基元（--space-1: 4px至--space-12: 48px）；圆角分四级——--radius-sm: 8px、--radius-md: 12px、--radius-lg: 18px、--radius-pill: 9999px（胶囊）。

层级、动效与容器：--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised: 0 24px 70px rgba(0, 0, 0, 0.42)、--focus-ring: 0 0 0 4px rgba(124, 255, 107, 0.30)；动效时长--motion-fast: 120ms/--motion-base: 210ms，缓动--ease-standard: cubic-bezier(0.2, 0, 0, 1)；容器--container-max: 1180px，三档栅距（桌面 36px / 平板 24px / 手机 16px）。

5.2 机器可读的令牌契约：design-tokens.json

design-tokens.json 将上述令牌导出为结构化 JSON（format: "od-design-tokens/v1"，contract: "TOKEN_SCHEMA"）。摘要数据印证了包的健康度：

totalTokens: 56，declaredTokens: 56，sourceBackedTokens: 56—— 全部令牌都有 tokens.css 源码背书；
分层统计：A1-identity: 8、A1-structure: 18、A2: 26、B-slot: 4；
score: 100、grade: "excellent"、recommendRebuild: false。

每个令牌条目都带type（color / fontFamily / dimension / number / shadow / duration / cubicBezier）、layer、confidence与sources（精确到tokens.css行号），例如--bg的sources: ["tokens.css:7"]。这套元数据让 Agent 可以程序化校验"我引用的令牌是否真实存在、来源是否可追溯"。而 source/token-contract.report.json 则把每一个 TOKEN_SCHEMA 绑定映射回 tokens.css 的声明行，作为回填审计证据。

5.3 Tailwind v4 桥接：tailwind-v4.css

如果构建环境使用 Tailwind v4，可导入 tailwind-v4.css 将令牌桥接进@theme：

@import "tailwindcss"; @import "./tokens.css"; @theme { --color-bg: var(--bg); --color-surface: var(--surface); --color-accent: var(--accent); --font-display: var(--font-display); --font-body: var(--font-body); --text-2xl: var(--text-2xl); --spacing-4: var(--space-4); --radius-md: var(--radius-md); --shadow-raised: var(--elev-raised); /* ... 完整映射见文件本体 */ }

注意该文件首行注释的硬约束："Derived from tokens.css. Keep tokens.css as the source of truth."（派生自 tokens.css，保持 tokens.css 为事实源）。桥接层只是把令牌重命名为 Tailwind 约定命名空间（--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*），值全部引用原始变量，不复制值、不重新定义。

6. 组件清单：复用优先，自造次之

components.manifest.json（schemaVersion: 1）提供了紧凑的组件清单，其 fixture 摘要显示参考实现包含 1 个样式块、48 个选择器、26 个类、19 个元素。清单将组件归入 9 个组：

组 id	标签	关键选择器/类
`buttons`	Buttons and calls to action	`.btn`、`.btn-primary`、`.btn-secondary`（含`:hover`、`:focus-visible`）
`inputs`	Form fields and controls	`.field`、`input`、`input:focus`、`label`
`cards`	Cards and panels	`.card-row`、`.panel`、`.panel-head`、`.tile`
`badges`	Badges, chips, and status labels	`.status`
`links`	Links and inline actions	`a`
`typography`	Typography scale and text utilities	`.eyebrow`、`.lead`、`h1`–`h3`
`layout`	Layout primitives	`.container`、`.metric-grid`、`section`
`keyboard`	Keyboard hints	未出现（present: false）
`icons`	Icon slots	未出现（present: false）

每个组都带tokenReferences，直接列出该组件组消费的令牌——例如buttons组引用--accent、--accent-on、--border、--radius-md、--space-5、--motion-fast、--ease-standard等 12 个令牌；cards组引用--border、--elev-raised、--radius-lg、--surface。这形成了一条可审计的「组件 → 令牌」依赖链。

清单还统计了令牌使用情况：declared56 个、referenced43 个、unusedDeclared7 个（--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn），undeclaredReferenced: []——即没有任何被引用却未声明的令牌，印证了令牌体系的自洽性。

6.1 从参考实现中提取精确选择器

当需要精确选择器或状态细节时，打开 components.html。其<style>块提供了完整可复制的组件 CSS，例如：

.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), border-color var(--motion-fast) var(--ease-standard), color var(--motion-fast) var(--ease-standard), transform var(--motion-fast) var(--ease-standard), box-shadow 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); } .btn-secondary:hover { border-color: var(--accent); color: var(--accent); }

这段代码演示了本包的全部交互哲学：主按钮是"通电"状态（绿色底--accent+ 深色字--accent-on），悬停用--accent-hover轻微压暗并上浮 1px；次按钮用--elev-ring环状描边制造"内嵌"感，悬停时边框与文字转为强调色；键盘焦点统一走--focus-ring（4px 半透明绿环），符合可达性基线。

其他关键参考片段还包括：

面板与指标：.panel使用color-mix(in oklab, var(--surface), transparent 4%)半透明表面 +--elev-raised重阴影 +--radius-lg；.status::before用 8px 圆形--success色点模拟"在线"状态灯；
表单输入：input采用--surface背景 +--border边框 +--radius-sm，input:focus触发--focus-ring且边框转--accent；
响应式：@media (max-width: 860px)下.hero、.lower、.metric-grid、.card-row全部坍缩为单列。

7. Do 与 Avoid：可执行的设计约束

USAGE.md 的 Do / Avoid 两节构成了消费该包时的行为准则，原文内容如下（逐条继承，并附实现层面的解释）：

应当（Do）

精确保留 schema 令牌名，以保证跨品牌切换的可靠性——令牌名就是契约本身，改名等于破坏契约；这与 tokens.schema.ts 定义的 TOKEN_SCHEMA 约束相呼应；
--accent用于主行动、链接、焦点态，以及一个清晰的焦点元素——强调色是"唯一能量源"，不可滥用（一次只服务一个焦点）；
优先复用 components.manifest.json 中的组件组，再考虑发明新控件；
把source/文件当作打包 fixture 回填的审计证据——即source/evidence.md、source/token-contract.report.json、source/tokens.source.json用于核验令牌与组件的来源合法性。

避免（Avoid）

避免在复制的:root令牌块之外使用裸十六进制色值——颜色必须经由令牌引用，这一条同时是 craft/color.md 与 craft/accessibility-baseline.md（manifest 的craft.suggested列表）所倡导的实践；
避免脱离 tokens.css 独立重定义 Tailwind 或设计令牌值——tokens.css 是唯一事实源，任何派生层（tailwind-v4.css、design-tokens.json）都必须引用它而不是复制它；
避免声称拥有上游原始源码证据——本包基于 OpenDesign 策展的打包 fixture（见 source/evidence.md），不得虚构抓取来源；
避免添加 components.html 或 DESIGN.md 中未呈现的新组件配方——组件清单之外的自造组件会破坏可审计性。

8. 从 DESIGN.md 理解"为什么"：视觉意图与反模式速览

虽然落地实现以 tokens.css 为准，但 DESIGN.md 提供了理解品牌意图的完整背景，尤其是它的 Don't 清单——这些反模式同样值得在评审时逐条对照：

不要用明亮/浅色背景做主表面——整个身份建立在近黑背景上；
不要引入暖色（橙、红、黄）作为装饰强调色——暖色只留给语义状态（警告、错误）；
不要把 Emerald Signal Green 用在大面积表面或背景填充上——它是强调色，不是表面色；
不要把标题行高提高到 1.33 以上——压缩密度是工程平台身份的核心；
不要滥用重阴影——层级靠边框权重（1px→2px→3px）与颜色迁移表达，阴影只留给 Level 4–5；
不要用纯白#ffffff作为默认正文色——Snow White#f2f2f2才是标准；
不要混入衬线或装饰字体——整套系统是几何无衬线 + 等宽；
不要给内容卡用超过 8px 的圆角——9999px 胶囊只留给小标签与徽章；
不要跳过暖灰边框系统——没有#3d3a39边框的卡片会在深色画布上"失重"；
不要做激进动画——动画缓慢而克制（跑马灯 25–100s、光晕轻微脉冲），快速动效与"工程精密"氛围相悖。

此外，DESIGN.md 还给出了可直接投喂给 Agent 的组件提示词模板与迭代指南（例如："use Warm Parchment (#b8b3b0) not 'make it lighter'"、用边框权重而非阴影表达层级、"Always specify which font"），这些内容与 USAGE.md 的 Do/Avoid 一脉相承，是编写/评审 artifact 时的速查字典。

9. 实操路线：把 VoltAgent 包用于你的下一个 artifact

综合以上全部信息，在 OpenDesign 中使用 VoltAgent 包的标准工作流可以收敛为六步：

读契约：打开 USAGE.md，确认包级规则；
看意图：通读 DESIGN.md 的 Key Characteristics 与 Don't 清单，建立视觉心智模型；
注入令牌：将 tokens.css 的完整:root块原样粘贴进 artifact 首个<style>块——这是所有后续 CSS 的地基；
查清单复用组件：对照 components.manifest.json 的九个组件组，优先复用.btn、.panel、.field、.status等既有配方；需要精确选择器时参考 components.html；
（可选）接入 Tailwind：若使用 Tailwind v4，导入 tailwind-v4.css 完成令牌桥接，切勿自行重定义值；
视觉验收与审计：打开preview/三个页面核对令牌渲染，必要时用source/token-contract.report.json与 design-tokens.json 验证令牌来源；对照 USAGE.md 的 Do/Avoid 清单做最终自检。

需要再次强调的边界：本包是 OpenDesign 的只读资产，使用时是"查看、复制、引用"而非修改包内文件；令牌的唯一事实源是 tokens.css，一切派生产物都以它为基准重建。遵循这套流程，无论是人类评审还是编码 Agent，都能在同一份契约下稳定地产出符合 VoltAgent 品牌意图——碳黑画布、单一电光绿、密集排版、工程终端气质——的高质量界面。