waggle-os/docs/redesign-warm-hive/BUILD-PLAN.md

Warm-Hive Redesign — Build Plan (DRAFT, pending founder confirmation)

Source design package: docs/design_handoff_waggle_app/ (README.md, SCREENS.md, DESIGN_POV.md, design-files/styles/waggle.css, 19 HTML refs + screenshots). This plan recreates that concept inside the existing apps/web stack (React 19 + TS + Vite + Tailwind 3 + shadcn/ui + React Router 6) — not by pasting the HTML.

Status: proposal. No feature code until the open decisions in §7 are confirmed.

---

1. The concept in one paragraph

A warmer "Hive" identity that fixes five live-product problems: overloaded nav (~18 destinations), engineer-first language, flat 10–13px density, five semantic colors firing at once, and buried differentiators. The fixes: a 5-item calm spine + ⌘K command bar (progressive disclosure), plain labels with the technical term as a mono subtitle, a single honey accent with desaturated status-only semantics, warm graphite ↔ warm paper themes, and "hero moments" for memory / overnight work / coordination. Memory is sold as a trustworthy, editable, accountable asset — the Memory-Trust layer (DESIGN_POV #1, already designed) is the keystone.

---

2. Current state → target gap (grounded in codebase recon)

Area	Current reality (verified)	Target	Gap size
Tailwind	3.4.17, JS config apps/web/tailwind.config.ts (CLAUDE.md's "Tailwind 4" is stale; root has the @tailwindcss/vite plugin but web uses TW3)	n/a — keep TW3, remap token values	none (no migration)
Theme infra	data-theme="light" attribute + localStorage['waggle-theme']; boot in App.tsx, toggle in SettingsApp.tsx, reactivity via MutationObserver in AppShell.tsx + useIsLightTheme.ts. next-themes installed but unused.	A real ThemeProvider owning data-theme + persistence + system pref	medium (consolidate scattered logic; infra already matches design's [data-theme] selector)
Tokens	hive-grays (12) + honey (7) + status (5) + KG colors; cooler palette (--hive-950:#08090c, --honey-500:#e5a000). shadcn core in HSL.	warm Hive set from waggle.css (--bg:#14110b, --honey:#e9a52c, desaturated semantics, +wash/line/glow, r-sm..r-xl, 4 shadows)	medium (values swap + add missing tokens)
Fonts	Space Grotesk (display) + DM Sans (body) + JetBrains Mono	Hanken Grotesk (display+body) + JetBrains Mono	small
UI lib	shadcn/ui fully installed — components.json, 57 ui/ components, cn(), CVA, Radix, lucide, framer-motion, sonner, cmdk. (base-ui at root but unused.)	same — style shadcn primitives to the tokens	none (design's shadcn assumption holds)
Shell	AppShell.tsx w-52 left nav rendering the full 5-zone tree (Work/Intelligence/Extend/Team/System, ~18 destinations) via dock-tiers.ts	5-item spine (Home, Chat, Memory, Agents & tasks, Library) + workspace switcher + user row; everything else → ⌘K	large (IA collapse)
⌘K	CommandCenter.tsx exists — cmdk, Ctrl/Cmd-K, 6 verb groups, backend search	regroup to Jump to / Do / Power tools, plain-name + mono subtitle, first-result auto-select, Pro "★ Pinned" group	medium (rework existing)
Routing	React Router 6.30, ~28 routes under AppShell layout, routeFor(appId, ctx)	unchanged; spine items map onto existing routes	none

Net: the plumbing is in great shape (data-theme strategy, shadcn, cmdk, routing all align with the design). The real work is (a) a faithful token + font swap, (b) a ThemeProvider to replace ad-hoc DOM code, (c) collapsing the visible nav to 5 + ⌘K, then (d) rebuilding screens to the specs.

---

3. Token mapping (PR1) — waggle.css → apps/web

Strategy: make the design's named tokens the source of truth in index.css (:root dark + :root[data-theme="light"] light), set to the exact hex from waggle.css, then point the shadcn HSL core tokens and the existing hive/honey scales at those warm values so the 57 themed components restyle automatically.

3.1 Named tokens (verbatim from waggle.css §7) — add to index.css

• Surfaces: --bg --bg-2 --surface --surface-2 --surface-3
• Lines: --line --line-soft --line-strong
• Text: --text --text-2 --text-muted --text-dim
• Honey: --honey --honey-bright --honey-deep --honey-wash --honey-line --honey-glow
• Semantics: --work --intel --healthy --attention --risk + each *-wash
• Shadows: --shadow-sm --shadow --shadow-lg --shadow-pop (warm light variants)
• Radii: --r-sm:8 --r:12 --r-lg:18 --r-xl:26; pills/toggles 999px
• Type: --sans (Hanken Grotesk) · --mono (JetBrains Mono) · --serif: var(--sans)

3.2 shadcn HSL core → derive from warm palette (recolor)

Convert warm hex → HSL channels (e.g. --bg #14110b → --background: 40 29% 6%): --background←--bg · --foreground←--text · --card/--popover←--surface · --secondary/--accent/--muted (surface)←--surface-2 · --muted-foreground←--text-muted · --border/--input←--line · --ring←--honey · --primary←--honey with --primary-foreground:#1a1407 · --destructive←--risk. Keep the existing hive-*/honey-* Tailwind scales but recolor their CSS vars to the warm steps.

3.3 Fonts

Swap the Google Fonts @import to Hanken Grotesk (300–800) + JetBrains Mono (400–600); set body/--font-sans to Hanken, h1–h6 display to Hanken 600 (-0.02..-0.03em), keep --font-mono. (Self-host in the Tauri/Platform pass for offline — follow-up.)

3.4 Utilities (port into waggle-theme.css, reconcile with existing)

.hex clip-path (reconcile with existing .hex-avatar) · .comb honeycomb data-URI · .dot-live + @keyframes breathe (reconcile with existing honey-pulse) · :focus-visible honey outline · ::selection honey · warm scrollbar · .pill .kbd.

3.5 PR1 verification

tsc -p apps/web/tsconfig.app.json 0 errors · npm run test (FE) green · npm run lint clean · visual smoke: dark default + light toggle on Home/Chat/Settings, no contrast regressions (re-run light-mode-tokens.test.ts).

---

4. Theme provider (PR1)

New apps/web/src/providers/ThemeProvider.tsx: context owning 'dark' | 'light' | 'system', writes data-theme + localStorage['waggle-theme'], subscribes to matchMedia('(prefers-color-scheme)') when system, honors prefers-reduced-motion for entrance gating. Exposes useTheme(). Refactor: remove the boot snippet in App.tsx, the toggle logic in SettingsApp.tsx, and re-back useIsLightTheme() with the context (keep its signature). Recommend a small custom context over next-themes (Vite SPA, not Next; keeps the exact data-theme contract the design's CSS already targets).

---

5. App shell — 5-item spine + ⌘K (PR2)

5.1 Sidebar (ia.html)

Replace the zone-tree render in AppShell.tsx:272–303 with: workspace switcher pill (hex + name + chevron) → 5 nav items with honey active state (left honey bar + --honey-wash) → "Everything else" ⌘K tile → spacer → user row (avatar + name → Settings). Spine → routes:

Spine item	Route (initial)	Later combined surface
Home	/home	—
Chat	active workspace chat routeFor('chat', ctx) → /workspaces/:id/chat (fallback /home)	—
Memory	/memory	+ per-workspace Memory tab
Agents & tasks [badge]	/agents (badge = pending approvals)	tabs: Agents · Automations · Approvals
Library	/artifacts	tabs: Artifacts · Files · Skills

Everything else (waggle-dance, connectors, MCP, marketplace, launcher, room, vault, mission-control, timeline, usage, team, evolution, benchmark, platform) → ⌘K only. Pro mode (tier-aware toggle) inserts a "Pinned · power tools" group (Agent swarm, Connectors, Approvals). Pro-pinned may be deferred to a PR2 follow-up.

5.2 ⌘K (CommandCenter.tsx rework)

Regroup to Jump to / Do / Power tools; each result = icon + plain name + mono subtitle (technical term) + optional shortcut; first result auto-selected; Pro "★ Pinned · Pro" group prepended in Pro mode. Reuse cmdk + the existing adapter search. Copy patterns from SCREENS §05 ("Run a team of agents · waggle-dance · swarm", "Connect a tool · MCP servers · 21 tools", "Launch a coding agent · Claude Code · Cursor · Codex").

5.3 PR2 verification

tsc/test/lint green · live smoke: every spine item routes; ⌘K opens (Ctrl/Cmd-K), fuzzy filters, arrow/Enter/Esc nav, routes + closes; all hidden destinations reachable from ⌘K; active-state highlight via matchNavRoute.

---

6. Phased roadmap (follows README §12; ship dark first)

PR	Scope	Key files	Screens
PR1	Tokens → TW theme + ThemeProvider + fonts	index.css, tailwind.config.ts, waggle-theme.css, providers/ThemeProvider.tsx, App.tsx, SettingsApp.tsx, useIsLightTheme.ts	(foundation)
PR2	App shell: 5-item sidebar + ⌘K rework	AppShell.tsx, dock-tiers.ts, CommandCenter.tsx	05
PR3	Home (A Editorial) · Chat (B split-canvas) · Workspace (A overview+tabs)	HomeCockpit, ChatWindowInstance, WorkspaceChatApp	01·02·03
PR3.5	Memory-Trust layer (DESIGN_POV #1) — confidence/freshness + forget/correct + stale-review + "why did you do that?" trace	MemoryCenterApp, memory adapter, confidence-badge/evidence-* (exist)	19
PR4	Marketplace + shared install store ("sync") (grid + agent-pick + inline-in-chat)	MarketplaceApp, new install store	09
PR5	Settings (models-first + failover pilot) · Onboarding (6-step + model gate)	SettingsApp, onboarding wizard	11·10
PR6	Remaining surfaces: Launcher · Storage/Files · Power surfaces · App-surfaces sextet · Evolution · Benchmark · Platform · Habit-on-Home	many	06·07·08·16·12·17·18·15·04
PR7	Auth (Clerk themed) · Billing (Stripe themed)	auth, billing	13·14
PR8	apps/www landing (Next.js) — full content + identity	apps/www	Landing

Memory-Trust early (PR3.5): DESIGN_POV says its primitives "should land early because everything else trades on them." Memory is a spine item, so it surfaces in PR2/PR3 anyway — wiring trust right after gives the differentiator a real home before the long tail.

---

7. Open decisions (need founder confirmation before implementing)

1. First-PR scope — split PR1 (tokens + ThemeProvider + fonts) then PR2 (shell + ⌘K) (recommended — tokens land first, lower risk per PR), or one combined PR?
2. IA collapse — confirm reducing the always-visible nav from ~18 → 5-item spine + ⌘K, Settings via user row, power features ⌘K-only (+ optional Pro-pinned). Anything that must stay always-visible beyond the 5?
3. Memory-Trust placement — land early (PR3.5, right after shell) (recommended) or after the core screens?
4. Recommend-and-proceed unless you object: ThemeProvider = small custom context (not next-themes); fonts via Google Fonts now / self-host in Platform pass; keep Tailwind 3.
5. Flag for later (blocks Billing/PR7, not now): DESIGN_POV #4 — who pays for inference (BYO-key vs Waggle-metered). Decide before PR7.

---

8. Notes / discrepancies surfaced (honesty log)

• CLAUDE.md §1 lists Tailwind 4 and base-ui/react; apps/web actually runs Tailwind 3.4.17 and shadcn/ui + Radix (base-ui unused in web). No action — just don't trust those two CLAUDE.md lines for this work.
• next-themes is a dependency but unused; PR1 either adopts or removes it.
• All 19 screen HTMLs + per-screen "ship this variation" notes are in docs/design_handoff_waggle_app/SCREENS.md — consult per PR.

9. PR1 adversarial-review follow-ups (deferred LOW, tracked)

A 17-agent adversarial review of PR1 confirmed 10 findings; 8 were fixed in-PR (1 HIGH light-mode honey-button contrast + WCAG ratchet extension, 1 MEDIUM spine/pinned /approvals double-active collision, duplicate Agents/swarm badge, unbacked ⌘K shortcut hints, platform-aware ⌘K glyph). Two LOW items are deferred to PR3 with rationale:

• Chat spine item, no-workspace state — routeFor('chat') falls back to /home when there's no real workspace, so the clicked Chat item isn't highlighted (Home wins). Semi-intentional: Home is the workspace selector (routes.ts §9.7). PR3 can dim Chat or route it to the workspace switcher when !hasRealActiveWorkspace.
• Sidebar user row userName={null} — renders "Account" + "W" avatar. A real display name exists in the /api/home/briefing contract (HomeBriefing.userName); thread it through when the user-identity surface lands (PR3).