waggle-os/docs/redesign-warm-hive/pr3-recon/primitives.md

PR3 Recon — Warm-Hive primitives & global patterns

One shared vocabulary for the three PR3 screen builders (Home / Chat / Workspace). Post-PR1 inventory of what already exists in apps/web + the design's global patterns extracted from docs/design_handoff_waggle_app/. Use the token names and components below — do NOT invent ad-hoc colors or re-build atoms that exist.

Sources of truth:

• Warm tokens: apps/web/src/index.css (@layer base) + apps/web/src/waggle-theme.css (note: file is at src/, NOT src/styles/).
• Tailwind utilities: apps/web/tailwind.config.ts
• Design global: docs/design_handoff_waggle_app/README.md §6/§7 + SCREENS.md 01/02/03

---

1. Warm token cheatsheet

Dark is the default :root; :root[data-theme="light"] overrides every color. Radii / type / shadow tokens are theme-independent. Prefer the named warm token (var(--x)) for screen chrome; the shadcn HSL utility (bg-card, text-foreground) for any component that already derives from the HSL core.

Surfaces (apps/web/src/index.css:20-44, 149-153)

Token	Dark hex	Tailwind / usage
--bg	#14110b	bg-background — app shell
--bg-2	#1a160f	rails, recessed panels (sidebar uses bg-[var(--bg-2)])
--surface (= --card)	#1f1a12	bg-card — cards
--surface-2 (= --secondary)	#272117	bg-secondary — hover/insets
--surface-3 (= --muted)	#322a1d	bg-muted — chips, icon tiles
--line	#38301f	border-border ≈ — default border
--line-soft	#2a2417	subtle dividers (card border in design = --line-soft)
--line-strong	#4a4030	emphasized border / kbd / scrollbar

Text (index.css:21,36,89,153 + waggle-theme.css:24-29)

Token	Tailwind / alias
--text (= --foreground) #f6f1e4	text-foreground
--text-2 #c8bfa9	secondary copy
--text-muted (= --muted-foreground) #948a73	text-muted-foreground
--text-dim (= --hive-500 #6b6250)	labels, meta, mono section labels

Honey — the ONE accent (index.css:91-100, 155-159)

Token	Dark hex	Notes
--honey (= --honey-500, --primary)	#e9a52c	bg-primary / text-honey-500; primary btn, active nav, key numbers, focus
--honey-bright (= --honey-400)	#f6c45a	gradient top of hex avatar
--honey-deep (= --honey-600)	#c07e16	gradient bottom of hex avatar
--honey-wash	rgba(233,165,44,.10)	tinted fills (active nav bg, streak/honey chips)
--honey-line	rgba(233,165,44,.28)	tinted borders (card hover, chip border)
--honey-glow	rgba(233,165,44,.12)	soft glow / --shadow-honey
On-honey ink	#1a1407	text/icon color on any honey fill (matches --primary-foreground)

Semantics — desaturated, STATUS ONLY (never decoration) (index.css:161-169)

Token	Dark / Light	Meaning	Wash
--work	#7aa6d6 / #3f72b0	tasks, workspaces (blue)	--work-wash
--intel	#b196dd / #7d57b8	memory / intelligence / provenance (violet)	--intel-wash
--healthy	#6cb78c / #3c8a5f	complete / healthy (sage)	--healthy-wash
--attention	#e9a52c / #b57d12	attention / automation (= honey)	(use --honey-wash)
--risk	#db8068 / #c0573c	risk / failure (terracotta)	--risk-wash

There is also a parallel --sem-* alias set (--sem-work/-intelligence/-healthy/-attention/-risk, index.css:110-114) wired into the EXISTING primitives (StatusBadge, ConfidenceBadge). The vivid --status-* / bg-status-* tokens (#34d399 etc.) are the legacy palette — prefer the desaturated --work/--intel/... (or --sem-*) for warm-Hive screens.

Shadows / radii / fonts (index.css:171-183)

Token	Value
--shadow-sm / --shadow / --shadow-lg / --shadow-pop	card → overlay elevation
--shadow-honey	0 0 0 1px rgba(233,165,44,.25), 0 8px 30px -10px rgba(233,165,44,.35)
--r-sm 8px · --r 12px · --r-lg 18px · --r-xl 26px · pills 999px	rounded-sm/md/lg/xl map to the shadcn radius scale, NOT these raw px — use rounded-[18px]/rounded-[var(--r-lg)] for design-exact cards
--sans Hanken Grotesk · --mono JetBrains Mono	font-sans / font-mono; --serif = --sans (no book-serif)

Caveat for builders: Tailwind rounded-lg = --radius (0.75rem/12px = design --r), NOT --r-lg (18px). Design cards want 18px → use rounded-[18px]. Design hero card wants 26px → rounded-[26px]. Pills → rounded-full.

Utility classes already shipped (index.css + waggle-theme.css)

• .hex (waggle-theme.css:140) — hex clip-path for brandmark/avatars/tiles.
• .hex-avatar (index.css:377) — same clip path (duplicate; either works).
• .comb (waggle-theme.css:143) + .honeycomb-bg (index.css:369) — subtle hex mesh bg.
• .dot-live → @keyframes breathe 2.4s (index.css:429-435) — live/active status dot.
• .heartbeat (2s), .honey-pulse, .float, .hex-cursor (streaming type cursor), .token-stream, .send-flash, .card-enter, .hex-spin — all in index.css:408-503 and mirrored as Tailwind animate-* in tailwind.config.ts:107-156.
• .pill (waggle-theme.css:151) — status/filter chip base.
• .kbd (waggle-theme.css:160) — keyboard hint chip.
• .glass / .glass-strong / .glow-primary / .text-glow (index.css:334-358).
• .waggle-card-lift (waggle-theme.css:112) — hover translateY(-2px) + honey border (matches design card hover). .waggle-interactive, .waggle-nav-hover, .waggle-press.
• Focus: global :focus-visible { outline: 2px solid var(--honey-500); offset 2px } (index.css:389). Selection = honey @ .28 (index.css:383).

---

2. Existing reusable components (REUSE — do not rebuild)

Component	Path	Props	Reuse for which PR3 screen
ConfidenceBadge	apps/web/src/components/ui/confidence-badge.tsx:22	value?: number; compact?: boolean; className? — 0-100 → High/Med/Low band via --sem-*, never color-only	Workspace "What Waggle knows" fact rows; Chat memory-write steps
EvidenceChip	apps/web/src/components/ui/evidence-chip.tsx:16	label: string; title?; onClick?; className? — the inline provenance pill promoted to a primitive	Chat activity-stream provenance pills; Workspace fact/artifact ⬡ source · when
EvidencePanel	apps/web/src/components/ui/evidence-panel.tsx:18	source?; sourceId?; sourceUrl?; evidence?: string[]; className? — "Provenance & evidence" block of chips	Workspace memory detail; Chat memory-write detail
StatusBadge	apps/web/src/components/ui/status-badge.tsx:31	tone: 'healthy'|'attention'|'risk'|'info'|'neutral'; label: string; icon?; className? — always-labeled --sem-* pill	Home run-chip status dots, Workspace status card, all status pills
ApprovalModal	apps/web/src/components/ui/approval-modal.tsx:60	request: ApprovalRequest|null; approveLabel?; busy?; onApprove; onCancel (ApprovalRequest = {action, scope[], riskLevel, approvalClass?, trustSource?})	Chat inline approval card is a different surface — but reuse this modal for the same flow + share RISK_LABELS/risk-display.tsx
DetailDrawer	apps/web/src/components/ui/detail-drawer.tsx:22	open; onOpenChange; title; subtitle?; headerExtra?; footer?; children; className? — right sheet for object detail	Workspace fact/artifact detail; Chat artifact detail
BuilderStepper	apps/web/src/components/ui/stepper.tsx:29	steps: BuilderStep[]; ... body-portaled focus-trapped modal stepper	not core to Home/Chat/Workspace; available
shadcn primitives	apps/web/src/components/ui/	card, button, badge, tabs, dialog, tooltip, popover, command, scroll-area, separator, avatar, input, textarea, switch, sheet, sonner/toast, hover-card, dropdown-menu, alert-dialog, progress, skeleton, table, +30 more	Workspace tab bar = tabs.tsx; ⌘K already on command.tsx; cards/buttons everywhere; toasts via sonner
Sidebar (calm spine)	apps/web/src/components/os/Sidebar.tsx:44	workspaceName; spine: SidebarNavItem[]; pinned?; onOpen*; userName; tierLabel — already implements active = left honey bar + --honey-wash + honey icon (Sidebar.tsx:82-91) and the hex avatar inline (:116)	Already the shell; reuse its active-state recipe + hex pattern verbatim
⌘K catalog	apps/web/src/lib/command-catalog.ts:58	buildCommandCatalog(ctx) → plain-name + mono-subtitle groups (Pinned/Jump/Do/Power)	Chat/Home "⌘K" hints route here; don't re-author the vocabulary

shadcn button.tsx default variant = bg-primary text-primary-foreground = honey bg / #1a1407 ink → already matches the design primary button. ghost/outline variants cover the design "ghost" button. shadcn badge.tsx is color-capable but not always-labeled — prefer StatusBadge when conveying status (a11y).

---

3. Missing primitives to build in PR3 (NET-NEW shared components)

These appear across Home/Chat/Workspace and have no component today (the hex avatar exists only as inline markup in Sidebar.tsx:116). Build them once as shared atoms. Suggested home: apps/web/src/components/os/warm/ (new folder for warm-Hive-specific composite atoms) — keep generic, token-driven, a11y-labeled primitives in ui/ and the opinionated warm compositions in os/warm/.

Net-new primitive	Where	Minimal prop API	Used by
HexAvatar	os/warm/HexAvatar.tsx	label: string; size?: number; gradient?: boolean; className? — .hex clip + honey gradient linear-gradient(150deg,var(--honey-bright),var(--honey-deep)) + #1a1407 initial; extract from Sidebar.tsx:116	workspace switcher, Home workspace cards, Chat context header, Workspace header (46px), bot avatar
DotLive	os/warm/DotLive.tsx	tone?: 'healthy'|'attention'|'risk'|'work'|'intel'|'honey'; className? — colored dot + .dot-live breathe; honor prefers-reduced-motion	Home greeting live dot, Workspace "1 agent live", status cards
RunChip	os/warm/RunChip.tsx	label: string; tone?: StatusTone — status dot + label inline chip ("Teardown drafted · 9 competitors")	Home overnight hero run-chip row
StreakChip	os/warm/StreakChip.tsx	days: number; weekDots?: boolean[]; className? — 🔥 + "12-day streak", --honey-wash bg / --honey-line border	Home greeting (§ habit-loop mechanic lives on Home, not a page)
SectionLabel	os/warm/SectionLabel.tsx	children; className? — 11px mono, uppercase, .12-.14em tracking, --text-dim, trailing hairline rule	every screen section header (README §6)
ScreenHead (.shead)	os/warm/ScreenHead.tsx	title; subtitle?; action?: ReactNode — H1 (Hanken 600 ~24-28px) + subtitle + primary action row	Workspace header; power surfaces; generic screen chrome (README §6 / SCREENS §08)
ProvenanceLine	os/warm/ProvenanceLine.tsx	source: string; when?: string; onClick? — ⬡ source · when in mono --intel	Workspace fact rows + recent-work rows; Chat activity steps (thin wrapper over EvidenceChip styled to --intel mono)
ModelPill	os/warm/ModelPill.tsx	mode?: string; model: string; onClick? — "auto · Claude Sonnet" pill in Chat header	Chat context header
ActivityStream	os/warm/ActivityStream.tsx	summary: string; durationMs?; steps: {tone, text, provenance?}[]; defaultOpen? — collapsible --bg-2 card, violet spark, per-step colored dot + ProvenanceLine	Chat "the magic" activity card (default-open on active turn)
InlineApprovalCard	os/warm/InlineApprovalCard.tsx	reuse ApprovalRequest; onApprove; onDecline; alwaysAllow? — --honey-wash bg, attention border, warning icon (NOT a modal — inline in thread)	Chat approval card (shares risk vocab w/ ApprovalModal)
OvernightHero	os/warm/OvernightHero.tsx (composite, Home-only)	eyebrow; statement: ReactNode; runs: RunChipProps[] — --r-xl gradient card + honey radial glow	Home (composes RunChip)
AskBar	os/warm/AskBar.tsx	placeholder?; onSubmit; cmdkHint?: boolean — full-width pill, honey +, ⌘K hint, honey send	Home (and Chat composer reuses the send affordance)
HexCheckTile	os/warm/HexCheckTile.tsx	tone?; size? — small .hex tile w/ check, for fact rows	Workspace "What Waggle knows" fact rows
IconTile	os/warm/IconTile.tsx	icon: ElementType; tone?: StatusTone — tinted (*-wash) rounded square icon tile	Home "Waggle suggests" rows; Workspace recent-work ext tiles

Build order suggestion: HexAvatar, SectionLabel, ProvenanceLine, DotLive, RunChip, IconTile first (shared by all three screens), then the screen-specific composites. Keep each <80 LOC, token-driven, prefers-reduced-motion-safe.

---

4. Global pattern rules (apply on every PR3 screen)

From README.md §6 and SCREENS.md:

1. Density / scale: body 16px / line-height 1.55 (set on body, index.css:321); never below 12px. Honey words in headlines are honey-colored, not italic, same weight. Headlines Hanken 600, letter-spacing -0.02em (already on h1-h6, index.css:327).
2. Section labels: 11px mono, uppercase, .12-.14em tracking, --text-dim, trailing hairline rule. (Sidebar zone label is the reference: Sidebar.tsx:102, 9.5px mono uppercase tracking-[0.14em] text-[var(--text-dim)].)
3. One accent — honey, sparingly: primary buttons, active nav, key numbers, focus only. Semantics are desaturated and status-only, never decoration.
4. Cards: bg-card (--surface), 1px solid --line-soft, radius 18px (--r-lg), hover → --honey-line border + translateY(-2px) + --shadow. Use .waggle-card-lift for the hover recipe.
5. Active nav state: left honey bar (absolute -left-3 h-[18px] w-[3px] bg-[var(--honey)])
   • --honey-wash bg + honey icon — already implemented in Sidebar.tsx:82-91; mirror on the Workspace tab bar as a honey underline on the active tab.
6. Provenance everywhere: any memory / fact / artifact shows ⬡ source · when in mono / --intel. Core trust pattern — never drop it. Use ProvenanceLine / EvidenceChip.
7. Buttons: primary = honey bg / #1a1407 ink (shadcn default); ghost = bg-card / --line-strong border, hover honey border. Radius 9-13px.
8. Hex motif: brandmark + agent/workspace avatars + icon tiles use .hex clip with the honey gradient. Honeycomb (.comb/.honeycomb-bg) is decorative-only at ~.05.
9. Motion: entrances cubic-bezier(.16,1,.3,1) ~.7s, content visible without JS / reduced-motion. Hover transitions .14-.18s. Live status = .dot-live (breathe 2.4s). Honor prefers-reduced-motion on every animated atom.
10. Focus / a11y: 2px solid --honey, 2px offset (global). Status is never color-only — always a text label (StatusBadge/ConfidenceBadge pattern). Keep keyboard access on ⌘K, tabs, composer.
11. Dark + light: both warm (graphite ↔ paper) via :root[data-theme="light"]; drive through the app theme provider (apps/web/src/providers/ThemeProvider.tsx), NOT localStorage scaffolding. Every new color must resolve from a token so light mode inherits for free (light-mode AA is test-guarded).

Per-screen anchor (ship-variation)

• Home → Variation A (Editorial): centered column max-w 920px; greeting (mono date + DotLive + StreakChip) → OvernightHero (run chips) → "Pick up where you left off" 2-col workspace cards (HexAvatar) → "Waggle suggests" rows (IconTile) → AskBar. (SCREENS.md 01)
• Chat → Variation B (Split work canvas): context header (HexAvatar + name + memory count + ModelPill) → thread (user bubble asymmetric radius 4px 14px 14px 14px; bot hex avatar; ActivityStream w/ ProvenanceLine; InlineApprovalCard) → composer; right work-canvas (~42%) with .hex-cursor live draft. (SCREENS.md 02)
• Workspace → Variation A (Overview + tabs, Memory = a tab): ScreenHead (breadcrumb + 46px HexAvatar + meta) → Tabs (Overview/Chat/Memory/Artifacts/Files/Team, honey underline) → 2-col (1.7fr/1fr): left = summary + "What Waggle knows" (HexCheckTile + ProvenanceLine fact rows) + "Recent work" (IconTile rows); right = Status card + Up-next + Team. Do NOT make the graph the default. (SCREENS.md 03)