ss-audit

---
name: ss-audit
description: Audit screens for UX issues using Nielsen's heuristics and modern mobile UX best practices
license: MIT
---

# UX Audit
## Registry-first artifact boundary

When `.styleseed/project.json` and `.styleseed/artifacts/index.json` exist, resolve the requested artifact ID first, then read only `.styleseed/bundles/<artifact-id>.md` and `.styleseed/manifests/<artifact-id>.json`. Never fall back to the global legacy bundle for a registry project. Legacy projects may use `.styleseed/effective-rules.md` only when no registry exists.

## When NOT to use

- For accessibility-only issues → use `/ss-a11y`
- For design system token/golden-rule compliance → use `/ss-review`
- For copy/microcopy quality → use `/ss-copy`
- For brand new screens that don't exist yet — design first with `/ss-page` or `/ss-flow`

Target: **$ARGUMENTS**

## Audit Framework

### Nielsen's 10 Usability Heuristics

#### 1. Visibility of System Status
- [ ] Loading states present (skeleton screens, not spinners)
- [ ] Success/error feedback after actions (toast notifications)
- [ ] Progress indicators for multi-step flows
- [ ] Active state clearly shown on navigation items
- [ ] Real-time data has timestamp showing freshness

#### 2. Match Between System and Real World
- [ ] Labels use user's language, not technical jargon
- [ ] Icons are universally recognizable (Lucide standard set)
- [ ] Number formats match user expectations (comma separators, currency symbols)
- [ ] Date formats are locale-appropriate

#### 3. User Control and Freedom
- [ ] Back navigation available on all non-root screens
- [ ] Destructive actions have confirmation dialogs
- [ ] Undo available for reversible actions (toast with undo)
- [ ] Bottom sheet/modal can be dismissed (backdrop tap, swipe down, X button)
- [ ] No dark patterns (no forced actions, always a way to dismiss)

#### 4. Consistency and Standards
- [ ] Same action = same appearance everywhere
- [ ] Color meanings are consistent (green=success, red=error, brand=active)
- [ ] Text hierarchy follows the 5-level grayscale system
- [ ] Surface treatment follows the resolved grammar and brand recipe
- [ ] Spacing follows the resolved token scale and adapter constraints

#### 5. Error Prevention
- [ ] Destructive buttons are visually distinct (destructive variant)
- [ ] Form validation happens on blur (not while typing)
- [ ] Dangerous actions require explicit confirmation
- [ ] Input constraints are visible before errors occur (character limits, format hints)

#### 6. Recognition Rather Than Recall
- [ ] Icon controls have accessible labels; navigation labels follow the selected adapter
- [ ] Current state visible without memorization (active tab highlighted)
- [ ] Recent/frequent items shown for quick access
- [ ] Placeholder text shows expected format

#### 7. Flexibility and Efficiency
- [ ] Key actions are reachable through an appropriate product-specific path
- [ ] Refresh behavior follows the platform adapter and the product's data semantics
- [ ] Touch targets >= 44x44px (no tiny tap areas)
- [ ] Frequently used actions are placed according to the resolved navigation adapter

#### 8. Aesthetic and Minimalist Design
- [ ] Each screen focuses on ONE primary task
- [ ] No decorative elements that don't serve a purpose
- [ ] Information pyramid respected (most important = biggest)
- [ ] Card and collection density follows the resolved grammar and task complexity
- [ ] No competing visual elements (one hero metric per page)

#### 9. Help Users Recover from Errors
- [ ] Error messages explain what went wrong in plain language
- [ ] Error messages suggest how to fix the problem
- [ ] Partial failures don't break the whole page (one card fails, others load)
- [ ] Network errors show retry button
- [ ] Form errors highlight the specific field

#### 10. Help and Documentation
- [ ] Empty states guide users to take action
- [ ] Onboarding for first-time features (if applicable)
- [ ] Tooltips for complex metrics (if applicable)

### Mobile-Specific UX Checks

#### Touch & Gesture
- [ ] Touch targets minimum 44x44px
- [ ] Minimum 8px between adjacent touch targets
- [ ] No hover-dependent interactions (mobile has no hover)
- [ ] Swipe gestures have visible affordances (carousel indicators)

#### Performance Perception
- [ ] Skeleton screens appear within 300ms
- [ ] Optimistic updates for user actions
- [ ] Above-the-fold content loads first
- [ ] No layout shift after content loads

#### Safe Areas
- [ ] Content not hidden behind notch/Dynamic Island
- [ ] Bottom content not behind home indicator
- [ ] Navigation surfaces respect the platform safe-area contract when one applies

### Dark Pattern Prevention
- [ ] No forced bottom sheets on entry
- [ ] No exit-prevention dialogs
- [ ] Every screen has a way to go back/dismiss
- [ ] CTA labels clearly describe the action
- [ ] No manipulative graphics (begging, urgency)

## Output Format

1. **Score**: A+ to F rating with breakdown
2. **Critical Issues**: Must fix (blocks usability)
3. **Major Issues**: Should fix (degrades experience)
4. **Minor Issues**: Nice to fix (polish)
5. **Recommendations**: Specific code changes for each issue