| name | uix-lens |
| description | Activate for any ticket that changes React components, user-facing flows, or UI state. Ensures all five observable UI states are verified before state:ready-for-qa. |
| argument-hint | Component name, user flow, or ticket reference |
UIX — UI State Coverage Lens
Activate this lens when a ticket changes React components, pages, UI state, or any user-facing flow. It does not replace software-engineer-mode — it adds a mandatory pre-handoff gate on top of it.
When to Activate
Load this lens when the ticket changes any of the following:
- A React component or page (
src/components/, src/pages/, src/app/)
- User-facing routing or navigation
- Form validation or submission flows
- Data-fetching hooks or loading states (
useQuery, useMutation, Supabase realtime subscriptions)
- Auth-gated UI (redirects, role-based rendering,
RequireGuest, RequireAuth)
- Error boundaries or error display components
The Five States
Every user-facing UI change must be verified against all five states before claiming state:ready-for-qa. Name the component and confirm each state was observed:
| State | What to verify |
|---|
| Empty | Component renders correctly when there is no data — empty list, zero results, first-time user with no records |
| Loading | Skeleton, spinner, or suspense fallback renders correctly while data is in flight; no layout jump when content loads |
| Success | Data renders correctly when the Supabase query or mutation returns a successful result |
| Validation error | Field-level and form-level error messages render, are associated with the correct input (htmlFor/id pairing), and are visible without scrolling |
| System error | A Supabase error, network failure, or unexpected server response is caught and shown to the user without crashing the component or rendering a blank screen |
Additional Checks
Apply these when the ticket explicitly requires them or when the changed component is interactive:
- Accessibility — interactive elements have
aria-label or visible labels; keyboard navigation reaches all controls; focus order is logical after state changes
- Responsive — layout does not break at
sm / md breakpoints when the ticket touches layout or spacing
- Auth boundary — protected routes still redirect unauthenticated users; role-restricted views still gate correctly after the change
- State transition — if the component transitions from empty to success (e.g., after form submission triggers a refetch), verify the transition renders correctly without a flash, duplicate render, or stale data display
Pre-Handoff Gate
Before moving the ticket to state:ready-for-qa, post the following confirmation on the GitHub issue:
UIX verified:
- Empty: [what was observed]
- Loading: [what was observed]
- Success: [what was observed]
- Validation error: [what was observed]
- System error: [what was observed]
If a state is not applicable to this component (e.g., a static display component has no loading state), state why it was skipped. Do not leave fields blank — a blank field signals an untested state, not an inapplicable one.
Tester will verify these states independently. Submitting a ticket to QA without this confirmation means Tester is likely to return PARTIAL PASS on states that were never verified by Builder.
