Files

Mike Swanson bc5048b885 feat(human-flow): AST-based scanner v2 + Friction Index rubric

Upgrade the human-flow skill (Gemini-assisted, Claude-reviewed):
- scan.mjs rewritten to AST-based (@babel/parser/traverse) with 4
  detectors: unlabeled-icon-button, tiny-target, missing-feedback-props,
  click-without-keyboard; regex fallback on parse failure.
- Objective Friction Index (Motor 3.0 / Cognitive 2.5 / Keyboard 2.5 /
  Feedback 2.0); 0-10 Human Workflow Score.
- New heuristics: State-Flow Audit, Precision Rail / Fumble Zones,
  Restraint-o-Meter (1-5) for the fancy pass.
- `fix` command DISABLED for now (advisory only): the AST generator
  reprints whole files and produces noisy diffs; agents apply surgical
  fixes from the report. To be revisited with a string-splice editor.
- Add @babel/* deps + package-lock.json.
- Memory: agy review/review-files is NOT actually read-only (wrote files
  + ran npm despite documented plan-mode) — diff after every agy review.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-05 17:58:10 -07:00

4.0 KiB

Raw Blame History

Human-Flow Report Template

Use this structure for all scan, audit, and report outputs.

Human-Flow Report: <Target / Component / Page>

Date: YYYY-MM-DD
Scanner: human-flow v2 (AST-Powered)
Overall Human Workflow Score: X/10

Friction Index Rubric

Motor (3.0): Target size, precision, travel distance.
Cognitive (2.5): Discoverability, affordance, consistency.
Keyboard (2.5): Accessibility, focus flow, parity.
Feedback (2.0): Visual response, state transitions.

Summary
(2-4 sentences: the biggest sources of unintuitive behavior for a human operator using mouse and keyboard, and the net effect on daily workflow.)

High Friction (P0 — fix before broader use)

List the most damaging issues for frequent tasks.

Issue 1 — Severity: high (mouse + keyboard)

Location: path/to/file.tsx:42 (or component + specific element)
Pattern: Hover-revealed row actions / small icon targets / missing keyboard activation / etc.
Human Experience: When scanning the Sessions list with a mouse, the Control and End buttons are dimmed until the pointer is exactly over the row. A keyboard user tabbing through never sees them at full strength. The primary action for an operator (taking control of a machine) requires extra precision and discovery.
Why costly: High-frequency task. Small miss rate + extra hover step adds up across dozens of sessions per day. Creates "hunt and hope" instead of "glance and act".
Recommended improvement (better for humans):
- Make actions at least 70-80% opacity at rest (or always fully visible in a dedicated column).
- Ensure the primary action (Control/View) is the strongest visual target and also activates on row click + Enter.
- Add explicit aria-label + visible focus treatment.
- Example pattern: always-visible ghost buttons with generous hit area + row click as power-user shortcut.

Issue 2 — ...

Medium Friction (P1)

...

Low / Polish (P2)

...

Strengths (things that already feel good for humans)

Fancy / Delight Opportunities (from `fancy` pass)

This section only appears when the fancy command/mode is run.

Appropriateness verdict: [Highly appropriate / Appropriate with restraint / Better kept minimal / Not appropriate for this surface]

Delight Idea 1 — Category: micro-interaction / transition / loading / etc.

Location: ...
Current state: ...
Opportunity: A tasteful [specific elegant behavior] would make this interaction feel more premium and responsive.
Why it fits (or doesn't): ...
Suggested implementation notes: ...
Reduced-motion fallback: ...

(Repeat for 2–5 highest-leverage ideas. Be ruthless — only suggest things that genuinely elevate without adding noise.)

Recommended Next Steps

Notes for implementation:

Any change here should be validated with both frontend-design visual checklist and this scanner afterward.
Consider adding a small set of visible keyboard shortcuts for the top 2-3 actions and surface them in the UI (e.g. in a help footer or on hover of the main button).
After making fancy changes, re-run human-flow fancy to check that the additions feel intentional rather than tacked-on.

Quick Reference for Common Fixes

Small targets → Increase min size + padding. Use the generous wrapper pattern.

Hover-only actions → Raise resting opacity or move to always-visible "Actions" area. Never rely on hover for primary or frequent actions.

Mouse-only activation → Add tabIndex, onKeyDown for Enter/Space, strong :focus-visible, and aria-* labels.

Weak feedback → Add immediate :active/loading state, row highlight on selection, and clear disabled messaging.

Precision-heavy workflows → Widen hit areas, reduce number of steps, make the "obvious next thing" the biggest target.

This template is intentionally human-first in language. Every finding must explain the lived experience of a person with a mouse and keyboard, not just the code smell.

4.0 KiB Raw Blame History Unescape Escape