Skip to content

Accessibility Quick Reference

WCAG 2.1 AA requirements for NepWalk design. These are non-negotiable.

Colour Contrast

Text type Minimum ratio Check with
Normal text (< 18px or < 14px bold) 4.5:1 design_system.md token pairings
Large text (≥ 18px or ≥ 14px bold) 3:1 design_system.md token pairings
UI components (borders, icons) 3:1 design_system.md token pairings
Decorative elements no requirement —

Pre-approved token pairings (confirmed WCAG AA): These are checked during design: system and documented in design_system.md. Always use token names in specs — never invent new colour combinations.

Touch Targets

  • Minimum 44×44px for ALL interactive elements on mobile
  • Applies to: buttons, links, icons used as buttons, tab bar items, checkboxes, toggles
  • If the visual element is smaller (e.g., a 16px icon), add invisible padding to reach 44×44px
  • Note the touch target in the component spec if the visual size is less than 44px

Typography

  • Never use colour alone to convey meaning (also need an icon or text label)
  • Text must scale to 200% in browser settings without horizontal scroll
  • Line height: minimum 1.5× font size for body text
  • Letter spacing: do not override to negative values

Focus Management

  • Every interactive element must have a visible focus indicator
  • Focus ring: 2px solid color-primary, 2px offset (defined in design_system.md)
  • Never outline: none without a replacement focus indicator
  • Tab order must follow visual reading order (left to right, top to bottom)
  • Modals trap focus and return focus to the trigger element on close
  • Toast and alert messages do not disrupt keyboard focus

Forms

  • Every input has a visible <label> — placeholder text alone is NOT a label
  • Error messages linked to their input via aria-describedby
  • Required fields marked with visible indicator (not just colour)
  • Error message appears below the field, in color-error token + icon
  • Validation triggers: blur for format errors, submit for server errors

Dynamic Content

  • aria-live="polite" for non-urgent updates (new notification count, save confirmation)
  • aria-live="assertive" for urgent updates (error, loss of connection)
  • Loading states: aria-busy="true" on the container, aria-label="Loading" on spinner
  • Progress updates announced via aria-live

Images and Icons

  • Decorative images: alt="" or aria-hidden="true"
  • Informative images: descriptive alt text
  • Icons used as buttons: aria-label on the button element
  • Icons next to text: aria-hidden="true" on the icon (the text provides the label)

PWA-Specific

  • Offline indicator: user must know when they're offline — do not silently fail
  • Touch gestures (swipe/drag): must have keyboard alternative
  • Drag to reorder: keyboard alternative with arrow keys, announce position via aria-live

Quick checklist for every spec

[ ] All text meets 4.5:1 contrast with background token
[ ] All interactive elements ≥ 44×44px touch target
[ ] All form inputs have visible labels
[ ] Focus ring visible on all interactive elements
[ ] Error messages use aria-describedby
[ ] Loading states use aria-busy
[ ] Dynamic updates use aria-live
[ ] Tab order is logical