Principle accessibility

<!-- preload-canary: SWB-PRELOAD-PRINCIPLE-ACCESSIBILITY -->

Accessibility Principles

Accessibility bugs are correctness bugs. They are cheapest to fix before the first line of markup is written.

Semantic HTML First

Native elements carry built-in roles, keyboard behavior, and accessible names — no ARIA required.

• Prefer <button> over <div role="button">; prefer <a href> over <span onClick>. Native elements are accessible by default.
• Use landmark elements (<main>, <nav>, <header>, <footer>, <aside>) to define regions screen readers can navigate directly.
• Maintain a logical heading hierarchy (h1 → h2 → h3); never skip levels to achieve visual styling.
• Mark up lists with <ul>/<ol> + <li> — screen readers announce item count and position.
• Use <table> with <th scope> and <caption> for tabular data; never for layout.

ARIA: Use Sparingly

The first rule of ARIA: do not use ARIA if a native HTML element already provides the semantics.

• Never add redundant roles (<button role="button">) — they add noise without benefit.
• Every ARIA widget role has required owned elements and states; a listbox without option children is broken.
• Live regions (aria-live, aria-atomic) announce dynamic changes — use assertive only for time-critical alerts; default to polite.
• aria-label / aria-labelledby / aria-describedby are the canonical tools for providing accessible names when native labeling is insufficient.
• aria-hidden="true" on a focusable element is a contradiction — the element is both hidden from the tree and reachable by keyboard.

Keyboard Navigation & Focus

Every user who cannot use a pointer must be able to reach and operate every interactive element via keyboard alone.

• All interactive elements must be reachable by Tab and operable by Enter/Space; use arrow keys for composite widgets (menus, tabs, grids).
• Preserve DOM source order as the logical tab order; avoid tabindex values > 0 (they override natural order globally).
• Visible focus indicators are required (WCAG 2.2 SC 2.4.11 AA): the indicator must have ≥3:1 contrast against adjacent colors and sufficient area (at minimum, a solid 2px outline around the component perimeter). A thin 1px outline at 3:1 passes contrast but fails on area.
• Modals must trap focus while open — Tab cycles through focusable children; Escape closes and restores focus to the trigger element.
• Skip links (<a href="#main-content">) let keyboard users bypass repeated navigation; place as the first focusable element on the page.

Color, Contrast & Motion

Visual information conveyed by color alone is inaccessible to color-blind users.

• WCAG 2.2 AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (≥18pt or ≥14pt bold), 3:1 for UI components and graphical objects.
• Never use color as the only means to convey meaning — pair with text, icon, or pattern (e.g., error = red + icon + label).
• Respect prefers-reduced-motion: declare animations normally, then disable or reduce them inside @media (prefers-reduced-motion: reduce). The opt-in pattern (no-preference) is fragile in environments that do not evaluate media queries.
• WCAG 2.2 SC 2.5.8: touch/pointer targets must be ≥24×24 CSS px, or the offset from every adjacent target must be sufficient that a 24 px circle centred on each target does not intersect another.

Screen Reader & Assistive Tech

Automated tools (axe, Lighthouse) catch ~40% of issues; manual testing with a real screen reader catches the rest.

• Every <img> needs an alt attribute — empty (alt="") for decorative images, descriptive text for informative ones.
• Every form input needs an associated <label> via for/id or aria-labelledby — placeholder is not a label substitute.
• Status messages (save confirmation, cart update) must be announced without stealing focus: use a live region or role="status".
• Test with VoiceOver (macOS/iOS), NVDA or JAWS (Windows) — screen reader support for ARIA diverges. axe passing is necessary but not sufficient.

When Accessibility Engineering is Overkill

• Purely internal CLI tools with no graphical interface.
• Throwaway prototypes that will never be seen by end users.
• Admin tools with a documented legal exemption covering the specific user population.
• Public web and native UI: never overkill regardless of timeline or scope pressure.

Red Flags

Flag	Problem
<div onClick> or <span onClick> without role + tabindex	Not keyboard-reachable; not announced to screen readers
Missing alt attribute on <img>	Image content invisible to screen readers
tabindex="-1" on an element with no roving-tabindex parent and no programmatic focus() call	Silently unreachable: excluded from sequential tab order and nothing focuses it programmatically
Modal without a focus trap	Tab escapes the dialog; background content becomes operable
Color-only error signaling	Color-blind users miss the error state entirely
placeholder used as the visible label	Disappears on input; fails contrast at default browser styles
autofocus on page load without user consent	Disorienting for screen reader users who have not yet reached that element
aria-hidden="true" on a focused element	Element is simultaneously hidden from the accessibility tree and keyboard-reachable
Missing or low-contrast focus indicator	Keyboard users lose their position in the page