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

name, description, user-invocable, argument-hint

name	description	user-invocable	argument-hint
human-flow	A UI/UX scanner that specializes in detecting interaction patterns unintuitive or inefficient for humans using a mouse and keyboard. Expands on frontend-design and impeccable by focusing on real human workflow friction: motor control (Fitts's Law, target sizing, precision), discoverability (affordances, hover vs always-visible), keyboard parity (full navigation and activation without mouse), feedback loops (immediate state changes, error recovery), task efficiency (click/keystroke count, context switches), and forgiving interaction models. It produces structured reports with code locations, "why this feels bad for a human" explanations, and specific, actionable recommendations to make mouse+keyboard workflows smoother, faster, and more intuitive. Use when reviewing or building any interactive UI, especially data-heavy tools, dashboards, lists, forms, and 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]	Quick static + heuristic scan of files or directories for mouse/keyboard friction. Produces a prioritized report.
audit [target]	Deeper pass: combines code analysis, component review, and workflow walkthroughs. Scores intuitiveness and suggests specific refactors.
fancy [target]	"Fancy as fuck" mode — a second, beauty- and elegance-focused pass. Evaluates opportunities for tasteful delight (transitions, micro-interactions, hover states, view transitions, loading experiences, etc.), determines appropriateness, and suggests refinements/polish.
report [target]	Generate a clean, user-facing markdown report suitable for sharing with designers/devs.

If no command, defaults to scan on the provided target (or current frontend dir).

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.

"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.
• 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.