agentleFS
plugin87plugin87/full-stack-design-skills/.claude/skills/web-accessibility-a11y/SKILL.md

web-accessibility-a11y

Skill10 starsChanged 4 months agoMITView on GitHub

Build accessible web experiences that work for everyone. Use this skill whenever dealing with WCAG compliance, semantic HTML, ARIA patterns, screen reader testing, keyboard navigation, contrast ratios, accessibility audits, or inclusive design patterns. Triggers include: accessibility concerns, form design, modal dialogs, focus management, live regions, color-only differentiation, keyboard shortcuts, keyboard traps, link/button semantics, landmark navigation, heading hierarchy, skip links, and alt text strategy. Essential for designers, developers, and QA ensuring digital products are usable by people with disabilities.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All interactive elements must be keyboard accessible.

    line 182
  2. Distinctive:

    Use the natural tab order (HTML source order).

    line 186
  3. Distinctive:

    Custom focus style: must have ≥3px visible area, 3:1 contrast

    line 208
  4. Distinctive:

    Avoid situations where keyboard users can't escape using keyboard.

    line 219
  5. Distinctive:

    If you define custom keyboard shortcuts (Ctrl+S, etc.):

    line 240
  6. Distinctive:

    Avoid single-key shortcuts (break form inputs)

    line 241
  7. Distinctive:

    Document all shortcuts in Help

    line 243
  8. Distinctive:

    Test with real AT — browser extensions don't replicate the experience

    line 306
  9. Distinctive:

    Ensure information conveyed by color also uses icons, text, patterns

    line 314
  10. Very specific:

    Fix: Every image needs alt="" (can be empty if decorative, but must be present).

    line 326
  11. Distinctive:

    Fix: Add icons, text labels, or patterns alongside color.

    line 330
  12. Very specific:

    Fix: Never remove focus outline.

    line 334
  13. Distinctive:

    Fix: Use sequential hierarchy (h1 → h2 → h3).

    line 342
  14. Very specific:

    Fix: Always use <label>. Placeholder disappears when user types.

    line 346
  15. Very specific:

    Fix: Add visible text or aria-label="Back" / aria-label="Menu".

    line 350

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Web Accessibility (a11y)

A practical guide to building digital products that work for everyone, regardless of ability.

Accessibility is not an afterthought—it's a foundational design principle. This skill covers the technical standards (WCAG 2.1) and practical patterns for building inclusive web experiences.

Why Accessibility Matters

Legal: WCAG 2.1 compliance is increasingly required (ADA, ATAG, EN 301 549, UK EQA).

Business: ~15% of the global population has a disability. Accessible design benefits everyone (captions help in noisy environments, voice control helps people with mobility issues, clear navigation helps users with cognitive disabilities).

Technical: Accessible patterns are often better for SEO, performance, and maintainability.


Core Principles: WCAG 2.1

WCAG (Web Content Accessibility Guidelines) has four principles, abbreviated as POUR:

1. Perceivable

Information must be perceivable—users must be able to see, hear, or otherwise sense it.

Guidelines:

  • Text alternatives — Images need alt text
  • Captions & transcripts — Audio/video needs text
  • Adaptable content — Info not lost when zoomed or reflow
  • Distinguishable — Text is readable (4.5:1 contrast, font size ≥12px)

2. Operable

Interfaces must be operable—users must be able to navigate and interact.

Guidelines:

  • Keyboard accessible — All functions available via keyboard
  • Enough time — Users can pause auto-playing content
  • Seizure prevention — No flashing/flickering (3+ times/second)
  • Navigable — Clear landmarks, skip links, heading hierarchy

3. Understandable

Content and operation must be understandable.

Guidelines:

  • Readable — Clear language, short sentences, defined jargon
  • Predictable — Consistent navigation, no surprises
  • Input assistance — Form errors are identified and labeled clearly

4. Robust

Code must be robust—compatible with assistive technologies.

Guidelines:

  • Valid HTML — Correct use of semantic elements
  • ARIA correctly — Only use ARIA when HTML can't do it
  • Naming, role, value — Every interactive element has a label (name), is understood (role), and exposes state (value)

Semantic HTML: The Foundation

Semantic HTML means using HTML elements for their intended purpose. This is 80% of accessibility.

Correct Element Usage

Don't:

<div onclick="submit()">Submit</div>
<span class="heading">Page Title</span>
<div role="button" tabindex="0">Click me</div>

Do:

<button>Submit</button>
<h1>Page Title</h1>
<button>Click me</button>

Essential Semantic Elements

ElementPurposeScreen Reader Announces
<button>Clickable action"Button: [label]"
<a href="">Navigation link"Link: [label]"
<h1>–<h6>Headings (hierarchy)"Heading level 1: [text]"
<nav>Navigation region"Navigation"
<main>Main content region"Main"
<article>Self-contained content"Article"
<section>Thematic grouping"Region"
<aside>Sidebar/supplementary"Complementary"
<header>, <footer>Page regionsLandmarks
<label for="">Form label (paired to input)"Label: [text]"
<fieldset> & <legend>Group related form inputs"Group: [legend]"
<ul>, <ol>, <li>Lists"List, X items"
<table>, <thead>, <th>, <td>Data tables (not layout)Headers + cells announced
<figure> & <figcaption>Images with captions"Figure: [caption]"

Landmark Navigation

Users of screen readers navigate by landmarks (regions). Provide at least:

  • One <main> — Contains primary content
  • One <nav> — Contains navigation
  • Optional <header>, <footer>, <aside>
<body>
  <header>
    <nav><!-- Primary navigation --></nav>
  </header>
  <main>
    <article><!-- Primary content --></article>
  </main>
  <aside><!-- Sidebar --></aside>
  <footer><!-- Footer --></footer>
</body>

Form Accessibility

Forms are the most common source of accessibility issues.

Labeling

Every input needs a label, associated via for/id:

<label for="email">Email address</label>
<input id="email" type="email" name="email" />

Not this:

<input type="email" placeholder="Email" />

Placeholder text vanishes when you start typing — users with memory issues won't know what the field was for.

Required Fields

Indicate required fields clearly in label + legend text:

<label for="name">Name <span aria-label="required">*</span></label>
<input id="name" type="text" name="name" aria-required="true" />

Error Handling

When validation fails:

  1. Announce the error immediately (use aria-live="polite")
  2. Identify which field failed
  3. Describe the error (not "Invalid" but "Phone number must be 10 digits")
  4. Suggest correction
<label for="phone">Phone</label>
<input id="phone" type="tel" aria-invalid="true" aria-describedby="phone-error" />
<div id="phone-error" role="alert">Phone must be 10 digits, e.g., 415-555-0123</div>

Fieldsets & Legends

Group related inputs (radio buttons, checkboxes) with <fieldset> and label with <legend>:

<fieldset>
  <legend>Select your experience level</legend>
  <label><input type="radio" name="level" value="beginner" /> Beginner</label>
  <label><input type="radio" name="level" value="intermediate" /> Intermediate</label>
  <label><input type="radio" name="level" value="expert" /> Expert</label>
</fieldset>

Keyboard Navigation

All interactive elements must be keyboard accessible. Users without mice rely entirely on keyboard.

Tab Order

Use the natural tab order (HTML source order). If visual order differs from source order, fix the source:

Bad:

<!-- visually: 1, 2, 3 but tab order is: 1, 3, 2 -->
<button style="order: 2">Button 2</button>
<button style="order: 3">Button 3</button>
<button style="order: 1">Button 1</button>

Good:

<!-- visual and tab order match source order -->
<button>Button 1</button>
<button>Button 2</button>
<button>Button 3</button>

Focus Management

  • Never remove focus outline — Users need visual feedback of where they are
  • Focus should be visible on all interactive elements (buttons, links, inputs, custom controls)
  • Custom focus style must have ≥3px visible area, 3:1 contrast
button:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

Keyboard Traps

Avoid situations where keyboard users can't escape using keyboard. Test: Press Tab repeatedly — can you reach every element and move past it?

Example trap:

<button onclick="openModal()">Open Modal</button>
<!-- Modal opens, focus not moved to modal, Tab cycles through background -->

Fix:

<button onclick="openModal()">Open Modal</button>

<div role="dialog" aria-modal="true">
  <button autofocus>Close Modal</button>
  <!-- Focus trap: Tab cycles only within modal until closed -->
  <!-- Last focusable element's Tab cycles back to first -->
</div>

Keyboard Shortcuts

If you define custom keyboard shortcuts (Ctrl+S, etc.):

  • Avoid single-key shortcuts (break form inputs)
  • Allow users to disable or remap shortcuts
  • Document all shortcuts in Help

ARIA (Accessible Rich Internet Applications)

ARIA adds accessibility information to HTML. Use semantic HTML first; ARIA only when HTML can't do it.

Golden Rules of ARIA

  1. No ARIA is better than bad ARIA — Incorrect ARIA breaks things for screen reader users
  2. ARIA doesn't change DOM — role="button" on a <div> doesn't make it keyboard accessible; still need tabindex="0" and onkeydown
  3. ARIA is for exceptions — 90% of a11y is semantic HTML

Common ARIA Attributes

AttributeUseExample
role=""Tells AT the element's purpose<div role="button"> (only if not semantic element)
aria-label=""Visible label missing<button aria-label="Close">×</button>
aria-labelledby=""Connect to visible heading<h2 id="x">Title</h2> <div aria-labelledby="x">
aria-describedby=""Additional description<input aria-describedby="hint"> + <div id="hint">
aria-required="true"Field is required<input aria-required="true">
aria-invalid="true"Field has error<input aria-invalid="true">
aria-expanded="false"Toggle button state<button aria-expanded="false">Menu</button>
aria-hidden="true"Hide from AT<span aria-hidden="true">→</span>
aria-live="polite"Announce content changes<div aria-live="polite">3 items added</div>

When to Use ARIA

Don't use ARIA for:

  • Semantic HTML does it already (<h1>, <button>, <label>, etc.)
  • Simple styling or layout (just use CSS)

Do use ARIA for:

  • Custom components without semantic HTML (tabs, accordion, tooltip)
  • Live regions that update (chat, notifications, search results)
  • Hidden/collapsed content state (aria-expanded)
  • Relationships between non-adjacent elements (aria-labelledby, aria-describedby)

Testing & Validation

Automated Tools (Catch ~30% of issues)

  • axe DevTools (browser extension) — Fast, reliable
  • WebAIM Contrast Checker — Verify color contrast
  • WAVE — Visual accessibility feedback
  • Lighthouse (Chrome DevTools) — Performance + accessibility audit

Manual Testing (Required for remaining 70%)

Keyboard-only navigation:

  • Unplug your mouse
  • Navigate entire site with Tab, Enter, Shift+Tab, Arrow keys
  • Identify any keyboard traps or missing focus

Screen reader testing:

  • NVDA (Windows, free)
  • JAWS (Windows, paid)
  • VoiceOver (Mac, free — press Cmd+F5 to enable)
  • TalkBack (Android, free)
  • Test with real AT — browser extensions don't replicate the experience

Zoom testing:

  • Zoom to 200% — text should reflow, no horizontal scroll
  • Zoom to 400% — should still be readable

Colorblind testing:

  • Simulator: Coblis
  • Ensure information conveyed by color also uses icons, text, patterns

Accessibility Audit Checklist

See bundled resources for comprehensive WCAG 2.1 AA checklist.


Common Mistakes & Fixes

Missing Alt Text

Problem: Images have no alt text. Fix: Every image needs alt="" (can be empty if decorative, but must be present). Describe content concisely: alt="Coffee cup on wooden table" not alt="image.jpg".

Color-Only Indicators

Problem: Red = error, green = success (no other differentiation). Fix: Add icons, text labels, or patterns alongside color.

No Focus Visible

Problem: outline: none applied globally to remove focus ring. Fix: Never remove focus outline. Customize it: outline: 2px solid blue; outline-offset: 2px.

Inaccessible Modals

Problem: Modal opens; focus stays on background; keyboard user can't close it. Fix: Move focus into modal on open. Trap Tab within modal. Move focus back to trigger on close.

Incorrect Heading Hierarchy

Problem: h1, then h3, skipping h2. Fix: Use sequential hierarchy (h1 → h2 → h3). Users rely on heading structure to navigate.

Placeholder ≠ Label

Problem: Form fields use only placeholder; label removed "for clarity." Fix: Always use <label>. Placeholder disappears when user types.

Unlabeled Buttons

Problem: <button>←</button> or <button><i class="icon-menu"></i></button> (no text). Fix: Add visible text or aria-label="Back" / aria-label="Menu".


Reference Files & Further Reading

Bundled resources:

  • wcag-2-1-checklist.md — WCAG AA compliance checklist
  • aria-patterns-guide.md — Common ARIA patterns (tabs, accordion, tooltip, etc.)
  • keyboard-navigation-guide.md — Keyboard interaction patterns

When to Use This Skill

✅ Do use for:

  • WCAG compliance review and audit
  • Form accessibility design and testing
  • Keyboard navigation and focus management
  • ARIA attribute selection and implementation
  • Alt text strategy for images
  • Modal, tooltip, popover, tab panel accessibility
  • Color contrast compliance
  • Heading hierarchy and landmark review
  • Error handling and form validation
  • Screen reader testing strategies

❌ Don't use for:

  • CSS styling details (see design-fundamentals)
  • Framework-specific implementation (see appropriate framework skill)
  • Performance optimization (see web-performance-optimization)
  • Design system component creation (see design-systems-architecture)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.