Mike Swanson
d4741e447f
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>
88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 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
|
||
1. ...
|
||
2. ...
|
||
|
||
**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.* |