ss-audit

name	ss-audit
description	Audit screens for UX issues using Nielsen's heuristics and modern mobile UX best practices
argument-hint	[file-path or screen-name]
allowed-tools	Read, Grep, Glob

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