diff --git a/docs/design/design-system.md b/docs/design/design-system.md
new file mode 100644
index 0000000..6a161b5
--- /dev/null
+++ b/docs/design/design-system.md
@@ -0,0 +1,141 @@
+# Mosaic Stack Design System
+
+## Overview
+
+The Mosaic Stack design system provides a unified visual language across the dashboard application. It uses CSS custom properties for theming, inline styles for `packages/ui` components, and a dark-first approach with light theme support.
+
+## Design Tokens
+
+All tokens are defined in `apps/web/src/app/globals.css` as CSS custom properties on `:root` (dark default) and `[data-theme="light"]`.
+
+### Color Palette
+
+| Token             | Dark Value | Purpose                        |
+| ----------------- | ---------- | ------------------------------ |
+| `--ms-blue-400`   | `#4d94ff`  | Primary accent, active states  |
+| `--ms-blue-500`   | `#2f80ff`  | Primary brand color            |
+| `--ms-teal-400`   | `#2dd4bf`  | Success, positive metrics      |
+| `--ms-teal-500`   | `#14b8a6`  | Success emphasis               |
+| `--ms-purple-400` | `#a78bfa`  | Orchestrator, secondary accent |
+| `--ms-purple-500` | `#8b5cf6`  | Purple emphasis                |
+| `--ms-amber-400`  | `#fbbf24`  | Warnings, caution              |
+| `--ms-red-400`    | `#f87171`  | Errors, danger                 |
+| `--ms-cyan-500`   | `#06b6d4`  | Info, neutral accent           |
+
+### Semantic Tokens
+
+| Token         | Dark Value            | Purpose                |
+| ------------- | --------------------- | ---------------------- |
+| `--bg`        | `#0a0e17`             | Page background        |
+| `--bg-mid`    | `#111827`             | Card/panel background  |
+| `--bg-deep`   | `#060a12`             | Terminal/deep surfaces |
+| `--surface`   | `#151c2c`             | Card surfaces          |
+| `--surface-2` | `#1e2940`             | Hover/active surfaces  |
+| `--border`    | `#1e2940`             | Default borders        |
+| `--text`      | `#e8ecf4`             | Primary text           |
+| `--text-2`    | `#94a3b8`             | Secondary text         |
+| `--muted`     | `#64748b`             | Muted/label text       |
+| `--primary`   | `var(--ms-blue-500)`  | Primary action         |
+| `--success`   | `var(--ms-teal-500)`  | Success state          |
+| `--danger`    | `var(--ms-red-400)`   | Error state            |
+| `--warn`      | `var(--ms-amber-400)` | Warning state          |
+
+### Typography
+
+| Token    | Value                          | Purpose                   |
+| -------- | ------------------------------ | ------------------------- |
+| `--font` | `Inter, system-ui, sans-serif` | Body text                 |
+| `--mono` | `JetBrains Mono, monospace`    | Code, metrics, timestamps |
+
+### Spacing & Radii
+
+| Token    | Value  | Purpose                         |
+| -------- | ------ | ------------------------------- |
+| `--r-sm` | `4px`  | Small radius (buttons, inputs)  |
+| `--r`    | `8px`  | Default radius (cards, panels)  |
+| `--r-lg` | `12px` | Large radius (sections, modals) |
+
+## App Shell Layout
+
+The dashboard uses a CSS Grid layout:
+
+```
+grid-template-columns: var(--sidebar-w) 1fr;
+grid-template-rows: var(--topbar-h) 1fr;
+```
+
+- **Header** spans full width (`grid-column: 1 / -1`)
+- **Sidebar** width: `240px` (expanded) / `60px` (collapsed)
+- **Topbar** height: `52px`
+
+### Responsive Breakpoints
+
+| Breakpoint            | Behavior                                        |
+| --------------------- | ----------------------------------------------- |
+| `< 768px` (Mobile)    | Single column, sidebar as overlay with backdrop |
+| `768-1023px` (Tablet) | Sidebar toggleable, hidden by default           |
+| `>= 1024px` (Desktop) | Sidebar always visible                          |
+
+## Shared Components (packages/ui)
+
+All `packages/ui` components use inline styles with CSS custom properties since the package is built with `tsc` only (no CSS processing).
+
+### Button
+
+Variants: `primary` (blue), `secondary` (transparent), `ghost`, `danger` (red), `success` (teal)
+
+### Badge
+
+Variants: `badge-teal`, `badge-amber`, `badge-red`, `badge-blue`, `badge-muted`, `badge-purple`, `badge-pulse`
+
+Pill shape with monospace font. `badge-pulse` includes an animated dot.
+
+### Card
+
+Flat design with `var(--surface)` background, `var(--border)` border, `var(--r-lg)` border-radius. Header and footer slots available.
+
+### Dot
+
+Status indicator (7x7px circle with glow). Variants: `teal`, `blue`, `amber`, `red`, `muted`.
+
+### MetricsStrip
+
+Grid of metric cells with colored top borders, hover state, and optional trend indicators. Each cell: value (large mono), label (small muted), trend (colored directional text).
+
+### ProgressBar
+
+4px track with fill animation. Variants: `blue`, `teal`, `purple`, `amber`. Full ARIA progressbar semantics.
+
+### FilterTabs
+
+Segmented control with active/hover states.
+
+### SectionHeader
+
+Flex row with title/subtitle on left, action slot on right.
+
+### DataTable
+
+Generic typed table with column render functions, row hover, and row click support.
+
+### LogLine
+
+3-column grid (timestamp, level, message) with color-coded log levels.
+
+## Dashboard Page Layout
+
+The dashboard page uses:
+
+1. **MetricsStrip** (full width, 6 cells)
+2. **Two-column grid** (`1fr 320px`):
+   - Main: OrchestratorSessions + QuickActions
+   - Sidebar: ActivityFeed + TokenBudget
+
+## Terminal Panel
+
+Bottom drawer component (`apps/web/src/components/terminal/TerminalPanel.tsx`) with:
+
+- Height animation (0 → 280px)
+- Tab bar (main, build, logs)
+- Color-coded output lines (prompt, command, output, error, warning, success)
+- Blinking cursor animation