claudetools/.claude/skills/human-flow/SKILL.md

name, description, user-invocable, argument-hint

name	description	user-invocable	argument-hint
human-flow	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).	true	[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)

## 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

# 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.