accessibility_basics v1.0.0

name: "accessibility_basics" description: "Apply web accessibility fundamentals: WCAG 2.2 AA quick wins for alt text, keyboard navigation, color contrast, forms, and headings, plus how to run automated checks and manual screen reader tests. Use when auditing a page, reviewing a PR, building UI, or asked about alt text, contrast, keyboard access, or accessibility testing."

Purpose

Make a web page usable by people with disabilities using the highest-leverage fixes first. The reference standard is WCAG 2.2 at level AA. You do not need to memorize the spec; you need to work through the quick-win checklist, run one automated scan, and do one keyboard plus one screen reader pass. Details live in references/.

Workflow

1. Structure and text alternatives

• Every <img> gets an alt decision: informative images get a short description of what they convey; decorative images get alt="" so screen readers skip them; functional images (icons that act as buttons/links) describe the action or destination, not how the icon looks.
• Write alt text for the context, not the pixels. "Revenue chart showing 40% growth in Q3" beats "a bar chart". Skip "image of" or "photo of" prefixes; the screen reader already announces the image. Keep it under ~150 characters.
• Use real semantic markup: one h1, headings in order with no skipped levels, <nav>, <main>, <footer>, real <button> and <a>, lists as lists, tables with <th> headers.
• Set <html lang="..."> and give every page a descriptive <title>.

2. Keyboard pass

Put the mouse away. Tab through the whole page, Shift+Tab back, activate with Enter/Space:

• Every interactive element is reachable, and the tab order matches the visual order.
• Focus is always visible: never remove the outline without a replacement indicator of at least 3:1 contrast against adjacent colors.
• No keyboard traps: you can always tab out. Modal dialogs are the exception: focus must stay inside while open, Esc closes, and focus returns to the element that opened it.
• Drop in a skip link as the first focusable element (<a href="#main">Skip to main content</a>).
• Custom dropdowns, tabs, and comboboxes follow the ARIA Authoring Practices patterns for their widget.

3. Contrast check

• Normal text: 4.5:1 against its background. Large text (18pt+, or 14pt bold): 3:1.
• UI components, borders, icons, and focus indicators: 3:1 against adjacent colors.
• Check with the bundled CLI: python3 bin/check_contrast.py "#foreground" "#background".
• Never convey meaning by color alone. An error state needs text or an icon alongside the red.

4. Forms

• Every input gets an associated <label>. Placeholder text is not a label.
• Required fields, errors, and success states are announced: errors go next to their field and into an aria-live region so screen readers read them when they appear.
• Do not clear a user's entry on error; keep what they typed and say what to fix.

5. Automated scan

Run axe-core against the rendered page:

npm install -g @axe-core/cli
axe <url> --tags wcag2aa --exit

Lighthouse (lighthouse <url> --only-categories=accessibility) or pa11y (pa11y --standard WCAG2AA <file-or-url>) work as alternates. Automated tools catch roughly a third of issues; a clean scan is a floor, not a verdict.

6. Screen reader spot check

Fifteen minutes per major flow is enough to catch semantic and labeling bugs:

• VoiceOver (macOS): toggle with Cmd+F5, navigate with Ctrl+Option+arrow keys, interact with Ctrl+Option+Space, open the rotor with Ctrl+Option+U to list headings, links, and landmarks.
• NVDA (Windows, free): navigate with the arrow keys, jump through headings with H, list elements with Insert+F7.
• Listen for: labels on every form input, buttons announcing their purpose (not "button, button, button"), alt text on informative images, headings in logical order, errors announced when they appear.

Full command tables are in references/manual-test-guide.md.

Output Contract

When asked to audit or fix a page, produce:

1. A verdict per check (pass/fail/needs manual review) mapped to the quick-win list.
2. For each failure: the element or snippet, the WCAG 2.2 success criterion number, and the specific fix.
3. A re-test plan: which failures the automated scan will catch on re-run and which need the keyboard or screen reader pass again.

Operating Rules

1. Never invent WCAG numbers, ratios, or dates. Verify from references/ or the W3C before citing one.
2. Never claim a page "passes" on an automated scan alone; say which manual checks still need doing.
3. No accessibility overlay widgets as the fix. They do not make a page compliant.
4. Prefer native HTML elements over ARIA. Use ARIA to fill gaps, not to rebuild what the browser already provides.
5. When fixing, change the markup, not the person: an inaccessible pattern is a code bug, filed like any other bug.