ux-validator

UX Validator Agent — User Experience Verification

Absorbed from Autopus-ADK ux-validator agent. Phase 3.5: Runs automatically after Phase 3 when frontend files (.tsx/.vue/*.svelte) were modified. Checks accessibility, loading states, error states, responsive behavior.

---

Trigger Condition

Auto-activate in Phase 3.5 when implementation included ANY of:

• *.tsx / *.jsx files
• *.vue files
• *.svelte files
• *.css / *.scss with layout changes

SKIP if only backend files modified.

---

Check 1 — Accessibility (WCAG 2.1 AA)

# Scan for common accessibility issues
grep -rn "<img" src/ | grep -v "alt="                      # Missing alt
grep -rn "<input\|<textarea\|<select" src/ | grep -v "id=" # Missing ID for label
grep -rn "<label" src/ | grep -v "htmlFor=\|for="          # Label without htmlFor
grep -rn "onClick\|onChange" src/ | grep "div\|span"        # Non-semantic interactives

Issues:

• <img> without alt → FAIL
• <input> without associated <label> → FAIL
• onClick on <div> or <span> without role="button" → FAIL
• Error messages without role="alert" → WARN
• Missing aria-label on icon-only buttons → WARN

Focus Management

For modals/dialogs:

// Required: focus moves into dialog on open
useEffect(() => {
  if (isOpen) firstFocusableRef.current?.focus()
}, [isOpen])

// Required: focus returns to trigger on close
useEffect(() => {
  if (!isOpen) triggerRef.current?.focus()  
}, [isOpen])

---

Check 2 — Loading States

For every component that fetches data:

□ Loading skeleton or spinner shown during fetch
□ Button disabled during form submission (prevents double-submit)
□ Cursor changes to "not-allowed" on disabled elements
□ Progress indication for long operations (> 2 seconds expected)

Detect missing loading states:

grep -rn "useQuery\|useMutation\|fetch\|axios" src/ |
  # For each file, check if isLoading/isPending is used

---

Check 3 — Error States

□ User-facing error message (not raw Error.message or stack trace)
□ Error displayed near the failing operation
□ Retry option available for network errors
□ Error boundary wraps dynamic content sections
□ Form field errors inline (not just alert at top)