stuffbucket Design Audit
Audit and improve front-end interfaces using 15 established usability principles.
What This Skill Does
Perform a comprehensive design audit — thinking like a senior UX designer reviewing an interface end-to-end. Inspect existing code against 15 established design principles, identify problems at component and system level, rate severity, and provide concrete fixes.
This is not a surface-level lint. Evaluate the full picture: component issues, cross-page consistency, design system coherence, interaction patterns, information architecture, and the holistic user journey.
Who This Is For
Anyone with front-end code to improve. Adjust language to the user:
- Most users won't know UX jargon — explain why each principle matters
- If user seems UX-savvy, be concise and reference principles by name
- When in doubt, explain. Educational value is part of the skill's purpose.
The 15 Usability Principles
| # | Principle |
|---|---|
| 1 | Visibility of System Status |
| 2 | Match Between System and Real World |
| 3 | User Control and Freedom |
| 4 | Consistency and Standards |
| 5 | Error Prevention |
| 6 | Recognition Over Recall |
| 7 | Flexibility and Efficiency |
| 8 | Aesthetic and Minimalist Design |
| 9 | Error Recovery |
| 10 | Help and Documentation |
| 11 | Affordances and Signifiers |
| 12 | Structure |
| 13 | Accessibility |
| 14 | Perceptibility |
| 15 | Tolerance and Forgiveness |
For detailed definitions, violation patterns, and fix guidance: read references/heuristics.md.
Severity Scale
| Rating | Label | Action |
|---|---|---|
| 4 | Catastrophe | Must fix — users cannot complete tasks |
| 3 | Major | High priority — users struggle significantly |
| 2 | Minor | Low priority — users notice but work around |
| 1 | Cosmetic | Fix if time — aesthetic issue only |
Three factors: Frequency (rare/occasional/frequent) x Impact (workaround/struggle/blocked) x Persistence (one-time/recurring). Rate by user impact, not fix difficulty.
Two Input Modes
Local Project (source code) — Full access to read, evaluate, and implement fixes.
Live Website (URL) — Report-only. Use WebFetch. Note limitations: evaluating served HTML, not source; JS behavior, loading states, dynamic content may not be observable.
Workflow
Discussion Mode (Default)
- Discover — Read front-end code (local) or fetch page (URL). Identify interface type, stack, primary flows.
- Evaluate — Read
references/heuristics.md. Systematically inspect against all 15 principles at component, hidden UI, visual design, and system levels. - Report — Present structured findings grouped by severity (see format below).
- Discuss — Walk user through findings. Explain why each matters. Let user decide what to skip.
- Implement — Fix all findings by default through the design system. Read
references/patterns.mdfor code examples. Three phases: establish design foundation (tokens), apply fixes, design coherence pass. (Local only.) - Verify — Post-implementation review. Not "confirm you did it" — focused second look for fix-introduced issues and first-pass misses. Typically catches 3-8 additional findings.
Quick Mode
- Discover → 2. Evaluate → 3. Summary → 4. Implement all → 5. Verify → 6. Report changes.
Evaluation Process
Step 1: Discover
Local: Read ALL front-end files. Include application shell (index.html, global CSS, layout). Multi-page projects: read every page — different pages have different issues.
URL: Fetch key pages (up to 5). Extract: document structure, semantic landmarks, accessibility attributes, link/button patterns, stylesheets.
Step 2: Evaluate
Read references/heuristics.md first.
Walk through every principle, one by one. For each, ask: "Does this interface violate this principle anywhere?"
Evaluate at these levels:
- Component level — HTML structure, CSS styling, JS behavior, accessibility attributes, responsive behavior
- Hidden/dynamic UI — Modals, dropdowns, drawers, tooltips, accordions, tabs, form validation states, empty/loading/error states, confirmation dialogs. These get the least design attention and contain the worst issues.
- Visual design — Typography hierarchy, spacing/proximity, visual weight, color purpose, information density, alignment, interactive state visibility
- System level — Cross-page consistency, interaction patterns, design system coherence, navigation, meta/SEO
Important: If finding fewer than 10 issues, go back through "clean" principles and look harder — especially visual design, hidden UI, cross-page patterns, and edge cases. If all findings are ARIA labels and semantic HTML, you're missing the visual design layer.
Principle Coverage Verification: Before writing the report, confirm every one of the 15 principles was consciously assessed.
Step 3: Report
## UX Design Audit Report
**Scope:** [what was evaluated]
**Source:** [all files or URLs reviewed]
**Interface type:** [dashboard / form / e-commerce / etc.]
### Summary
| Severity | Count |
|----------|-------|
| 4 - Catastrophe | X |
| 3 - Major | X |
| 2 - Minor | X |
| 1 - Cosmetic | X |
### Quick Wins
1. [Finding] (Severity X) — [one-line fix]
### Findings
#### [Severity 4] Finding title
- **Principle:** [which principle violated]
- **Location:** `file.tsx:42`
- **Issue:** [what's wrong]
- **User impact:** [what real users experience]
- **Fix:** [specific, actionable recommendation]
### Strengths
[At least 3 things done well. A report that's only negative is demoralizing.]
Step 5: Implement
Read references/patterns.md for concrete code examples.
Phase 1: Design Foundation — Extract and consolidate implicit design system. Define CSS custom properties for spacing scale, type scale, color palette, shadows, radii, transitions.
Phase 2: Apply Fixes — Through the design system, not with ad-hoc values. Be confidently visible — if type scale is flat, establish clear hierarchy.
Phase 3: Coherence Pass — Review holistically. Check spacing rhythm, typography consistency, color discipline, icon consistency, component patterns, interactive states, transitions, alignment, semantic-visual sync.
Step 6: Verify
Check for fix-introduced issues: semantic-visual sync, specificity conflicts, token leaks, visual balance shifts. Check for first-pass misses: complex components, state combinations, content edge cases.
Anti-Patterns
- Trending color sameness (indigo/purple/blue defaults)
- Cards for everything
- Competing CTAs — one primary per region
- Equal visual weight everywhere
- Padding as whitespace
- System structure instead of user tasks
- Low contrast text (never below 4.5:1)
Commands
/design-audit— Full evaluation with discussion/design-audit:evaluate— Report only, no implementation/design-audit:improve— Jump to implementation from existing evaluation/design-audit:quick— Auto-accept: evaluate and implement without discussion
References
references/heuristics.md— Read during evaluation. Definitions, violation patterns, severity guidance for all 15 principles.references/patterns.md— Read during implementation only. Code examples for common fixes.references/testing-methods.md— Usability testing, A/B testing, accessibility testing methods.