accessibility

name	accessibility
description	Use when building UI that ships to users, when reviewing for WCAG AA compliance, when adding keyboard navigation, when ensuring screen reader support, when auditing color contrast, or when preparing a UI surface for an EU or government customer.

Accessibility

Overview

Establish WCAG AA as the baseline floor for every UI surface — before it ships. Output is .forge/accessibility.md — the semantic-HTML rules, the ARIA usage policy, keyboard navigation requirements, focus management rules, contrast policy, reduced-motion respect, and the screen-reader testing checklist. Pairs with design-system (which defines the visual tokens that meet contrast) and interaction-patterns (which defines the keyboard and focus contract).

When to Use

• A UI surface is going to production and there's no accessibility audit
• The product ships to EU, government, healthcare, or education customers (legal requirement)
• A user reports that they can't use a feature with keyboard or screen reader
• A new component category is being added (modal, drawer, command palette) and focus management is unclear
• An existing UI is being audited and ARIA usage looks suspicious

When NOT to Use

• Internal CLI tools or backend services with no UI
• Throwaway prototypes that will never ship
• Single one-line copy changes that don't touch interaction or structure

Common Rationalizations

Thought	Reality
"Accessibility is a nice-to-have"	It's a legal requirement in most markets (ADA in US, EAA in EU, AODA in Canada) and a usability requirement everywhere.
"We'll add it later"	Retrofitting a11y costs 10x building it in. Every component pattern picked without a11y becomes a refactor.
"Our users don't need it"	You don't know that — assistive tech use is often invisible. ~20% of users have a disability in some form.
"ARIA fixes everything"	ARIA overuse is worse than no ARIA. Native semantic HTML always beats <div role="button">.
"Just make the visible thing look right"	Screen readers see structure, not pixels. A visually-correct page can be unusable with VoiceOver.
"Color is enough to signal state"	Colorblind users can't see red-vs-green; every meaningful color needs a text or icon backup.

Red Flags

• A <div onClick={...}> instead of <button> (not keyboard accessible by default)
• ARIA roles applied to elements that already have native semantics (<button role="button"> is a smell)
• outline: none on a focusable element with no replacement focus-visible style
• A modal that doesn't trap focus, doesn't return focus on close, or can't be closed with Esc
• A form <input> without a <label> (or aria-label for icon-only)
• Color used as the only signal for state (red = error, green = success, no icon, no text)
• An animation that violates prefers-reduced-motion
• A heading skipped (<h1> followed by <h3> with no <h2>)
• Image with no alt (or alt="" for non-decorative images)

Core Process

Step 1: Establish WCAG AA baseline

In .forge/accessibility.md, declare the conformance target (AA at minimum for most products; AAA only where regulatory). Document which assistive technologies are tested against:

• VoiceOver on macOS Safari
• VoiceOver on iOS Safari
• NVDA on Windows Firefox
• TalkBack on Android Chrome

Step 2: Audit semantic HTML usage

The rule: prefer native elements over ARIA every time.

Use	Not
<button>	<div role="button">
<a href>	<div onClick={navigate}>
<input type="checkbox">	<div role="checkbox">
<dialog> or <div role="dialog"> with focus trap and labelling	<div className="modal">
<nav>, <main>, <aside>, <header>, <footer>	<div> everywhere
<ul>/<li> for lists	A pile of <div>s

Run a structural audit: every interactive element is a native interactive element, or has a documented reason it isn't.

Step 3: Review ARIA usage (sparingly)

The rules for ARIA:

1. No ARIA is better than bad ARIA. A wrong aria-label lies to screen readers.
2. Use ARIA only when native semantics aren't enough — e.g., to announce live regions (aria-live), to label icon-only buttons (aria-label), to associate hint text (aria-describedby), to wire combobox/listbox patterns that have no native equivalent.
3. Never add a role that the element already has. <button role="button"> is a smell.
4. Test what ARIA does — open VoiceOver and listen, don't trust the visual inspector.

Step 4: Verify keyboard navigation

For every interactive element and every page:

• Tab order matches visual reading order
• Every interactive element has a visible focus-visible style (2px outline, sufficient contrast)
• Esc closes any modal, drawer, popover, command palette
• Focus is trapped inside modals (no Tab leak to background)
• Focus returns to the trigger element when a modal closes
• Arrow keys work where they should (menus, lists, comboboxes, custom controls)
• Enter and Space both activate buttons; Enter activates links

Cross-reference interaction-patterns for the canonical keyboard contract.

Step 5: Check color contrast

• Body text: 4.5:1 contrast against background (AA)
• Large text (≥18pt or 14pt bold): 3:1
• Non-text UI components (icons, focus rings, borders that convey state): 3:1
• State conveyed by color must also be conveyed by text or icon

Audit every token pairing in design-system — every text/background combination meets AA. Document the contrast ratio next to each token.

Step 6: Verify motion respects prefers-reduced-motion

• Animations longer than 100ms are disabled when prefers-reduced-motion: reduce is set
• Parallax, autoplay, marquee, infinite carousels are off by default and require explicit user opt-in
• Essential motion (loading indicators) remains, but at minimal intensity

Step 7: Create the screen reader testing checklist

For every UI surface before it ships:

• Tab through every focusable element in order — no missing or unreachable element
• VoiceOver reads each element with meaningful, non-redundant text
• Modals announce themselves on open and trap focus
• Form errors announce when they appear (role="alert" or live region)
• Loading states are announced (aria-busy + aria-live="polite")
• Images have alt (decorative = empty alt="")
• Headings form a valid outline (no skipped levels)

Verification

• .forge/accessibility.md written with the conformance target
• Every interactive element is a native interactive element (or has documented ARIA + reason)
• No <div onClick> in the codebase (grep-verified)
• Every form input has a label (visible or aria-label)
• Contrast verified AA for every text/background token pairing
• No outline: none without a focus-visible replacement
• Every modal traps focus and restores it on close
• prefers-reduced-motion is respected (verified in a test or storybook)
• Last 3 UI PRs ran through the screen reader checklist