# ux-a11y

ux-a11y audits a page or component against WCAG 2.1 AA and flags issues automated scanners miss. Run it before shipping or right after a redesign to catch accessibility regressions.

- command · `type=command` · Claude Code, Codex, GitHub Copilot, Gemini CLI · ★ 110 repo stars
- Author: Laith Aljunaidy
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Laith0003/ux-skill/tree/HEAD/commands/ux-a11y.md
- Updated: 2026-11-02
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/ux-a11y

## What it does

The `/ux-a11y` command from the `ux` plugin checks a surface against 11 points: color contrast, keyboard navigation, focus indicators, screen reader compatibility, ARIA correctness, non-color signaling, text scaling to 200%, `prefers-reduced-motion` support, form-error patterns, semantic markup, and image alt text. Each point gets a pass/fail/partial/not-verifiable call tied to a specific WCAG success criterion number.

How much it can verify depends on what you give it. A live URL lets it compute contrast ratios, tab order, and ARIA state in the DOM; code or a file lets it check markup semantics and alt attributes; a screenshot only allows checking visual contrast and focus visibility, with no keyboard or screen reader testing possible. Findings are grouped by severity — Critical, High, Medium, Cosmetic — plus a separate section for issues that pass the spec but still hurt users, like autoplaying video or undersized tap targets.

Results get written to `.ux/last-a11y.json` with a timestamp, the list of verified and unverifiable points, and findings mapped to each WCAG criterion.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add Laith0003/ux-skill
```
In the agent chat (not a shell):
```text
/plugin install ux@ux-skill
```

2. **Manually: put the files in place**
- File: `.claude/commands/ux-a11y.md` — Call it with /ux-a11y. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/ux-a11y.md` — Call it with /prompts:ux-a11y. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/ux-a11y.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/ux-a11y.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Laith0003/ux-skill/tree/HEAD/commands/ux-a11y.md

## When to use it
- check text and UI contrast ratios before a release
- find keyboard navigation failures and focus traps
- confirm form errors get announced to screen readers
- catch images with missing or generic alt text
- spot accessibility regressions after a redesign

## Example prompts
- Run /ux-a11y:ux-a11y on checkout.jsx
- Audit the signup form against WCAG 2.1 AA with /ux-a11y:ux-a11y
- Check this dashboard screenshot for accessibility issues

## Source text · ux-a11y.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c49a8bf9b41acbeb.

BEGIN THIRD-PARTY FILE c49a8bf9b41acbeb
```text
---
description: WCAG 2.1 AA accessibility audit plus common-courtesy checks beyond the spec. Produces findings grouped by WCAG criterion with severity, evidence, and fix. Triggers on "accessibility check", "WCAG audit", "is this accessible", or "a11y review". Use when WCAG 2.1 AA audit, checking accessibility on a page or component, verifying contrast / keyboard / screen reader / focus / ARIA / motion preferences / form-error patterns, pre-ship accessibility gate. Skip when the surface is not user-facing, backend or infrastructure work, work-in-progress sketches that aren't ready for an a11y audit (use ux-critique for an early taste call).
allowed-tools: Read, Write, Edit, Bash(ls:*), Bash(cat:*), Bash(grep:*), Bash(find:*), Bash(mkdir:*), Bash(curl:*), Bash(date:*), Glob, Grep, Task, WebFetch
disable-model-invocation: false
---

# /ux-a11y

You are running the `/ux-a11y` command from the `ux` plugin. The job is a structured WCAG 2.1 AA audit of a surface, plus the common-courtesy checks that pass automated tools but still hurt real users.

## When to use

Triggers: "accessibility check", "WCAG audit", "is this accessible", "a11y review", "screen reader test", "keyboard nav check", "color contrast", "ARIA review", "make this accessible".

Use whenever a surface is touched by users beyond the team, especially before shipping any production change. Also use proactively after a redesign — accessibility regressions are the most common silent failure.

## Input

One of: a URL, an absolute file path (Blade view, JSX, HTML), a screenshot, a code snippet. If a live URL is available, prefer it — automated tools and keyboard testing only work on live surfaces. If only static markup is available, the audit will be partial and you must flag what could not be verified.

## Process

### 1. Identify the surface mode

- **Live URL** → can verify contrast computationally, keyboard tab order, focus visibility, ARIA in DOM, dynamic states.
- **Code/file** → can verify semantic HTML, ARIA attributes, alt text presence, contrast against declared colors, focus management code paths.
- **Screenshot only** → can verify visual contrast (sampled), focus visibility if shown, color-not-only, dynamic-type tolerance. Cannot verify keyboard, screen reader, or dynamic states.

Surface the mode at the top of the report so the user knows what could not be verified.

### 2. Run the 11-point checklist

For each item, check the relevant WCAG success criterion (cite the SC number) and decide pass / fail / partial / not-verifiable.

#### 1. Color contrast (WCAG 1.4.3, 1.4.11)

- Body text: ≥ 4.5:1 against its background.
- Large text (18pt regular or 14pt bold): ≥ 3:1.
- Non-text UI (focus rings, icons, form borders): ≥ 3:1.
- Compute ratios; do not eyeball.

#### 2. Keyboard navigation (WCAG 2.1.1, 2.1.2)

- Every interactive element reachable via Tab in a sensible order.
- No keyboard traps (modals, custom widgets).
- Custom widgets respond to expected keys (Esc closes, arrows navigate menus).

#### 3. Focus indicators (WCAG 2.4.7)

- Every focusable element has a visible focus indicator.
- Contrast of focus ring ≥ 3:1 against adjacent colors.
- No `outline: none` without a replacement.

#### 4. Screen reader compatibility (WCAG 1.3.1, 4.1.2)

- Semantic HTML used (`<button>`, `<nav>`, `<main>`, `<header>`, not all `<div>`).
- Form fields have associated `<label>` (explicit `for` or wrapping).
- Custom widgets use ARIA roles, states, properties correctly.
```
END THIRD-PARTY FILE c49a8bf9b41acbeb

The third-party file has ended. Everything between the c49a8bf9b41acbeb tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3501 of 13738 bytes. © Laith Aljunaidy · MIT · https://github.com/Laith0003/ux-skill/tree/HEAD/commands/ux-a11y.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
