17 KiB
Handoff: Waggle — App + Landing Refactor (the "warm Hive" concept)
A complete design concept for refactoring Waggle OS — the persistent-memory, local-first, model-agnostic AI workspace (monorepo:
marolinik/waggle-os, memory substrate:marolinik/hive-mind). This package contains 22 interactive HTML design references plus the design-system stylesheet, and the brief to recreate them in the real codebase.
1. Overview
Waggle is a workspace-native AI agent platform: persistent memory that compounds, model-agnostic orchestration (Claude / GPT / Gemini / local models), a skills + connectors marketplace, a multi-agent "waggle-dance" swarm, and an "AI-OS" launcher that runs external coding agents (Claude Code, Cursor, Codex…) inside a workspace's shared memory. It ships as a Tauri desktop app for Windows + macOS.
This concept is a top-to-bottom redesign addressing five problems found in the live product:
- Overloaded navigation — ~18 always-visible destinations across 5 zones.
- Engineer-first language — "Spawn", "Waggle-Dance", "MCPs", "GEPA".
- Uniform 10–13px density — reads as a control panel, never premium.
- Five semantic colors firing at once over glass + wallpaper + honeycomb.
- Hidden differentiators — memory, overnight work, coordination buried in tallies.
The response is a warmer "Hive" identity, a 5-item spine + ⌘K command bar (progressive disclosure), plain-language labels with the technical term as a subtitle, and legible "hero moments" for the differentiators.
Target users: knowledge workers / operators (non-technical first), without removing any depth power users need.
2. About the design files (READ THIS FIRST)
The files in design-files/ are design references created in HTML — interactive
prototypes that show intended look, layout, copy, and behavior. They are not
production code to copy verbatim.
Your task: recreate these designs inside the existing Waggle codebase
(apps/web is React + TypeScript + Vite + Tailwind + shadcn/ui + React Router;
apps/www is the Next.js marketing site), using its established components,
routing, state, and data layer. Where this concept introduces a new pattern (e.g.
the ⌘K palette, the warm token set), implement it in the codebase's idiom — don't
paste HTML/inline styles.
Two files are the entry points:
Waggle Reimagined.html— the concept narrative + an index that embeds every app screen in an iframe. Open it first; its top nav links to every section.Waggle Landing.html— the redesigned public marketing site (apps/www).
Everything shares one stylesheet: design-files/styles/waggle.css — the source
of truth for tokens (see §7).
3. Fidelity
High-fidelity. Final colors, typography, spacing, radii, shadows, motion, and
copy are all intentional and specified in §7 and the per-screen appendix (§10).
Recreate the UI pixel-faithfully using the codebase's existing libraries — map the
tokens in waggle.css onto the Tailwind theme / CSS variables, then build screens
with shadcn/ui primitives styled to match.
One caveat: the prototypes use vanilla JS for view-switching and the dark/light toggle. That plumbing is demonstration scaffolding — replace it with real React state, React Router routes, and the app's theme provider. The visuals, layout, and interaction design are what to preserve.
4. Information architecture (the spine)
Collapse ~18 destinations into 5 everyday places, with everything else reachable from ⌘K:
| Spine item | Plain label | Maps to existing routes / apps |
|---|---|---|
| Home | Home | /home (HomeCockpit) |
| Chat | Chat | the agent runtime / chat |
| Memory | Memory | /memory + per-workspace Memory tab |
| Agents & tasks | Agents & tasks | /agents + /automations + /approvals |
| Library | Library | /artifacts + /files + /skills |
⌘K command bar holds the full depth, each entry plain-language with the technical term as a subtitle (e.g. "Run a team of agents · waggle-dance · swarm"; "Connect a tool · MCP servers"; "Launch a coding agent · Claude Code · Cursor"). A Pro mode floats a "★ Pinned" group of power tools to the top of ⌘K.
Reference: screens/ia.html (working sidebar + ⌘K + Pro toggle).
5. The screens (what's in this bundle)
22 interactive references. Most use a top segmented control to switch variations or sub-views — that chrome is prototype-only; ship the chosen variation (noted per screen in §10) or wire the others as real routes/states.
| # | File | Screen(s) | Notes |
|---|---|---|---|
| — | Waggle Reimagined.html |
Concept index + narrative | embeds all app screens; coverage map at the end |
| — | Waggle Landing.html |
Marketing site (apps/www) |
hero, BYO-agent, proof (SOTA), self-evolve, personas, pricing, footer |
| 01 | screens/home.html |
Home / Cockpit | ship variation A (Editorial); B/C are alternates |
| 02 | screens/chat.html |
Chat / agent runtime | ship variation B (split work-canvas) as default |
| 03 | screens/workspace.html |
Single workspace | ship variation A (Overview+tabs); Memory stays a tab |
| 04 | screens/workspaces.html |
All-workspaces index | grid + table; storage badges; search/filter |
| 05 | screens/ia.html |
Sidebar + ⌘K command bar | calm spine + Pro-pinned |
| 06 | screens/launcher.html |
Launcher (AI-OS) | external agents share workspace memory |
| 07 | screens/storage.html |
Storage & Files | virtual/local/team model + file browser |
| 08 | screens/surfaces.html |
Power surfaces | Tools · Automations · Approvals · Vault · Usage |
| 09 | screens/marketplace.html |
Marketplace | agent-searchable; shared install state ("sync"); inline-in-chat |
| 10 | screens/onboarding.html |
First-run (6 steps) | includes the required model gate |
| 11 | screens/settings.html |
Settings | progressive disclosure; Models + failover pilot |
| 12 | screens/evolution.html |
Skill evolution + diffusion | the second moat |
| 13 | screens/auth.html |
Auth (Clerk) | sign in/up, OTP verify, SSO |
| 14 | screens/billing.html |
Billing (Stripe) | plans → checkout → success → manage |
| 15 | screens/habit.html |
Engagement / habit loop | streak, compounding, variable reward, nudges |
| 16 | screens/appsurfaces.html |
Agents · Room · Artifacts · Mission Control · Timeline · Profile | six routes, one rail |
| 17 | screens/benchmark.html |
Benchmarks | capability matrix vs competitors + LoCoMo SOTA |
| 18 | screens/platform.html |
Platform & roadmap | Tauri desktop, boot, 404, "coming next" |
Per-screen detail (layout, components, copy, interactions, ship-this-variation) is in §10.
6. Global patterns (apply everywhere)
- App chrome: left sidebar (5 items + workspace switcher + user row), main
column with a
.shead(title + subtitle + primary action) over a scrolling body. Power surfaces and Settings use a secondary left rail inside the main column. - Density & scale: body 16px / 1.55; never below 12px. Section labels are
11px mono, uppercase,
.12emtracking,--text-dim, with a trailing hairline rule. - One accent: honey (
--honey) is used sparingly — primary buttons, active nav, key numbers, focus. Semantics (work/intel/healthy/attention/risk) are desaturated and only for status, never decoration. - Provenance everywhere: any memory/fact/artifact shows a
⬡ source · whenline in mono /--intel. This is a core trust pattern — keep it. - Cards:
--surfacebg,1px solid --line-soft, radius--r-lg(18px), hover →--honey-lineborder +translateY(-2px)+--shadow. - Buttons: primary = honey bg /
#1a1407text; ghost =--surface/--line-strongborder, hover honey border. Radius 9–13px. See §7. - Dark + light: every screen supports both via
[data-theme]. The toggle in the prototypes writeslocalStorage['waggle-concept-theme']; replace with the app theme provider. Both themes are warm (warm graphite ↔ warm paper) — see §7. - Motion: entrances
cubic-bezier(.16,1,.3,1)~.7s, gated so content is visible if JS/print/reduced-motion. Hover transitions .14–.18s. A live "breathing" dot (@keyframes breathe) marks active/live status. Honorprefers-reduced-motion. - Focus:
2px solid --honey,2pxoffset. Keep keyboard access on ⌘K, OTP, forms.
7. Design tokens (source of truth: styles/waggle.css)
Map these onto the codebase's Tailwind theme + CSS variables. Dark is default;
[data-theme="light"] overrides. All radii/type/shadow tokens are theme-independent.
Colors — Dark (default)
--bg: #14110b (app background, warm near-black)
--bg-2: #1a160f (recessed panels, rails)
--surface: #1f1a12 (cards)
--surface-2: #272117 (hover / insets)
--surface-3: #322a1d (chips, icon tiles)
--line: #38301f (default border)
--line-soft: #2a2417 (subtle dividers)
--line-strong: #4a4030 (emphasized border / scrollbar)
--text: #f6f1e4 (primary)
--text-2: #c8bfa9 (secondary)
--text-muted: #948a73 (tertiary / body-muted)
--text-dim: #6b6250 (labels, meta)
Colors — Light ([data-theme="light"])
--bg:#f7f1e4 --bg-2:#f1e9d8 --surface:#fffdf8 --surface-2:#f6efe0 --surface-3:#efe6d2
--line:#e4d8be --line-soft:#ede3cd --line-strong:#d2c3a2
--text:#211b11 --text-2:#5a5140 --text-muted:#847a64 --text-dim:#a99e85
Accent — Honey (the one accent)
Dark: --honey:#e9a52c --honey-bright:#f6c45a --honey-deep:#c07e16
Light: --honey:#b57d12 --honey-bright:#cf932a --honey-deep:#92620a
--honey-wash: rgba(honey, .10) (tinted fills)
--honey-line: rgba(honey, .28) (tinted borders)
--honey-glow: 0 0 0 1px rgba(honey,.25), 0 8px 30px -10px rgba(honey,.35)
On honey buttons, text/icon color is #1a1407.
Semantics (desaturated; status only) — Dark / Light
--work #7aa6d6 / #3f72b0 (tasks, workspaces, blue)
--intel #b196dd / #7d57b8 (memory/intelligence, violet) — also provenance
--healthy #6cb78c / #3c8a5f (complete/healthy, sage)
--attention#e9a52c / #b57d12 (attention/automation = honey)
--risk #db8068 / #c0573c (risk/failure, terracotta)
Each has a matching *-wash at ~.12 alpha for tinted chips/fills.
Typography
--sans: 'Hanken Grotesk', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif
--mono: 'JetBrains Mono', ui-monospace, monospace
--serif: var(--sans) ← display intentionally uses the SAME grotesk (no book-serif)
Display headlines: Hanken Grotesk 600, letter-spacing -0.02 to -0.03em.
- Hero (landing): clamp(40px, 5.6vw, 68px)
- Section H2: clamp(28px, 3.8vw, 44px)
- Screen H1: ~24–28px / 650
Body: 14–16px / 400–550, line-height ~1.55.
Labels/meta: 10–12px JetBrains Mono, uppercase, letter-spacing .10–.14em.
Honey words in headlines are NOT italic — same weight, just --honey color.
Radius / Shadow / Misc
--r-sm:8px --r:12px --r-lg:18px --r-xl:26px (pills/toggles: 999px)
--shadow-sm: 0 1px 2px rgba(0,0,0,.4)
--shadow: 0 4px 24px -8px rgba(0,0,0,.55), 0 1px 2px rgba(0,0,0,.4)
--shadow-lg: 0 24px 60px -20px rgba(0,0,0,.7), 0 2px 8px rgba(0,0,0,.4)
--shadow-pop:0 30px 80px -24px rgba(0,0,0,.8)
(light theme has softer brown-tinted equivalents — see waggle.css)
Hexagon motif: .hex { clip-path: polygon(50% 0,100% 25%,100% 75%,50% 100%,0 75%,0 25%); }
used for the brandmark, agent/workspace avatars, icon tiles.
Honeycomb texture: .comb (inline SVG bg at ~.05 opacity) — very subtle, decorative only.
Live dot: .dot-live → @keyframes breathe (2.4s).
8. Cross-cutting behaviors to implement
- ⌘K command palette (
screens/ia.html): global hotkey (⌘/Ctrl-K) toggles a centered modal; fuzzy filter over grouped commands; arrow/Enter/Esc keyboard nav; groups = Jump to / Do / Power tools; Pro mode prepends a "★ Pinned" group. Each result = plain name + mono subtitle (technical term). Routes to real destinations. - Theme: dark default; persist user choice; both themes are warm. Use the app theme provider, not localStorage scaffolding.
- Marketplace install = one shared state (
screens/marketplace.html): a single install store drives the grid, the agent-suggestion picks, AND the inline-in-chat card — installing anywhere reflects everywhere ("sync"). Type-aware one-click flows: skill = instant Add; connector = "Connect" → auth → token to Vault; MCP = "Enable" tools. Each fires a confirmation toast + updates an "N in this workspace" bar. - Onboarding model gate (
screens/onboarding.html, step 3): the flow cannot reach "first task" without a working model — either a validated provider API key or a detected/running local model. This mirrors the hard requirement that Waggle needs ≥1 working model. The same gate's permanent home is Settings → Models. - Model failover pilot (
screens/settings.html): Primary → Fallback on error → Budget/local model when daily budget hit. Maps to the repo'sdefaultModel / fallbackModel / budgetModel+budgetThreshold / dailyBudget. - Provenance on every memory/artifact/fact (see §6).
- Approvals: agent actions that touch external systems gate on a risk-badged approval card (inline in chat + an Approvals surface). "Always allow for this workspace" is an option.
9. The marketing site (Waggle Landing.html → apps/www)
Full content rewrite + new identity. Sections in order: nav → hero ("Your AI doesn't reset. Your work doesn't either.") → trust band → problem → 6 pillars → how-it-works (3 steps) → Bring-your-own-agent band (launch Claude Code/Cursor/Codex into shared memory) → Proof (LoCoMo SOTA: Waggle 87.66 vs Memori 81.95 / LangMem 78.05 / Mem0 62.47; +5.71pp, p<10⁻⁵; 92.75% single-hop; 100% local) → Self-evolving (skills improve 71→84→91% + diffuse across the hive) → personas (13) → pricing (Solo $0 / Pro $19 / Teams $49-seat + KVARK sovereign) → final CTA → footer. All copy is final; lift it verbatim. Reveal-on-scroll is JS-gated so content is always visible without JS (keep that property for SEO/no-JS).
Numbers come from the real benchmark docs / hive-mind repo. Keep them accurate;
if the public claim must stay conservative until the SOTA PR merges, gate the headline.
10. Per-screen specifications
See SCREENS.md in this folder for the full per-screen breakdown (layout,
components, exact copy, interactions, and which variation to ship).
11. Assets
- No raster assets / no external images. All iconography is inline SVG
(1.7–1.8 stroke, round caps) — reuse the codebase's icon set (e.g. lucide) matched
to these shapes. The brandmark is the letter W in a
.hexclip-path over a honey gradient. The honeycomb texture is an inline SVG data-URI (.combinwaggle.css). - Fonts: Hanken Grotesk + JetBrains Mono (Google Fonts). Self-host in the Tauri app for offline use.
- Competitor / provider names (Stripe, Clerk, Salesforce, Claude, GPT, etc.) are shown as mono text/initials, not logos — swap in real logos per each brand's guidelines if desired.
12. Tech mapping (existing monorepo)
apps/web React + TS + Vite + Tailwind + shadcn/ui + React Router → all app screens
apps/www Next.js marketing site → Waggle Landing.html
apps/browser-ext → roadmap (beta)
packages/* core / memory (hive-mind) / agent runtime / connectors / mcp
Desktop Tauri (Windows + macOS) → screens/platform.html
Auth Clerk → screens/auth.html
Billing Stripe → screens/billing.html
Recommended order: (1) tokens → Tailwind theme + theme provider; (2) app
shell (sidebar + ⌘K); (3) Home, Chat, Workspace; (4) Marketplace + install
store; (5) Settings (models/failover) + Onboarding gate; (6) the remaining
surfaces; (7) Auth + Billing; (8) apps/www landing. Ship dark first.
13. Files in this bundle
design_handoff_waggle_app/
├── README.md ← this file
├── SCREENS.md ← per-screen specifications
├── DESIGN_POV.md ← designer's strategic contributions (incl. the built Trust layer)
├── screenshots/ ← reference captures (1 per screen) + index
│ ├── README.md
│ └── 00–19 *.png
└── design-files/
├── Waggle Reimagined.html ← concept index (open first)
├── Waggle Landing.html ← marketing site
├── styles/waggle.css ← design tokens (source of truth)
└── screens/*.html ← 19 app-screen references
Open design-files/Waggle Reimagined.html in a browser and use its top nav to walk
the whole concept; toggle dark/light with the ☾ button; try ⌘K inside the Navigation
section.