| name | ux-states-audit |
| description | Audit UI code for missing loading states, empty states, and error states. Every async operation and data-driven UI must handle all three. Finds gaps and implements the missing states using the app's existing patterns. |
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
- Identify the scope from the user's request
- Find every component that fetches data or triggers async work
- For each: check whether loading, empty, and error states are handled
- Implement missing states using the patterns found in Step 0
- 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.
