# Design System -- LLMHosts.com

## META
- created: 2026-02-14
- references: ADR-005 (Next.js + shadcn/ui), PRD
- library: shadcn/ui + Radix UI + Tailwind CSS v4
- mode: dark-first (developer tool)

---

## 1. DESIGN PRINCIPLES

1. **Density over whitespace**: Developers want information, not padding.
2. **Clarity over decoration**: No gradients or animations without purpose. Data speaks.
3. **Trust through transparency**: Show routing decisions, cache reasoning, cost math.
4. **Speed is respect**: Dashboard loads <500ms. Real-time updates. No spinners >2s.
5. **Terminal-native**: TUI is first-class. Web mirrors terminal, not the reverse.

---

## 2. COLOR SYSTEM

### Primitives (hex)

gray-50:#fafafa gray-100:#f4f4f5 gray-200:#e4e4e7 gray-300:#d4d4d8
gray-400:#a1a1aa gray-500:#71717a gray-600:#52525b gray-700:#3f3f46
gray-800:#27272a gray-900:#18181b gray-950:#09090b

primary-400:#60a5fa primary-500:#3b82f6 primary-600:#2563eb
green-400:#4ade80 green-500:#22c55e green-600:#16a34a
amber-400:#fbbf24 amber-500:#f59e0b
red-400:#f87171 red-500:#ef4444
emerald-400:#34d399 emerald-500:#10b981 (savings ticker)
orange-400:#fb923c (cost/spend)

### Semantic Tokens (dark / light)

| Token | Dark | Light |
|-------|------|-------|
| color-bg-default | gray-950 #09090b | gray-50 #fafafa |
| color-bg-surface | gray-900 #18181b | white #ffffff |
| color-bg-card | gray-800 #27272a | gray-100 #f4f4f5 |
| color-bg-muted | gray-800 #27272a | gray-200 #e4e4e7 |
| color-text-primary | gray-50 #fafafa | gray-950 #09090b |
| color-text-secondary | gray-400 #a1a1aa | gray-500 #71717a |
| color-text-muted | gray-500 #71717a | gray-400 #a1a1aa |
| color-border-default | gray-700 #3f3f46 | gray-200 #e4e4e7 |
| color-interactive | primary-500 #3b82f6 | primary-600 #2563eb |
| color-interactive-hover | primary-400 #60a5fa | primary-500 #3b82f6 |
| color-feedback-success | green-400 #4ade80 | green-600 #16a34a |
| color-feedback-error | red-400 #f87171 | red-500 #ef4444 |
| color-feedback-warning | amber-400 #fbbf24 | amber-500 #f59e0b |
| color-savings | emerald-400 #34d399 | emerald-500 #10b981 |
| color-cost | orange-400 #fb923c | orange-400 #fb923c |

### Contrast (WCAG AA verified)
- text-primary on bg-default: 19.5:1 dark, 18.1:1 light PASS
- text-secondary on bg-default: 6.3:1 PASS
- savings on bg-default: 11.2:1 PASS

---

## 3. TYPOGRAPHY

Fonts: Inter (body/headings via next/font/google), JetBrains Mono (code via next/font/google). display:swap.

| Token | Font | Size | Weight | Line-Height | Letter-Spacing |
|-------|------|------|--------|-------------|---------------|
| h1 | Inter | 30px/1.875rem | 700 | 1.2 | -0.025em |
| h2 | Inter | 24px/1.5rem | 600 | 1.25 | -0.02em |
| h3 | Inter | 20px/1.25rem | 600 | 1.3 | -0.015em |
| h4 | Inter | 16px/1rem | 600 | 1.4 | -0.01em |
| body-lg | Inter | 16px/1rem | 400 | 1.6 | 0 |
| body | Inter | 14px/0.875rem | 400 | 1.5 | 0 |
| body-sm | Inter | 12px/0.75rem | 400 | 1.5 | 0 |
| caption | Inter | 11px/0.6875rem | 500 | 1.4 | 0.02em |
| code-lg | JetBrains Mono | 15px/0.9375rem | 400 | 1.6 | 0 |
| code | JetBrains Mono | 13px/0.8125rem | 400 | 1.5 | 0 |
| code-sm | JetBrains Mono | 11px/0.6875rem | 400 | 1.5 | 0 |

Mobile: h1=24px, h2=20px, h3=18px. Body sizes unchanged.

---

## 4. SPACING AND LAYOUT

Base unit: 4px

| Token | Value | Use |
|-------|-------|-----|
| space-0.5 | 2px | Inline icon gap |
| space-1 | 4px | Tight gap |
| space-1.5 | 6px | Badge padding |
| space-2 | 8px | Compact card padding |
| space-3 | 12px | Form field gap |
| space-4 | 16px | Card padding, section gap |
| space-5 | 20px | Comfortable padding |
| space-6 | 24px | Section separator |
| space-8 | 32px | Major section gap |
| space-10 | 40px | Page section gap |
| space-12 | 48px | Top-level page padding |
| space-16 | 64px | Hero spacing |

Containers: sm=640px, md=768px, lg=1024px, xl=1280px, 2xl=1536px
Grid: 12 columns, 16px gutter
Dashboard: sidebar 256px expanded / 64px collapsed + fluid main + 48px topbar height

---

## 5. BORDERS AND SHADOWS

Radii: none=0, sm=2px, md=4px (default), lg=8px, xl=12px, full=9999px
Borders: thin=1px, default=1.5px

| Shadow Token | CSS Value |
|-------------|-----------|
| shadow-xs | 0 1px 2px rgba(0,0,0,0.3) |
| shadow-sm | 0 2px 4px rgba(0,0,0,0.3) |
| shadow-md | 0 4px 8px rgba(0,0,0,0.4) |
| shadow-lg | 0 8px 16px rgba(0,0,0,0.5) |
| shadow-glow-primary | 0 0 12px rgba(59,130,246,0.3) |
| shadow-glow-savings | 0 0 12px rgba(52,211,153,0.3) |

---

## 6. ANIMATION

| Token | Duration | Easing | Use |
|-------|----------|--------|-----|
| instant | 0ms | -- | Focus ring |
| fast | 100ms | ease-out | Hover, tooltips |
| default | 200ms | ease-in-out | Modal open/close |
| slow | 300ms | ease-in-out | Page transitions |
| counter | 500ms | ease-out | Savings ticker roll-up |

prefers-reduced-motion: all durations to 0ms.

---

## 7. ICONOGRAPHY

Library: Lucide React (MIT, matches shadcn/ui). Sizes: sm=16px, md=20px, lg=24px, xl=32px. Stroke: 1.5px. Color: currentColor.
Key icons: Activity=requests, DollarSign=cost, Wifi/WifiOff=tunnel, Server=backend, Database=cache, Shield=PII, Zap=cached, BarChart3=metrics.

---

## 8. SHADCN/UI COMPONENTS

| Component | Use | Rules |
|-----------|-----|-------|
| Button | Actions | variant=default for primary. Max 2 inline. |
| Card | Dashboard widgets | No nesting cards. |
| Table | Request logs, model lists | Sticky header. Virtual scroll >100 rows. |
| Badge | Status, routing tier | rule=gray, knn=blue, bert=purple, qwen=amber |
| Dialog | Confirms, under 400px wide | Sheet for >5 field forms |
| Tooltip | Routing reasons on hover | Not for critical info |
| Tabs | Dashboard sections | Max 5 |
| Input | Config, search | Always labeled |
| Select | 3-15 options | Switch for 2 options |
| Switch | Toggles | Always labeled |
| Toast | Notifications | Auto-dismiss 5s, max 3 stacked |
| Skeleton | Loading states | Match layout, max 3s |
| ScrollArea | Long lists | Virtual scroll >100 items |
| Sheet | Mobile sidebar, detail panels | Left=nav, right=detail |

---

## 9. RESPONSIVE

| Breakpoint | Width | Behavior |
|-----------|-------|----------|
| mobile | <640px | Sidebar hidden (Sheet), single col, stacked cards |
| tablet | 640-1023px | Sidebar collapsed (64px), 2-col grid |
| desktop | 1024-1279px | Sidebar expanded (256px), full grid |
| widescreen | >=1280px | Wider content, more table columns |

---

## 10. ACCESSIBILITY

Focus: 2px solid primary-500, 2px offset, always visible on keyboard.
Touch: 44x44px minimum all interactive.
Live regions: savings ticker=aria-live polite, error toasts=assertive.
Color-blind: never color alone, always pair with icon or text.
Screen reader: all icons have aria-label, savings ticker announces dollar amount.

---

## 11. TUI TOKENS (Rich/Textual)

| Web Token | Terminal | Rich Markup |
|-----------|---------|-------------|
| text-primary | white | [bold white] |
| text-secondary | bright_black | [bright_black] |
| interactive | blue | [blue] |
| savings | green | [bold green] |
| cost | yellow | [yellow] |
| error | red | [bold red] |
| success | green | [green] |
| warning | yellow | [yellow] |

Cards: Panel(border_style="dim"). Layout: Textual CSS grid, sidebar 20 cols + main fluid. Topbar 3 rows.
