Ux Accessibility Audit

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:

1. Every finding cites the WCAG criterion and level it violates — not a vague suggestion.
2. Every finding gets a severity based on how completely it blocks access — so the list is prioritized.
3. Every finding has a concrete fix — the specific markup/design change.
4. 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 ` per page | Page title only | | Heading hierarchy | No skipped levels (h1 → h2 → h3, never h1 → h3) | | Semantic heading tags | Use –, not styled or ` | | 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 ` tags — ` 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 ` element — never use tables for layout | | Table caption | immediately after opening tag | | Header cells | 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 , , or appropriately — not styled rows | | Unordered lists | For items where order doesn't matter | | Ordered lists | For sequential steps, rankings, instructions | | Description lists | / / ` 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

1. 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).
2. Sweep all six categories. The value of this skill over a default review is completeness — don't stop at contrast and alt text.
3. Rate by barrier, not by effort. A one-line alt fix can still be Critical.
4. Be specific in fixes. Give the exact change (markup, attribute, ratio, or design adjustment), not "make it accessible."
5. 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 | | Click here | Download the onboarding guide (PDF, 1.2 MB) | | ` (no alt) | | | Decorative image with alt text | | | 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 to | Always use → → in order | | Table for page layout | CSS Grid or Flexbox for layout; ` 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)

• Intro to Accessibility
• Accessibility Tools
• Color Accessibility
• Text Accessibility
• Forms Accessibility
• Links Accessibility
• Multimedia Accessibility
• Tables & Lists Accessibility

Source & license

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

• Author: Uxcel-Lab
• Source: Uxcel-Lab/product-skills
• License: MIT
• Homepage: https://uxcel.com

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