Skip to content

guidance layer

Accessibility

Follow these accessibility rules when building user interfaces. All interactive content must be usable by people with diverse abilities, including those using assistive technologies.

Semantic HTML

  • Use semantic elements (<nav>, <main>, <article>, <section>, <header>, <footer>) for page structure.
  • Use heading elements (<h1>–<h6>) in logical hierarchy; never skip levels for styling.
  • Use <button> for actions and <a> for navigation; never use <div> or <span> as interactive elements without proper roles.
  • Use <label> elements explicitly associated with form inputs via for/id pairing.
  • Use lists (<ul>, <ol>, <dl>) for grouped items rather than styled <div> sequences.

ARIA Usage

  • Prefer native HTML semantics over ARIA; add ARIA only when no native element provides the required semantics.
  • Use aria-label or aria-labelledby for interactive elements that lack visible text labels.
  • Set aria-expanded, aria-selected, aria-checked states dynamically to reflect current UI state.
  • Apply role="alert" or aria-live="polite" for dynamic content that must be announced to screen readers.
  • Never use aria-hidden="true" on focusable elements.

Keyboard Navigation

  • All interactive elements must be reachable and operable via keyboard alone (Tab, Shift+Tab, Enter, Space, Arrow keys).
  • Maintain a logical tab order that follows the visual reading flow; avoid positive tabindex values.
  • Provide visible focus indicators on all focusable elements; never remove outline without a visible replacement.
  • Implement keyboard shortcuts for complex widgets (modals, dropdowns, tabs) per WAI-ARIA Authoring Practices.
  • Trap focus inside modal dialogs until dismissed; restore focus to the triggering element on close.

Color and Contrast

  • Maintain a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (WCAG AA).
  • Never use color as the sole means of conveying information; pair color with text, icons, or patterns.
  • Verify contrast in both light and dark modes if the application supports theme switching.
  • Ensure focus indicators have at least 3:1 contrast against adjacent colors.

Images and Media

  • Provide meaningful alt text for informative images; use alt="" for decorative images.
  • Provide captions or transcripts for video and audio content.
  • Avoid auto-playing media; if unavoidable, provide an immediate mechanism to pause or stop.
  • Ensure animated content can be paused and does not flash more than 3 times per second.

Forms and Errors

  • Associate error messages with their input fields using aria-describedby or aria-errormessage.
  • Display error summaries at the top of forms with links to the offending fields.
  • Do not rely solely on placeholder text as a label; placeholders disappear on input.
  • Group related form controls with <fieldset> and <legend>.
  • Provide clear instructions before the form and inline help where input format is constrained.

Responsive and Adaptive Design

  • Support zoom up to 200% without loss of content or functionality.
  • Use relative units (rem, em, %) for text and spacing rather than fixed pixels.
  • Ensure touch targets are at least 44x44 CSS pixels for mobile interfaces.
  • Test layouts with different text sizes, languages, and reading directions (LTR/RTL).

Testing and Verification

  • Run automated accessibility scans (axe-core, Lighthouse) in CI and fix all critical/serious issues.
  • Test with at least one screen reader (VoiceOver, NVDA, or JAWS) for major user flows.
  • Validate keyboard-only navigation for all primary workflows.
  • Note: full WCAG conformance requires manual testing with assistive technologies and expert review.