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 broad UI polish, heuristic review, hierarchy, or interface consistency → web-design-guidelines
• The main task is reusable primitive / slot / variant API design or component-family ownership → ui-component-patterns
• 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
• classify title/heading announcement plus focus-reset strategy
• include manual AT verification after the fix
• avoid turning the task into generic routing architecture work

Example 3: component-boundary confusion

Input

Our button primitive API is messy and some variants are not accessible. Is this web-accessibility or ui-component-patterns?

Output direction

• keep accessible-name, focus-state, and disabled/loading announcement fixes in web-accessibility
• route primitive API / variant ownership to ui-component-patterns
• split the plan instead of forcing one skill to own everything

Example 4: manual checks after Lighthouse

Input

Lighthouse says contrast is okay now. What should I still test manually?

Output direction

• treat this as verification planning, not score celebration
• verify keyboard order, focus visibility, routed-flow cues, and screen-reader announcement quality where relevant
• include zoom/reflow and reduced-motion checks when the interface depends on them

Best practices

1. Start with the user task and failing surface, not the rule number. 2. Treat automated tools as accelerators, not as proof of accessibility completeness. 3. Prefer native HTML semantics before ARIA-heavy patches. 4. Keep focus behavior intentional for overlays, route changes, and async validation. 5. Separate remediation packets from broader design-review or component-architecture work. 6. When unsure, name the manual verification still required instead of pretending the scan is enough.

References

• W3C: Evaluating Web Accessibility Overview
• W3C: Easy Checks – A First Review of Web Accessibility
• web.dev: Manual accessibility testing
• MDN: Keyboard accessible
• React Router: Accessibility
• Next.js: Accessibility

Accessibility Audit → Remediation Checklist

Use this when the user asks for an accessibility audit, remediation plan, or post-scan manual verification checklist.

1. Frame the surface

• Page / flow / component:
• Critical user task:
• Buckets involved: structure, keyboard/focus, name/role/value, content/feedback, visual perception, media

2. Automated pass

Capture issues from tools such as axe, Lighthouse, Pa11y, or Accessibility Insights.

Typical automated-friendly findings:

• missing labels or accessible names
• duplicate IDs
• invalid ARIA usage
• contrast issues on simple cases
• missing landmark / heading / form relationships

3. Manual verification

Always check what automated tools cannot fully prove:

• tab order is logical
• focus indicator stays visible
• overlays move focus in and return it correctly
• Escape / Enter / Space / arrow-key behavior matches the widget type
• error messages are understandable and announced
• screen-reader output is useful, not just technically present
• zoom/reflow and reduced-motion behavior still work for the task

4. Fix order

1. Blockers: keyboard trap, inaccessible primary controls, broken form submission paths 2. Meaning: missing labels, unclear instructions, bad announcements, poor error text 3. Robustness: semantic cleanup, ARIA simplification, consistency across widgets 4. Visual follow-up: contrast, motion, visible states, zoom/reflow edge cases

5. Route-outs

• broader UI/polish audit → web-design-guidelines
• reusable primitive API work → ui-component-patterns
• system-level token/pattern ownership → design-system
• viewport/layout adaptation → responsive-design

6. Packet template

## Findings
1. ...

## Recommended fixes
- ...

## Verification
- Automated:
- Manual keyboard:
- Manual screen-reader / AT:

## Route-outs
- ...

Handoff Boundaries for web-accessibility

Use this file when multiple frontend skills could plausibly activate.

Keep work in web-accessibility when

• the main job is fixing or verifying accessibility behavior
• the user mentions a11y, WCAG, keyboard trap, focus return, labels, ARIA, screen readers, contrast, reduced motion, or manual accessibility checks
• the question is what still needs manual or assistive-technology verification after an automated scan

Route to web-design-guidelines when

• the request is a broader UI audit, design/polish review, or multi-rule compliance review
• accessibility is only one part of a wider review surface
• the user asks to review UI files against general interface/design guidance

Route to ui-component-patterns when

• the main question is primitive/component API shape, composition, slots, variants, or controlled-vs-uncontrolled design
• accessibility is a constraint on the component architecture, not the whole task

Route to design-system when

• the work is about token, primitive, pattern-library, or system-governance direction
• the team needs rules for multiple components before remediating one instance

Route to responsive-design when

• the main failure is viewport adaptation, breakpoint behavior, responsive media, or mobile layout
• accessibility semantics are secondary to the layout problem

Mixed cases

When a request spans multiple skills, split the answer explicitly:

• web-accessibility owns remediation and verification for the a11y failure
• neighboring frontend skills own broader review, API architecture, or layout concerns

Do not force one skill to own everything if the better answer is a divided plan.

Accessibility Intake Packets and Route-Outs

Use this note after the main accessibility surface has been classified.

1. semantics-structure

Use when the core problem is missing or misleading HTML semantics.

Focus

• landmarks, headings, lists, tables, links, and button semantics
• form label/control relationships
• replacing clickable div / span patterns with native controls
• simplifying ARIA that is compensating for bad markup

Return

• highest-risk semantic gaps
• native-first replacement plan
• where headings/landmarks/form relationships must change first
• route-outs if the problem is really system governance or component API architecture

Route-outs

• reusable primitive API ownership → ui-component-patterns
• multi-product token/pattern governance → design-system

2. keyboard-focus

Use when interactive flow quality is the main risk.

Focus

• tab order and reachability
• visible focus states
• modal/dialog/listbox/menu/tab keyboard behavior
• initial focus, trapped focus, and focus return

Return

• the highest-risk interaction failures
• exact focus movement rules to implement
• which widgets need native semantics versus custom interaction work
• manual keyboard proof required before sign-off

Route-outs

• reusable primitive API redesign → ui-component-patterns
• broad UI critique unrelated to accessibility → web-design-guidelines

3. labels-announcements

Use when controls are technically present but meaning is unclear.

Focus

• accessible names for icon-only or ambiguous controls
• field labels, helper text, required-state messaging, and error summaries
• live-region usage for async save/validation/status updates
• announcements that are technically present but not useful in context

Return

• missing/weak names and relationships
• clearer instruction/error/announcement fixes
• where copy changes matter more than extra ARIA
• which updates must be verified with screen readers or AT

Route-outs

• broad content/copy hierarchy review → web-design-guidelines
• form/system architecture beyond accessibility messaging → neighboring product/frontend skill

4. visual-perception-reflow

Use when visual access or layout adaptation blocks real task completion.

Focus

• contrast, focus visibility, and state visibility
• zoom and reflow behavior
• reduced-motion handling and animation safety
• touch-target or visibility problems tied to responsive layouts

Return

• the highest-risk visibility/reflow failures
• whether the issue is accessibility remediation versus layout-strategy ownership
• manual verification for zoom, motion, and real task completion
• route-outs when viewport/container strategy is the primary problem

Route-outs

• breakpoint/container/layout strategy → responsive-design
• system-level color/motion/token governance → design-system

5. media-alternatives

Use when images, audio, or video lack useful alternatives.

Focus

• informative vs decorative images
• alt-text quality in context
• captions, transcripts, and descriptions
• fallback text for charts/complex visuals

Return

• which media need alternatives first
• quality bar for alt/caption/transcript work
• content or editorial ownership notes
• manual review needed because usefulness is contextual

Route-outs

• editorial/content-strategy ownership → content/documentation skill
• broader media-production workflow → media-specific skill

6. routed-navigation-feedback

Use when client-routed apps lose browser navigation cues.

Focus

• route-change title/heading announcements
• where focus should move after navigation
• loading/transition announcements in SPA or app-router flows
• route changes that leave focus on stale controls or old nav items

Return

• preferred page-change feedback strategy
• exact focus-reset or announcement expectations
• which flows need manual screen-reader verification
• honest boundary between accessibility remediation and broader router/runtime design

Route-outs

• generic routing/data-flow architecture without accessibility failure evidence → router/framework skill
• pure React/Next performance issues → react-best-practices

Quick routing heuristic

• If the request starts from axe/Lighthouse output, classify the failure surface before suggesting fixes.
• If keyboard or focus breaks task completion, prefer keyboard-focus even when other issues exist.
• If the request says “screen reader users don’t know the page changed,” prefer routed-navigation-feedback.
• If the issue is mostly layout strategy or breakpoint choice, route to responsive-design and keep accessibility here only for verification/remediation spillover.
• If the issue is mostly reusable primitive ownership, split the answer with ui-component-patterns instead of stretching this skill.