waggle-os/docs/briefs/2026-04-29-ui-ux-component-inventory.md

# Waggle UI/UX Component Inventory — 2026-04-29

**Purpose:** Brief Claude Design (explore + research mode) on the current UI/UX state of Waggle so it can produce a polish pass without re-discovering the surface area.

**Scope:** Read-only scan. No code changes performed. Sources of truth cited at the end so Claude Design can pull primary artifacts directly.

**Reading order for Claude Design:**
1. §1 — Two distinct UI surfaces exist (do not conflate)
2. §2–§3 — Surface inventories (Landing → OS Shell)
3. §4 — Cross-surface design system tokens (single source of truth)
4. §5 — Drift / open issues / polish opportunities
5. §6 — Source artifacts to consume (priority-ranked)

---

## §1. Two distinct UI surfaces

Waggle has two physically separate UI codebases with different chrome paradigms, different tech stacks, and different design maturity. **They share only the design tokens.**

| Surface | Repo path | Purpose | Stack | Maturity |
|---|---|---|---|---|
| **A. Marketing landing** | `D:/Projects/waggle-os/apps/www` | waggle-os.ai marketing site (download CTA, pricing, persona narrative) | Vite + React 19, **pure CSS with custom properties** (no Tailwind in `apps/www` despite v2.3 spec calling for Tailwind 4), `lucide-react` icons | Legacy v0/v1 implementation present; v2.3 spec authored but **not yet generated** (output pending claude.ai/design `ea934a60` paste) |
| **B. OS shell / desktop app** | `D:/Projects/waggle-os/apps/web` | macOS-style desktop inside Tauri 2.0 native window — 25 OS apps + dock + menubar + ⌘K | Vite + React + Tailwind + shadcn/ui (60+ primitives) + `framer-motion` + `lucide-react` | Paradigm correction in flight (DS audit v2 issued 2026-04-23). Chrome scaffolding built; per-app polish needed. Bees confirmed landing-only. |

`apps/web` runs inside the Tauri shell as the desktop app. `apps/www` is the public marketing site. Do not mix patterns between the two.

---

## §2. Surface A — Marketing landing (`apps/www`)

### §2.1 Tech stack — actual

- Entry: `apps/www/src/main.tsx` → `App.tsx`
- Styles: `apps/www/src/styles/globals.css` (96 lines, **pure CSS custom properties**, no Tailwind)
- Components: `apps/www/src/components/*.tsx` (10 files, 1,003 LOC total)
- Tests: `apps/www/__tests__/BrandPersonasCard.test.tsx`
- Data: `apps/www/src/data/personas.ts`

**Drift from spec:** v2.3 brief (`briefs/2026-04-28-claude-design-landing-v2.3-prompt.md` §5) prescribes Tailwind 4 utilities. Reality is inline styles + CSS custom properties. Polish should reconcile (either keep pure CSS for substrate independence, or migrate; do not author against a missing Tailwind config).

### §2.2 Implemented components — current `App.tsx` mount sequence

Order of mount in `apps/www/src/App.tsx`:

| # | Component | File | LOC | Status / notes |
|---|---|---|---|---|
| 1 | `Navbar` | `components/Navbar.tsx` | 77 | Implemented |
| 2 | `Hero` | `components/Hero.tsx` | 50 | Implemented — uses `bee-orchestrator-dark.png` directly in hero (legacy art-direction; v2.3 spec moves bees to footer mark only) |
| 3 | `Features` | `components/Features.tsx` | 58 | Implemented |
| 4 | `CrownJewels` | `components/CrownJewels.tsx` | 93 | Implemented (legacy "Crown Jewels" framing — not in v2.3 spec; likely candidate for replacement by Proof/SOTA band) |
| 5 | `HowItWorks` | `components/HowItWorks.tsx` | 51 | Implemented |
| 6 | `Pricing` | `components/Pricing.tsx` | 134 | Implemented (3-tier or 4-tier — verify against v2.3 4-tier spec: Free/Pro/Teams/Enterprise) |
| 7 | `Enterprise` | `components/Enterprise.tsx` | 34 | Implemented (KVARK bridge) |
| 8 | `BetaSignup` | `components/BetaSignup.tsx` | 62 | Implemented (legacy beta CTA; v2.3 spec removes BetaSignup entirely — Download is the conversion) |
| 9 | `Footer` | `components/Footer.tsx` | 26 | Implemented |

### §2.3 Orphan / unmounted components

| Component | File | LOC | State |
|---|---|---|---|
| `BrandPersonasCard` | `components/BrandPersonasCard.tsx` | **419** | **Implemented but NOT imported into `App.tsx`** — orphan. Has its own test file. Per v1.1 LOCKED wireframe + LOCKED 2026-04-22 personas decisions, this is the canonical 13-bee `6+6+1` personas grid component. Polish target: re-mount in correct slot per v2.3 (4×4 + Coordinator callout — note v2.3 evolved away from 13 bees toward 17 agent personas, see drift in §5). |

### §2.4 Components specified in v2.3 but not yet implemented

Per `briefs/2026-04-28-claude-design-landing-v2.3-prompt.md` §3 + §5, the v2.3 ship version requires these components which do **not** exist in `apps/www/src/components/`:

| Spec'd component | Spec section | Notes |
|---|---|---|
| `<Hero variant="A\|B">` with variant resolver | §3 SECTION 1 | Hero exists but not as variant component; `lib/hero-headline-resolver.ts` not present |
| `<ProofPointsBand>` (5-card elastic grid) | §3 SECTION 2 | Not implemented; replaces `CrownJewels` semantically |
| `<HarvestBand>` (11 logo tiles + 2 sync-mode callouts + feature stripe) | §3 SECTION 3 | Not implemented |
| `<MultiAgentRoom>` (window mockup + persona tiles + message bus + code snippet) | §3 SECTION 4 | Not implemented |
| `<HowItWorks>` 3-step variant | §3 SECTION 5 | Existing `HowItWorks` is 5-step from v1.1 wireframe — v2.3 simplified to 3 steps. Reconciliation needed. |
| `<PersonasGrid>` 4×4 + Coordinator sidebar | §3 SECTION 6 | `BrandPersonasCard` is the closest — but it implements 13-bee `6+6+1` from LOCKED 2026-04-22 IA, not the 4×4+1 agent-personas grid v2.3 ships |
| `<PricingTiers>` 4-tier (Free/Pro/Teams/Enterprise) + billing toggle + collapsible compare | §3 SECTION 7 | `Pricing.tsx` exists; verify tier count + billing toggle implementation |
| `<TrustBand>` (5 trust signals + Egzakta spine + hex-texture bg + MCP one-line) | §3 SECTION 8 | Not implemented |
| `<FinalCTA>` + KVARK bridge | §3 SECTION 9 | Partial via `Enterprise`; not in canonical FinalCTA shape |
| Updated `Footer` 5-column layout | §3 SECTION 10 | Existing 26-LOC `Footer.tsx` likely needs full rebuild |
| `lib/hero-headline-resolver.ts` | §5 | Variant gate for `?p=` / `utm_source` |
| `data/proof-points.ts` | §5 | 5 entries, ordered |
| `data/harvest-adapters.ts` | §5 | 11 entries |
| `data/pricing.ts` | §5 | 4 tiers |
| Event taxonomy (`landing.*` events) | §5 | Stub only required pre-launch |

### §2.5 Design tokens (canonical: `apps/www/src/styles/globals.css`)

This file is the **single source of truth** for landing tokens. Mirror these into Claude Design's token panel before iterating.

```css
:root {
  /* Hive neutral ladder — 12 stops */
  --hive-50:  #f0f2f7;
  --hive-100: #dce0eb;
  --hive-200: #b0b7cc;
  --hive-300: #7d869e;
  --hive-400: #5a6380;
  --hive-500: #3d4560;
  --hive-600: #2a3044;
  --hive-700: #1f2433;
  --hive-800: #171b26;
  --hive-850: #11141c;
  --hive-900: #0c0e14;
  --hive-950: #08090c;   /* canonical dark ground */

  /* Honey accent ladder — 4 stops + 2 glow tokens */
  --honey-300: #fcd34d;
  --honey-400: #f5b731;
  --honey-500: #e5a000;   /* primary CTA fill */
  --honey-600: #b87a00;
  --honey-glow:  rgba(229, 160, 0, 0.12);
  --honey-pulse: rgba(229, 160, 0, 0.06);

  /* Status accents (sparingly) */
  --status-ai:      #a78bfa;   /* violet — synthesis / AI activity */
  --status-healthy: #34d399;   /* mint — done / healthy */

  /* Elevation */
  --shadow-honey:    0 0 24px rgba(229,160,0,0.12), 0 0 4px rgba(229,160,0,0.08);
  --shadow-elevated: 0 4px 16px rgba(0,0,0,0.5),    0 2px 4px rgba(0,0,0,0.3);
}
```

**Typography:**
- Primary: `Inter` (variable), system-ui fallback
- Code: `JetBrains Mono` (per spec; verify in landing — code blocks rare on landing)
- Anti-aliasing: `-webkit-font-smoothing: antialiased`
- Selection color: `rgba(229, 160, 0, 0.3)` on `--hive-50`
- Headline scale per v2.3 spec: hero 48–64px, section 36–48px, subhead 24–32px
- Body: 16–18px, caption 14px
- Letter-spacing on display: `-0.02em`

**Motion utilities (defined in `globals.css`):**
- `@keyframes float` — translateY ±8px, 3s ease-in-out infinite
- `@keyframes honey-pulse` — opacity 0.4↔0.8 + scale 1↔1.05, 3s
- `@keyframes card-enter` — opacity + 20px translateY, 0.6s ease-out
- Stagger classes: `.card-enter-1` through `.card-enter-4` (0.1s steps)
- Hover affordance: `.card-lift` (translateY -2px + shadow-honey + honey-500 border)
- Active feedback: `.btn-press` (scale 0.97)
- Background: `.honeycomb-bg` — inline SVG hex pattern at `#1f2433` 15% opacity

**Breakpoints (per v1.1 wireframe spec):** `sm` 640 / `md` 768 / `lg` 1024 / `xl` 1280. Desktop-first; every section must collapse cleanly at `sm`.

### §2.6 Brand assets

| Asset | Location | Usage rules (v2.3 LOCKED) |
|---|---|---|
| `waggle-logo.svg` | `apps/www/public/brand/` | Header + footer ONLY |
| 13 × `bee-*-dark.png` (orchestrator, hunter, researcher, analyst, connector, architect, builder, writer, marketer, team, celebrating, confused, sleeping) | `apps/www/public/brand/` + reference copies in `D:/Projects/PM-Waggle-OS/_generated/bee-assets/` | **Landing-restricted.** v2.3 says: NOT in primary sections; reserved for loading skeletons, 404 page, and optional small monochrome footer mark. Do NOT inject into OS shell chrome. |
| `hex-texture-dark.png` honeycomb pattern | `apps/www/public/brand/` | Trust band background ONLY at 8–12% opacity, soft-light blend (per v2.3 §3 SECTION 8) |
| `bee-builder-dark-v1.png` + 2k variant | `_generated/bee-assets/` | Reference renders; latest builder-bee from 2026-04-21 regen |

**Conflict to resolve:** current `Hero.tsx` mounts `bee-orchestrator-dark.png` at 176×176 in hero center — directly contradicts v2.3 anti-pattern. Polish pass should remove or relocate.

### §2.7 Anti-patterns (v2.3 binding — surface to Claude Design)

Generation will fail pre-launch review if any of these are present. Pulling the most polish-relevant entries:

- NO blue accent — locked palette is honey + violet + mint
- NO LoCoMo / Opus / SOTA performance numbers (held until benchmark publishes)
- NO competitor names (Cowork, Mem0, Letta, Notion AI, Cursor as competitor, etc.)
- NO bee mascot grid as primary section; bees footer-mark only on landing
- NO "mind" as user-facing vocabulary — use "memory" or "knowledge graph"
- NO "cognitive layer" jargon in first 3 scroll viewports
- NO trust-logos carousel, NO CEO quote carousel, NO feature-icon grid
- NO scroll-triggered storytelling motion — hover micro-interactions only
- NO 5+ tier pricing — exactly 4 tiers (Free / Pro / Teams / Enterprise)
- NO `github.com` URL until repo migrates to egzakta org

Full list: `briefs/2026-04-28-claude-design-landing-v2.3-prompt.md` §4 (correctness, voice, hygiene tiers).

---

## §3. Surface B — OS shell / desktop app (`apps/web`)

### §3.1 Tech stack — actual

- Entry: `apps/web/src/main.tsx` → `App.tsx` → `pages/Index.tsx`
- Tailwind: `apps/web/tailwind.config.ts` (configured)
- shadcn/ui: 60+ primitives in `apps/web/src/components/ui/`
- Animation: `framer-motion`
- Icons: `lucide-react`
- State: hooks pattern (`hooks/useWindowManager`, `useWaggleDance`, `useKnowledgeGraph`, `useOnboarding`, etc.)
- Adapter: `lib/adapter.ts` (Tauri ↔ web stub)

### §3.2 Chrome layer (`apps/web/src/components/os/`)

These define the macOS-paradigm shell that wraps every app window.

| Component | File | Role |
|---|---|---|
| `Desktop` | `Desktop.tsx` (497 LOC) | Top-level shell — wallpaper, window manager host, app config map, overlay coordination, status bar focus |
| `Dock` | `Dock.tsx` (170 LOC) | Tier-aware dock with zone-based trays (`getDockForTier(tier, billingTier)`) — handles open/minimized indicators, escape-to-close, dock labels (`useDockLabels`) |
| `DockTray` | `DockTray.tsx` | Tray panel that pops out from a dock zone |
| `AppWindow` | `AppWindow.tsx` | Draggable / resizable / minimize / maximize panel — traffic-light controls per macOS convention |
| `StatusBar` | `StatusBar.tsx` | Top bar — status cluster (provider pill, cost meter, policy indicator, clock, ⌘K trigger) |
| `BootScreen` | `BootScreen.tsx` | Tauri cold-boot splash |
| `ContextMenu` | `ContextMenu.tsx` | Right-click menus on dock + windows |
| `ErrorBoundary` | `ErrorBoundary.tsx` | Per-app crash containment |
| `LockedFeature` | `LockedFeature.tsx` | Tier-gate stub |
| `ModelSelector` / `ModelPilotCard` | `ModelSelector.tsx` / `ModelPilotCard.tsx` | LLM provider pickers |
| `WorkspaceBriefing` | `WorkspaceBriefing.tsx` | Workspace landing card |

**Wallpaper:** `apps/web/src/assets/wallpaper.jpg` (dark) + `wallpaper-light.jpg` — desktop-background brand-defining surface (DS audit v2 calls for 25–35% honeycomb texture overlay; verify current opacity).

**Logo asset:** `apps/web/src/assets/waggle-logo.jpeg` (dark) + `.png` (light).

### §3.3 OS Apps (25 implemented in `apps/web/src/components/os/apps/`)

The DS audit v2 references "24 OS Apps" per `docs/WAGGLE-SYSTEM-VISUAL.html:684`. Current count is **25 app components**:

| # | Component file | Likely app id | Per DS-audit MVP first-launch dock? |
|---|---|---|---|
| 1 | `ChatApp.tsx` + `ChatWindowInstance.tsx` | chat | ✅ |
| 2 | `DashboardApp.tsx` | dashboard | (Cockpit superset) |
| 3 | `CockpitApp.tsx` | cockpit | ✅ |
| 4 | `MemoryApp.tsx` | memory | ✅ |
| 5 | `AgentsApp.tsx` | agents | ✅ |
| 6 | `RoomApp.tsx` | room (multi-agent) | ✅ (likely) |
| 7 | `WaggleDanceApp.tsx` | waggle-dance | ✅ (likely) |
| 8 | `MissionControlApp.tsx` | mission-control | (probably gated) |
| 9 | `ConnectorsApp.tsx` | connectors | (Providers superset) |
| 10 | `CapabilitiesApp.tsx` | capabilities | (Skills/policy area) |
| 11 | `MarketplaceApp.tsx` | marketplace | |
| 12 | `FilesApp.tsx` + `FilesAppTabs.tsx` | files | ✅ |
| 13 | `VaultApp.tsx` | vault | |
| 14 | `EventsApp.tsx` | events | |
| 15 | `TimelineApp.tsx` | timeline | |
| 16 | `TelemetryApp.tsx` | telemetry | |
| 17 | `BackupApp.tsx` | backup | |
| 18 | `SettingsApp.tsx` | settings | ✅ |
| 19 | `UserProfileApp.tsx` | user-profile | |
| 20 | `ApprovalsApp.tsx` | approvals | |
| 21 | `ScheduledJobsApp.tsx` | scheduled-jobs | |
| 22 | `TeamGovernanceApp.tsx` | team-governance | (Teams tier) |
| 23 | `VoiceApp.tsx` | voice | |
| (sub) | `agents/`, `chat-blocks/`, `cockpit/`, `connectors/`, `files/`, `memory/` | per-app sub-component folders | — |

**Apps named in DS audit v2 not directly visible as top-level files (likely under sub-folders or pending):** Graph, Provenance, Providers, Policy, Preferences, Wiki, Skills, Scopes, Tasks, Audit, Prompts, Search, Terminal, Notes, Export, About. Polish step: reconcile against `lib/dock-tiers.ts` to confirm canonical AppId set.

### §3.4 Overlays (13 implemented in `apps/web/src/components/os/overlays/`)

System-level layer between windows and ⌘K palette.

| Component | Role |
|---|---|
| `GlobalSearch.tsx` | **⌘K Spotlight equivalent** — launch app, search memory, invoke command. DS audit v2 confirms this survives paradigm shift. |
| `OnboardingWizard.tsx` + `OnboardingTooltips.tsx` + `onboarding/` subfolder | First-run guided tour |
| `LoginBriefing.tsx` | Post-login briefing card |
| `WorkspaceSwitcher.tsx` + `CreateWorkspaceDialog.tsx` | Workspace switcher + creator |
| `PersonaSwitcher.tsx` | Active persona switcher |
| `SpawnAgentDialog.tsx` | Spawn-agent shortcut from dock |
| `NotificationInbox.tsx` | Notification center |
| `KeyboardShortcutsHelp.tsx` | `?` overlay listing shortcuts |
| `ContextRail.tsx` | Side rail for active-app context (knowledge graph, memory frames, etc.) |
| `UpgradeModal.tsx` + `TrialExpiredModal.tsx` | Tier-gate modals |

### §3.5 shadcn/ui primitive library (60 + components in `components/ui/`)

Full shadcn surface installed: `accordion`, `alert`, `alert-dialog`, `aspect-ratio`, `avatar`, `badge`, `breadcrumb`, `button`, `calendar`, `card`, `carousel`, `chart`, `checkbox`, `collapsible`, `command`, `context-menu`, `dialog`, `drawer`, `dropdown-menu`, `form`, `hint-tooltip`, `hover-card`, `input`, `input-otp`, `label`, `menubar`, `navigation-menu`, `pagination`, `popover`, `progress`, `radio-group`, `resizable`, `scroll-area`, `select`, `separator`, `sheet`, `sidebar`, `skeleton`, `slider`, `sonner`, `switch`, `table`, `tabs`, `textarea`, `toast`, `toaster`, `toggle`, `toggle-group`, `tooltip`.

**Polish implication:** the design system primitives are already standardized; the polish pass operates one layer up — composed components, density, state coverage, motion, micro-interactions.

### §3.6 Hooks (state surface visible in `Desktop.tsx`)

`useWorkspaces`, `useMemory`, `useEvents`, `useAgentStatus`, `useNotifications`, `useKeyboardShortcuts`, `useOnboarding`, `useOfflineStatus`, `useKnowledgeGraph`, `useWaggleDance`, `useWindowManager`, `useOverlayState`, `useDockNudge`, `useDockLabels`, `useToast`. Knowing these helps Claude Design design loading / empty / error states with the actual data shapes available.

### §3.7 Paradigm correction status (DS audit v2, 2026-04-23)

Per `briefs/2026-04-23-ds-audit-v2-macOS-paradigm-correction.md`, the previous DS mockup (left HIVE/SCOPES/SETTINGS sidebar + central Memories canvas) was diagnosed as Linear/Notion SaaS dashboard, not OS. The correction calls for:

| Paradigm element | Required state | Implementation evidence |
|---|---|---|
| Menubar (top, fixed) | Logo + system menus + status cluster + ⌘K | `StatusBar.tsx` exists; verify menu items wired |
| Dock (24 apps) | Hover tooltip, running-app indicator, magnification, separators | `Dock.tsx` + `DockTray.tsx` present, tier-filtered via `dock-tiers.ts` |
| App windows | Draggable / resizable / minimize / maximize, traffic-lights left, multi-window z-order | `AppWindow.tsx` present; `useWindowManager` hook live |
| Desktop background | Honeycomb texture **25–35%** overlay/soft-light (brand-defining canvas) | `wallpaper.jpg` present; **opacity verification needed** |
| ⌘K palette | Modal layer above windows, launch app / search memory / invoke command | `GlobalSearch.tsx` overlay present |
| Overlays layer | Between windows and palette: OnboardingWizard, modals, toasts, alerts | 13 overlays implemented |

Texture opacity ramp (DS audit v2 §"Honeycomb texture"): Desktop BG 25–35% / Window BG 4–8% / Empty states 15–20% / Menubar+Dock chrome 0–3%. **Polish target — verify and tune.**

**Reserved bee usage in OS shell:** loading skeletons, 404 page, optional small footer brand mark. Bees never decorate app chrome.

---

## §4. Cross-surface design system

Both surfaces share **only** the token vocabulary. They diverge on chrome paradigm.

### §4.1 Color (locked palette)

- Ground: `--hive-950` `#08090c` (dark-first locked across both surfaces; light mode is v3 stretch)
- Accent: honey 400/500/600 (CTA, focus rings, brand emphasis)
- Status: violet `#a78bfa` (AI activity, synthesis pulse) + mint `#34d399` (healthy, done state)
- **No blue** — explicit anti-pattern
- Hex texture: `#1f2433` at 15% opacity in `.honeycomb-bg` SVG

### §4.2 Typography
- Display + body: `Inter` variable (400–700)
- Monospace: `JetBrains Mono` (code blocks, tool names, file paths)
- Headline scale: 48–64 hero / 36–48 section / 24–32 subhead
- Body: 16–18 / caption 14
- Letter-spacing on display: `-0.02em`

### §4.3 Motion
- Hover micro-interactions only (no scroll-triggered storytelling per v2.3 anti-pattern)
- `prefers-reduced-motion: reduce` mandatory on hero MPEG-4 loop
- Easing: ease-out for entrances, ease-in-out for loops

### §4.4 Iconography
- Primary library: `lucide-react` (used in both `apps/www` and `apps/web`)
- DS bee illustrations are landing-only

### §4.5 Iconic moments to preserve in polish
- Honey-pulse halo behind hero CTA (`apps/www/Hero.tsx` lines 8–12)
- Card lift hover (`apps/www/globals.css` `.card-lift`)
- Honeycomb SVG background pattern
- Floating bee animation (landing only)

---

## §5. Drift / open issues / polish opportunities

These are the gaps a polish pass should close. Ranked rough-priority.

### §5.1 Critical drift (ship-blocking)

1. **Landing section sequence mismatch.** `App.tsx` mounts a 9-section legacy layout (Navbar / Hero / Features / CrownJewels / HowItWorks / Pricing / Enterprise / BetaSignup / Footer). v2.3 ship spec requires (Hero / Proof / Harvest / MultiAgent / How / Personas / Pricing / Trust / FinalCTA / Footer). Five new sections need to land; two legacy sections (`CrownJewels`, `BetaSignup`) need to be retired or reframed.
2. **Personas grid model conflict.** v1.1 LOCKED wireframe (2026-04-22) ships **13 brand bees in `6+6+1`** geometry via `BrandPersonasCard` (orphan in code). v2.3 ship brief (2026-04-28) replaces with **17 agent personas in `4×4 + Coordinator sidebar`** (text-only tiles, no bee mascots). PM ratification trail favors v2.3. Polish must pick one — and `BrandPersonasCard.tsx` either rebuilds or retires.
3. **Hero copy + art-direction.** Current `Hero.tsx` shows "Your AI Operating System" / "AI Agents That Remember" with bee-orchestrator center. v2.3 requires variant A (Marcus default) "Your AI doesn't reset. Your work doesn't either." + variant B (Klaudia/regulated) "AI workspace that satisfies your CISO." with NO bee in primary content. Hero variant resolver also missing.
4. **Pricing tier count.** v2.3 mandates **4 tiers** (Free / Pro / Teams / Enterprise). Verify `Pricing.tsx` matches; in v1.1 the spec said 3 tiers (Solo / Pro / Teams + KVARK in Enterprise tier card). Drift between locked decisions is real and PM ratification trail favors v2.3 4-tier.

### §5.2 Important drift (polish-grade)

5. **Tailwind absent on landing.** v2.3 §5 prescribes Tailwind 4 utilities; reality is inline styles + CSS custom properties. Decide: keep pure CSS (substrate independence) or migrate. Mixed approach will rot.
6. **Bee-on-hero violation.** `Hero.tsx` line 16 mounts a 176px bee illustration centrally — directly contradicts v2.3 binding rule "bee illustrations: NOT in primary sections."
7. **`HowItWorks` step count.** v1.1 wireframe locks 5 steps (Capture / Encode / Retrieve / Reason / Audit). v2.3 collapses to 3 steps (Install once / Work normally / Compound). Decide and align.
8. **OS shell texture opacity.** DS audit v2 calls for 25–35% honeycomb on desktop background. Verify `wallpaper.jpg` overlay matches; if not, this is the single highest-leverage brand moment in the entire OS shell.
9. **OS shell missing apps from canonical 24-list.** Top-level component files do not include explicit `Graph`, `Provenance`, `Providers`, `Policy`, `Preferences`, `Wiki`, `Audit`, `Prompts`, `Search`, `Terminal`, `Notes`, `Export`, `About`. Reconcile against `lib/dock-tiers.ts` — some may live in sub-folders.

### §5.3 Polish-only (no architectural change)

10. Empty states across all 25 OS apps need persona-illustration + 15–20% texture per DS audit v2 ramp.
11. Window state matrix coverage: spec calls for normal / focused / blurred / minimized-preview / maximized variants — verify `AppWindow.tsx` renders all five distinguishable.
12. Loading skeletons should use bee-* mascots (the only sanctioned non-landing bee usage).
13. Status bar density tuning (28–32px height per DS audit v2; "tanka, elegantna, bez texture").
14. Dock magnification on hover — DS audit calls it "opciono ali poželjno"; check current implementation.
15. ⌘K palette (`GlobalSearch.tsx`) already polished per DS audit; preserve in any iteration.
16. Footer needs 5-column rebuild (Product / Research / OSS / Company / Legal) per v2.3 §3 SECTION 10.
17. Trust band hex-texture-dark.png at 8–12% soft-light blend, not yet implemented (no Trust component).
18. Pricing billing toggle (Monthly / Annual save ~17%) — verify presence in `Pricing.tsx`.

---

## §6. Source artifacts (priority-ranked for Claude Design)

Read these in order. The first three are the **canonical** sources; everything below is supporting evidence or audit trail.

### §6.1 Canonical (read in full)

1. `D:/Projects/PM-Waggle-OS/strategy/landing/landing-wireframe-spec-v1.1-LOCKED-2026-04-22.md` — 65KB, 7-section landing wireframe with locked component contracts, copy keys, measurability, anti-patterns. Authoritative for any section v2.3 hasn't changed.
2. `D:/Projects/PM-Waggle-OS/briefs/2026-04-28-claude-design-landing-v2.3-prompt.md` — 36KB, **ship version** for landing v2 generation. Contains the 9-section + footer brief, palette lock, anti-patterns, 22 PASS/FAIL signals.
3. `D:/Projects/PM-Waggle-OS/briefs/2026-04-23-ds-audit-v2-macOS-paradigm-correction.md` — 12KB, OS shell paradigm correction with paste-ready DS chat prompt for menubar / dock / windows / desktop / palette / overlays.

### §6.2 Supporting (skim or query)

4. `D:/Projects/PM-Waggle-OS/strategy/landing/information-architecture-2026-04-19.md` — 50KB master IA (9 sections; v1.1 simplified to 7; v2.3 evolved to 9 again).
5. `D:/Projects/PM-Waggle-OS/strategy/landing/persona-research-2026-04-18-rev1.md` — 84KB persona research, 7 archetypes for v2.3 hero variant gating.
6. `D:/Projects/PM-Waggle-OS/briefs/2026-04-28-landing-copy-v4-waggle-product.md` — 31KB latest landing copy v4.
7. `D:/Projects/PM-Waggle-OS/briefs/2026-04-22-claude-design-landing-brief.md` — original Claude Design landing brief (audit trail; superseded by v2.3).
8. `D:/Projects/PM-Waggle-OS/briefs/2026-04-22-brand-bee-personas-card-spec.md` — 6.6KB, 13-bee persona card component spec.
9. `D:/Projects/PM-Waggle-OS/briefs/2026-04-22-cc-personas-card-component-parallel.md` — 11KB, parallel implementation brief that produced `BrandPersonasCard.tsx`.
10. `D:/Projects/PM-Waggle-OS/briefs/2026-04-22-personas-card-copy-refinement.md` — 9.9KB, locked persona copy.
11. `D:/Projects/PM-Waggle-OS/decisions/2026-04-22-h-audit-1-design-ratified.md` — design ratification decision log.
12. v2.0 / v2.1 / v2.2 prompt history under `briefs/` — audit trail for how v2.3 evolved (do not reuse).

### §6.3 Repo references (verify against)

- `D:/Projects/waggle-os/apps/www/src/styles/globals.css` — canonical token source for landing.
- `D:/Projects/waggle-os/apps/www/src/components/*.tsx` — current implementation (10 components).
- `D:/Projects/waggle-os/apps/www/src/data/personas.ts` — persona data (13-bee shape).
- `D:/Projects/waggle-os/apps/web/src/components/os/` — OS shell + 25 apps + 13 overlays + 60+ shadcn primitives.
- `D:/Projects/waggle-os/apps/web/tailwind.config.ts` — Tailwind config (OS shell only).
- `D:/Projects/waggle-os/apps/web/src/lib/dock-tiers.ts` — canonical dock AppId list + tier filtering rules.
- `D:/Projects/waggle-os/docs/WAGGLE-SYSTEM-VISUAL.html` — architectural diagram referenced by DS audit v2.
- `D:/Projects/waggle-os/CLAUDE.md` + `docs/ARCHITECTURE.md` — package + persona canonical lists.

### §6.4 Brand assets (binary references)

- `D:/Projects/waggle-os/apps/www/public/brand/` — `waggle-logo.svg`, 13 × `bee-*-dark.png`, `hex-texture-dark.png`.
- `D:/Projects/PM-Waggle-OS/_generated/bee-assets/` — latest builder-bee renders (v1, 2k variant).
- `D:/Projects/waggle-os/apps/web/src/assets/` — `wallpaper.jpg` (dark) + `wallpaper-light.jpg`, `waggle-logo.jpeg/.png`.

---

## §7. Polish-pass instruction shape (suggested — for Claude Design briefing)

Suggested framing for the Claude Design exploration prompt:

> Audit Waggle's two UI surfaces (`apps/www` landing and `apps/web` OS shell) against the v1.1 wireframe spec, the v2.3 ship brief, and the DS audit v2 paradigm correction. Reconcile drift between implemented components (per §2.2 and §3.2–§3.4 of `briefs/2026-04-29-ui-ux-component-inventory.md`) and the locked targets. Output: (a) a polish backlog grouped by surface and severity, (b) targeted Figma / claude.ai/design iterations for the top 5 highest-leverage gaps, (c) per-app empty/loading/error state coverage matrix for the 25 OS apps. Honor the locked palette (honey + violet + mint, no blue), the bee-usage rules (landing-only, footer-mark only on landing primary, never on app chrome), the macOS desktop paradigm in the shell, and the dark-first ground at `--hive-950` `#08090c`.

---

**End of inventory.**

Generated 2026-04-29 from read-only scan. No code or repo files modified.