accessibilityby Addy Osmani

Accessibility Skill.

A Claude Code and Codex skill for design review: audits and improves web accessibility following WCAG 2.2.

Design Review & Accessibility
Review report

addyosmani/web-quality-skills · skills/accessibility/SKILL.mdSKILL.md

--- name: accessibility description: Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible". --- ## Evidence-led audit workflow ## WCAG Principles: POUR ## Conformance levels ## Perceivable ## Operable ## Understandable

Front matter and section headings read from the upstream file on 2026-09-14 · 14,265 characters in full

01 What it does

What the accessibility Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

This skill audits and fixes web accessibility against WCAG 2.2, organized around POUR — Perceivable, Operable, Understandable, Robust — and the A, AA and AAA conformance levels. It runs an evidence-led workflow: when a rendered page is available, run a live Lighthouse accessibility audit (lighthouse_audit with Chrome DevTools MCP), use the failed nodes to localize the component, inspect the accessibility tree with take_snapshot, then fix the source and re-run.

If live tools are missing, Lighthouse CLI or axe cover the automated half and the same manual checks still apply. It ships code-level rules for alt text, contrast ratios, focus visibility, target size, reduced motion, form errors and accessible authentication, plus a triage list ranked critical, serious and moderate.

What it produces

A prioritized issue list grouped into Critical (fix immediately), Serious (fix before launch) and Moderate (fix soon) tiers with named examples.
Corrected markup and paste-ready snippets, including a visually-hidden utility for exposing icon-button labels to assistive tech.
Full reference implementations in references/A11Y-PATTERNS.md covering form labels, modal focus trap, skip link, ARIA tabs, live regions, error handling and screen reader commands.

See the example prompt ↗

How It Works

01
Run a Live Accessibility Audit
Start with a rendered page and run a live Lighthouse Accessibility audit, using mobile navigation mode for general public pages or snapshot mode when reloading would lose authenticated state.
02
Localize the Failing Component
Use the failed audit nodes to point at the specific component or template rather than grepping the whole repository for generic patterns.
03
Inspect the Accessibility Tree
Read a rendered accessibility-tree snapshot to check names, roles, states, landmarks and heading structure, then exercise the affected flow with the keyboard.
04
Fix the Source and re-verify
Change the source rather than the rendered output, then repeat the same audit and the same manual interaction to confirm the fix.
05
Fall Back to CLI Tooling
When live browser tooling is not available, pair Lighthouse CLI or axe output with the same manual checks, because automation alone covers only part of the barriers.

02 Find your fit

When to Use the accessibility Skill

Use the accessibility skill in Claude Code or Codex when the job is design review of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

A request phrased as an a11y audit, WCAG compliance work, screen reader support, keyboard navigation or "make accessible".
Teams aiming at Level AA, which the file treats as the standard target and a legal requirement in many jurisdictions.
Pages where sticky headers or footers swallow the keyboard focus ring, a criterion new in WCAG 2.2.
Interfaces that must be fully operable without a mouse, including custom widgets built from non-interactive elements.

Know the Boundaries

Inline text links, browser-controlled sizing and targets whose 24px circle does not overlap another target are exempt from the minimum target size rule.
Level AAA is treated as optional rather than a requirement.
Anti-pattern the file calls out: adding manual keyboard activation to a native button, which double-triggers because Enter and Space already fire click.

What to Provide

A rendered pageThe live workflow starts when a rendered page is available, since the audit, the node list and the accessibility tree all come from it.
The page's navigation modeTell the agent whether this is a general public page or a flow where reloading would lose authenticated or user-created state, because that decides mobile navigation or snapshot mode.
The keyboard flow to exerciseBe ready to walk the affected interaction with the keyboard during the audit, alongside the accessibility-tree inspection.

03 Inside the skill

Rules the accessibility Skill Gives Claude Code and Codex

7 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Reach for a Native Element First
Native button, anchor and form controls already handle Enter/Space activation, focus and assistive-tech semantics, so manual keyboard handling is a last resort for elements you cannot replace.
Keep Focus Visibly Styled
Never strip outlines.
Hold the 24 × 24 Target Minimum
Interactive targets must be at least 24 × 24 CSS pixels at AA, with 44 × 44 recommended as the comfortable touch size for buttons, checkboxes and radio labels.
Neutralize Animation on Request
Under prefers-reduced-motion the file collapses animation and transition durations to 0.01ms, caps iteration count at 1 and resets scroll-behavior to auto.
Never Signal with Color Alone
Error states combine color with an icon and text; the markup pairs aria-invalid="true" with aria-describedby pointing at the error message element.
Announce and Focus Errors
Push errors to screen readers with role="alert" or aria-live, mark the offending fields, and move focus to the first error on submit.
Keep Authentication low-cognition
Login flows must not depend on remembering a password or solving a puzzle unless copy-paste or autofill works, an alternative such as a passkey or email link exists, or the test uses object recognition or personal content.

04 Put it to work

Install accessibility in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add accessibility to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/addyosmani/web-quality-skills --skill accessibility

Generic skills CLI form for skills/accessibility/SKILL.md; the repository may document its own path.

Give the Skill a First Design Review Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Audit [page URL or route] with Lighthouse and then fix the accessibility problems in the source. The form inputs in [component path] have no programmatically associated labels, the icon buttons have no accessible names, and focus outlines are being removed on [element]. Re-run the same audit afterwards and check keyboard navigation and target sizes.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Tab through the entire page and activate controls with Enter and Space.

In OpenDesign import accessibility from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Addy Osmani
Repository: github.com/addyosmani/web-quality-skills Branch main
Skill file: skills/accessibility/SKILL.md Content checksum recorded at verification; commit afa8da9
License: MIT From LICENSE; SKILL.md says “MIT”.
Repository stars: 2,786 GitHub snapshot taken 2026-09-14 for the whole addyosmani/web-quality-skills repository. Not a rating or usage count for accessibility.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

The Skill's Own Description

“Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".”

Front-matter description from SKILL.md. The full file is about 14,265 characters. Read the full file on GitHub.

Accessibility

Run accessibility on a Real Design Review Task.

Download OpenDesign, import accessibility from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills

Terminal

npx skills add https://github.com/addyosmani/web-quality-skills --skill accessibility

What the accessibility Skill Does in Claude Code and Codex

In the Skill's Own Terms

How It Works

When to Use the accessibility Skill

Good Fit

Know the Boundaries

What to Provide

Rules the accessibility Skill Gives Claude Code and Codex

Reach for a Native Element First

Keep Focus Visibly Styled

Hold the 24 × 24 Target Minimum

Neutralize Animation on Request

Never Signal with Color Alone

Announce and Focus Errors

Keep Authentication low-cognition