1
# Accessibility Rules
2
3
## Semantics first
4
5
1. **Use the element that means what you mean.** A `button` for an action, an `a[href]`
6
   for navigation, `input` for input. Every native element brings keyboard behavior,
7
   focus handling and a role for free.
8
2. **Never put a click handler on a div or span.** It is unreachable by keyboard and
9
   invisible to assistive technology. If you catch yourself adding `tabindex`, `role`
10
   and `onKeyDown` to a div, you wanted a button.
11
3. **ARIA is a last resort, not a garnish.** The first rule of ARIA is not to use ARIA.
12
   A wrong role is worse than no role, because it overrides what was correct.
13
4. **Headings describe structure, not size.** One `h1` per page, no skipped levels.
14
   Use CSS for the size you want.
15
16
## Names
17
18
5. **Every control needs an accessible name.** A `label` tied to the input by `for`, or
19
   `aria-label` where no visible label exists.
20
6. **Icon-only buttons need a name.** An SVG is not a name. Add `aria-label` and mark
21
   the icon `aria-hidden="true"`.
22
7. **Link text must make sense alone.** Screen reader users navigate by a list of
23
   links; "click here" and "read more" are useless in that list.
24
8. **Every meaningful image needs alt text describing its content.** Every decorative
25
   image needs `alt=""`, not a missing alt.
26
27
## Keyboard
28
29
9. **Everything doable with a mouse must be doable with a keyboard.** Tab to it, Enter
30
   or Space to activate it, Escape to dismiss it.
31
10. **Never remove the focus outline without replacing it.** `outline: none` with no
32
    replacement makes the page unusable for keyboard users. A visible, high-contrast
33
    focus style is not optional.
34
11. **Tab order follows visual order.** Do not reorder with positive `tabindex`. Fix the
35
    DOM order instead.
36
12. **Trap focus inside a modal while it is open**, restore it to the trigger on close.
37
38
## Visual
39
40
13. **Text contrast is at least 4.5:1**, or 3:1 for large text. Check it, do not
41
    estimate it. Placeholder and disabled text are the usual failures.
42
14. **Never use color as the only signal.** Pair it with text, an icon, or a pattern.
43
15. **The interface must work at 200% zoom** and at 320px wide without horizontal
44
    scrolling.
45
16. **Respect `prefers-reduced-motion`.** Disable non-essential animation when it is set.
46
47
## Dynamic content
48
49
17. **Announce important changes** with a live region. A result that appears silently
50
    does not exist for a screen reader user.
51
18. **Move focus deliberately** after a navigation or a modal opens, so the next Tab
52
    lands somewhere sensible.
53
19. **Form errors are associated with their field** by `aria-describedby`, and are text,
54
    not just a red border.
55