# Human-Flow Heuristics: Polish & Redesign (the "Elevate" layer)

The friction heuristics (`mouse-keyboard-heuristics.md`) find what *hurts*. This layer
finds what's *missing to be excellent* — and decides when a screen is beyond polishing
and should be **restructured**. Synthesized from three independent model passes (Claude,
Gemini, Grok), which converged hard on this set.

**The bar.** The maintainer is not a designer. After an `elevate` pass, the UI should
feel/look/act as if a senior product designer + UI expert + UX team planned it. So this
layer is *prescriptive*: don't just flag — propose the concrete better version, and when
warranted, sketch a redesign.

**How to run it.** `elevate` is primarily an **agent judgment pass** seeded by static
signals — read the component, understand the user's task, then score and prescribe. The
scanner can surface signals (heading counts, raw magic-number styles, missing state
branches, animation imports) but the call is the agent's.

Each heuristic below gives: **what it evaluates** (static signal vs. judgment), the
**top-notch bar**, and the **prescription** (the move to recommend — tweak *or* redesign).

---

## 1. Hierarchy & Visual Anchors
- **Evaluates:** Does visual weight follow importance? *Static:* multiple `<h1>`, repeated identical font-size/weight across unrelated text, div-soup without `section`/`article`/landmark structure, 4+ equally-weighted blocks. *Judgment:* does the dominant thing on screen match the primary user goal?
- **Top-notch:** Passes the squint test — one clear primary message, 2–3 supporting levels max, scannable in under 3 seconds without reading every line.
- **Prescription:** Consolidate to one `h1` + two supporting levels; promote the key value/data to a large semantic heading, demote metadata to caption/secondary. If 4+ blocks compete, restructure to "primary panel + supporting stack."

## 2. Signature Moment (First 5 Seconds)
- **Evaluates:** Quality of the initial viewport / hero / primary card. *Static:* generic header+content vs. a dedicated orientation block; headline present without supporting microcopy or a primary action. *Judgment:* does it answer "what is this and why act now?"
- **Top-notch:** Instant orientation plus a functional or emotional hook — headline + one supporting line + primary action, above the fold, zero ambiguity.
- **Prescription:** Replace the generic title with a Signature block (outcome-focused headline, one-sentence value, single primary CTA). On an operator tool, make it a task-oriented "what you can do right now" panel.

## 3. Action Gravity
- **Evaluates:** Is the primary action unmistakable? *Static:* count of primary-styled buttons (>1 is a smell), generic copy ("Submit", "Save"), key actions buried in menus. *Judgment:* is the most important action for *this* context the most salient?
- **Top-notch:** Exactly one primary action (or a small, clearly-ranked set), visually and positionally dominant; everything else is secondary/tertiary.
- **Prescription:** Elevate the one true primary (size, accent, top-right or sticky action bar). Demote the rest to ghost/icon actions. Rewrite labels to outcome verbs ("Publish changes", "Apply filters"). If two actions are genuinely co-primary for different users, put a segmented choice up front.

## 4. Narrative Coherence
- **Evaluates:** Does the screen tell one logical story matching the task sequence? *Static:* JSX section order vs. logical order, competing CTAs at equal weight, unrelated concerns interleaved. *Judgment:* can a user with the stated goal follow a path without backtracking or "why is this here?"
- **Top-notch:** Layout order matches the user's decision/task sequence — one primary thread, clear branches, no random panels.
- **Prescription:** Reorder to Context → Decision → Confirmation. Move "related items" into a collapsible tray. If the screen serves two unrelated tasks/roles, split into two focused views.

## 5. The Lonely States (Empty / Zero / Loading / Error / Success)
- **Evaluates:** Are non-happy-path states *designed*? *Static:* conditional rendering with only a happy branch, inline "no data" text, no skeleton/spinner, no `<EmptyState>`/`<ErrorState>`. *Judgment:* does each state reduce anxiety and offer the next action?
- **Top-notch:** Every state is designed, not defaulted. Empty states explain *why* and offer the most relevant action; errors are specific + retry + support; success confirms without blocking.
- **Prescription:** Add a first-class EmptyState (illustration slot + outcome copy + primary CTA). Replace "no results" with a contextual suggestion (closest useful filter or a create flow). Surface the real error reason + retry, never a bare "something went wrong."

## 6. Progressive Disclosure & Density Tuning
- **Evaluates:** Is density managed, secondary info deferred? *Static:* many visible fields/columns/metrics at once, hover-only details, no accordion/tabs/"show more", long flat tables without grouping. *Judgment:* can the primary task complete without seeing ~80% of the content?
- **Top-notch:** Critical path is sparse; secondary detail is one expansion/click away; the user controls the level of detail.
- **Prescription:** Collapse the bottom ~60% of a long form into an "Advanced" disclosure. Turn a 12-column table into summary cards + "View details" side panel. For dashboards, add tiered views (Summary / Standard / Full) with a per-user density toggle.

## 7. Spacing Rhythm & Grid
- **Evaluates:** Consistent spatial system? *Static:* hardcoded odd values (`margin: 13px`, `p-[17px]`), inconsistent sibling padding, no spacing scale, cramped containers. *Judgment:* does whitespace group related things and separate unrelated ones (proximity)?
- **Top-notch:** Strict 4px/8px grid; related elements closer than unrelated ones; generous, intentional breathing room.
- **Prescription:** Normalize all raw px to the nearest spacing token; apply a consistent container `gap`; increase separation between unrelated groups so the eye chunks the layout.

## 8. Typographic Scale & Readability
- **Evaluates:** Is text comfortable and contrasted? *Static:* body < 14px, missing `line-height` on prose, grey-on-grey, raw hex colors vs. WCAG AA. *Judgment:* is long-form content actually pleasant to read?
- **Top-notch:** Body 16px+, line-height ~1.5–1.6, a clear primary vs. de-emphasized text system, AA contrast minimum.
- **Prescription:** Raise body size/line-height; establish a small type scale (display / heading / body / caption); fix low-contrast pairings to meet AA.

## 9. System Consistency (Token Fidelity)
- **Evaluates:** Do styles come from the system, not one-offs? *Static:* raw numbers in classes (`text-[13px]`, `#3f2a1b`), inline styles, 3 near-identical button/card variants, magic numbers in layout. *Judgment:* justified exception vs. drift?
- **Top-notch:** 95%+ of visual decisions come from tokens; new components are *composed*, not invented; rare one-offs are commented.
- **Prescription:** Replace raw values with the nearest token. Consolidate near-duplicate components into one with size/emphasis variants. Extract recurring patterns (e.g. section header) into a reusable component that enforces rhythm.

## 10. Surface, Depth & the Finish Layer (Trust Cues)
- **Evaluates:** Does it feel finished and trustworthy? *Static:* no elevation shadows on floating elements, no `:active`/press feedback, generic button text, misaligned numbers, missing timestamps/ownership. *Judgment:* does it feel *crafted* or *assembled*?
- **Top-notch:** Subtle shadows convey a Z-axis; interactive elements give a tactile press; numbers right-align; actions read as outcomes; small reassurances ("Last synced 2m ago", "Changes saved automatically") remove doubt.
- **Prescription:** Add a consistent surface/chrome to the primary area; `active:` press transform on buttons; right-align numerics; add "last updated" context; unify card/section treatment so widgets read as one product.

## 11. Intentional Motion & Choreography
- **Evaluates:** Does motion serve comprehension, not decoration? *Static:* transition/framer-motion usage without variants, multiple simultaneous transforms on load, >300ms on non-modal elements, no `prefers-reduced-motion`. *Judgment:* does each animation have a purpose (reveal, state change, spatial relationship)?
- **Top-notch:** Sparse, purposeful, choreographed; entrances/exits respect spatial relationships; honors reduced-motion. (Calibrate intensity with the Restraint-o-Meter in `fancy-as-fuck.md`.)
- **Prescription:** Keep only optimistic state transitions (120–180ms ease), modal/drawer enter-exit with backdrop fade, and at most one staggered reveal that aids scanning. Add a reduced-motion guard. If motion is hiding a weak layout, fix the layout first.

## 12. Redesign Triggers (Beyond Polishing)
- **Evaluates:** Can local polish even fix this? *Static + structural:* >6 competing top-level sections; conditional rendering producing 4+ distinct layouts in one file; component >300 lines or >3 nested ternaries; deep nesting to model a simple hierarchy; "TODO: redesign" comments; a view that accreted 3+ features without re-architecture. *Judgment:* is the screen's conceptual model fundamentally broken?
- **Top-notch:** One defensible conceptual model; adding the next feature wouldn't need another special case.
- **Prescription:** Declare the redesign threshold crossed. Define the information model first (e.g. "Workspace → Item → Activity"), then a master-detail / two-pane layout that absorbs future features. Provide a sketched component tree + data shape. Do **not** patch the 14-section accordion.

---

## Scoring: the Elevation Index

Score each heuristic **1–5** (1 = absent/harmful, 3 = competent, 5 = senior-designer execution).

- **Elevation Index** (0–10): weighted average of the 12, scaled to 10. Weight the
  high-user-impact dimensions heaviest — **Hierarchy, Signature Moment, Action Gravity,
  Narrative Coherence** (×1.5); the rest ×1.0.
- **Redesign Urgency** (0–5): a *separate* score driven mainly by **#12 Redesign
  Triggers**, reinforced by low **Narrative Coherence** and **Progressive Disclosure**.
  Urgency ≥ 4 ⇒ lead the report with a **Structural Audit** ("this screen has exceeded
  patch capacity — restructure, don't polish") and a sketched alternative.

### Prioritize, don't dump
For each finding compute **Opportunity = ImpactWeight × (5 − CurrentScore)**, sort
descending, and present the top **5–7** concrete moves (rest in an appendix). Group into
three tiers:

| Tier | Contains | Cost |
|---|---|---|
| **Quick Wins** | spacing, type, token fidelity, finish details | low effort, high return |
| **Elevations** | hierarchy, states, motion, depth, disclosure, action gravity | structural/component-level |
| **Redesign Candidates** | Redesign Urgency ≥ 4, or multiple high-impact structural heuristics failing | re-architecture |

Every recommendation must cite the **file/component**, the **signal that triggered it**,
and the **exact replacement pattern or new component/layout shape** — not a vague "improve this."

---

## Output shape (elevate)
```markdown
## Human-Flow Elevate: <target>

**Elevation Index:** 6.4/10   **Redesign Urgency:** 2/5

[If Urgency >= 4: Structural Audit block first — why patching won't work + sketched redesign]

### Quick Wins (do this sprint)
1. <file:line> — <signal> -> <concrete token/type/spacing/finish fix>

### Elevations
1. <file:component> — <signal> -> <hierarchy/state/motion/disclosure restructure>

### Redesign Candidates (plan)
1. <file/view> — <triggers> -> <new information model + component tree sketch>

### Scorecard
| Heuristic | Score | Top opportunity |
```

Pair with `scan` (fix friction first) and `fancy` (then calibrated delight). `elevate`
is the bridge between "no longer painful" and "genuinely top-notch."
