ux-principles
UX principles review — Laws of UX (Fitts, Hick, Doherty, Peak-End, Gestalt, …) plus progressive disclosure, affordances, mapping, defaults, and forgiveness. Complements ux-heuristics.
Install
npx skills add https://github.com/sanmidable/ux-principles --skill ux-principlesUX principles review
Apply psychology and interaction principles to a screen or flow. One job: explain and prioritize principle-level guidance. Do not run a Nielsen scorecard here — that belongs to ux-heuristics. Do not redesign or edit code unless asked.
Ownership (no double-counting)
| Skill | Owns |
|---|---|
ux-heuristics |
Nielsen's 10 usability heuristics (usability problem scorecard) |
ux-principles (this skill) |
Laws of UX + classic principles below |
Anti-overlap rules:
- If the issue is fully a Nielsen violation (status, errors, consistency, recall, etc.), say so and defer the finding to
ux-heuristics— do not re-score it here. - Jakob's Law, Mental Model, Miller's Law, Chunking, Working Memory, general Cognitive Load, Occam's Razor, and Paradox of the Active User are folded into Nielsen — mention as mechanism only, never as standalone principle findings.
- Accessibility sizing/contrast/ARIA → a11y skill. Motion craft → animation skills.
- One root cause → one finding. Cite the primary principle; mention secondary effects in Why.
Rubrics
| File | Contents |
|---|---|
| laws.md | Fitts, Hick, Doherty, Peak-End, Serial Position, Von Restorff, Zeigarnik, Goal-Gradient, Tesler, Postel, Gestalt, Aesthetic-Usability (caution) |
| principles.md | Progressive disclosure, affordances & signifiers, natural mapping, smart defaults, forgiveness, direct manipulation, perceived performance |
Workflow
1. Resolve scope and mode
| Mode | Coverage | Finding cap |
|---|---|---|
quick |
Primary path; HIGH/MEDIUM only | 5 |
full |
Full requested scope + edge states | 12 |
Default quick. State the screen/flow and primary task.
2. Walk the task
Complete or simulate the primary path. Prefer evidence over speculation.
3. Apply laws, then classic principles
- Load laws.md — check each applicable law.
- Load principles.md — check each classic principle.
- Skip folded-into-Nielsen items as standalone findings.
- Consolidate duplicates.
4. Severity
CRITICAL— blocks task, data loss, or hostile peak/end with no escapeHIGH— major friction from choice overload, unhittable targets, missing progress near goals, brittle input, etc.MEDIUM— meaningful inefficiency or confused grouping/disclosureLOW— polish;fullmode only
5. Read-only by default
Do not edit product code unless asked to implement.
Output format
# UX principles review: [scope]
**Mode:** quick | full
**Primary task:** …
## Principles hit
| Principle | Status | Notes |
| --- | --- | --- |
| Fitts's Law | ok / issue / n/a | … |
| … | | |
(Include only principles you actually assessed.)
## Findings
| Sev | Principle | Location | Issue | Why | Fix |
| --- | --- | --- | --- | --- | --- |
| HIGH | Hick's Law | … | … | … | … |
## Defer to ux-heuristics
- (Nielsen-owned issues noticed but not scored here)
## Strengths
- 2–3 principle-aligned things that already work
## Out of scope / not verified
- …
Common mistakes
- Re-running a full Nielsen audit inside this skill
- Treating Aesthetic-Usability Effect as a positive score
- Filing Gestalt clutter as H8 and as a principle finding — pick one owner (
ux-heuristicsH8 vs Gestalt when grouping relationships are wrong) - Padding to the finding cap
Related
bots
Turns chosen Grok Bots into a shakeable pile, portfolio cards and an org chart page, each with a link to copy the bot, with private details stripped.
prose
Writes posts and breakdowns that open on where the author stands, show the options that lost, give exact numbers and mark every guess as a guess.
stageshow
Build faux product UI that looks real — stills, cursor demos, phones, dashboards, bento grids and marketing heroes in React and CSS.
avatar
Draws any object as a flat character with two capsule eyes, then animates its whole body so it glances, blinks, breathes, follows the pointer and falls asleep.
frames
Records a performance trace of one interaction on a throttled CPU, names what drops frames or delays input, then proves the fix with a second trace.
keyboard
Walks a running page with the keyboard alone, records every focus stop and reports controls it cannot reach, see or operate.