---
name: human-flow
description: "UI/UX scanner for mouse+keyboard interaction friction: Fitts's Law/target sizing, discoverability/affordances, keyboard parity, feedback loops, task efficiency, forgiving interactions. Produces reports with code locations + fixes. Use when reviewing/building interactive UI (dashboards, lists, forms, complex workflows)."
user-invocable: true
argument-hint: "[scan|audit|report] [target path or component]"
---

# human-flow — Human Mouse + Keyboard Workflow Scanner

This skill is a specialized scanner for **human intuition and ergonomics** in pointer + keyboard interfaces. It goes beyond visual polish, code quality, and general UX heuristics (covered by `frontend-design` and `impeccable`) to focus on what actually feels *clunky, hidden, or frustrating* when a real person is driving with a mouse and keyboard.

**Core Philosophy**
- Humans have limited precision, attention, and patience.
- Mouse users hate tiny targets, hidden controls, and precision clicking.
- Keyboard users hate missing focus, no activation keys, and mouse-only gestures.
- Good workflow design makes the *anticipated next action* obvious and low-effort with either input method.
- The best interfaces feel "just right" — large enough targets, immediate feedback, discoverable without hunting, and consistent models.

It is **mandatory** to consider human-flow when any mouse or keyboard interaction is involved.

## When to Invoke

- Before or after implementing interactive features (buttons, tables, lists, modals, forms, drag, selection).
- When reviewing a dashboard, admin tool, or data-heavy UI (e.g. session lists, machine management).
- To audit an existing interface for workflow friction.
- As a complement to `impeccable critique` / `audit` and `frontend-design` validation.

Run via natural language ("human-flow scan the sessions table", "run human-flow audit on the dashboard components") or explicitly.

## Commands

| Command             | Description |
|---------------------|-------------|
| `scan [target]`     | AST-powered scan of files/directories for workflow friction. Produces a 0-10 Friction Index report. |
| `audit [target]`    | Deeper pass: combines AST analysis, component review, and state-flow audit. |
| `elevate [target]`  | **Polish & redesign pass.** Goes beyond friction to make a UI top-notch: information hierarchy, signature moment, action gravity, lonely states, density, rhythm, type, tokens, depth/finish, motion — and flags when a screen should be **redesigned, not patched**. Produces an Elevation Index + prioritized tiers (Quick Wins / Elevations / Redesign Candidates). Add `--redesign` to emphasize structural restructuring. See `references/polish-and-redesign.md`. |
| `fix [target]`      | **DISABLED (advisory only for now).** Auto-apply is off — the AST code generator reprints whole files and produces noisy diffs. Use the scan/report output and have an agent apply the fixes surgically. Will be revisited with a surgical (string-splice) editor. |
| `fancy [target]`    | **"Fancy as fuck" mode** — elegance pass with a calibrated Restraint-o-Meter. |
| `report [target]`   | Generate a formatted markdown report with the Friction Index rubric. |

If no command, defaults to `scan` on the provided target.

## Friction Index (0-10)

The scan produces an objective score based on weighted deductions:
- **Motor (3.0)**: Target size, precision, Fitts's Law.
- **Cognitive (2.5)**: Discoverability, affordance, consistency.
- **Keyboard (2.5)**: Accessibility, focus flow, parity.
- **Feedback (2.0)**: Visual response, state transitions.

Score = 10 - Σ(IssueSeverity * DimensionWeight)

You can combine: e.g. run `scan` first for friction, then `fancy` for delight opportunities.

## Usage in Practice (for the Agent)

1. Resolve the target (file, component, page, or directory of .tsx/.jsx/.css/.ts).
2. Load the heuristics from `references/`.
3. Use code tools (read_file, grep, list_dir) + the scanner script if helpful to find candidate patterns.
4. For each finding: 
   - Cite exact file:line or component.
   - Explain *why it is unintuitive for a human with mouse and/or keyboard*.
   - Give a concrete "better for humans" recommendation (with example diff or pattern when useful).
5. Prioritize by impact on common workflows (high-frequency actions first).
6. End with an overall "Human Workflow Score" (0-10) and top 3-5 recommended changes.

Always separate **mouse friction** and **keyboard friction** in reports, then **combined workflow** issues.

## Heuristics (Core Categories)

The full detailed list with examples and detection guidance lives in `references/mouse-keyboard-heuristics.md`.

High-level categories the scanner always checks:

- **Target Size & Motor Precision** (Fitts's Law)
- **Discoverability & Affordance** (does it look clickable/tappable? do secondary actions hide?)
- **Hover vs Always-Visible** (actions that require mouse hover to even see options)
- **Keyboard Parity & Activation** (can you do everything the mouse can, with reasonable keys?)
- **Focus & Navigation Flow** (tab order, focus trapping, visible focus, escape hatches)
- **Feedback & State Transitions** (does the UI react immediately and clearly to every mouse/keyboard action?)
- **Selection & Multi-Action Models** (row click vs checkbox, drag vs buttons — are they consistent and forgiving?)
- **Workflow Efficiency** (number of steps, precision required, dead space, context loss for common tasks)
- **Error Prevention & Recovery** (destructive actions, undo, clear "I didn't mean that" paths)
- **Density vs Clarity** (too much crammed into small areas forcing careful mousing)

The scanner is **opinionated toward making the happy path for a human operator faster and less error-prone**, even if it means slightly more visual weight or always-visible controls.

## Scripts & Tooling

- `scripts/scan.mjs` — runnable Node scanner.
  - `node scripts/scan.mjs --path <target>` → friction mode (default)
  - `node scripts/scan.mjs --path <target> --fancy` → fancy mode (collects signals + prompts for the qualitative beauty pass)
- The agent is expected to supplement with semantic understanding (reading full components, understanding the user task flow in the app) and the rich references. The fancy pass is intentionally more qualitative than the friction scanner.

## Integration with Other Skills

- Run **after** `frontend-design` visual validation and **alongside** `impeccable critique/audit`.
- Use `stop-slop` thinking when generating any example fixes or new component code.
- Can feed findings into `impeccable polish` or `harden` passes.

## Output Format (Preferred)

```markdown
## Human-Flow Scan: <target>

**Overall Human Workflow Score:** 6.5/10 (Mouse: 7/10, Keyboard: 6/10)

### High Friction (P0)
- **File:** ...:123 — Hover-only row actions
  Why unintuitive: Secondary actions (End, Control) are at 0.5 opacity until hover. A keyboard user or rushed mouse user scanning the list will miss or struggle to target them.
  Human impact: Common task (ending a session) requires extra precision and discovery step.
  Recommendation: ...
```

See `references/report-template.md` for the full structure.

## "Elevate" Mode (`elevate`) — Polish & Redesign

Where `scan` finds what *hurts*, `elevate` finds what's *missing to be excellent* — and
decides when a screen is beyond polishing and should be **restructured**. It exists because
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.

It is primarily an **agent judgment pass** seeded by static signals — read the component,
understand the user's task, score each dimension 1–5, then prescribe the concrete better
version (a tweak, or a sketched redesign). The 12 heuristics, the scoring model, and the
output shape live in `references/polish-and-redesign.md`. In brief:

- **12 heuristics:** Hierarchy & Visual Anchors · Signature Moment · Action Gravity ·
  Narrative Coherence · Lonely States (empty/error/loading/success) · Progressive
  Disclosure & Density · Spacing Rhythm · Typographic Scale · Token Fidelity · Surface/
  Depth/Finish · Intentional Motion · Redesign Triggers.
- **Elevation Index (0–10):** weighted score, with Hierarchy / Signature / Action Gravity /
  Narrative weighted heaviest.
- **Redesign Urgency (0–5):** if ≥ 4, lead with a Structural Audit ("restructure, don't
  polish") and a sketched alternative layout/component tree.
- **Prioritized, not dumped:** `Opportunity = ImpactWeight × (5 − score)`; present the top
  5–7 as **Quick Wins / Elevations / Redesign Candidates**, each citing file + signal +
  exact replacement.

Recommended sequence: `scan` (kill friction) → `elevate` (reach top-notch / decide redesign)
→ `fancy` (calibrated delight on top).

## "Fancy as Fuck" Mode (`fancy`)

This is a deliberate second (or standalone) pass focused on **beauty, refinement, and elegant interaction**.

### Philosophy
- Not every interface needs (or should have) fancy elements. The first question is always: *"Does this beauty make the experience more useful?"*
- **Core principle**: Don't be pretty just to be pretty. In the course of being as useful as possible, do it with panache.
- "Useful decoration" is explicitly welcomed on surfaces where beauty can amplify comprehension, guidance, emotional reassurance, decision speed, or long-term connection to the product.
- On dense internal tools (operator consoles, admin dashboards): favor *restrained luxury* and precision. Think "high-end instrument." Only add panache where it clearly helps the operator.
- On other surfaces (onboarding, public tools, marketing moments, creative experiences): more room for expressive, delightful "useful decoration."
- Fancy must **serve the human workflow**. It should increase perceived quality, clarity, emotional satisfaction, or effectiveness without adding cognitive load, slowing tasks, or hurting performance/accessibility.
- "Fancy" includes (but is not limited to): transitions & easing, micro-interactions, hover/focus states, page/view transitions (View Transitions API), loading & skeleton experiences, selection/confirmation moments, empty/success states, scroll reveals, depth/layering, typography shifts, cursor feedback, and tasteful celebration moments.

### How the Fancy Pass Works
1. Assess appropriateness for the surface and user context.
2. Look for **opportunities** where a small amount of elegant motion or feedback would make interactions feel more premium and alive.
3. Critique existing attempts that are half-baked, janky, overused, or performance-negative.
4. Suggest specific, high-craft refinements and polish.
5. Always respect `prefers-reduced-motion` and provide graceful fallbacks.

See `references/fancy-as-fuck.md` for the full set of beauty/elegance heuristics, appropriateness guidelines, and examples.

### Recommended Invocation Pattern
```bash
# Friction first
human-flow scan the dashboard

# Then delight
human-flow fancy the dashboard
```

The output of a `fancy` pass should live in its own section of the report (or a dedicated delight report) and feed nicely into `impeccable polish` or `delight` work.

## Creating / Extending

- Add new heuristics to `references/mouse-keyboard-heuristics.md` (with detection hints and "better human workflow" examples).
- Add fancy/delights ideas to `references/fancy-as-fuck.md`.
- Add polish/redesign heuristics to `references/polish-and-redesign.md` (the `elevate` layer).
- Update the scanner script for new static patterns (fancy detection is intentionally more qualitative).
- The skill is designed to be extended — new categories of mouse/keyboard friction **and** opportunities for tasteful elegance are welcome.

**Remember:** The goal is not "perfect accessibility" in isolation or "pretty UI". It is **making the actual anticipated physical and cognitive workflow of a human with a mouse and a keyboard feel natural, fast, and low-friction** — and, when appropriate, doing so with panache and high craft. Beauty that serves usefulness is excellent. Beauty for its own sake is noise.
