# 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