source

---
name: VoltAgent
description:
  Deep-space command terminal for AI agents — near-pure-black canvas with
  emerald signal green accents, warm-gray borders, glow effects, code-as-hero.
originalFonts:
  primary: "system-ui"
  mono: "SFMono-Regular"
  fallbacks:
    - "-apple-system"
    - "Segoe UI"
    - "Roboto"
    - "Ubuntu"
    - "Cantarell"
    - "Noto Sans"
    - "Helvetica"
    - "Arial"
    - "Apple Color Emoji"
    - "Segoe UI Emoji"
    - "Segoe UI Symbol"
colors:
  background: "#050507"
  surface: "#101010"
  ink: "#F2F2F2"
  accent: "#00D992"
  emerald-signal-green: "#00D992"
  voltagent-mint: "#2FD6A1"
  tailwind-emerald: "#10B981"
  soft-purple: "#818CF8"
  cobalt-primary: "#306CCE"
  deep-cobalt: "#2554A0"
  ring-blue: "#3B82F6"
  abyss-black: "#050507"
  carbon-surface: "#101010"
  warm-charcoal-border: "#3D3A39"
  border: "#3D3A39"
  snow-white: "#F2F2F2"
  pure-white: "#FFFFFF"
  warm-parchment: "#B8B3B0"
  steel-slate: "#8B949E"
  fog-gray: "#BDBDBD"
  mist-gray: "#DCDCDC"
  near-white: "#EEEEEE"
  success-emerald: "#008B00"
  success-light: "#80D280"
  warning-amber: "#FFBA00"
  warning-pale: "#FFDD80"
  danger-coral: "#FB565B"
  danger-rose: "#FD9C9F"
  info-teal: "#4CB3D4"
typography:
  h1:
    family: "Inter"
    size: "3.75rem"
    weight: 400
    lineHeight: 1.0
  body:
    family: "Inter"
    size: "1rem"
    weight: 400
    lineHeight: 1.5
  code:
    family: "JetBrains Mono"
    size: "0.88rem"
    weight: 400
    lineHeight: 1.43
spacing:
  xs: "0.25rem"
  sm: "0.5rem"
  md: "1rem"
  lg: "1.5rem"
  xl: "3rem"
rounded:
  sm: "4px"
  md: "6px"
  lg: "8px"
  xl: "9999px"
shadows:
  sm: "rgba(92, 88, 85, 0.2) 0px 0px 15px"
  md: "rgba(0, 0, 0, 0.7) 0px 20px 60px"
  lg:
    "rgba(0, 0, 0, 0.7) 0px 20px 60px, rgba(148, 163, 184, 0.1) 0px 0px 0px 1px
    inset"
components:
  button-primary:
    background: "{colors.carbon-surface}"
    color: "{colors.voltagent-mint}"
    border: "1px solid {colors.voltagent-mint}"
    radius: "{rounded.md}"
    padding: "0.75rem 1rem"
  button-secondary:
    background: "transparent"
    color: "#FFFFFF"
    border: "1px solid {colors.warm-charcoal-border}"
    radius: "{rounded.md}"
    padding: "0.75rem 1rem"
  card:
    background: "{colors.carbon-surface}"
    border: "1px solid {colors.warm-charcoal-border}"
    radius: "{rounded.lg}"
    padding: "1.5rem"
  input:
    background: "{colors.carbon-surface}"
    color: "{colors.snow-white}"
    border: "1px solid {colors.warm-charcoal-border}"
    radius: "{rounded.md}"
    padding: "0.5rem 0.75rem"
---

<!-- source: VoltAgent/awesome-design-md @ 80bbbc2 (MIT) — see ATTRIBUTION.md -->

# Design System Inspiration of VoltAgent

## 1. Visual Theme & Atmosphere

VoltAgent's interface is a deep-space command terminal for the AI age — a
developer-facing darkness built on near-pure-black surfaces (`#050507`) where
the only interruption is the electric pulse of emerald green energy. The entire
experience evokes the feeling of staring into a high-powered IDE at 2am: dark,
focused, and alive with purpose. This is not a friendly SaaS landing page — it's
an engineering platform that announces itself through code snippets,
architectural diagrams, and raw technical confidence.

The green accent (`#00d992`) is used with surgical precision — it glows from
headlines, borders, and interactive elements like a circuit board carrying a
signal. Against the carbon-black canvas, this green reads as "power on" — a
deliberate visual metaphor for an AI agent engineering platform. The supporting
palette is built entirely from warm-neutral grays (`#3d3a39`, `#8b949e`,
`#b8b3b0`) that soften the darkness without introducing color noise, creating a
cockpit-like warmth that pure blue-grays would lack.

Typography leans on the system font stack for headings — achieving maximum
rendering speed and native-feeling authority — while Inter carries the body and
UI text with geometric precision. Code blocks use SFMono-Regular, the same font
developers see in their terminals, reinforcing the tool's credibility at every
scroll.

**Key Characteristics:**

- Carbon-black canvas (`#050507`) with warm-gray border containment (`#3d3a39`)
  — not cold or sterile
- Single-accent identity: Emerald Signal Green (`#00d992`) as the sole chromatic
  energy source
- Dual-typography system: system-ui for authoritative headings, Inter for
  precise UI/body text, SFMono for code credibility
- Ultra-tight heading line-heights (1.0–1.11) creating dense, compressed power
  blocks
- Warm neutral palette (`#3d3a39`, `#8b949e`, `#b8b3b0`) that prevents the dark
  theme from feeling clinical
- Developer-terminal aesthetic where code snippets ARE the hero content
- Green glow effects (`drop-shadow`, border accents) that make UI elements feel
  electrically alive

## 2. Color Palette & Roles

### Primary

- **Emerald Signal Green** (`#00d992`): The core brand energy — used for accent
  borders, glow effects, and the highest-signal interactive moments. This is the
  "power-on" indicator of the entire interface.
- **VoltAgent Mint** (`#2fd6a1`): The button-text variant of the brand green —
  slightly warmer and more readable than pure Signal Green, used specifically
  for CTA text on dark surfaces.
- **Tailwind Emerald** (`#10b981`): The ecosystem-standard green used at low
  opacity (30%) for subtle background tints and link defaults. Bridges
  VoltAgent's custom palette with Tailwind's utility classes.

### Secondary & Accent

- **Soft Purple** (`#818cf8`): A cool indigo-violet used sparingly for secondary
  categorization, code syntax highlights, and visual variety without competing
  with green.
- **Cobalt Primary** (`#306cce`): Docusaurus primary dark — used in
  documentation contexts for links and interactive focus states.
- **Deep Cobalt** (`#2554a0`): The darkest primary shade, reserved for
  pressed/active states in documentation UI.
- **Ring Blue** (`#3b82f6`): Tailwind's ring color at 50% opacity — visible only
  during keyboard focus for accessibility compliance.

### Surface & Background

- **Abyss Black** (`#050507`): The landing page canvas — a near-pure black with
  the faintest warm undertone, darker than most "dark themes" for maximum
  contrast with green accents.
- **Carbon Surface** (`#101010`): The primary card and button background — one
  shade lighter than Abyss, creating a barely perceptible elevation layer. Used
  across all contained surfaces.
- **Warm Charcoal Border** (`#3d3a39`): The signature containment color — not a
  cold gray but a warm, almost brownish dark tone that prevents borders from
  feeling harsh against the black canvas.

### Neutrals & Text

- **Snow White** (`#f2f2f2`): The primary text color on dark surfaces — not pure
  white (`#ffffff`) but a softened, eye-friendly off-white. The most-used color
  on the site (1008 instances).
- **Pure White** (`#ffffff`): Reserved for the highest-emphasis moments — ghost
  button text and maximum-contrast headings. Used at low opacity (5%) for subtle
  overlay effects.
- **Warm Parchment** (`#b8b3b0`): Secondary body text — a warm light gray with a
  slight pinkish undertone that reads as "paper" against the dark canvas.
- **Steel Slate** (`#8b949e`): Tertiary text, metadata, timestamps, and
  de-emphasized content. A cool blue-gray that provides clear hierarchy below
  Warm Parchment.
- **Fog Gray** (`#bdbdbd`): Footer links and supporting navigation text —
  brightens on hover to Pure White.
- **Mist Gray** (`#dcdcdc`): Slightly brighter than Fog, used for secondary link
  text that transitions to bright green on hover.
- **Near White** (`#eeeeee`): Highest-contrast secondary text, one step below
  Snow White.

### Semantic & Accent

- **Success Emerald** (`#008b00`): Deep green for success states and positive
  confirmations in documentation contexts.
- **Success Light** (`#80d280`): Soft pastel green for success backgrounds and
  subtle positive indicators.
- **Warning Amber** (`#ffba00`): Bright amber for warning alerts and caution
  states.
- **Warning Pale** (`#ffdd80`): Softened amber for warning background fills.
- **Danger Coral** (`#fb565b`): Vivid red for error states and destructive
  action warnings.
- **Danger Rose** (`#fd9c9f`): Softened coral-pink for error backgrounds.
- **Info Teal** (`#4cb3d4`): Cool teal-blue for informational callouts and tip
  admonitions.
- **Dashed Border Slate** (`#4f5d75` at 40%): A muted blue-gray used exclusively
  for decorative dashed borders in workflow diagrams.

### Gradient System

- **Green Signal Glow**: `drop-shadow(0 0 2px #00d992)` animating to
  `drop-shadow(0 0 8px #00d992)` — creates a pulsing "electric charge" effect on
  the VoltAgent bolt logo and interactive elements. The glow expands and
  contracts like a heartbeat.
- **Warm Ambient Haze**: `rgba(92, 88, 85, 0.2) 0px 0px 15px` — a warm-toned
  diffused shadow that creates a soft atmospheric glow around elevated cards,
  visible at the edges without sharp boundaries.
- **Deep Dramatic Elevation**: `rgba(0, 0, 0, 0.7) 0px 20px 60px` with
  `rgba(148, 163, 184, 0.1) 0px 0px 0px 1px inset` — a heavy, dramatic downward
  shadow paired with a faint inset slate ring for the most prominent floating
  elements.

## 3. Typography Rules

### Font Family

- **Primary (Headings)**: `system-ui`, with fallbacks:
  `-apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica, Arial, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol`
- **Secondary (Body/UI)**: `Inter`, with fallbacks inheriting from system-ui
  stack. OpenType features: `"calt", "rlig"` (contextual alternates and required
  ligatures)
- **Monospace (Code)**: `SFMono-Regular`, with fallbacks:
  `Menlo, Monaco, Consolas, Liberation Mono, Courier New, monospace`

### Hierarchy

| Role                | Font              | Size              | Weight  | Line Height  | Letter Spacing | Notes                                                    |
| ------------------- | ----------------- | ----------------- | ------- | ------------ | -------------- | -------------------------------------------------------- |
| Display / Hero      | system-ui         | 60px (3.75rem)    | 400     | 1.00 (tight) | -0.65px        | Maximum impact, compressed blocks                        |
| Section Heading     | system-ui         | 36px (2.25rem)    | 400     | 1.11 (tight) | -0.9px         | Tightest letter-spacing in the system                    |
| Sub-heading         | system-ui         | 24px (1.50rem)    | 700     | 1.33         | -0.6px         | Bold weight for emphasis at this size                    |
| Sub-heading Light   | system-ui / Inter | 24px (1.50rem)    | 300–400 | 1.33         | -0.6px         | Light weight variant for softer hierarchy                |
| Overline            | system-ui         | 20px (1.25rem)    | 600     | 1.40         | 0.5px          | Uppercase transform, positive letter-spacing             |
| Feature Title       | Inter             | 20px (1.25rem)    | 500–600 | 1.40         | normal         | Card headings, feature names                             |
| Overline Small      | Inter             | 18px (1.13rem)    | 600     | 1.56         | 0.45px         | Uppercase section labels                                 |
| Body / Button       | Inter             | 16px (1.00rem)    | 400–600 | 1.50–1.65    | normal         | Standard text, nav links, buttons                        |
| Nav Link            | Inter             | 14.45px (0.90rem) | 500     | 1.65         | normal         | Navigation-specific sizing                               |
| Caption / Label     | Inter             | 14px (0.88rem)    | 400–600 | 1.43–1.65    | normal         | Descriptions, metadata, badge text                       |
| Tag / Overline Tiny | system-ui         | 14px (0.88rem)    | 600     | 1.43         | 2.52px         | Widest letter-spacing — reserved for uppercase tags      |
| Micro               | Inter             | 12px (0.75rem)    | 400–500 | 1.33         | normal         | Smallest sans-serif text                                 |
| Code Body           | SFMono-Regular    | 13–14px           | 400–686 | 1.23–1.43    | normal         | Inline code, terminal output, variable weight for syntax |
| Code Small          | SFMono-Regular    | 11–12px           | 400     | 1.33–1.45    | normal         | Tiny code references, line numbers                       |
| Code Button         | monospace         | 13px (0.81rem)    | 700     | 1.65         | normal         | Copy-to-clipboard button labels                          |

### Principles

- **System-native authority**: Display headings use system-ui rather than a
  custom web font — this means the largest text renders instantly (no FOIT/FOUT)
  and inherits the operating system's native personality. On macOS it's SF Pro,
  on Windows it's Segoe UI. The design accepts this variability as a feature,
  not a bug.
- **Tight compression creates density**: Hero line-heights are extremely
  compressed (1.0) with negative letter-spacing (-0.65px to -0.9px), creating
  text blocks that feel like dense technical specifications rather than airy
  marketing copy.
- **Weight gradient, not weight contrast**: The system uses a gentle
  300→400→500→600→700 weight progression. Bold (700) is reserved for
  sub-headings and code-button emphasis. Most body text lives at 400–500,
  creating subtle rather than dramatic hierarchy.
- **Uppercase is earned and wide**: When uppercase appears, it's always paired
  with generous letter-spacing (0.45px–2.52px), transforming dense words into
  spaced-out overline labels. This treatment is never applied to headings.
- **OpenType by default**: Both system-ui and Inter enable `"calt"` and `"rlig"`
  features, ensuring contextual character adjustments and ligature rendering
  throughout.

## 4. Component Stylings

### Buttons

**Ghost / Outline (Standard)**

- Background: transparent
- Text: Pure White (`#ffffff`)
- Padding: comfortable (12px 16px)
- Border: thin solid Warm Charcoal (`1px solid #3d3a39`)
- Radius: comfortably rounded (6px)
- Hover: background darkens to `rgba(0, 0, 0, 0.2)`, opacity drops to 0.4
- Outline: subtle green tint (`rgba(33, 196, 93, 0.5)`)
- The default interactive element — unassuming but clearly clickable

**Primary Green CTA**

- Background: Carbon Surface (`#101010`)
- Text: VoltAgent Mint (`#2fd6a1`)
- Padding: comfortable (12px 16px)
- Border: none visible (outline-based focus indicator)
- Outline: VoltAgent Mint (`rgb(47, 214, 161)`)
- Hover: same darkening behavior as Ghost
- The "powered on" button — green text on dark surface reads as an active
  terminal command

**Tertiary / Emphasized Container Button**

- Background: Carbon Surface (`#101010`)
- Text: Snow White (`#f2f2f2`)
- Padding: generous (20px all sides)
- Border: thick solid Warm Charcoal (`3px solid #3d3a39`)
- Radius: comfortably rounded (8px)
- A card-like button treatment for larger interactive surfaces (code copy
  blocks, feature CTAs)

### Cards & Containers

- Background: Carbon Surface (`#101010`) — one shade lighter than the page
  canvas
- Border: `1px solid #3d3a39` (Warm Charcoal) for standard containment;
  `2px solid #00d992` for highlighted/active cards
- Radius: comfortably rounded (8px) for content cards; subtly rounded (4–6px)
  for smaller inline containers
- Shadow Level 1: Warm Ambient Haze (`rgba(92, 88, 85, 0.2) 0px 0px 15px`) for
  standard elevation
- Shadow Level 2: Deep Dramatic (`rgba(0, 0, 0, 0.7) 0px 20px 60px` +
  `rgba(148, 163, 184, 0.1) 0px 0px 0px 1px inset`) for hero/feature showcase
  cards
- Hover behavior: likely border color shift toward green accent or subtle
  opacity increase
- Dashed variant: `1px dashed rgba(79, 93, 117, 0.4)` for workflow/diagram
  containers — visually distinct from solid-border content cards

### Inputs & Forms

- No explicit input token data extracted — the site is landing-page focused with
  minimal form UI
- The npm install command (`npm create voltagent-app@latest`) is presented as a
  code block rather than an input field
- Inferred style: Carbon Surface background, Warm Charcoal border, VoltAgent
  Mint focus ring, Snow White text

### Navigation

- Sticky top nav bar on Abyss Black canvas
- Logo: VoltAgent bolt icon with animated green glow (`drop-shadow` cycling
  2px–8px)
- Nav structure: Logo → Product dropdown → Use Cases dropdown → Resources
  dropdown → GitHub stars badge → Docs CTA
- Link text: Snow White (`#f2f2f2`) at 14–16px Inter, weight 500
- Hover: links transition to green variants (`#00c182` or `#00ffaa`)
- GitHub badge: social proof element integrated directly into nav
- Mobile: collapses to hamburger menu, single-column vertical layout

### Image Treatment

- Dark-themed product screenshots and architectural diagrams dominate
- Code blocks are treated as primary visual content — syntax-highlighted with
  SFMono-Regular
- Agent workflow visualizations appear as interactive node graphs with green
  connection lines
- Decorative dot-pattern backgrounds appear behind hero sections
- Full-bleed within card containers, respecting 8px radius rounding

### Distinctive Components

**npm Install Command Block**

- A prominent code snippet (`npm create voltagent-app@latest`) styled as a
  copyable command
- SFMono-Regular on Carbon Surface with a copy-to-clipboard button
- Functions as the primary CTA — "install first, read later" developer
  psychology

**Company Logo Marquee**

- Horizontal scrolling strip of developer/company logos
- Infinite animation (`scrollLeft`/`scrollRight`, 25–80s durations)
- Pauses on hover and for users with reduced-motion preferences
- Demonstrates ecosystem adoption without cluttering the layout

**Feature Section Cards**

- Large cards combining code examples with descriptive text
- Left: code snippet with syntax highlighting; Right: feature description
- Green accent border (`2px solid #00d992`) on highlighted/active features
- Internal padding: generous (24–32px estimated)

**Agent Flow Diagrams**

- Interactive node-graph visualizations showing agent coordination
- Connection lines use VoltAgent green variants
- Nodes styled as mini-cards within the Warm Charcoal border system

**Community / GitHub Section**

- Large GitHub icon as the visual anchor
- Star count and contributor metrics prominently displayed
- Warm social proof: Discord, X, Reddit, LinkedIn, YouTube links in footer

## 5. Layout Principles

### Spacing System

- Base unit: 8px
- Scale: 2px, 4px, 5px, 6px, 6.4px, 8px, 12px, 16px, 20px, 24px, 28px, 32px,
  40px, 48px, 64px
- Button padding: 12px 16px (standard), 20px (container-button)
- Card internal padding: approximately 24–32px
- Section vertical spacing: generous (estimated 64–96px between major sections)
- Component gap: 16–24px between sibling cards/elements

### Grid & Container

- Max container width: approximately 1280–1440px, centered
- Hero: centered single-column with maximum breathing room
- Feature sections: alternating asymmetric layouts (code left / text right, then
  reversed)
- Logo marquee: full-width horizontal scroll, breaking the container constraint
- Card grids: 2–3 column for feature showcases
- Integration grid: responsive multi-column for partner/integration icons

### Whitespace Philosophy

- **Cinematic breathing room between sections**: Massive vertical gaps create a
  "scroll-through-chapters" experience — each section feels like a new scene.
- **Dense within components**: Cards and code blocks are internally compact,
  with tight line-heights and controlled padding. Information is concentrated,
  not spread thin.
- **Border-defined separation**: Rather than relying solely on whitespace,
  VoltAgent uses the Warm Charcoal border system (`#3d3a39`) to delineate
  content zones. The border IS the whitespace signal.
- **Hero-first hierarchy**: The top of the page commands the most space — the
  "AI Agent Engineering Platform" headline and npm command get maximum vertical
  runway before the first content section appears.

### Border Radius Scale

- Nearly squared (4px): Small inline elements, SVG containers, code spans — the
  sharpest treatment, conveying technical precision
- Subtly rounded (6px): Buttons, links, clipboard actions — the workhorse radius
  for interactive elements
- Code-specific (6.4px): Code blocks, `pre` elements, clipboard copy targets — a
  deliberate micro-distinction from standard 6px
- Comfortably rounded (8px): Content cards, feature containers, emphasized
  buttons — the standard containment radius
- Pill-shaped (9999px): Tags, badges, status indicators, pill-shaped navigation
  elements — the roundest treatment for small categorical labels

## 6. Depth & Elevation

| Level                    | Treatment                                                                 | Use                                                      |
| ------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------- |
| Flat (Level 0)           | No shadow, no border                                                      | Page background (`#050507`), inline text                 |
| Contained (Level 1)      | `1px solid #3d3a39`, no shadow                                            | Standard cards, nav bar, code blocks                     |
| Emphasized (Level 2)     | `3px solid #3d3a39`, no shadow                                            | Large interactive buttons, emphasized containers         |
| Accent (Level 3)         | `2px solid #00d992`, no shadow                                            | Active/highlighted feature cards, selected states        |
| Ambient Glow (Level 4)   | `rgba(92, 88, 85, 0.2) 0px 0px 15px`                                      | Elevated cards, hover states, soft atmospheric lift      |
| Dramatic Float (Level 5) | `rgba(0, 0, 0, 0.7) 0px 20px 60px` + `rgba(148, 163, 184, 0.1) 1px inset` | Hero feature showcase, modals, maximum-elevation content |

**Shadow Philosophy**: VoltAgent communicates depth primarily through **border
weight and color**, not shadows. The standard `1px solid #3d3a39` border IS the
elevation — adding a `3px` border weight or switching to green (`#00d992`)
communicates importance more than adding shadow does. When shadows do appear,
they're either warm and diffused (Level 4) or cinematic and dramatic (Level 5) —
never medium or generic.

### Decorative Depth

- **Green Signal Glow**: The VoltAgent bolt logo pulses with a `drop-shadow`
  animation cycling between 2px and 8px blur radius in Emerald Signal Green.
  This is the most distinctive decorative element — it makes the logo feel
  "powered on."
- **Warm Charcoal Containment Lines**: The warm tone of `#3d3a39` borders
  creates a subtle visual warmth against the cool black, as if the cards are
  faintly heated from within.
- **Dashed Workflow Lines**: `1px dashed rgba(79, 93, 117, 0.4)` creates a
  blueprint-like aesthetic for architecture diagrams, visually distinct from
  solid content borders.

## 7. Do's and Don'ts

### Do

- Use Abyss Black (`#050507`) as the landing page background and Carbon Surface
  (`#101010`) for all contained elements — the two-shade dark system is
  essential
- Reserve Emerald Signal Green (`#00d992`) exclusively for high-signal moments:
  active borders, glow effects, and the most important interactive accents
- Use VoltAgent Mint (`#2fd6a1`) for button text on dark surfaces — it's more
  readable than pure Signal Green
- Keep heading line-heights compressed (1.0–1.11) with negative letter-spacing
  for dense, authoritative text blocks
- Use the warm gray palette (`#3d3a39`, `#8b949e`, `#b8b3b0`) for borders and
  secondary text — warmth prevents the dark theme from feeling sterile
- Present code snippets as primary content — they're hero elements, not
  supporting illustrations
- Use border weight (1px → 2px → 3px) and color shifts (`#3d3a39` → `#00d992`)
  to communicate depth and importance, rather than relying on shadows
- Pair system-ui for headings with Inter for body text — the speed/authority of
  native fonts combined with the precision of a geometric sans
- Use SFMono-Regular for all code content — it's the developer credibility
  signal
- Apply `"calt"` and `"rlig"` OpenType features across all text

### Don't

- Don't use bright or light backgrounds as primary surfaces — the entire
  identity lives on near-black
- Don't introduce warm colors (orange, red, yellow) as decorative accents — the
  palette is strictly green + warm neutrals on black. Warm colors are reserved
  for semantic states (warning, error) only
- Don't use Emerald Signal Green (`#00d992`) on large surfaces or as background
  fills — it's an accent, never a surface
- Don't increase heading line-heights beyond 1.33 — the compressed density is
  core to the engineering-platform identity
- Don't use heavy shadows generously — depth comes from border treatment, not
  box-shadow. Shadows are reserved for Level 4–5 elevation only
- Don't use pure white (`#ffffff`) as default body text — Snow White (`#f2f2f2`)
  is the standard. Pure white is reserved for maximum-emphasis headings and
  button text
- Don't mix in serif or decorative fonts — the entire system is geometric sans +
  monospace
- Don't use border-radius larger than 8px on content cards — 9999px (pill) is
  only for small tags and badges
- Don't skip the warm-gray border system — cards without `#3d3a39` borders lose
  their containment and float ambiguously on the dark canvas
- Don't animate aggressively — animations are slow and subtle (25–100s durations
  for marquee, gentle glow pulses). Fast motion contradicts the "engineering
  precision" atmosphere

## 8. Responsive Behavior

### Breakpoints

| Name          | Width       | Key Changes                                                                  |
| ------------- | ----------- | ---------------------------------------------------------------------------- |
| Small Mobile  | <420px      | Minimum layout, stacked everything, reduced hero text to ~24px               |
| Mobile        | 420–767px   | Single column, hamburger nav, full-width cards, hero text ~36px              |
| Tablet        | 768–1024px  | 2-column grids begin, condensed nav, medium hero text                        |
| Desktop       | 1025–1440px | Full multi-column layout, expanded nav with dropdowns, large hero (60px)     |
| Large Desktop | >1440px     | Max-width container centered (est. 1280–1440px), generous horizontal margins |

_23 breakpoints detected in total, ranging from 360px to 1992px — indicating a
fluid, heavily responsive grid system rather than fixed breakpoint snapping._

### Touch Targets

- Buttons use comfortable padding (12px 16px minimum) ensuring adequate touch
  area
- Navigation links spaced with sufficient gap for thumb navigation
- Interactive card surfaces are large enough to serve as full touch targets
- Minimum recommended touch target: 44x44px

### Collapsing Strategy

- **Navigation**: Full horizontal nav with dropdowns collapses to hamburger menu
  on mobile
- **Feature grids**: 3-column → 2-column → single-column vertical stacking
- **Hero text**: 60px → 36px → 24px progressive scaling with maintained
  compression ratios
- **Logo marquee**: Adjusts scroll speed and item sizing; maintains infinite
  loop
- **Code blocks**: Horizontal scroll on smaller viewports rather than wrapping —
  preserving code readability
- **Section padding**: Reduces proportionally but maintains generous vertical
  rhythm between chapters
- **Cards**: Stack vertically on mobile with full-width treatment and maintained
  internal padding

### Image Behavior

- Dark-themed screenshots and diagrams scale proportionally within containers
- Agent flow diagrams simplify or scroll horizontally on narrow viewports
- Dot-pattern decorative backgrounds scale with viewport
- No visible art direction changes between breakpoints — same crops,
  proportional scaling
- Lazy loading for below-fold images (Docusaurus default behavior)

## 9. Agent Prompt Guide

### Quick Color Reference

- Brand Accent: "Emerald Signal Green (#00d992)"
- Button Text: "VoltAgent Mint (#2fd6a1)"
- Page Background: "Abyss Black (#050507)"
- Card Surface: "Carbon Surface (#101010)"
- Border / Containment: "Warm Charcoal (#3d3a39)"
- Primary Text: "Snow White (#f2f2f2)"
- Secondary Text: "Warm Parchment (#b8b3b0)"
- Tertiary Text: "Steel Slate (#8b949e)"

### Example Component Prompts

- "Create a feature card on Carbon Surface (#101010) with a 1px solid Warm
  Charcoal (#3d3a39) border, comfortably rounded corners (8px). Use Snow White
  (#f2f2f2) for the title in system-ui at 24px weight 700, and Warm Parchment
  (#b8b3b0) for the description in Inter at 16px. Add a subtle Warm Ambient
  shadow (rgba(92, 88, 85, 0.2) 0px 0px 15px)."
- "Design a ghost button with transparent background, Snow White (#f2f2f2) text
  in Inter at 16px, a 1px solid Warm Charcoal (#3d3a39) border, and subtly
  rounded corners (6px). Padding: 12px vertical, 16px horizontal. On hover,
  background shifts to rgba(0, 0, 0, 0.2)."
- "Build a hero section on Abyss Black (#050507) with a massive heading at 60px
  system-ui, line-height 1.0, letter-spacing -0.65px. The word 'Platform' should
  be colored in Emerald Signal Green (#00d992). Below the heading, place a code
  block showing 'npm create voltagent-app@latest' in SFMono-Regular at 14px on
  Carbon Surface (#101010) with a copy button."
- "Create a highlighted feature card using a 2px solid Emerald Signal Green
  (#00d992) border instead of the standard Warm Charcoal. Keep Carbon Surface
  background, comfortably rounded corners (8px), and include a code snippet on
  the left with feature description text on the right."
- "Design a navigation bar on Abyss Black (#050507) with the VoltAgent logo
  (bolt icon with animated green glow) on the left, nav links in Inter at 14px
  weight 500 in Snow White, and a green CTA button (Carbon Surface bg, VoltAgent
  Mint text) on the right. Add a 1px solid Warm Charcoal bottom border."

### Iteration Guide

When refining existing screens generated with this design system:

1. Focus on ONE component at a time
2. Reference specific color names and hex codes — "use Warm Parchment (#b8b3b0)"
   not "make it lighter"
3. Use border treatment to communicate elevation: "change the border to 2px
   solid Emerald Signal Green (#00d992)" for emphasis
4. Describe the desired "feel" alongside measurements — "compressed and
   authoritative heading at 36px with line-height 1.11 and -0.9px
   letter-spacing"
5. For glow effects, specify "Emerald Signal Green (#00d992) as a drop-shadow
   with 2–8px blur radius"
6. Always specify which font — system-ui for headings, Inter for body/UI,
   SFMono-Regular for code
7. Keep animations slow and subtle — marquee scrolls at 25–80s, glow pulses
   gently