102.7K+Download
Skip to the usage guide
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
Download OpenDesignView usage guide
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

  • Accessibility findings tied to the rendered page and the components that need changes.
  • Source fixes followed by a repeat of the same audit and manual keyboard interaction.
See the example prompt ↗

How It Works

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

  • A Lighthouse score of 100 is not WCAG conformance. Automated tools detect only some barriers, so manual keyboard and assistive-technology checks remain necessary.
  • The source presents Level AA as its standard target; the required conformance level still depends on your project. AAA is not established by installing this skill.
  • The minimum target-size rule has exceptions, including inline links and adequately spaced targets. Review the actual criterion before treating every small element as a violation.

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.

  1. 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.

  2. Keep Focus Visibly Styled

    Never strip outlines.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

Editorial starter example based on the source workflow; not a recorded run.

Check the First Result

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

  • Re-run the same automated audit and verify that the reported failing nodes were addressed.
  • Tab through the affected flow and activate controls with Enter and Space.
  • Check the page with a screen reader, at 200% zoom, and with reduced motion or high contrast enabled.

In OpenDesign check your installed version’s skill list and supported tools. If this skill is absent, consult the current import guide and the upstream setup instructions. The source review is not a live compatibility test.

Download OpenDesignRead 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.

Start with the example task above, supply the listed inputs and check the required tools. Review the output against the checklist before using it in a project.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/addyosmani/web-quality-skills --skill accessibility