Accessibility Implementation

---
name: accessibility-implementation
description: "Guides autonomous agents to implement accessible web interfaces using semantic HTML, ARIA, keyboard navigation, and WCAG compliance."
metadata:
  tags: "accessibility, web-development, inclusive-design, aria, semantic-html, keyboard-navigation, wcag, screen-readers"
  source: "https://skilldb.dev/skills/autonomous-agent-skills/accessibility-implementation"
  pack: "autonomous-agent-skills"
  category: "Autonomous Agents"
---

# Accessibility Implementation

## When to use this skill
Use when the user says things like:
- "Help me implement accessibility in a web UI."
- "Make this component accessible with ARIA."
- "Audit this page for WCAG and semantic HTML."
- "Guide keyboard navigation for a custom widget."
- "Ensure color contrast meets WCAG standards."


You are an autonomous agent that builds inclusive web experiences. Accessibility is not a feature to be bolted on at the end — it is a fundamental aspect of quality software. Every interface you create should be usable by people with diverse abilities, using diverse input methods and assistive technologies.

## Philosophy

The web was designed to be accessible to all. When you write semantic HTML and follow established accessibility patterns, you are not adding extra work — you are building things correctly. Accessibility benefits everyone: keyboard users, screen reader users, people with motor impairments, people in bright sunlight, and people with temporary injuries. Build for the full spectrum of human ability.

## Techniques

### Semantic HTML First
- Use `<button>` for clickable actions, not `<div onclick>`. Buttons get keyboard support and screen reader announcements for free.
- Use `<a href>` for navigation, `<button>` for actions. Never use one when you mean the other.
- Use heading elements (`<h1>` through `<h6>`) in a logical hierarchy. Do not skip levels.
- Use `<nav>`, `<main>`, `<aside>`, `<header>`, `<footer>`, and `<section>` to define page landmarks.
- Use `<ul>`, `<ol>`, and `<dl>` for lists. Screen readers announce list length and position.
- Use `<table>` with `<thead>`, `<th>`, and `<caption>` for tabular data. Never use tables for layout.

### ARIA Attributes
- ARIA is a supplement, not a replacement. Use native HTML elements first. Only add ARIA when HTML alone cannot express the semantics.
- Use `aria-label` or `aria-labelledby` for elements that lack visible text labels.
- Use `aria-describedby` to associate descriptive text with form controls or complex widgets.
- Use `aria-live="polite"` for dynamic content updates that screen readers should announce (e.g., toast notifications, search results counts).
- Use `aria-expanded`, `aria-selected`, `aria-checked` to communicate widget state.
- Use `role` only when no native HTML element provides the needed semantics. Custom roles must implement all expected keyboard interactions.

### Keyboard Navigation
- Every interactive element must be reachable via the Tab key. Use `tabindex="0"` to add custom elements to the tab order.
- Never use `tabindex` values greater than 0. They disrupt natural tab order.
- Implement arrow key navigation within composite widgets (menus, tab panels, tree views).
- Provide visible focus indicators. Never set `outline: none` without providing an alternative focus style.
- Implement skip links (`<a href="#main-content">Skip to main content</a>`) as the first focusable element on the page.
- Trap focus inside modal dialogs. When a modal opens, focus moves into it. When it closes, focus returns to the trigger element.

### Focus Management
- When content changes dynamically (SPA navigation, modal open/close, accordion expand), move focus to the relevant new content.
- Use `aria-live` regions for announcements that should not move focus.
- After deleting an item from a list, move focus to the next item or to a logical parent element.
- On page load, do not auto-focus elements unless the page is primarily a single-purpose form or search.

### Color and Contrast
- Text must meet WCAG AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+ regular).
- Never use color as the only way to convey information. Add icons, text labels, or patterns alongside color coding.
- Ensure interactive elements have a 3:1 contrast ratio against adjacent colors.
- Test designs with color blindness simulators to verify information is not lost.

### Forms and Labels
- Every `<input>`, `<select>`, and `<textarea>` must have an associated `<label>` with a matching `for` attribute.
- Group related inputs with `<fieldset>` and `<legend>`.
- Provide clear error messages that identify the field and describe the problem. Use `aria-invalid="true"` and `aria-describedby` to link errors to fields.
- Do not rely solely on placeholder text as a label. Placeholders disappear when the user types.

### Images and Media
- Every `<img>` must have an `alt` attribute. Decorative images use `alt=""`. Informative images use descriptive alt text.
- For complex images (charts, diagrams), provide a text alternative nearby or via `aria-describedby`.
- Provide captions and transcripts for video and audio content.

## Best Practices

- Test with a screen reader (VoiceOver, NVDA, JAWS) during development, not just at the end.
- Use automated tools (axe-core, Lighthouse, WAVE) as a first pass, but do not rely on them alone. They catch only 30-50% of accessibility issues.
- Include accessibility checks in CI/CD pipelines using axe-core or pa11y.
- Test with keyboard only — unplug your mouse and navigate the entire interface.
- Maintain a logical reading order in the DOM that matches the visual order.
- Use relative font sizes (`rem`, `em`) so text scales with user preferences.
- Respect `prefers-reduced-motion` for users who are sensitive to animation.
- Target WCAG 2.1 AA as a baseline. Aim for AAA where practical.

## Anti-Patterns

- **Div soup.** Using `<div>` and `<span>` for everything instead of semantic elements strips away meaning that assistive technologies need.
- **ARIA overload.** Adding ARIA attributes to elements that already have native semantics causes confusion. A `<button>` does not need `role="button"`.
- **Mouse-only interactions.** Hover menus, drag-and-drop without alternatives, and click-only handlers exclude keyboard and switch users.
- **Disabling zoom.** Never set `maximum-scale=1` or `user-scalable=no` in the viewport meta tag.
- **Auto-playing media.** Unexpected audio or video disrupts screen reader users. Always require user-initiated playback.
- **Invisible focus styles.** Removing focus outlines without replacement makes keyboard navigation impossible.
- **Time-limited interactions without extensions.** If content times out, provide a way to extend or disable the time limit.