ux-states-audit

# UX States Audit Every piece of UI that fetches data or triggers async work has three states beyond the happy path: **loading**, **empty**, and **error**. LLMs implement the happy path and leave the rest blank. This skill finds and fills those gaps. This is distinct from error-audit: error-audit finds errors that are *suppressed*. This finds states that were *never implemented*. ## Step 0: Understand existing patterns Before touching anything, read the codebase to understand how it currently handles these states: - What components or primitives exist for loading (skeletons, spinners, shimmer)? - What does an empty state look like — is there a shared component, or inline? - How are errors shown to users — toast, inline message, error boundary? Use these patterns exclusively. Don't introduce a new loading spinner if one already exists. ## What to look for **Missing loading state:** - Data fetch starts, nothing changes in the UI until data arrives - Button triggered action with no pending/disabled state - Form submission with no in-progress indicator - Navigation or route transition with no feedback **Missing empty state:** - List or table that renders nothing (blank space) when data is an empty array - Search results that show nothing without explanation - Dashboard widgets that disappear when there's no data instead of explaining why **Missing error state:** - Fetch fails → component renders identical to loading or blank - Form submission fails → nothing visible changes - Mutation errors that are caught in the data layer but never reach the UI ## Process 1. Identify the scope from the user's request 2. Find every component that fetches data or triggers async work 3. For each: check whether loading, empty, and error states are handled 4. Implement missing states using the patterns found in Step 0 5. Report what was added, by component ## Fix principles - Loading states should be immediate — shown before the first byte arrives - Empty states should explain the situation and, where appropriate, offer an action ("No results — try a different search") - Error states should say what went wrong and what the user can do (retry, go back, contact support) - Don't invent new UI primitives — use what already exists in the codebase ## Reference files - `references/ux-patterns.md` — Framework-specific patterns for missing loading, empty, and error states. Detection patterns, bad/fix examples. Read before starting the audit. ## Report Summarize by component: which states were missing, what was added.