claudetools/.claude/skills/human-flow

human-flow

A focused UI/UX scanner for human mouse + keyboard workflow intuition, with a dedicated "Fancy as Fuck" mode for beauty and elegance.

It expands the excellent foundations in frontend-design (visual + interaction correctness) and impeccable (critique, heuristics, anti-slop, cognitive load) with a narrow lens:

What feels clunky, hidden, imprecise, or frustrating when a real person is sitting there with a mouse in one hand and a keyboard in the other, trying to get real work done?

The fancy mode adds an important principle: "In the course of being as useful as possible, do it with panache." "Useful decoration" (elegance that improves mental models, reduces anxiety, provides better feedback, or creates positive emotional connection) is explicitly welcomed, while gratuitous prettiness is discouraged. The mode carefully calibrates expectations based on whether the surface is a high-density internal tool or one that can benefit from more expressive delight.

Quick Start (as the agent)

# Fast static scan (friction / workflow)
node .claude/skills/human-flow/scripts/scan.mjs --path dashboard/src

# "Fancy as Fuck" beauty & elegance pass (useful decoration welcome)
node .claude/skills/human-flow/scripts/scan.mjs --path dashboard/src --fancy
# or: npm run fancy -- --path dashboard/src

# Or let the agent drive it naturally:
# "human-flow scan the sessions feature"
# "human-flow fancy the main interactive surfaces — look for useful decoration and panache where it enhances the experience"
# "Run a human-flow audit on the main data tables and action patterns"

The script emits structured findings (stronger in friction mode; signals + prompts in fancy mode). The agent then augments them with full file reads, task flow understanding, and the richer heuristics in references/. The fancy pass is intentionally more qualitative.

Core Files

• SKILL.md — the contract and invocation rules
• references/mouse-keyboard-heuristics.md — the detailed "why this hurts a human" rules
• references/human-flow-checklist.md — rapid mental model / quick checklist
• references/improvement-patterns.md — concrete before/after patterns that improve real workflows
• references/report-template.md — consistent output format
• scripts/scan.mjs — lightweight static detector you can run from the terminal

Philosophy

• Prioritize frequent tasks done by humans under real conditions (time pressure, imperfect pointing, mix of mouse and keyboard).
• Small targets, hidden-on-hover actions, and mouse-only gestures are the most common sources of daily friction in data-heavy tools.
• Good solutions usually involve making the right thing bigger, more visible, and reachable by both input methods — not just "adding more aria".

This skill is deliberately opinionated toward making the anticipated next action obvious and low-effort for a human operator.

Relationship to Sibling Skills

• Use frontend-design for visual/layout/contrast validation.
• Use impeccable critique|audit|polish for broader UX, emotional journey, and anti-slop.
• Use human-flow when you specifically want the "does this feel good in my hands with a mouse and keyboard?" pass.

They compose beautifully. Run them in sequence on the same target when doing serious interface work.