Web Accessibility

Web Accessibility

Use this skill when the job is to name the failing accessibility surface, fix it at the right layer, and leave behind a short remediation + verification packet.

The job is not to dump generic WCAG prose, paste raw scanner output, or absorb every neighboring frontend concern.

This skill should:

1. classify the failing accessibility surface,
2. separate automated findings from manual or assistive-technology follow-up,
3. choose the smallest credible remediation packet,
4. keep routed-app feedback and focus behavior explicit,
5. route broader design/layout/component-governance work honestly.

Read these support docs first:

• references/intake-packets-and-route-outs.md
• references/audit-remediation-checklist.md
• references/handoff-boundaries.md

When to use this skill

• A team says “make this accessible” and the missing accessibility surface is still unclear
• axe, Lighthouse, Accessibility Insights, Pa11y, QA notes, or user reports need to be turned into one remediation plan instead of a raw finding dump
• You need to decide whether the main issue is semantics, keyboard/focus, labels/announcements, reflow/contrast/motion, media alternatives, or routed-app navigation feedback
• A modal, form, nav, menu, table, dashboard, or routed flow needs manual-vs-automated verification guidance before release
• Screen-reader, keyboard-only, or zoom/reflow issues are suspected, but ownership and next checks are unclear

When not to use this skill

• The main task is reusable primitive / slot / variant API design or component-family ownership → design-system
• The main task is viewport adaptation, breakpoint strategy, container-query planning, or layout overflow control → responsive-design
• The main task is token governance, contribution rules, or system-wide frontend standards → design-system
• The task is only to run one tool and paste raw results; run the tool directly, then return here to prioritize remediation and manual follow-up

Instructions

Step 1: Frame the accessibility job before naming fixes

Capture the minimum packet first.

accessibility_intake:
  surface: page | routed-flow | modal | form | nav | menu | table | dashboard | component-family | mixed | unknown
  workflow_type: audit-review | remediation-pass | release-readiness | regression-follow-up | user-reported-bug | design-system-follow-up
  signal_source: axe | lighthouse | accessibility-insights | pa11y | manual-qa | screen-reader-report | user-feedback | mixed | unknown
  primary_surface: semantics | keyboard-focus | labels-announcements | visual-perception-reflow | media-alternatives | routed-navigation-feedback | mixed | unknown
  severity: blocker | major | medium | low | unknown
  ownership: app-team | frontend-platform | design-system | qa-accessibility | shared | unknown

Rule: do not start with “add ARIA,” “run axe again,” or “quote WCAG 2.1.” First label the failing accessibility surface.

Step 2: Choose exactly one primary remediation packet

Use the router in references/intake-packets-and-route-outs.md.

Primary packets:

1. semantics-structure
2. keyboard-focus
3. labels-announcements
4. visual-perception-reflow
5. media-alternatives
6. routed-navigation-feedback

Pick the highest-risk user-facing failure as primary. List everything else as follow-up, not as equal co-owners.

Step 3: Keep the invariants visible

These rules survive every answer:

• automated tools accelerate discovery, but they do not prove accessibility completeness
• native HTML semantics beat ARIA patching when native controls already solve the problem
• keyboard/focus failures in interactive flows usually outrank cosmetic cleanups
• routed apps need explicit focus and announcement decisions because browser navigation cues disappear
• labels, instructions, errors, and async status text are part of task completion, not polish
• every remediation recommendation needs a matching manual verification step

Step 4: Build the accessibility remediation packet

Return this structure:

# Accessibility Remediation Packet

## Scope
- Surface:
- Workflow type:
- Primary packet:
- Confidence: high | medium | low

## Current signal
- Tool or report source:
- What is already known:
- What still needs direct verification:

## Highest-risk gaps
1. ...
2. ...
3. ...

## Recommended first slice
1. ...
2. ...
3. ...

## Verification plan
- Automated re-check:
- Manual keyboard / focus:
- Manual screen-reader / AT:
- Visual / zoom / motion / reflow:

## Ownership and route-outs
- Primary owner:
- Adjacent skills / teams:

Step 5: Use the packet, not a giant checklist

Pull the packet from references/intake-packets-and-route-outs.md.

Packet rules:

• semantics-structure → landmarks, headings, lists, tables, buttons/links, form markup, native-first fixes
• keyboard-focus → tab order, visible focus, trap/escape behavior, initial focus, focus return, composite widget behavior
• labels-announcements → accessible names, helper/error relationships, live regions, status/error messaging, required-state clarity
• visual-perception-reflow → contrast, reduced motion, zoom, reflow, target visibility, state visibility
• media-alternatives → alt text, decorative-vs-informative imagery, captions, transcripts, fallback descriptions
• routed-navigation-feedback → page title / heading announcement, route-change focus strategy, SPA/app-router cues, async load state announcements

Step 6: Separate automated findings from manual proof

Use this split in every serious answer:

• Automated-friendly — missing labels, duplicate IDs, invalid ARIA, simple contrast failures, landmark/heading gaps
• Manual keyboard/focus — tab sequence, visible focus, trap behavior, initial focus, focus return, menu/listbox/dialog interaction
• Manual AT / content quality — announcement usefulness, alt-text quality, label clarity, route-change comprehension, async feedback quality

If the request starts from a scanner, say explicitly that the scanner is the input artifact, not the finished answer.

Step 7: Route adjacent work explicitly

Use these route-outs when the problem crosses boundaries:

Output expectations

A strong answer from this skill should:

1. identify the primary failing accessibility surface,
2. recommend one bounded remediation packet,
3. name the manual verification still required,
4. avoid equating a scanner pass with completion,
5. route broader frontend ownership questions outward instead of absorbing them.

Examples

Example 1: modal audit after axe

Input

Audit this checkout modal for accessibility issues and tell me what to test manually after axe.

Output direction

• choose keyboard-focus or labels-announcements
• treat axe as the input artifact, not the whole workflow
• verify initial focus, trap behavior, focus return, and announcement quality
• keep broader visual-polish critique out unless it materially affects accessibility

Example 2: routed app navigation confusion

Input

Screen-reader users say our React app changes routes but the new page is not announced and focus stays on the old nav link.

Output direction

• choose routed-navigation-feedback