Vauban Design Language (VDL) v5.0

The Vauban Design Language is the unified visual system governing all products in the Vauban ecosystem. It ensures visual coherence across 9+ applications while preserving each product's distinct identity through the Zone Accent system.

Design Principles

1. Dark-First, Institutional

Vauban targets sophisticated DeFi users managing real capital. The interface communicates trust, precision, and seriousness -- not playfulness.

• Dark backgrounds reduce eye strain during extended portfolio monitoring
• High-contrast text ensures readability across all lighting conditions
• Subtle brand glow effects guide attention without distraction

2. OKLCH-Sourced, Hex-Delivered

All colors are authored in OKLCH (perceptually uniform, CSS Color Level 4) for precise lightness/chroma control, then compiled to hex for delivery. This guarantees:

• Perceptually uniform scales -- equal visual steps between shade levels
• Pixel-identical rendering across Chrome, Firefox, Safari, and mobile browsers
• Zero runtime overhead -- resolved hex values, no oklch() function calls
• Generator script: packages/design-tokens/scripts/generate-scales.mjs (culori)

3. Three-Tier Token Architecture

Reference Layer    --vdl-slate-{1-12}, --vdl-indigo-{1-12}, ...
     │             Static, theme-agnostic. Raw 12-step scales.
     ▼
Semantic Layer     --vdl-bg-void, --vdl-text-primary, ...
     │             Purpose-bound, theme-reactive via CSS selectors.
     ▼
Component Layer    Per-component aliases (e.g. --card-bg, --btn-text)
                   Defined in component CSS, not in tokens.css.

Semantic tokens reference scale tokens: --vdl-bg-void: var(--vdl-slate-1). Zero visual change when switching layers -- same resolved values.

4. Three Themes, One Source

All three themes derive from a single tokens.css file. The :root block defines Navy (default), then [data-theme="zinc"] and [data-theme="light"] selectors override only the semantic variables that change.

5. Zone Accents

Each product has a unique accent with a full 12-step scale, creating instant visual identification:

Zone accents are static -- they never change between themes. Each zone has steps 1-12 for tinted backgrounds, borders, and text variants (see Zones).

6. Radix 12-Step Scale Model

Every color scale follows the Radix 12-step convention:

Token Layers

Layer 4: Tailwind Utilities   bg-vdl-base, text-vdl-primary, text-indigo-9
Layer 3: Tailwind v4 Theme    @theme { --color-vdl-base: var(--vdl-bg-base) }
Layer 2: Semantic Tokens       --vdl-bg-base: var(--vdl-slate-2)
Layer 1: Reference Scales      --vdl-slate-2: #0A0F1A  /* oklch(0.169 0.025 265) */

Background Scale (5 levels)

Text Scale (4 levels)

Status Colors

Typography

Type Scale

Dark mode weight compensation: Headings get +100 weight in dark themes to counteract halation (text appears thinner on dark backgrounds).

Font Features

Spacing & Layout

• 8px grid -- All spacing uses multiples of 4px (--vdl-space-1 = 4px through --vdl-space-24 = 96px)
• Header height: 56px
• Sidebar width: 256px
• Max content width: 1280px

Shadows & Effects

Dark themes use deeper, more opaque shadows. Light theme uses warm-toned subtle shadows inspired by natural stone.

The glow effect (--vdl-glow-brand) adds a subtle indigo halo to primary action elements, reinforcing brand identity without being distracting. A 7-intensity scale allows precise glow control for different interaction states.

Motion

VDL v5.0 includes a centralized motion system with spring physics, staggered reveals, and transaction-specific animations. See Motion for details.

Version History