[UI/UX Design] Design a rate-limited error UI with recovery guidance #340

Description

HTTP 429 responses currently render the generic ErrorState which lacks a "wait N seconds" affordance. Design a rate-limited variant with countdown, dev-facing headers surfaced, and clear next-step microcopy.

Requirements and context

• Must be accessible (WCAG 2.1 AA), responsive, and documented in the design system
• Should be consistent with existing patterns and easy to review
• Relevant code: src/components/ErrorState.tsx
• Countdown must be pausable when tab is backgrounded

Suggested execution

• Fork the repo and create a branch
• git checkout -b uiux/rate-limit-error
• Implement changes
  • Add a "rate-limited" variant with numeric countdown and progress ring
  • Design a "why did this happen?" popover explaining backoff
  • Document Retry-After parsing convention
• Validate accessibility and responsive assumptions

Test and commit

• Run checks
  • npm run lint and component/visual tests
• Cover edge cases
  • Missing Retry-After, tab visibility change, reduced motion
• Include screenshots/before-after and accessibility (axe) notes

Example commit message

design: rate-limited error variant

Guidelines

• Minimum 95 percent test coverage
• Clear documentation
• Timeframe: 96 hours