ai-agents-workspace-starter: Skill for Claude Code

UX/Accessibility Audit

Overview

Structured checklist for finding and fixing accessibility and UX issues in frontend code.

When to Use

• Reviewing a new page or component for accessibility compliance
• Auditing existing UI for WCAG 2.1 AA gaps
• Improving interaction quality (loading states, feedback, empty states)
• Preparing for accessibility review

When NOT to use:

• Full page redesigns (that's a design task, not an audit)
• Backend logic changes
• Performance optimization (use performance-audit)

Checklist

Accessibility (WCAG 2.1 AA)

• All icon-only buttons have aria-label
• All form inputs have associated <label> with htmlFor
• Required fields marked with visible indicator + aria-required
• Color contrast meets 4.5:1 ratio (text) / 3:1 (large text)
• All interactive elements reachable via Tab key
• Focus indicators visible on all interactive elements (focus-visible)
• Images have meaningful alt text (or alt="" for decorative)
• Skip-to-content link present on pages with nav
• ARIA roles and landmarks used correctly
• Screen reader announces dynamic content changes (aria-live)

Interaction Quality

• Async operations show loading state (spinner/skeleton)
• Button clicks provide immediate feedback
• Form submissions show success/error messages
• Disabled elements explain why they're disabled (tooltip)
• Multi-step processes show progress indicator
• Empty states have helpful guidance / call-to-action
• Destructive actions require confirmation dialog
• Error messages are actionable (tell user what to do)

Visual Polish

• Consistent spacing and alignment
• Hover states on all interactive elements
• Smooth transitions for state changes (150-300ms)
• Consistent icon usage (size, style, spacing)
• Responsive behavior on mobile breakpoints

Code Patterns

Good:

// Accessible button with ARIA label
<button
  aria-label="Delete project"
  className="hover:bg-red-50 focus-visible:ring-2"
  disabled={isDeleting}
>
  {isDeleting ? <Spinner /> : <TrashIcon />}
</button>

// Form with proper labels
<label htmlFor="email" className="text-sm font-medium">
  Email <span className="text-red-500">*</span>
</label>
<input id="email" type="email" required aria-required="true" />