waggle-os/docs/ux-refactor/path-to-9-2026-07-07.md

Path to 9 — premium feel, power usability, habit formation

The definitive analysis (2026-07-07, v3 FINAL) · goal: 5 persona judges ≥ 9/10 · founder framing: "premium UX + power feeling → addiction"

PATH-2 panel: 5/5 ENDORSED (predicted-if-executed 8.7–9.0). v3 integrates their 7 endorsement conditions. This is the agreed, executable path.

0. Standing and method

Evidence base: 7 video-judged rounds (R13–R19), 209 recorded fixes (88 HIGH), 10 shipped waves (P–X, merged to main 8ee7ac82), plus the 2026-05-28 addictiveness audit (Hook-Model rubric, 7 iterations, 5.0 → 7.7). Scores: video regime avg 7.08 → 7.70 (Fable ruler), min pinned at 7.5 for three rounds. Two measured plateaus prove the polish-wave engine is exhausted: per-round EV ≈ +0.02, and every remaining HIGH ask is either structural or systemic — not surgical.

The panel's own definition of the gap (R19, 5/5 unanimous, verbatim): "The product has the VISUAL craft of a 9 … but the MOTION identity of a ~7. Gap to 9 is not more features or more surfaces — it's a genuine motion system." Secondary unanimous asks: a shown, signature streaming moment; killing the boot interstitial; a systemic AA floor.

What a 9 means per lens (extracted from all 7 rounds' verdicts):

Judge	Their 9 requires	Their current ceiling-setter
design-director	spatial continuity, spring physics, choreographed transitions, multi-tier hover	"surfaces cut/fade instead of transforming"
knowledge-worker	instant feel (no boot tax, no staged arrival), interactions that telegraph	"make it feel instant"; boot + skeleton dwell on every route
competitor-critic	streaming rhythm at Claude/ChatGPT level + a motion language they lack	"the exact axis the video regime exposes: pure motion signature"
a11y-theme-parity	systemic AA tertiary tier + keyboard-first hover-reveals + hit areas	"systemic dim secondary text… weighs heaviest" (THE min-score gate)
brand-resonance	the hive alive on WORKING surfaces: honey responds to touch, streaming heartbeat, ambient life	"the brand goes quiet on the working surfaces"

1. Why the founder's "addiction" framing and the judges' "motion system" converge

The Hook Model (trigger → action → variable reward → investment) says habit forms when each loop is felt. The judged deficits map directly onto the loop's felt moments:

• Action feel = the power feeling. Instant boot, sub-100ms responses to the cursor, keyboard-first paths — Fogg's "ability" term. Today's boot tax + single-tier hovers make every loop pay a toll; a power user's loop must feel FREE.
• Variable reward = the visible aliveness. Streaming heartbeat, surprise-recall ("I REMEMBER" cards), honey blooming under the cursor — the dopamine surface. Judges keep scoring exactly these as the missing "signature moments."
• Investment made visible = memory counters, growth, compounding identity — the product already OWNS this (Memory Trust 8.2, "category-defining"); it needs the loop to celebrate accrual (count-ups, growth deltas in the briefing) rather than list it.
• Triggers are mostly outside the judged surface (digests, notifications) — real for retention, invisible to this panel. They ride the roadmap but not the score.

So: the same three workstreams that raise the judged score to 9 are the ones that manufacture the addiction loop. There is no tension between the founder ask and the panel's path.

2. The path — four pillars + a phase-0 vocabulary, sequenced

PHASE 0 · THE MOTION VOCABULARY (prerequisite; ships FIRST with Pillar 4) — [PATH-1: design blocking #2]

Before ANY new motion ships (including Pillar 3's aliveness moments):

1. One spring FAMILY, not one config — 2–3 named variants (micro / standard / expressive) sharing a single physical character, tuned once, exported as motion tokens. Kills the mixed CSS-ease/duration zoo. [design non-blocking, adopted]
2. A motion-spec reference page — an internal demo surface where every tier (spring family, hover tiers, settle gesture, route transitions, reduced-motion mappings) is demonstrable and reviewable. The arc's single source of motion truth. [design gap]
3. Reduced-motion mapping defined for EVERY tier (not just ambient): route transitions degrade to crossfade; hover keeps color/shadow, drops translate; settle gesture → instant state + color pulse; streaming caret → static cursor; count-ups → instant set. [design gap + a11y]
4. Interruptibility + input-primacy as ACCEPTANCE CRITERIA [design blocking #1]: every transition is interruptible and redirectable mid-flight; navigation and input NEVER wait on an exit animation or transition completion. The motion system must never fight the instant-feel pillar — this is a per-PR checklist item, not an aspiration.
5. Exit choreography in the same vocabulary: AnimatePresence exit definitions for cards, menus, modals, and route surfaces. [design non-blocking, adopted]
6. RETROFIT of already-shipped motion [PATH-2 design]: inventory every prior motion pass (Wave T/U hover tiers, Wave V lift+bloom + theme crossfade, Wave W entrance stagger, onboarding/streaming breathing) on the motion-spec page, then migrate each onto the Phase-0 tokens and spring family. Acceptance: ZERO non-token durations/easings on judged surfaces — one motion dialect, not two.
7. Signature-moment frequency/intensity taxonomy [brand blocking #2 + design/kw non-blocking — 3 judges independently]:
   • FULL settle (300–400ms): rare accrual milestones ONLY — memory saved (first per session), install success, agent spawned.
   • MICRO variant (≤150ms, same gesture DNA): high-frequency actions — send-arm, selection.
   • Per-session cooldowns on full-amplitude moments; routine actions never flourish.

Pillar 1 · THE MOTION SYSTEM (structural; the unanimous #1; est. +0.6–0.9 panel-wide)

A dedicated engineering arc, NOT lanes. Builds ON the Phase-0 vocabulary.

1. Spatial continuity — a base tier everywhere + two heroes [PATH-2 design]: (a) DEFAULT tier: a low-risk fade-through crossfade with persistent chrome (150–200ms, Phase-0 standard spring) on ALL top-level sidebar route changes, feature-flagged, subject to the Phase-0.4 interruptibility criteria — the Settings↔Home pair is the template, not a one-off. Two morphs + five hard cuts would read as three set pieces, not a system. (b) HERO morphs (the only shared-element cases): card→workspace-open (the card grows into the surface) and Trust↔Memories tab morph. Implementation: framer-motion layoutId + AnimatePresence mode="popLayout" scoped to these two (NOT a global router rewrite — that's the regression trap). Focus + assistive-tech spec ships INSIDE the transition component [a11y blocking #1]: on every shared-element route change, focus moves to the destination surface's primary heading/main landmark; exiting AnimatePresence trees are set inert/aria-hidden for their exit duration (focus and the SR virtual cursor can never land in them); route changes are announced (document.title update + a polite live region).
2. Multi-tier hover — "honey responds to touch": rest → hover (120–160ms: lift 2-4px + shadow + honey border-warm + glow bloom) → press (scale .98) → focus-visible (same tier, keyboard). ONE implementation (a hive-interactive variant), adopted by cards, rows, chips, tiles. Can ship early (additive).
3. The signature gesture — commissioned as a DESIGNED MOTION ASSET [brand blocking #1]: a recognizably waggle-derived micro-choreography (brief directional waggle-run → settle, from the bee's actual figure-eight dance), prototyped and judged STANDALONE on exactly one moment (memory saved) BEFORE any propagation. Only after the panel scores the prototype does it roll out per the Phase-0 frequency taxonomy. Highest-upside, highest-kitsch-risk line in the path — treated accordingly.
4. Ambient hive life: the breathing glow (already shipped on onboarding, judged "the one unambiguously signature motion") recurs as idle ambient on Home hex-glow and empty states. Amplitude discipline: ambient means BELOW attention threshold.
5. Light-theme variants for every glow/bloom signature [brand]: deeper honey, tighter radius on ivory — the signatures must not vanish (or smear) in light. Kit v6 captures each signature moment in BOTH themes.
6. P1/P2 seam: cache-first warm paint lands with one subtle designed micro-settle rather than a raw instant pop. [design non-blocking, adopted]

Pillar 2 · THE INSTANT POWER FEEL (perceived performance; est. +0.3–0.5, biggest for kw/competitor)

1. Kill the returning-user boot tax: warm sessions land on content <1s (brand flash ≤500ms). Cache-first paint: the Home payload cache is disk-persisted and renders BEFORE the sidecar answers — the day-30 morning desktop launch is the moment that matters, not just SPA revisits. [kw gap, adopted]
2. The input-during-warmup CONTRACT [PATH-2 kw]: cache-first paint must be INTERACTIVE, not just visible — (a) the composer accepts typing at paint; queued sends dispatch when the sidecar is ready (never error, never silently drop); (b) first click on any cached card either acts or shows a truthful per-element pending state — never a dead click. The §3 hard gate measures time-to-first- INTERACTION, not just time-to-content, and kit v6 records a cold-start variant (sidecar down → app start → cached paint → first send).
3. The silent-refresh reconciliation CONTRACT [kw blocking]: when fresh data lands over a cache-first paint — (a) NO above-the-fold layout shift; (b) material deltas animate in via the Pillar 3.3 delta pulse instead of silently replacing content; (c) the briefing modal (reserved for ≥7-day absences — N=7, decided) renders from the SAME data source/component as the home hero cards, killing the number-drift bug class permanently. Wrong-then-corrected is worse than slow; the contract is a test, not a guideline.
4. Collapse the double catch-up: the "I REMEMBER" cards land INSIDE the home hero as the first staggered entrance; the modal fires only on ≥7-day absences (same component, same data — see 2.2).
5. The send-path budget [kw gap, adopted]: the single most repeated daily action (send → first token) gets an explicit instant contract — optimistic user-bubble echo, composer never locks on send, first-token latency never increased by any visual layer.
6. Route-cache everything judged: chat thread, marketplace, agents join memory/ workspaces — tab returns instant, no re-skeleton. Marketplace's first-match wait keeps its purpose-built skeletons (banked residual, R17). [kw]
7. Keyboard-power layer: focus-visible parity on every hover-reveal (kebab + memory rows remain), ~40px hit areas, a ≤2-keystroke path from anywhere to new-chat / last-workspace, and a discoverable shortcut cheat sheet (? / Cmd-/). [kw non-blocking, adopted] Double yield: this is also the a11y judge's #2 ask.

Pillar 3 · THE ALIVENESS LOOP (variable reward made visible; est. +0.3–0.5, brand/competitor)

1. Streaming as a PIPELINE deliverable, then a visual one [competitor blocking #1]: first resolve the dev echo-provider's whole-block behavior — emit true token/chunk streaming in the judged environment, or add a render-side cadence buffer that smooths chunks into a steady visible rhythm with ZERO added latency to first token. Acceptance: recorded s04 shows continuous sub-line accretion — no multi-second block pops, no layout jank as markdown forms. THEN the branded layer: the streaming text caret — a honey glow trailing the accreting text head (this is what "bee-trail cursor" means; it is NEVER a pointer-following trail [brand blocking #3]) + a subtle thinking pulse on the bee avatar during tool-trace. Reduced-motion: static caret, no pulse. The caret never occludes text or targets. [a11y] Streaming INTERACTION contract [PATH-2 competitor]: auto-follow scroll breaks INSTANTLY on user scroll (input-primacy applied to the stream) with a "jump to latest" affordance; a visible stop control halts output immediately; the recorded s04 acceptance prompt forces hard-case progressive rendering (a code block + a list/table) — markdown formation tested where Claude's streaming craft is strongest.
2. Surprise-recall as a first-class moment: when Auto Recall lands mid-chat, the memory chip blooms honey for ~600ms ("reward of the hunt", rubric dim 6 — the product's unique dopamine no competitor can copy).
3. Investment celebration with an HONESTY GATE [brand non-blocking, adopted]: count-ups and "+" delta pulses bind to the exact source-of-truth number — the settled value is never floored, clamped, or estimated (regression-tested); animation intermediates must never contradict a visible sub-stat (the Wave X lesson, generalized). Briefing states what ACCRUED since last visit ("12 new memories · 2 decisions"). Accessible treatment: one polite live announcement of the settled number, never intermediate frames. [a11y]
4. First-60s wow (rubric dim 3): wire the first chat message to demonstrably use the just-typed profile ("As a consultant, you'll want…") — the "it already knows me" hook.

Pillar 4 · THE AA FLOOR (systemic; unblocks the min-score judge; est. min 7.5→8+)

1. Token-level tier: define a --text-tertiary tier that is AA on EVERY surface token (bg/bg-2/surface/surface-2) in BOTH themes; migrate the ~dozen recurring offender families (top utility bar, timestamps, card meta, onboarding subtitle/ footnote, unselected chips).
2. Close the GENERATION vector, not just today's instances [a11y blocking #2]: (a) a lint/CI guard banning new non-token text colors (raw hex, palette classes, arbitrary values) on app surfaces; (b) contrast verification that models COMPOSITION — opacity-modified text and text over wallpaper/gradient/wash measured against effective background (a runtime axe-style pass on the judged surfaces). Token-pair math alone buys one clean round; this buys a floor.
3. The AFFORDANCE floor [PATH-2 a11y]: non-text contrast (WCAG 1.4.11, ≥3:1 against adjacent effective background, both themes) for focus indicators, input/chip borders, and state glyphs — a --focus-ring/border tier alongside --text-tertiary, asserted in the same CI runtime pass. Explicit acceptance: Pillar 1.2's focus-visible tier passes 3:1 in LIGHT (honey-on-ivory), MEASURED.
4. Hit-area and focus-visible items fold into Pillar 2.7 (double-yield, one implementation).

3. Sequencing, risk, verification

Order: Phase-0 + Pillar 4 (parallel, both token-level, zero-regression) → Pillar 2 → Pillar 3 → Pillar 1 — with Pillar 1.2 (hover grammar) allowed early as additive. Amended from v1: the motion vocabulary now PRECEDES all aliveness work. [design blocking #2]

Competitive teardown at arc start [competitor non-blocking, adopted]: record the equivalent journeys on current Claude and ChatGPT (spot-check Hermes/Odyssey); extract concrete numeric targets — warm time-to-content, visible token rhythm, transition/hover timings. "At Claude/ChatGPT level" becomes measured, not remembered.

Risks: route transitions carry regression risk (scoped routes, feature-flag, the Phase-0.4 interruptibility criteria, the P1.1 focus/AT spec); streaming choreography must never delay tokens (P2.4 budget); ambient motion must never read as busy (brand: "respectful, no gratuitous movement" is currently a WIN — don't lose it).

Verification — kit v6 [design blocking #3 + competitor blocking #2 + a11y blocking #3]:

• Judges pinned model:'fable' (ruler stability; the R19 lesson).
• Per-journey sampling matched to the deliverable, disclosed in the judge brief: transition/signature/streaming journeys delivered as ≥12fps micro-filmstrips or short native-framerate clips (spring character, token cadence, and settle choreography are invisible at 2–4fps — the arc's history proves measurement failures eat rounds); 2fps contact sheets remain for static-composition journeys.
• A keyboard-only journey, recorded and judged like the mouse journeys: tab-through home → open workspace → chat send → message actions via focus → memory row actions → settings, visible focus indicators expected in every frame.
• Warm time-to-first-INTERACTION as a HARD gate: Playwright-measured, fails the round if >1000ms to interactive content / >500ms brand flash. [kw, PATH-2]
• Reduced-motion ENFORCEMENT [PATH-2 a11y]: an automated Playwright pass with prefers-reduced-motion: reduce emulated, asserting the Phase-0.3 mappings per tier (route transitions crossfade-only; no transform animation on hover; settle → instant state; static streaming caret; count-ups set instantly), run per round like the contrast and warm-boot gates — plus one recorded reduced-motion spot-journey.
• New journeys: send→stream→settle (shipped v5), card→workspace-open transition, tab-morph, warm-boot timing, cold-start-to-first-send, keyboard-only, reduced-motion spot, waggle-settle prototype (standalone, both themes).
• Side-by-side clips vs current Claude and ChatGPT [PATH-2 competitor]: streaming
  • warm-launch journeys at minimum, from the arc-start teardown footage, refreshed at the 9-attempt round and delivered in the judge brief — parity/beat claims judged from paired evidence, not memory.

Success gates per round: min-of-5 ≥ 8.0 after Phase-0+P4+P2; ≥ 8.5 after P3; 9 attempt after P1. If two consecutive rounds plateau below gate → stop, re-analyze (the discipline that caught both prior plateaus).

4. What we deliberately do NOT do

• No more polish waves against the old ask lists (measured EV ≈ 0).
• No gamification-shaped addiction (streaks, badges, FOMO mechanics) — the panel would score it as noise and it contradicts the trust-first brand voice that earns the 8.2s. Addiction here = the loop feeling so good it self-reinforces, not manipulation.
• No global router rewrite; no motion on the working thread that competes with content; no pointer-following effects of any kind.
• No unreviewed propagation of the signature gesture: prototype → panel → rollout.

5. Panel disposition — AGREED (goal met)

• PATH-2 (v2): 5/5 ENDORSE — design 8.8 (high) · kw 9.0 (medium) · competitor 8.8 (high) · a11y 8.7 (high) · brand 9.0 (medium). Seven endorsement conditions → integrated in THIS v3: default route-transition tier + retrofit deliverable (design); input-during-warmup contract + first-interaction gate (kw); streaming interaction contract + side-by-side evidence (competitor); affordance floor + reduced-motion enforcement (a11y). The panel agrees on the path — v3 is the executable contract for the arc.

PATH-1 disposition (for the record)

v1 review: design 8.7 endorse · kw 8.7 endorse · competitor 8.5 endorse · brand 9.0 endorse · a11y 8.3 WITHHELD. All 12 blocking amendments integrated above (Phase-0; interruptibility; resequencing; silent-refresh contract; streaming pipeline rescope; high-framerate verification; focus/AT spec; generation-vector CI; keyboard journey; commissioned gesture; frequency taxonomy; caret disambiguation) plus 9 high-consensus non-blocking adoptions (spring family, motion-spec page, reduced-motion per tier, exit choreography, P1/P2 seam, send-path budget, disk-persisted cache, honesty gate, competitive teardown, light-theme signatures, shortcut cheat sheet).