13 KiB
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 existingapps/webstack (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/toggles999px - 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)
- First-PR scope — split PR1 (tokens + ThemeProvider + fonts) then PR2 (shell + ⌘K) (recommended — tokens land first, lower risk per PR), or one combined PR?
- 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?
- Memory-Trust placement — land early (PR3.5, right after shell) (recommended) or after the core screens?
- 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. - 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/webactually 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-themesis 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/homewhen 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/briefingcontract (HomeBriefing.userName); thread it through when the user-identity surface lands (PR3).