| name | ux-accessibility-audit |
| description | Run a structured WCAG 2.1 AA accessibility audit on a design, screen, component, or page. Produces a prioritized issue list — each finding cites the violated WCAG criterion, a severity rating (Critical/Major/Minor), and a concrete fix. Use when auditing for a11y compliance or as a validation step after generating UI. |
| license | MIT |
| metadata | {"author":"uxcel","version":"1.0.0"} |
Accessibility Audit Skill
How this skill behaves (read first)
This is an evaluative skill — it reviews existing work against a standard (WCAG), it doesn't generate UI. Flagging is safe, so it auto-runs and is designed to be called as a validation step by generative skills as well as invoked directly.
It owns the accessibility concern in this repo. Generative skills hand off to it (e.g. ux-login-signup, ux-pricing), and the heuristics audit (ux-heuristics-audit) deliberately defers contrast / keyboard / screen-reader specifics here rather than duplicating them. When invoked, do the full a11y pass; don't assume another skill covered it.
Scope discipline. When invoked directly (the user named this audit), review only this concern — don't pull in sibling audits. It runs alongside other lenses only when an orchestrator (ux-design-review) or a generative skill calls it under docs/orchestration-policy.md, where it sits in Tier B — offered (and narrowed to usage when a design system is in play). Explicit scope always wins.
What this skill changes vs. default behavior
By default, accessibility feedback tends to be partial and vague — a few obvious call-outs ("add alt text", "check contrast") with no standard, no severity, and no systematic sweep. This skill forces four things:
- Every finding cites the WCAG criterion and level it violates — not a vague suggestion.
- Every finding gets a severity based on how completely it blocks access — so the list is prioritized.
- Every finding has a concrete fix — the specific markup/design change.
- The audit is systematic — it sweeps all six categories below, so issues outside the obvious ones (focus order, heading hierarchy, table semantics, motion) actually get caught.
WCAG foundations
POUR principles — every audit item maps to one of these four:
- Perceivable — content must be detectable via at least one sense (sight, hearing, etc.)
- Operable — all interactions must work without a mouse (keyboard, switch, voice)
- Understandable — content and UI must be clear and predictable
- Robust — content must work across browsers, devices, and assistive technologies
Compliance levels:
- Level A — bare minimum; missing these creates complete barriers (e.g. no alt text, no keyboard access).
- Level AA — the legal standard most organizations must meet; the default target for every audit.
- Level AAA — aspirational; apply selectively where it adds high value.
Default audit target: WCAG 2.1 Level AA.
Audit checklist
Work through every category — a partial sweep is the main way real issues get missed. Flag each violation with WCAG criterion, severity (see model below), and a fix.
1. Color & Contrast
| Check | Requirement | Notes |
|---|
| Normal text vs background | ≥ 4.5:1 (AA) / 7:1 (AAA) | Applies to all text in UI: buttons, labels, cards, nav |
| Large text (≥ 18pt or ≥ 14pt bold) | ≥ 3:1 | |
| Icons (informational or interactive) | ≥ 3:1 | Decorative icons exempt |
| Input borders vs surrounding background | ≥ 3:1 | Including focus indicators |
| Text over images | ≥ 4.5:1 between text and the portion of image behind it | Use semi-transparent overlay if needed |
| Selection states | Same ratios as regular text | |
| Disabled elements | Exempt from contrast rules | Must still be recognizable as inactive |
| Logo text | Exempt | But good practice to maintain contrast anyway |
| Color as sole differentiator | ❌ Never | Always pair color with icon, pattern, label, or text |
| Stark contrast (pure black on white) | Discouraged | Use #333 on #F8F8F8 — exceeds AA while reducing eye strain |
Don't rely on color alone: error states need an icon + text, not just red. Charts need patterns or labels, not just color.
2. Typography & Text
| Check | Requirement |
|---|
| Base body font size | ≥ 16px |
| Line length | 45–75 characters (including spaces) |
| Text alignment | Follows reading direction (LTR → left-align; RTL → right-align) |
| Headings visually distinct | Larger size, bold weight, or color difference from body text |
One <h1> per page | Page title only |
| Heading hierarchy | No skipped levels (h1 → h2 → h3, never h1 → h3) |
| Semantic heading tags | Use <h1>–<h6>, not styled <div> or <p> |
| Language | Plain language, secondary-education reading level |
| Idioms & figures of speech | Avoid — confuse screen readers and non-native speakers |
| Typeface | Clear letterform distinctions (0 vs O, 1 vs l vs I); large x-height |
3. Forms
| Check | Requirement |
|---|
| Keyboard access | Every field, dropdown, checkbox, radio, button navigable via Tab / Shift+Tab / Enter / arrows |
| Focus indicators | Visible on every focused element — never remove browser default without replacing |
| Layout | Single-column preferred; multi-column increases cognitive load and screen-reader confusion |
| Input boundaries | Visible borders or backgrounds — never borderless inputs |
| Labels | Outside the field, not placeholder-only; min 16px; 4.5:1 contrast |
| Placeholder text | Supplemental only — disappears on input, so never the sole label |
| Autocomplete | Implement for name, email, phone, address, payment (HTML autocomplete attribute) |
| Error states | Multiple cues: icon + bold border + field-specific message. Never color alone |
| Error placement | Adjacent to the offending field + aria-describedby linking field to error |
| Error summary | At top of form on submit failure, with anchor links to each problem field |
| Authentication | No text-based CAPTCHA — use magic links, OTP, passkeys, or biometrics. Support paste in password fields |
| Mobile one-handed use | Center CTAs in lower-middle zone; avoid right-edge-only button placement |
4. Links & Navigation
| Check | Requirement |
|---|
| Link labels | Descriptive, specific — "Download pricing guide" not "Click here" or "Read more" |
| New-window links | Warn users in link text or aria-label: "opens in new tab" |
| File links | State type + size: "Annual Report (PDF, 2.5 MB)" |
| Raw URLs as link text | ❌ Never — screen readers read character by character |
| Link recognizability | Underline + color (not color alone) |
| Focus state | Visible, distinctive focus ring on every link and interactive element |
href attribute | Required on all <a> tags — <div> with click handler is not a link |
| Voice/tone | Link text should match the product's voice, but always prioritize clarity |
| Help links | Consistently placed (footer, header utility nav, or persistent help icon) |
5. Images & Multimedia
| Check | Requirement |
|---|
| Informational images | alt attribute with meaningful description |
| Decorative images | alt="" (null) — tells screen readers to skip |
| Images containing text | Alt text = the exact text in the image |
| Autoplay | ❌ Disabled by default — user must initiate playback |
| Media controls | Play/pause/stop/rewind/volume/mute/captions — keyboard accessible, sufficient size and contrast |
| Video captions | Required for all pre-recorded video with audio |
| Audio transcripts | Required for all audio-only content |
| Flashing/strobing content | ❌ No content flashing > 3 Hz or red flashing at any rate |
| Animations (GIF, SVG, CSS) | No more than 5 light-dark stripe pairs; provide a way to pause/stop |
| Icons | Pair with text labels; informational icons need aria-label or title |
| Swipe gestures | Support both directions or provide an alternate tap target |
6. Tables & Lists
| Check | Requirement |
|---|
| Data tables | Use <table> element — never use tables for layout |
| Table caption | <caption> immediately after <table> opening tag |
| Header cells | <th> with scope="col" or scope="row" — never empty |
| Complex tables | Avoid merged cells and multi-level headers; split into simpler tables if needed |
| Cell widths | Use % not px — allows browser reflow; never set cell height manually |
| Lists | Use <ul>, <ol>, or <dl> appropriately — not styled <div> rows |
| Unordered lists | For items where order doesn't matter |
| Ordered lists | For sequential steps, rankings, instructions |
| Description lists | <dl> / <dt> / <dd> for glossaries, FAQs, key-value metadata |
Severity rating
Rate each finding by how completely it blocks access and which WCAG level it fails:
| Severity | Meaning |
|---|
| Critical | Blocks access entirely for some users. Usually a Level A failure — no keyboard access, no alt text on informational images, missing captions, a keyboard trap. Fix before ship. |
| Major | Significant friction; users can sometimes work around it but shouldn't have to. Usually a Level AA failure — contrast below 4.5:1, placeholder-as-label, color-only error states, missing focus indicators. |
| Minor | Noticeable but low-impact, or a best-practice / AAA improvement — slightly short line length, stark pure-black text, a non-ideal but functional label. |
When in doubt, rate by the user impact (does it block a task or merely add friction?), not by how easy the fix is.
Audit output format
## Accessibility Audit — [Component / Screen Name]
Context: [platform · WCAG target (default AA) · design or code]
### Critical (blocks access entirely)
- [Issue]: [what's wrong] → [fix] — WCAG [X.X.X]
### Major (significant friction)
- [Issue]: [what's wrong] → [fix] — WCAG [X.X.X]
### Minor (best practice / AAA)
- [Issue]: [what's wrong] → [fix] — WCAG [X.X.X]
### Passed ✓
- [what's already working]
Always end with a one-line summary stating the overall WCAG AA compliance status and the top fixes that would get it there.
How to run a good audit
- Establish context. Platform (web/mobile/native), target level (AA by default — only go AAA if asked), and whether you're auditing a design or live code (some checks, like keyboard order and
aria-*, only apply to code).
- Sweep all six categories. The value of this skill over a default review is completeness — don't stop at contrast and alt text.
- Rate by barrier, not by effort. A one-line
alt fix can still be Critical.
- Be specific in fixes. Give the exact change (markup, attribute, ratio, or design adjustment), not "make it accessible."
- Note tooling limits. Automated scanners catch only ~30–40% of issues — manual review of focus order, alt-text quality, and reading order still matters.
Recommended tools
For automated scanning (catches ~30–40% of issues):
- WAVE (browser extension) — overlays visual indicators, references violated WCAG criteria
- axe DevTools (Chrome extension) — accurate, dev-friendly; powered by axe-core
- Google Lighthouse (Chrome DevTools → Lighthouse tab) — accessibility + SEO + performance in one pass
For contrast checking in design:
- Able (Figma plugin) — contrast checker + color-blindness simulator
- Stark (Figma / Sketch / Adobe XD) — contrast, vision simulator, focus order, alt-text annotations
- WCAG Color Contrast Checker (Chrome extension) — real-time ratio checking in browser
For screen-reader testing:
- VoiceOver (macOS/iOS, built-in) — navigate with
VO + arrow keys
- NV Access / NVDA (Windows, free) — most widely used Windows screen reader
For seizure risk:
- PEAT (downloadable) — analyzes video/animation for photosensitive epilepsy triggers
- Harding Test — online paid service for broadcast/video content
Common do/don't patterns
| ❌ Don't | ✅ Do |
|---|
| Use red text alone for errors | Red border + warning icon + descriptive message |
<a>Click here</a> | <a>Download the onboarding guide (PDF, 1.2 MB)</a> |
<img src="chart.png"> (no alt) | <img src="chart.png" alt="Bar chart showing Q3 revenue by region"> |
| Decorative image with alt text | <img src="bg-swoosh.svg" alt=""> |
Pure black #000 on pure white #FFF | Dark grey #333 on off-white #F8F8F8 |
| Placeholder as the only label | Persistent label above the field + optional placeholder |
Jump from <h1> to <h3> | Always use <h1> → <h2> → <h3> in order |
| Table for page layout | CSS Grid or Flexbox for layout; <table> for data only |
| Autoplay video | Controls visible at top; user initiates playback |
| Color-only chart legend | Add patterns, shapes, or data labels alongside color |
| Report only the obvious issues | Sweep all six categories; rate by barrier; cite the criterion |
Source lessons (Uxcel)
