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.