| name | interaction-patterns |
| description | Heuristic eval against Nielsen's 10 usability heuristics plus a WCAG 2.2 first-pass for keyboard, focus, contrast, and motion. Use when reviewing a UI's interaction design and baseline accessibility together. |
| allowed-tools | Read Bash |
| argument-hint | [--target <url-or-path>] [--scope <component|page|flow>] |
| mode | ["audit"] |
Interaction Patterns
Purpose
Walk a UI surface (a page, a component, or an end-to-end flow) against
Nielsen's 10 usability heuristics and a WCAG 2.2 first-pass for the
fast-to-check criteria — keyboard reachability, focus visibility, color
contrast, and motion/animation. Produces a finding-by-finding report
with severity and a remediation hint. Not a full a11y scan (see
a11y-scan for tool-driven scanning); this is the structured-thinking
pass that catches what tools miss.
Scope
In:
- One target surface — page URL, component path, or flow description.
- Nielsen's 10 heuristics, applied as a checklist.
- WCAG 2.2 fast-check criteria: 2.1.1 (keyboard), 2.4.7 (focus visible),
1.4.3 / 1.4.11 (contrast), 2.3.3 (animation from interactions),
2.2.2 (pause / stop / hide).
- A markdown report with severity tags and remediation hints.
Out:
- Tool-driven a11y scanning (axe, Pa11y, Lighthouse) — that's
a11y-scan.
- Visual design critique (color palette, spacing system, brand
cohesion) — that's
mockup-review.
- User research findings against real users — that's
usability-review
with a recruited cohort.
When to use
- Before a feature ships, as a structured second-pass after design
hand-off and before QA.
- When a designer says "I think this flow is fine" and you want a
reproducible heuristic walk to confirm.
- For component-library primitives — every primitive should pass the
full Nielsen + WCAG fast-check before adoption.
- During a design-system upgrade, against the project's flagship flows,
to catch interaction regressions.
When NOT to use
- For a brand-new mockup with no behavior yet — use
mockup-review
first; this skill needs interaction states to evaluate.
- As a substitute for the automated
a11y-scan — heuristic eval finds
different bugs than rule-based scanners. Run both.
- For server-side / API-only changes. No UI, no heuristics.
Automated pass
There is no fully automated pass — heuristic evaluation is judgment
work. The skill scaffolds the report and prompts the evaluator
through each heuristic.
-
Resolve the target:
target="${TARGET:?--target required: URL, component path, or flow id}"
scope="${SCOPE:-page}"
-
For each Nielsen heuristic, the evaluator answers: pass / minor /
major / catastrophic / N/A. The skill emits a template:
## H1. Visibility of system status
- Verdict: <pass|minor|major|catastrophic|n/a>
- Notes: <what feedback does the system give for state changes?
loading, success, error, in-progress, queued?>
- Findings: <bullet list>
## H2. Match between system and real world
## H3. User control and freedom
## H4. Consistency and standards
## H5. Error prevention
## H6. Recognition rather than recall
## H7. Flexibility and efficiency of use
## H8. Aesthetic and minimalist design
## H9. Help users recognize, diagnose, and recover from errors
## H10. Help and documentation
-
WCAG 2.2 fast-pass section. Each criterion has a yes/no/n/a check:
## WCAG 2.2 fast-pass
- 2.1.1 Keyboard: every interactive element reachable + operable
via keyboard alone? <yes|no|partial>
- 2.4.7 Focus visible: focused element has a visible indicator
(not relying on default that's overridden)? <yes|no>
- 1.4.3 Contrast (minimum): text contrast ≥ 4.5:1 (3:1 large)?
<yes|no|spot-checked>
- 1.4.11 Non-text contrast: UI control + state indicators ≥ 3:1?
<yes|no>
- 2.3.3 Animation from interactions: any motion ≥ 5s respects
prefers-reduced-motion? <yes|no|n/a>
- 2.2.2 Pause / stop / hide: any auto-updating content can be
paused? <yes|no|n/a>
-
Severity rollup. The report header shows the count by severity and
the worst finding. Catastrophic blocks merge; major requires an
ADR-style explicit accept; minor / cosmetic logged for next sprint.
Manual pass
For a fast spot-check, the evaluator uses a printed Nielsen card and
walks the surface in three modes:
- Mouse-only — does the obvious path work?
- Keyboard-only — Tab through every element. Does focus ever get
trapped or jump over an interactive element?
- Reduced-motion — flip the OS toggle. Anything still spinning,
parallaxing, or auto-playing?
…then write up the findings in a 5-line note. Skip the full template
for one-off checks.
Known gotchas
- Heuristic eval is reviewer-dependent. Two evaluators on the same
surface find ~60% overlap, not 100%. That's expected — both lists
are valid. Don't argue findings away; record them.
- WCAG 1.4.3 contrast check needs a tool. Eyeballing 4.5:1 is
unreliable. Use a contrast picker (browser dev-tool, Stark,
Contrast). Don't claim "yes" without measuring.
- Focus visibility regressions love
outline: none. A common bug:
designer removes the default outline and adds a :focus-visible
rule that only covers some elements. Tab through ALL elements, not
just the ones in the design.
- Modal / overlay focus traps. A correctly-focused modal moves
focus in on open and returns focus to the trigger on close.
Drive-by review misses this — explicitly open and close every
modal as part of the keyboard pass.
- prefers-reduced-motion is not a free pass to remove animation.
Subtle position/opacity transitions are usually fine. The criterion
targets motion that crosses the screen, parallax, and auto-playing
video. Be specific in findings.
- "Aesthetic and minimalist" (H8) is the most-abused heuristic.
It's not "make it pretty" — it's "don't put information on the
screen that the user doesn't need right now." Findings here should
cite specific noise, not vibes.
References
