Accessibility Audit

/accessibility-audit

Audit a TypeScript and React frontend against an opinionated accessibility baseline organised in three layers — tooling and automation, component patterns, and application shell — then offer to generate an implementation plan for the gaps. Targets WCAG 2.2 Level AA. The audit is fully static: it reads the codebase, never starts the development server, and never runs a live accessibility scanner. Screen-reader behaviour and focus-order verification are explicitly out of scope — they can only be verified reliably by a human.

The default mental model is React (any flavour: Vite, Create React App, Next.js, Remix). Detection is framework-agnostic, with extra hints emitted when Next.js or Remix is present because route-announcement expectations differ.

Usage

/accessibility-audit                              # default: concise Top 5 + full report saved + ask about plan
/accessibility-audit --worktree                          # create an isolated Git worktree, then run the audit there
/accessibility-audit --learn                      # mid-level engineer teaching mode (detailed explanations + file/line examples)
/accessibility-audit --teach                      # alias for --learn
/accessibility-audit --severity=error             # report only violations and missing-required checks

💡 Pro tip: Add --worktree to run this audit in an isolated Git worktree.

This skill never accepts --apply. Mutating the codebase is the responsibility of a separate fix step. The implementation plan is descriptive Markdown.

The opinionated baseline

A check resolves to one of four statuses:

• present — the check is fully satisfied; the audit found everything it expected.
• partial — some required signals resolved, others did not. The check is half-implemented.
• missing — the tooling, configuration, or pattern is not present at all.
• violation — the audit found code that actively contradicts the check (for example, an interactive `` with no keyboard handler).

missing and violation are distinct on purpose. missing means "the safety net isn't in place"; violation means "the safety net is missing and there is concrete code that the safety net would have caught."

Layer 1 — Tooling and automation

| Check | Expectation | Primary detection signals | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | jsx-accessibility lint plugin | eslint-plugin-jsx-a11y is installed and the recommended (or strict) ruleset is enabled in the active ESLint configuration. | package.json devDependency on eslint-plugin-jsx-a11y; extends entry in eslint.config.* or .eslintrc* referencing plugin:jsx-a11y/recommended or plugin:jsx-a11y/strict; no file-level or directory-level disables of the plugin. | | Axe in development | @axe-core/react is initialised in development mode so violations are logged to the browser console during local work. | devDependency on @axe-core/react; an entry-point file (typically src/main.tsx, src/index.tsx, or pages/_app.tsx) imports it and calls axe(React, ReactDOM, ...) behind a development guard. | | Component-test integration | jest-axe or vitest-axe is available, and at least one component test asserts expect(...).toHaveNoViolations(). | devDependency on jest-axe or vitest-axe; at least one test file imports the matcher and uses it. | | End-to-end accessibility scan | @axe-core/playwright (or the Cypress equivalent) is configured, and at least one end-to-end specification runs an axe scan against a rendered page. | devDependency on @axe-core/playwright or cypress-axe; a spec file imports and invokes the scanner. | | Storybook accessibility addon | If Storybook is in use, @storybook/addon-a11y is registered. | Storybook configuration file (.storybook/main.*) lists the addon in addons. Skipped silently if Storybook is not detected. | | Continuous integration enforcement | A continuous-integration workflow step runs the unit and end-to-end accessibility checks and fails the build on violations. | Workflow file under .github/workflows/, .gitlab-ci.yml, or equivalent contains a step invoking the relevant test command. |

Layer 2 — Component patterns

These checks require reading components. Use the knowledge graph to find the right entry points (god nodes for component clusters), then sample broadly. The audit reports counts and representative file references, not an exhaustive list.

| Check | Expectation | What counts as a violation | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Semantic HTML over generic containers | Interactive elements use the right tag (`, , , ); lists use , , or . | A or with an onClick and no role, no keyboard handler, and no tabIndex. A list-shaped UI rendered with children. A clickable item that should be a or . | | ARIA used correctly | ARIA attributes appear only on elements that support them, are not redundant, and are present where required. | aria-* on an element where it has no effect (for example, aria-checked on a without role="checkbox"). Redundant ARIA (role="button" on ). Icon-only buttons with no aria-label or aria-labelledby. Disclosure triggers without aria-expanded. Modals without aria-modal="true" and a labelling strategy. | | Keyboard support | Every interactive element is reachable by Tab and operable by keyboard. Focus is visible. | outline: none (or outline: 0) without a replacement focus style. Custom widgets that do not implement the WAI-ARIA Authoring Practices keyboard model. Keydown handlers that block default behaviour without re-implementing it. | | Focus management | Modals trap focus and restore on close; route changes move focus to a sensible target; a skip-to-content link is present and is the first focusable element. | A modal component without focus trap and without focus restoration. A custom router with no focus handling on navigation. Auto-focus on page load on a non-form-first page. | | Forms | Every input has an associated . Errors are programmatically associated with their fields. Required fields are indicated for both screen readers and sighted users. Grouped controls use and . | An whose only label is a placeholder. An error message that is rendered visually but not tied to its field by aria-describedby. A required field marked only with an asterisk. A radio or checkbox group without /. | | Images and media | Every has an alt attribute (empty alt="" is acceptable for purely decorative images). SVG icons used as content have or aria-label. Videos have captions. Auto-playing media is muted and has a pause control. | without alt. used as a content icon with no accessible name. without muted and without a pause control. | | Colour and contrast | Text colours meet WCAG AA contrast against their backgrounds. Information is never conveyed by colour alone. | When design tokens are statically defined (CSS custom properties, Tailwind theme, theme objects), text/background pairings that fall below 4.5:1 (or 3:1 for large text). UI states differentiated only by colour (for example, an error indicated only by red text). | | Motion and animation | Long animations respect prefers-reduced-motion. No essential information is delivered through animation alone. | Animations longer than five seconds with no pause control. Global stylesheets with no @media (prefers-reduced-motion: reduce) block. Auto-rotating carousels without pause. | | Text and content structure | Headings are in document order with no skipped levels. Link text is descriptive in isolation. | A page that jumps from to with no . Multiple per page (outside an ` context that warrants it). Link text such as "click here", "read more", or a bare URL. |

Layer 3 — Application shell

| Check | Expectation | Primary detection signals | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Document language | ` is set to a real language code. | The HTML shell (index.html, app/layout.tsx, pages/_document.tsx, app/root.tsx) sets a non-empty lang. | | Per-route document titles | Document title updates on every navigation. | Use of the framework's title primitive ( in Next.js metadata, in Vite-React, meta exports in Remix) on every routed view. | | Skip-to-content link | A skip link to the main landmark exists and is the first focusable element on every page. | An (or equivalent) rendered in the application shell, styled to be visible on focus. | | Route announcement | Client-side navigations are announced to assistive technology. | A live region in the shell, or use of the framework-provided announcer (Next.js app/ router's RouterAnnouncer, Remix's built-in announcement, or a custom aria-live region). | | Viewport meta | The viewport meta tag is present and does not disable scaling. | . The check fails if user-scalable=no or maximum-scale=1 appears. | | Landmark roles | The application shell renders the standard landmarks once per page: banner, main, contentinfo. navigation and complementary appear when the design has them. | The shell uses , , , (or the explicit role equivalents). No duplicate landmarks of the same role without an aria-label differentiating them. | | Error and not-found pages | Custom error and 404 pages have a heading, manage focus, and offer a way back to the main application. | Presence of an error route (app/not-found.tsx, app/error.tsx`, or framework equivalent). Heading present. A link or button that returns to a known landing route. | | Authentication pages | Sign-in and sign-up forms support password-manager autofill, declare input purposes, and do not trap users in moda

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BenSheridanEdwards
• Source: BenSheridanEdwards/ArchitectPlaybook
• License: MIT

Install and usage instructions live in the source repository linked above.