# Design System Migration Plan — Nexus UI → DESIGN.md (ClickHouse-inspired)

Status: **DRAFT, awaiting review**. Do not touch UI files until this is approved.

---

## 1. Executive summary

Migrate the Nexus UI from its current Tailwind v4 + Catppuccin (Mocha/Latte) + Tokyo Night setup to the new DESIGN.md aesthetic: **pure black canvas, Neon Volt (`#faff69`) as the sole chromatic accent, Forest Green (`#166534`) as secondary CTA, Inter/Basier/Inconsolata typography, sharp geometry, border-based depth**.

**Scope in numbers (from codebase scan):**

| Category | Count | How it migrates |
|---|---|---|
| CSS variables in `index.css` | 29 × 3 selectors | Rewrite `@theme inline` block (single file edit) |
| Tailwind theme-token classes (`bg-background`, `text-muted-foreground`, `border-border`, …) | ~1,250 instances | Auto-migrate when CSS vars change — zero source edits |
| Raw palette utilities (`bg-red-500`, `text-amber-600`, …) | ~274 instances across ~60 files | Manual remap to semantic tokens — per-file work |
| Hardcoded hex fallbacks in TSX (e.g., `#6366f1`, `#64748b`) | ~65 files | Find-and-replace with token refs |
| Status / priority / agent-role color maps (`lib/status-colors.ts`, `lib/agent-role-colors.ts`) | ~45 definitions | Rewrite against new palette |
| hljs syntax highlighting blocks in `index.css` | 3 theme blocks (Mocha, Tokyo, Latte) | Delete, write one block matching DESIGN.md |
| Theme switching machinery (`ThemeContext.tsx`, `Layout.tsx` toggle) | 2 files | Simplify — drop Catppuccin/Tokyo cycle, keep light/dark binary |
| Font loading (Inter/Basier/Inconsolata) | 0 currently | Add font-face declarations (or CDN) — new work |

**Effort estimate:** One careful pass, with the bulk of the mechanical work concentrated in ~3 files (`index.css`, `lib/status-colors.ts`, `lib/agent-role-colors.ts`) and a long tail in the ~60 files using raw palette utilities. The hardcoded hex cleanup is mostly in fallback expressions and is trivial once the token semantics are agreed.

**Key design decisions the user must make before Phase 1:**

1. **Light mode strategy.** DESIGN.md explicitly says "no light/white backgrounds anywhere." I've drafted a light mode anyway (Section 5), but I'd like confirmation on the direction — or explicit permission to drop light mode entirely.
2. **Neon Volt on white is unreadable.** In light mode, volt either gets reserved for border/active states (primary chromatic accent rotates to Forest Green) or we pick a darker neon-adjacent hue. See Section 5.
3. **Tokyo Night removal.** The `.theme-tokyo-night.dark` selector is defined in CSS but never applied by the current ThemeContext (dead code). I propose deleting it — confirm.
4. **Font pipeline.** Inter/Basier/Inconsolata are not currently loaded. Options: Google Fonts CDN, self-hosted woff2, or `@fontsource` npm packages. I'd suggest self-hosted woff2 for LAN/offline reliability, but that's 6–10 MB of fonts in `public/`. Confirm preference.
5. **Font weight 900 for display.** DESIGN.md calls this out as core to the identity. Current Nexus has no 96px+ display type. Adopt for hero/landing moments or skip?

---

## 2. Current state vs. DESIGN.md (side by side)

### Color philosophy

| Dimension | Current (Catppuccin Mocha) | Current (Tokyo Night) | DESIGN.md (ClickHouse) |
|---|---|---|---|
| Background | `#1e1e2e` (dark purple-gray) | `#1a1b26` (dark blue-gray) | `#000000` (pure black) |
| Card | `#181825` | `#16161e` | `#141414` or transparent |
| Primary | `#89b4fa` (blue) | `#7aa2f7` (blue) | `#faff69` (acid yellow-green) |
| Destructive | `#f38ba8` (pink) | `#f7768e` (pink) | TBD — DESIGN.md omits red |
| Border | `#313244` | `#24283b` | `rgba(65,65,65,0.8)` (charcoal) |
| Accent scale | Smooth pastels | Smooth blues | Binary: volt or green, nothing else |
| Overall vibe | Cozy, muted, rounded | Cozy, muted, rounded | Cockpit, sharp, maximum contrast |

### Typography

| Role | Current | DESIGN.md |
|---|---|---|
| Font family | System stack (no explicit loads — Tailwind default) | Inter + Basier + Inconsolata |
| Display weight | Up to 700 at 24–36px | **900 at 72–96px** |
| Body weight | 400 / 500 | 400 / 500 / 600 / 700 |
| Labels | Mixed case | **Uppercase + 1.4px tracking** |
| Code | Monospace (system) | Inconsolata 600 |

### Geometry

| | Current | DESIGN.md |
|---|---|---|
| Radius scale | `sm:2px md:4px lg:0 xl:0` (already sharpish) | Sharp 4px / comfortable 8px / pill 9999px — nothing else |
| Border style | Solid 1px | Solid 1px, charcoal `rgba(65,65,65,0.8)` — single workhorse color |
| Shadow | Subtle layered shadows | Border-based depth + inset "pressed" effect |

### Interaction

| | Current | DESIGN.md |
|---|---|---|
| Link hover | Muted highlight | **Volt (`#faff69`) — universal** |
| Active text | Opacity change | **Pale Yellow (`#f4f692`)** |
| Button hover | Subtle bg shift | BG shifts to `#3a3a3a`, text to volt/pale |

---

## 3. Token mapping — old vars → new vars (DARK mode)

The migration is primarily a rewrite of the `@theme inline` block in `/opt/nexus/ui/src/index.css`. Token **names** stay the same (so the ~1,250 Tailwind utility classes auto-migrate); only values change.

| Token | Current (Mocha) | New (DESIGN.md dark) | Notes |
|---|---|---|---|
| `--background` | `#1e1e2e` | `#000000` | Pure black, no compromise |
| `--foreground` | `#cdd6f4` | `#ffffff` | Pure white |
| `--card` | `#181825` | `#141414` | "Near Black" from DESIGN.md §2 |
| `--card-foreground` | `#cdd6f4` | `#ffffff` | — |
| `--popover` | `#181825` | `#141414` | Match card |
| `--popover-foreground` | `#cdd6f4` | `#ffffff` | — |
| `--primary` | `#89b4fa` (blue) | `#faff69` (**volt**) | The brand inversion — single biggest visual change |
| `--primary-foreground` | `#1e1e2e` | `#151515` | Near-black text on volt |
| `--secondary` | `#313244` | `#166534` (**forest**) | Secondary CTA becomes green |
| `--secondary-foreground` | `#cdd6f4` | `#ffffff` | — |
| `--muted` | `#313244` | `#141414` | Muted surfaces stay near-black |
| `--muted-foreground` | `#a6adc8` | `#a0a0a0` (**silver**) | DESIGN.md §2 "Silver" |
| `--accent` | `#45475a` | `#141414` | Accent surface = muted surface in this system |
| `--accent-foreground` | `#cdd6f4` | `#faff69` | Text on accent surfaces lights up volt |
| `--destructive` | `#f38ba8` (pink) | `#ef4444` (muted red) | DESIGN.md doesn't specify — I picked a restrained red that doesn't compete with volt. Confirm. |
| `--destructive-foreground` | `#1e1e2e` | `#ffffff` | — |
| `--border` | `#313244` | `rgba(65,65,65,0.8)` (**charcoal**) | Workhorse — DESIGN.md §2 |
| `--input` | `#313244` | `#141414` | Input fields use near-black fill, charcoal border |
| `--ring` | `#89b4fa` | `#faff69` | Focus ring is volt |
| `--chart-1` | `#89b4fa` | `#faff69` | Primary chart series = volt |
| `--chart-2` | `#a6e3a1` | `#166534` | Secondary = forest |
| `--chart-3` | `#cba6f7` | `#a0a0a0` | Tertiary = silver |
| `--chart-4` | `#f9e2af` | `#f4f692` (pale yellow) | Active/pressed accent |
| `--chart-5` | `#f38ba8` | `#ef4444` | Destructive (if needed for alerts) |
| `--sidebar` | `#181825` | `#000000` | Sidebar = pure black, no surface differentiation |
| `--sidebar-foreground` | `#cdd6f4` | `#a0a0a0` | Secondary silver — nav items dim, active is volt |
| `--sidebar-primary` | `#89b4fa` | `#faff69` | — |
| `--sidebar-primary-foreground` | `#1e1e2e` | `#151515` | — |
| `--sidebar-accent` | `#313244` | `#141414` | — |
| `--sidebar-accent-foreground` | `#cdd6f4` | `#ffffff` | — |
| `--sidebar-border` | `#313244` | `rgba(65,65,65,0.8)` | — |
| `--sidebar-ring` | `#89b4fa` | `#faff69` | — |

**New tokens to add** (not in current system but needed for DESIGN.md fidelity):

| New token | Value | Purpose |
|---|---|---|
| `--volt` | `#faff69` | Direct brand-accent reference (for code that needs the literal brand color, e.g. logo, chart emphasis) |
| `--volt-pale` | `#f4f692` | Active/pressed text color per DESIGN.md §2 |
| `--volt-border` | `#4f5100` | Dark olive ghost-button borders per DESIGN.md §2 |
| `--forest` | `#166534` | Direct secondary-CTA reference |
| `--forest-dark` | `#14572f` | Darker forest for border variant |
| `--near-black` | `#141414` | Button backgrounds, elevated dark surfaces |
| `--hover-gray` | `#3a3a3a` | Button hover background |
| `--silver` | `#a0a0a0` | Secondary/muted text |
| `--charcoal-border` | `rgba(65,65,65,0.8)` | Signature border |
| `--charcoal-divider` | `#343434` | Subtler division |

### Radius

DESIGN.md is strict: 4px, 8px, 9999px. Current `--radius-*` tokens are already close — audit and lock:

| Token | Current | New | Notes |
|---|---|---|---|
| `--radius-sm` | `2px` | `4px` | Bump to 4 (DESIGN.md "sharp") |
| `--radius-md` | `4px` | `4px` | Keep |
| `--radius-lg` | `0px` | `8px` | DESIGN.md "comfortable" for cards |
| `--radius-xl` | `0px` | `8px` | Alias to lg; audit xl usage and collapse |
| `--radius-full` | `9999px` | `9999px` | Pill unchanged |

**Audit task:** grep for `rounded-xl`, `rounded-2xl`, `rounded-3xl` — these violate the DESIGN.md scale and need to come down.

---

## 4. Typography migration

### Font loading

Currently: no explicit font loads — Tailwind falls back to system stack.

Proposed: self-hosted woff2 via `@font-face` in `index.css`, dropped into `ui/public/fonts/`. Rationale: LAN testing without internet; Nexus is meant to run offline-capable.

```css
@font-face {
  font-family: "Inter";
  src: url("/fonts/Inter-VariableFont_slnt,wght.woff2") format("woff2-variations");
  font-weight: 100 900;
  font-display: swap;
}
@font-face {
  font-family: "Inconsolata";
  src: url("/fonts/Inconsolata-VariableFont_wdth,wght.woff2") format("woff2-variations");
  font-weight: 100 900;
  font-display: swap;
}
/* Basier: not free — likely fallback to Inter for feature headings, or purchase license */
```

**Decision needed:** Basier is a paid font. Either:
- (A) License Basier (one-time cost) — true to DESIGN.md
- (B) Use Inter for both display and feature headings (skip Basier entirely) — simpler, free
- (C) Sub in a free alternative (Manrope, Space Grotesk, Archivo) with similar character

I recommend **(B)** for the migration — DESIGN.md's Inter/Basier split is subtle and the rest of the aesthetic carries the identity. Can upgrade to real Basier later.

### @theme additions

```css
@theme inline {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "Inconsolata", ui-monospace, "Courier New", monospace;
  --font-display: "Inter", ui-sans-serif, system-ui, sans-serif;  /* weight 900 usage */
}
```

### Tracking / weights

Audit component library (shadcn-like `components/ui/`) for heading weights and letter-spacing. Specifically:
- Button text: 600–700 weight
- Section overlines: uppercase + `tracking-[0.1em]` (≈ 1.4px at 14px font)
- Display heading: `text-6xl md:text-8xl font-black` (96px at weight 900)

---

## 5. Light mode derivation

DESIGN.md is dark-only by policy ("Don't use light/white backgrounds anywhere"). But the user explicitly asked for a light mode. I propose treating light mode as a **legibility alternative**, not a brand statement — it preserves accessibility without claiming design parity with the dark mode.

### Design principles for the light variant

1. **Neon Volt is downranked.** On white, `#faff69` is invisible. In light mode, volt is reserved for **border highlights and active states** — never backgrounds, never text. The primary chromatic accent rotates to **Forest Green (`#166534`)**, which DESIGN.md already treats as a primary CTA color.
2. **Canvas is near-white, not pure white.** Pure `#ffffff` is harsh; `#fafafa` gives the eye something to hold. Matches "paper on desk" affordance.
3. **Charcoal inverts to silver.** Border/divider workhorse becomes `rgba(20,20,20,0.12)` — faint, functional, same role.
4. **Text hierarchy inverts.** Primary text `#0a0a0a`, secondary `#6b6b6b` (a light-mode counterpart to DESIGN.md's Silver `#a0a0a0`).
5. **Sharp geometry stays.** Radius, fonts, weights, borders — identical. Only hue flips.

### Light mode token values

| Token | Value | Rationale |
|---|---|---|
| `--background` | `#fafafa` | Near-white canvas |
| `--foreground` | `#0a0a0a` | Near-black text |
| `--card` | `#ffffff` | Pure white cards sit above canvas |
| `--card-foreground` | `#0a0a0a` | — |
| `--popover` | `#ffffff` | — |
| `--popover-foreground` | `#0a0a0a` | — |
| `--primary` | `#166534` (**forest**) | In light mode, the CTA accent is forest green — volt is too unreadable |
| `--primary-foreground` | `#ffffff` | White on forest |
| `--secondary` | `#f1f5f1` | Very pale forest tint for secondary surfaces |
| `--secondary-foreground` | `#0a0a0a` | — |
| `--muted` | `#f4f4f5` | Pale gray for muted surfaces |
| `--muted-foreground` | `#6b6b6b` | "Light silver" — readable but clearly subordinate |
| `--accent` | `#fafff0` | Very faint volt tint for highlighted surfaces |
| `--accent-foreground` | `#4f5100` | Dark olive text (volt-family) on the pale volt surface |
| `--destructive` | `#dc2626` | Readable red on white |
| `--destructive-foreground` | `#ffffff` | — |
| `--border` | `rgba(20,20,20,0.12)` | Inverted charcoal — workhorse |
| `--input` | `#ffffff` | — |
| `--ring` | `#166534` | Focus ring matches primary (forest) |
| `--volt` | `#4f5100` | **In light mode, `--volt` resolves to the dark olive** (DESIGN.md's "Border Olive") so any component that references it directly stays readable |
| `--volt-pale` | `#8a8c00` | Mid-tone olive for active states |
| `--volt-border` | `#4f5100` | Same as current DESIGN.md spec |
| `--forest` | `#166534` | Unchanged — forest reads on both backgrounds |
| `--forest-dark` | `#14572f` | Unchanged |
| `--near-black` | `#0a0a0a` | Repurposed as the darkest text color |
| `--hover-gray` | `#e4e4e7` | Light hover background |
| `--silver` | `#6b6b6b` | Darker silver for light-mode legibility |
| `--charcoal-border` | `rgba(20,20,20,0.12)` | Inverted |
| `--charcoal-divider` | `rgba(20,20,20,0.08)` | Even fainter |
| `--sidebar` | `#ffffff` | — |
| `--sidebar-foreground` | `#6b6b6b` | Muted nav labels |
| `--sidebar-primary` | `#166534` | Active nav = forest |
| `--sidebar-primary-foreground` | `#ffffff` | — |
| `--sidebar-accent` | `#f4f4f5` | Hover bg |
| `--sidebar-accent-foreground` | `#0a0a0a` | — |
| `--sidebar-border` | `rgba(20,20,20,0.12)` | — |
| `--sidebar-ring` | `#166534` | — |

### Trade-offs of this approach

- **Pro:** Preserves DESIGN.md's dual-accent system (volt + forest) by promoting forest when volt can't perform.
- **Pro:** Sharp geometry and charcoal border identity carry across modes.
- **Con:** Light mode is objectively weaker brand-wise than dark — the neon-on-black drama is gone.
- **Con:** Components that rely on volt as their primary affordance (e.g., "click me, I'm the CTA") look different in light mode.
- **Con:** If Nexus is meant to be a cockpit, a light mode fundamentally undermines the atmosphere. The honest answer might be: don't ship a light mode.

**User decision required:** do I ship this light mode, drop light mode entirely, or iterate on the palette?

---

## 6. Raw Tailwind color utility remapping

The scan found **~274 instances** of raw color utilities (`bg-red-500`, `text-amber-600`, etc.) that bypass the theme-token system. These need manual remapping.

### Semantic categories and their new homes

| Use case | Current classes | New strategy |
|---|---|---|
| **Error / destructive** (`bg-red-*`, `text-red-*`) | 74 instances | → `bg-destructive`, `text-destructive` (theme tokens) |
| **Warning / pending** (`bg-amber-*`, `text-amber-*`, `bg-yellow-*`) | 70 instances | → New token `--warning` (proposed: `#f59e0b` dark, `#b45309` light), then `bg-warning`, `text-warning` |
| **Success / completed** (`bg-green-*`, `text-green-*`, `bg-emerald-*`) | 34 instances | → New token `--success` = `#166534` (matches forest); `bg-success` |
| **Info / in-progress** (`bg-blue-*`, `text-blue-*`, `bg-cyan-*`, `bg-sky-*`) | 63 instances | → `text-muted-foreground` or a new `--info` token = `#a0a0a0` (silver) in dark mode |
| **Role / agent hues** (violet, pink, teal, orange, indigo, rose) | ~14 instances | **These are the hardest**. In DESIGN.md's palette, everything non-volt/non-forest is neutral. Options: (a) collapse all role colors into silver/volt/forest variations, losing per-role distinction; (b) introduce a small "chart palette" of low-saturation grays and use pattern/icon differentiation instead of hue; (c) keep a small named-role palette as an exception. I lean toward **(a)** — use volt for the primary role, silver for the rest, rely on labels/icons for identity. |
| **Status/neutral** (`bg-neutral-*`, `bg-zinc-*`, `bg-slate-*`, `bg-gray-*`) | 24 instances | → `bg-muted`, `text-muted-foreground` |

**Impact on `lib/status-colors.ts` and `lib/agent-role-colors.ts`:**

These files are the primary home for the ~100 palette mappings. They define the source-of-truth dictionaries that most raw-utility usage pulls from. Rewriting these two files gets us ~60% of the raw-utility work done.

I'll draft the replacement dictionaries in Phase 2 (see Section 8) — that rewrite is the single biggest file-level change in the migration.

---

## 7. File-by-file scope

### Must change (foundation — Phase 1)

| File | Lines of change | Why |
|---|---|---|
| `ui/src/index.css` | ~300 → ~250 (rewrite theme blocks, hljs, scrollbars) | All token values, all three theme variants → two modes, new hljs palette |
| `ui/src/lib/status-colors.ts` | Full rewrite | ~30 status → color mappings need new palette |
| `ui/src/lib/agent-role-colors.ts` | Full rewrite | ~15 role → color mappings |
| `ui/src/context/ThemeContext.tsx` | Simplify | Drop `"custom"` theme type, drop Catppuccin/Tokyo cycle, keep light/dark binary |
| `ui/src/components/Layout.tsx` | ~10 lines | Drop theme cycle map (lines 66–72), simplify toggle |

### Should change (sweep — Phase 2)

Files with raw palette utilities, ordered by instance count (high-impact first). From the scan I'd need to enumerate these precisely in the execution phase, but the top offenders are predictable:

- Any "status pill" / "priority badge" / "agent role avatar" component — where most of the 274 raw utilities live
- `pages/OrgChart.tsx` — 6 hardcoded hex status colors + raw palette usage
- `pages/Inbox.tsx` — `#64748b` fallback + raw classes
- `pages/Routines.tsx` — `#64748b` fallback × 3
- `pages/CompanySettings.tsx`, `pages/ContentStudio.tsx` — brand color defaults
- `components/NewIssueDialog.tsx` — `#6366f1` project color fallback × 2
- `components/MarkdownEditor.tsx` — `#64748b` fallback
- `components/VoiceWaveform.tsx` — hardcoded `#89b4fa` (needs to become `var(--primary)` or `--volt`)
- `components/ThemePreviewPanel.tsx` — 12 hardcoded hexes (this file IS the theme preview; needs full rewrite against new palette)
- `components/ThemePaletteGrid.tsx` — Catppuccin green references

**Complete file list to be produced during Phase 2 execution** via a precise `rg '(bg|text|border|ring)-(red|blue|green|amber|yellow|cyan|violet|pink|slate|zinc|neutral|sky|teal|emerald|indigo|rose|orange)-' ui/src` with per-file counts.

### May change (audit — Phase 3)

- Typography usages: any `text-*xl`, `font-bold` etc. needing bump to `font-black` for display moments
- Radius audits: `rounded-2xl`, `rounded-3xl` need to come down to `rounded-lg` (8px) or `rounded-sm` (4px)
- Shadow audits: replace soft shadows with border-based elevation or inset "pressed" effects for active states

### Do NOT change

- `.planning/`, `doc/`, `docs/`, test fixtures, snapshots
- `packages/branding/` — has no colors, just vocabulary
- Test files that assert current palette (note: `ThemePreviewPanel.test.tsx` has snapshot tests that will need updating, but snapshot updates are mechanical, not design work)

---

## 8. Migration sequence

Ordered phases. Each phase is independently committable and reviewable.

### Phase 1 — Foundation (single commit)
**What:** Rewrite `ui/src/index.css` `@theme` block and all three theme selectors. Load new fonts. Simplify `ThemeContext.tsx` + `Layout.tsx` theme cycle.

**Goal:** After this phase, the app's ~1,250 theme-token class usages visually switch to the new palette with zero per-file edits. Raw utilities and hardcoded hexes will still look wrong — that's Phase 2.

**Deliverables:**
- New `ui/src/index.css` (rewritten theme blocks + font-face declarations)
- Fonts in `ui/public/fonts/` (woff2 Inter + Inconsolata)
- Simplified `ThemeContext.tsx` (binary light/dark, no Catppuccin/Tokyo)
- Simplified `Layout.tsx` theme toggle button

**Verification:** load any authenticated page, visually confirm black canvas + volt accents on borders and CTAs. Expect ugly patches where raw utilities still show their old colors — that's expected at this phase.

### Phase 2 — Status / role color rewrite (single commit)
**What:** Rewrite `lib/status-colors.ts` and `lib/agent-role-colors.ts` against the new palette. This cleans up ~60% of the raw-utility usage because those two files are the source of truth for most status/priority/role dictionaries.

**Deliverables:**
- New color dictionaries
- Any components that import from these files get their "wrongness" fixed automatically

**Verification:** inbox, org chart, agent cards all show volt/forest/silver status indicators instead of red/blue/green.

### Phase 3 — Raw utility sweep (one commit per logical component group)
**What:** Per-file cleanup of the remaining raw palette utilities and hardcoded hex fallbacks. Group by feature (dashboard, org chart, inbox, settings) so each commit is reviewable.

**Deliverables:**
- ~60 files touched, 274 utility instances replaced with theme tokens or new semantic tokens (`bg-warning`, `bg-success`, etc.)
- ~65 hardcoded hex fallbacks replaced with `var(--token)` refs or `text-muted-foreground` equivalents

**Verification:** grep for raw palette utilities — should be zero matches (or only well-justified exceptions). Visual regression via manual QA of each touched page.

### Phase 4 — Typography + radius audit (single commit)
**What:** Bump heading weights to 900 for display moments, enforce radius scale (4px/8px/9999px only), replace soft shadows with border-based depth.

**Deliverables:**
- Hero/landing pages use display typography
- `rounded-2xl`/`rounded-3xl` collapsed to `rounded-lg` or `rounded-sm`
- Soft `shadow-md`/`shadow-lg` replaced with `border` + inset shadows for active states

**Verification:** visual compliance with DESIGN.md §3-§6 on representative pages.

### Phase 5 — ThemePreviewPanel rewrite (single commit)
**What:** The theme preview / palette grid components currently showcase Catppuccin. They need a complete rewrite to preview the new system.

**Deliverables:**
- `ThemePreviewPanel.tsx` showing new palette
- `ThemePaletteGrid.tsx` or deprecation (if the grid no longer makes sense in a binary-mode system)

### Phase 6 — hljs syntax highlighting (single commit)
**What:** Replace the three Catppuccin/Tokyo hljs rule sets in `index.css` with a single DESIGN.md-compliant rule set: neon and white on dark, terminal aesthetic per §4.

**Deliverables:**
- `.hljs-*` rules rewritten in `index.css`
- Light mode hljs variant derived

### Phase 7 — Visual QA pass
**What:** Walk every top-level route, compare against DESIGN.md principles, capture screenshots for before/after, file any remaining issues. No code changes unless issues found.

---

## 8b. Structural overhaul phases (8–16) — see layout spec

Phases 1–7 above are a **visual repaint** of the existing structure. They do not change layout, navigation, information architecture, or what each page does.

A separate, larger overhaul to the layout and IA was approved 2026-04-11 and is captured in **`docs/specs/2026-04-11-nexus-layout-overhaul.md`**. That spec defines phases 8–16, summarized here:

| Phase | Title | Wave |
|---|---|---|
| 8 | Frame skeleton (56px icon rail, 48px top strip, kill ChatPanel/PropertiesPanel/sidebar) | 1 (alone, foundational) |
| 9 | Assistant mode (full-bleed chat at `/assistant`, History/Memory slide-overs, conversational home state) | 2 (parallel) |
| 10 | Studio mode (8-card workshop grid, fold ConvertPage in, freeform prompt) | 2 (parallel) |
| 11 | Projects + Builder mode (hero-stat cards, 7-tab Builder strip, demote 9 global routes to per-project tabs) | 2 (parallel) |
| 12 | Promote-to-project transition (700ms compress + rise animation with inset shadow ripple) | 3 (parallel) |
| 13 | Settings consolidation (single-column, Skills + Routines sections, drop nested settings routes) | 3 (parallel) |
| 14 | Voice + ⌘K globalization (mic in top header, voice queues to Assistant inbox, universal command palette) | 3 (parallel) |
| 15 | Mobile parity (bottom tab bar, project sub-tab strip, mobile takeovers for slide-overs) | 3 (parallel) |
| 16 | Cleanup pass (vocabulary sweep, dead-code removal, visual QA) | 4 (alone, sequential) |

The dispatch pattern for phases 8–16 is documented in §11 below.

**Phases 1–7 are independent of phases 8–16 and can ship first.** The overhaul does not block visual QA — and conversely, the visual repaint produces tokens that the overhaul phases consume. Phases 8–16 should not begin until phase 4 (typography + radius audit) is at minimum committed, because the new frame relies on the locked-in radius scale and font weights.

---

## 9. Risks and decisions

### Decisions required from you before Phase 1

1. **Light mode**: ship the derived palette (Section 5), drop it entirely, or iterate on my draft?
2. **Basier font**: license it, use Inter everywhere, or pick a free alternative?
3. **Destructive color**: DESIGN.md doesn't specify a red. I propose `#ef4444` (muted). Confirm or pick.
4. **Role hue collapse vs. preserve**: for agent roles / chart series, do we accept a silver-only palette with pattern differentiation, or keep a small named-role palette as a controlled exception?
5. **Display weight 900**: adopt for hero/landing moments, or skip the 96px Inter Black treatment?
6. **Theme toggle UX**: if we drop Tokyo Night, is the toggle still light ↔ dark, or do we simplify further (e.g., single dark mode, light is an accessibility fallback only)?
7. **Tokyo Night removal**: the `.theme-tokyo-night.dark` block in `index.css` is dead code (never applied by ThemeContext). Confirm I should delete it.

### Risks

- **Visual regression**: ~1,250 token-using elements will all shift on Phase 1. Expect surprise — Catppuccin is cozy and Nexus users may not be ready for cockpit-level contrast. Worth previewing on a throwaway branch.
- **Accessibility**: volt on black (`#faff69` on `#000000`) passes WCAG AAA for normal text, but volt on white fails for anything smaller than 18pt. That's why light mode downranks volt.
- **Chart/viz readability**: with only 5 semantic chart colors (volt, forest, silver, pale, red), multi-series visualizations get crowded. Consider using the same hue with pattern/opacity differentiation, or accepting the "chart palette" as a documented exception.
- **Catppuccin Mocha nostalgia**: if anyone on the team is attached to the Mocha look, DESIGN.md's aesthetic is going to feel jarring. Socialize early.
- **Component-library components** (`components/ui/*`): these are shadcn-ish primitives. They use theme tokens heavily, which is good — they'll auto-migrate. But any that hardcode radius or shadow styles need individual audit.
- **Onboarding wizard + InviteLanding**: just-touched files using the current palette. They'll shift visually in Phase 1 — worth a dedicated visual review since they're the first thing a new user sees.
- **Font loading flash**: adding web fonts for the first time introduces FOUT/FOIT. Use `font-display: swap` and preload the most critical weights (Inter 400, 700, 900).

### Out of scope (for this migration)

- Custom user themes (the current `"custom"` theme type is seldom used; I propose dropping it)
- Per-company branding overrides (covered by separate `worktree-branding.ts` system — untouched)
- Print styles
- High-contrast accessibility mode beyond normal WCAG

---

## 10. Open questions for the user

Answer these and I'll kick off Phase 1:

1. Light mode: **ship / drop / iterate**?
2. Fonts: **license Basier / Inter only / free alternative (name one)**?
3. Destructive red: **`#ef4444` / other (specify)**?
4. Role hues: **collapse to silver / keep small named palette / something else**?
5. Display 900: **adopt / skip**?
6. Theme toggle: **binary light/dark / dark only**?
7. Tokyo Night dead code: **delete / keep as future option**?

Once answered, I'll update this file with the resolved decisions and begin Phase 1 on a separate branch.

---

## 11. Subagent dispatch pattern (binding for phases 8–16)

**Directive from user 2026-04-11:** structural overhaul phases (8–16) MUST be implemented by dispatching subagents in parallel for any work that does not share files. Sequential implementation is wrong for work of this size. The implementation plan derived from `docs/specs/2026-04-11-nexus-layout-overhaul.md` will spell out the dispatch waves; this section is the standing rule.

**Pattern:**

1. **Read the spec** before each wave. The spec (`docs/specs/2026-04-11-nexus-layout-overhaul.md`) is the source of truth for what to build. Don't infer from the code.
2. **Group phases into waves** based on file overlap. Phases that touch disjoint files run in parallel. Phases that share files (or where one builds on another's output) run sequentially.
3. **Dispatch one subagent per phase per wave**, in a single message with multiple Agent tool calls. Each subagent gets:
   - The phase number and title
   - The relevant section(s) of the spec verbatim
   - The specific files it owns (so two subagents in the same wave never touch the same file)
   - The atomic-commit requirement (one phase = one commit)
4. **After each wave**, verify all subagents committed cleanly before dispatching the next wave. If a wave produces conflicts on any file outside its declared ownership, stop and re-plan.
5. **Use the `superpowers:dispatching-parallel-agents` skill** for the actual dispatch. The skill enforces the message structure for parallel tool calls.

**Anti-patterns explicitly forbidden by the user:**
- Doing phases 8–16 sequentially in the main session
- Doing one phase yourself "to get started" and then dispatching the rest
- Dispatching subagents for phases that share files (will produce merge chaos)
- Using subagents for phase 16 cleanup (sequential by design — touches everything)

**Wave structure for the layout overhaul:**

```
Wave 1: [ Phase 8 ]                                  # foundational, alone
Wave 2: [ Phase 9 | Phase 10 | Phase 11 ]            # 3 subagents, parallel
Wave 3: [ Phase 12 | Phase 13 | Phase 14 | Phase 15 ] # 4 subagents, parallel
Wave 4: [ Phase 16 ]                                 # sequential cleanup, alone
```

This is captured here in MIGRATION-PLAN.md (rather than only in the spec) so that any future session opening this branch finds the directive even if it doesn't read the spec.