Voltagent

---
version: alpha
name: "Voltagent"
description: "Voltagent 的 DESIGN.md 中文参考模板，保留原始 design token 与专业术语，覆盖 color system、typography、layout、components、motion 与 interaction states。"
language: zh-CN
sourceLanguage: en
---

## 概览
Voltagent 是面向开发者构建的 AI agent engineering platform，品牌也坦然展示这一受众定位：near-black `{colors.canvas}` (`#101010`) page background edge-to-edge 铺开，没有 light-mode counterpart；单一 electric-green accent（`{colors.primary}` `#00d992`）只保留给 CTA、status pill 和品牌 lightning glyph；typography system 则把 sentence-case Inter 与用于 inline code / command snippet 的 SF Mono 配对。整个页面读起来像一份打磨精细、同时也承担销售任务的文档。

装饰系统非常克制。没有 gradient mesh，没有 atmospheric backdrop，也没有 illustration suite。品牌改用小型 typography moment 来标记身份：绿色 code chip（`npx voltagent...`）、置于同一 near-black canvas 上的 3-px outlined feature card、section band 之间的 green hairline divider。结果是一个极具工程感的页面：每张 card 都有 hairline border，每个 snippet 都有 copy-to-clipboard button，每个 metric 都以 numeric monospace 渲染。

Type 保持冷静。Hero display 是 60 px regular weight，并带 `-0.65 px` tracking；它不是 billboard headline，更像 documentation H1。Section heading 以相近字重降到 36 px / 24 px。Body copy 是 16 px Inter，line-height 1.65，符合长文档开发者预期的可读性。Uppercase eyebrow 很常见，也就是 section headline 上方 `EVERYTHING YOU NEED` 风格的 mono-cap label；它们使用 Inter weight 600，并带宽松 positive tracking（14 px 时 `2.52 px`）。

**Key Characteristics:**
- 单一 electric-green accent `{colors.primary}` (`#00d992`) 承载所有 CTA、所有 status pill 和品牌 lightning logo。没有第二个 accent。
- Dark canvas（`{colors.canvas}` `#101010`）是唯一 page surface；没有 light-mode rhythm，整个站点读起来是一块连续 dark surface，只被 feature-card boundary 打断。
- Hairline-bordered feature card（`{colors.hairline}` `#3d3a39`，1 px solid）是品牌 primary chrome；没有 shadow，没有 fill，只有精确的 hairline rectangle。
- 标志性的 dashed-border accent（`1px dashed rgba(79, 93, 117, 0.4)`）出现在 section 之间，作为安静的 rhythm cue；这是品牌唯一的 ornamental line。
- Inter + SF Mono 配对承载所有 typographic role。SF Mono 只保留给 code block、inline command snippet 和 metric counter。
- Button 是紧凑的 6 px rounded rectangle（不是 pill）；只有 inline status tag 使用 9999 px full pill。

## Colors

### Brand & Accent
- **Electric Green** (`{colors.primary}` — `#00d992`): 单一 brand accent。用于所有 primary CTA、所有 status pill、所有 "live" indicator，以及品牌 lightning glyph 本身。需克制使用。
- **Primary Soft** (`{colors.primary-soft}` — `#2fd6a1`): 略 muted 的 green，用于 button-ghost variant 和 tooltip / focus indicator。
- **Primary Deep** (`{colors.primary-deep}` — `#10b981`): 更深的 green，用于 body copy 中的 inline link color。

### Surface
- **Canvas** (`{colors.canvas}` — `#101010`): 默认 near-black page background。品牌 marketing system 中唯一的 surface mode。
- **Canvas Soft** (`{colors.canvas-soft}` — `#1a1a1a`): 略亮的 dark fill，用于 code block 和 form input 内部，让它们相对 canvas 具备视觉区分。
- **Hairline** (`{colors.hairline}` — `#3d3a39`): 1 px solid border；用于 feature card、button、row divider。品牌通用的 "edge" color。
- **Hairline Soft** (`{colors.hairline-soft}` — `#b8b3b0`): 更浅的 divider tint，用于少见的 on-light secondary context。

### Text
- **Ink** (`{colors.ink}` — `#f2f2f2`): Dark canvas 上的默认文本色；略 off-white，以降低对比疲劳。
- **Ink Strong** (`{colors.ink-strong}` — `#ffffff`): Pure-white text，用于 hero headline 和 high-emphasis copy。
- **Body** (`{colors.body}` — `#bdbdbd`): Secondary text；用于 supporting copy 和长文 section 中的 body paragraph。
- **Mute** (`{colors.mute}` — `#8b949e`): 优先级最低的 on-dark text；用于 caption、fine print、footer secondary line。
- **Canvas Text Soft** (`{colors.canvas-text-soft}` — `#f5f6f7`): 用于 code mockup 内部，让 code color 比周围 body text 略冷。

### Semantic Colors
品牌在公开 marketing page 中不暴露独立 error / warning palette；底层 Docusaurus default semantic palette 存在于 design system 中，但保留给 in-product / docs context。Marketing surface 上的 validation cue 使用 primary green 表示 success，用 muted body grey 表示 missing state。

## Typography

### Font Family
系统由两套字体承担：
1. **Inter** 用于所有 display、body、button 和 link role。工作字重是 400 / 500 / 600 / 700。页面全局启用 OpenType features `"calt"` 和 `"rlig"`，让 Inter 的 geometric ligature 和 contextual alternate 正确渲染。
2. **SF Mono**（`SFMono-Regular`，带 Menlo / Monaco / Consolas / Liberation Mono fallback）用于 inline code、command snippet、terminal mockup 和品牌 numeric counter。存在 400 / 549 / 550 / 700 字重；不寻常的 549 / 550 sub-bold weight 让 mono 在强调时呈现“比 regular 略重”的声音。

### Hierarchy

| Token | Size | Weight | Line Height | Letter Spacing | 用途 |
|---|---|---|---|---|---|
| `{typography.display-xl}` | 60px | 400 | 60px | -0.65px | Hero headline（"AI Agent Engineering Platform"）。 |
| `{typography.display-lg}` | 36px | 400 | 40px | -0.9px | Section headline。 |
| `{typography.display-md}` | 24px | 700 | 32px | -0.6px | Sub-section / card-title display。 |
| `{typography.display-sm}` | 20px | 600 | 28px | 0 | Dense grid 中的 card title。 |
| `{typography.eyebrow-mono}` | 14px | 600 | 20px | 2.52px | UPPERCASE eyebrow tag（"EVERYTHING YOU NEED"）。 |
| `{typography.eyebrow-uppercase}` | 18px | 600 | 28px | 0.45px | Hero subsection 上方更大的 uppercase eyebrow。 |
| `{typography.body-lg}` | 18px | 400 | 28px | 0 | Lead paragraph。 |
| `{typography.body-md}` | 16px | 400 | 26px | 0 | Default body paragraph。 |
| `{typography.body-md-strong}` | 16px | 600 | 24px | 0 | Bolded inline body。 |
| `{typography.body-sm}` | 14px | 400 | 20px | 0 | Secondary body。 |
| `{typography.body-sm-strong}` | 14px | 600 | 23px | 0 | Bold caption / pill-tag label。 |
| `{typography.caption}` | 12px | 400 | 16px | 0 | Fine print。 |
| `{typography.caption-strong}` | 12px | 500 | 16px | 0 | Bold caption。 |
| `{typography.code}` | 13px | 400 | 18px | 0 | Code block、inline command snippet。 |
| `{typography.code-strong}` | 13px | 550 | 16px | 0 | Emphasised inline code（SF Mono 的 "almost-bold" weight）。 |
| `{typography.button-md}` | 16px | 600 | 24px | 0 | Button label。 |

### Principles
- **60 px display 使用 Inter regular**，这是品牌对 AI marketing 常见高喊风格的冷静反制。轻 tracking 和克制 weight 读起来像文档。
- **双字体对比承载技术声音。** Inter 用于叙述；SF Mono 用于任何可能在 terminal 中输入的内容。
- **带 tracking 的 uppercase eyebrow 是品牌 signature label style。** 14 px 时 `2.52 px` 是记录值。

### Font Substitutes
- **Sans** — *Inter* 就是品牌实际字体；self-hosting 不可用时替代仍是它本身。
- **Mono** — *SF Mono* 是 Apple-system；*JetBrains Mono* 或 *Geist Mono* 是最佳免费替代。

## Layout

### Spacing System
- **Base unit**: 4 px；5 / 6.4 px 这类小值出现在 code-mockup line-height compensation 中。
- **Tokens**: `{spacing.xxs}` 2 px · `{spacing.xs}` 4 px · `{spacing.sm}` 8 px · `{spacing.md}` 12 px · `{spacing.lg}` 16 px · `{spacing.xl}` 20 px · `{spacing.2xl}` 24 px · `{spacing.3xl}` 32 px · `{spacing.4xl}` 40 px · `{spacing.5xl}` 48 px · `{spacing.6xl}` 64 px。
- **Section padding**: hero + content band 使用 `{spacing.5xl}` 48 px top/bottom。
- **Card interior padding**: feature card 使用 `{spacing.2xl}` 24 px。

### Grid & Container
- Marketing container 居中在约 1200 – 1400 px；content 在颜色上保持 edge-to-edge，desktop 上有 `{spacing.3xl}` horizontal gutter。
- Feature-card grid：desktop 为 2-up 到 3-up，mobile 为 1-up。

### Responsive Strategy

#### Breakpoints

| Name | Width | 关键变化 |
|---|---|---|
| Mobile | < 768px | Hero 60→32 px；card 1-up；nav hamburger。 |
| Tablet | 768–1023px | Card 2-up；nav 保持 horizontal。 |
| Desktop | ≥ 1024px | 完整 3-up card grid。 |

#### Touch Targets
Button 渲染高度约 44 px（12 px vertical padding + 24 px line-height）。所有 breakpoint 均满足 WCAG AAA。

#### Collapsing Strategy
Nav 在 mobile 折叠为 hamburger；menu overlay 保持同一个 green CTA 固定在底部。Feature-card grid 降为 1-up；hero typography 流式缩放。

#### Image Behavior
Code-editor mockup 渲染为 image-like card，并带 copy-to-clipboard affordance。品牌 marketing surface 中没有 photography。

## Elevation & Depth

| Level | Treatment | 用途 |
|---|---|---|
| Level 0 — Flat | 无 shadow、无 border。 | Full-bleed band。 |
| Level 1 — Hairline | `{colors.canvas}` 上的 1 px solid `{colors.hairline}` border。 | 每个 feature card 和 button 的默认处理。 |
| Level 2 — Inset Glow | `0 0 15px rgba(92, 88, 85, 0.2)` subtle outer glow。 | Hovering / featured card。 |
| Level 3 — Modal Stack | `0 20px 60px rgba(0,0,0,0.7), 0 0 0 1px rgba(148,163,184,0.1) inset` heavy drop + inset ring。 | In-product modal / dialog surface。 |

### Decorative Depth
- Dark canvas 上的 hairline card 是品牌唯一真正的 elevation mode。
- 2 px solid `{colors.primary}` green border 偶尔用于标记 card 的 "featured" 或 "active" status。
- 1 px dashed `rgba(79, 93, 117, 0.4)` divider 位于 section band 之间，作为安静的 rhythm cue。

## Shapes

### Border Radius Scale

| Token | Value | 用途 |
|---|---|---|
| `{rounded.none}` | 0px | Full-bleed band。 |
| `{rounded.xs}` | 4px | 最小 inline pill、code inline chip。 |
| `{rounded.sm}` | 6px | 默认 button 和 input radius。 |
| `{rounded.md}` | 8px | Card chrome、code-block chrome。 |
| `{rounded.pill}` | 9999px | Inline status tag（"Live", "Beta"）。 |
| `{rounded.full}` | 9999px | Circular icon container。 |

## Components

### Buttons

**`button-primary`** — electric-green CTA。
- Background `{colors.primary}`、text `{colors.on-primary}`（near-black）、label `{typography.button-md}`、padding `{spacing.md} {spacing.lg}`、shape `{rounded.sm}` 6 px。

**`button-outline-on-dark`** — hairline-on-dark secondary button。
- Background `{colors.canvas}`、text `{colors.ink}`、1 px solid `{colors.hairline}` border，同样 typography / padding / shape。

**`button-ghost-green`** — 带 green label 的 text-only button，用于 tertiary action。
- Background `{colors.canvas}`、text `{colors.primary-soft}`、无 border。

**`button-pill-tag`** — 用于 category tag / status label 的 inline pill。
- Background `{colors.canvas}`、text `{colors.ink}`、hairline border，body 使用 `{typography.body-sm}`，padding `{spacing.xs} {spacing.md}`，shape `{rounded.pill}` 9999 px。

### Cards & Containers

**`card-feature`** — 默认 feature card。
- Background `{colors.canvas}`、text `{colors.ink}`、1 px solid `{colors.hairline}` border、padding `{spacing.2xl}`、shape `{rounded.md}` 8 px。品牌最常重复使用的 card chrome。

**`card-feature-emphasized`** — 同款 card，但使用 3 px hairline border 来强调。
- Chrome 与 `card-feature` 相同，但使用 3 px solid `{colors.hairline}`。

**`code-mockup`** — 带 copy-to-clipboard affordance 的 dark code-editor card。
- Background `{colors.canvas}`、text `{colors.ink}`、1 px solid `{colors.hairline}`，body 使用 `{typography.code}`（SF Mono 13 px），padding `{spacing.xl}`、shape `{rounded.md}`。

**`code-inline-chip`** — inline command snippet pill。
- Background `{colors.canvas-soft}`、text `{colors.canvas-text-soft}`、body 使用 `{typography.code}`、padding `{spacing.xxs} {spacing.sm}`、shape `{rounded.sm}`。

### Inputs & Forms

**`text-input`** — dark 上的标准 text input。
- Background `{colors.canvas-soft}`、text `{colors.ink}`、1 px solid `{colors.hairline}`、body 使用 `{typography.body-sm}`、padding `{spacing.md} {spacing.lg}`、shape `{rounded.sm}` 6 px。

### Navigation

**`nav-bar`** — dark 上的 sticky top nav。
- Background `{colors.canvas}`、text `{colors.ink}`、padding `{spacing.md} {spacing.3xl}`。

**`nav-link`** — nav 中的 link item。
- Text `{colors.body}`，使用 `{typography.body-sm}`。

**`footer`** — dark footer band。
- Background `{colors.canvas}`、text `{colors.body}`、padding `{spacing.4xl} {spacing.3xl}`。Body 使用 `{typography.body-sm}`。

### Signature Components

**`hero-band`** — 带 60-px Inter headline 的 dark hero band。
- Background `{colors.canvas}`、text `{colors.ink}`（headline 使用 `{colors.ink-strong}` white）、padding `{spacing.5xl} {spacing.3xl}`。Headline 使用 `{typography.display-xl}`（60 px / weight 400 / `-0.65 px` tracking）。Headline 上方 eyebrow 使用 `{typography.eyebrow-mono}`（uppercase、tracked）。

**`content-band`** — 承载 feature grid 的标准 content band。
- Background `{colors.canvas}`、text `{colors.ink}`、padding `{spacing.5xl} {spacing.3xl}`。Section headline 使用 `{typography.display-lg}`。

**`green-divider-band`** — 偶尔分隔主要 section 的细 green-glow band。
- Background `{colors.canvas}`、top/bottom border 为 2 px solid `{colors.primary}`。这是品牌唯一的 chromatic divider。

### Examples (illustrative)

> 自动派生的 kit-mirror demonstration surfaces（`scripts/derive-examples-block.mjs`）。每个 `ex-*` 条目都引用 brand-native primitive，让下游消费者（`/preview-design`、`/generate-kit`）可以一致地重新换肤同一组 10 个 surface。`TO_FILL` 标记表示缺失 primitive，需要在 LLM judgment pass 中解决。

**`ex-pricing-tier`** — 默认 Pricing tier card。复用 feature-card chrome，并使用品牌 canvas-soft surface。
- Properties: `backgroundColor`, `textColor`, `borderColor`, `rounded`, `padding`

**`ex-pricing-tier-featured`** — Featured/highlighted tier；polarity-flipped surface（light mode 中 dark fill + light text，dark mode 中 light fill + dark text）。
- Properties: `backgroundColor`, `textColor`, `rounded`, `padding`

**`ex-product-selector`** — What's Included summary card；为 SaaS / B2B vertical 重新设定用途（不是字面意义上的 product gallery）。
- Properties: `backgroundColor`, `rounded`, `padding`

**`ex-cart-drawer`** — Subscription summary；为 SaaS / B2B 重新设定用途（每个 add-on 一行，不是字面意义上的 cart）。
- Properties: `backgroundColor`, `rounded`, `padding`, `item-divider`

**`ex-app-shell-row`** — App Shell 示例中的 sidebar nav row。Active state 使用 brand primary 作为 indicator。
- Properties: `backgroundColor`, `activeIndicator`, `rounded`, `padding`

**`ex-data-table-cell`** — 默认 data-table th + td chrome。Header 使用 mono-caps eyebrow typography；body 使用 body-sm。
- Properties: `headerBackground`, `headerTypography`, `bodyTypography`, `cellPadding`, `rowBorder`

**`ex-auth-form-card`** — Sign-in / sign-up card。复用 feature-card chrome，内部使用 text-input primitive。
- Properties: `backgroundColor`, `rounded`, `padding`

**`ex-modal-card`** — Modal dialog surface；与 feature-card 使用相同 chrome，并带 elevated shadow。
- Properties: `backgroundColor`, `rounded`, `padding`

**`ex-empty-state-card`** — Empty-state illustration frame。
- Properties: `backgroundColor`, `rounded`, `padding`, `captionTypography`

**`ex-toast`** — Toast notification surface；feature-card shape + medium shadow。
- Properties: `backgroundColor`, `rounded`, `padding`, `typography`

## Do's and Don'ts

### Do
- 将 `{colors.primary}` (`#00d992`) 保留给每个 primary CTA、lightning logo glyph 和 live-status indicator。Green 是品牌重心。
- 使用 dark `{colors.canvas}` (`#101010`) 作为唯一 page surface。没有 light-mode rhythm。
- Card 使用 1 px `{colors.hairline}` border 构建，而不是 shadow。Dark 上的 hairline 就是品牌 elevation system。
- 将 Inter（sentence-case）与 SF Mono（inline code、command snippet）配对。每个 uppercase moment 都使用 Inter weight 600 和 `2.52 px` tracking，而不是单独的 mono。
- Button 使用 `{rounded.sm}` 6 px，card 使用 `{rounded.md}` 8 px，`{rounded.pill}` 9999 px 只用于 inline status tag。

### Don't
- 不要引入 light-mode counterpart。品牌只使用 dark-canvas。
- 不要把 primary green 用作 body-text fill。它只属于 CTA。
- 不要给 card 加 soft drop-shadow。品牌使用 hairline + 偶发 glow，从不使用 material shadow。
- 不要用 heavy weight（700+）渲染 hero headline。品牌 display 刻意保持 weight 400 的冷静。
- 不要用其它字体替代 Inter 或 SF Mono；这两套字体都是品牌 voice 和 pairing 的一部分。