Accessibility Engineering

This skill owns engineering implementation. It does not own design-side WCAG interpretation or formal accessibility-test programs.

Quick Reference

Need	Default	Notes
fix component semantics	semantic HTML first	add ARIA only when HTML is insufficient
keyboard support	tab order, visible focus, correct key handling	test manually every time
screen reader verification	Primary browser/reader pair for the affected users	add a second platform for shared primitives or cross-platform claims
automated coverage	axe-core plus Lighthouse or Pa11y	automation catches markup-level issues, not the full experience
modal or composite widget	APG-aligned pattern	do not invent custom keyboard behavior
compliance prep	Design/test to WCAG 2.2 AA, then map the applicable legal or procurement baseline	do not describe the design target as the binding version everywhere
WCAG 2.2 checklist, axe-core/Pa11y snippets, EU Accessibility Act	references/wcag-2-2-checklist.md	technical mapping only; EAA applicability goes to qualified counsel
run axe-core in CI	scripts/run_axe.sh	exits non-zero on violations

When to Use This Skill

Use this skill when the main work is:

• remediating semantic HTML, labels, roles, and landmarks
• fixing keyboard access, focus management, or SPA route focus behavior
• implementing APG-style component patterns
• improving screen-reader announcements and dynamic content handling
• adding accessibility engineering checks to CI

Route elsewhere when the main work is:

Need	Use Instead
design-side accessibility and interaction design	../software-ui-ux-design/SKILL.md
accessibility test automation program or formal audit flow	../qa-testing-accessibility/SKILL.md
usability research with disabled users	../software-ux-research/SKILL.md
frontend stack setup and general UI build work	../software-frontend/SKILL.md
platform-specific mobile accessibility behavior	../software-mobile/SKILL.md

Defaults

• semantic HTML before ARIA
• visible focus always on
• keyboard support for every interactive element
• screen-reader checks before calling the fix complete
• automation as baseline, not proof of full accessibility
• current standards and regulatory deadlines are volatile and must be verified before final compliance advice

Workflow

1. Identify the affected flow, component, and assistive-technology risk.
2. Replace incorrect custom markup with semantic HTML where possible.
3. Add the minimum ARIA state and relationship attributes required for the pattern.
4. Verify keyboard interaction and focus behavior.
5. Verify screen-reader announcements and dynamic updates.
6. Add or update automated checks to prevent regression. For recorded criterion claims, check_a11y_baseline.py rejects unassessed criteria and missing evidence; its template starts unassessed and it checks claim completeness, not conformance.

Implementation Rules

Semantic HTML First

Default order:

1. native element
2. minimal ARIA enhancement
3. fully custom widget only when no native pattern exists

Common mistakes to avoid:

• div or span used as buttons
• focusable elements hidden from assistive tech
• redundant or conflicting aria-label
• missing state attributes such as aria-expanded
• stripping semantics from interactive elements

Keyboard and Focus

Every interactive surface must support:

• logical tab order
• visible focus indicator
• escape and arrow-key behavior where the pattern requires it
• focus trap and focus restoration for dialogs
• route-change focus management in SPAs

Screen Reader Verification

Minimum verification set:

• landmarks and heading structure
• form labels and error association
• role and state announcement for controls
• live-region behavior for dynamic feedback
• meaningful alt text and decorative-image hiding

Choose the assistive-technology matrix from the claim and blast radius:

Change	Minimum manual evidence
Page-specific copy, label, or state fix	One supported browser/reader pair used by the affected audience
Shared widget or design-system primitive	One Apple and one Windows/browser pair where the product supports both
Mobile-native behavior	The platform reader on a physical target device (VoiceOver or TalkBack)
Broad “accessible” or conformance claim	Product support matrix plus disabled-user testing or a qualified audit; automation alone is insufficient

If a required platform is unavailable, report that cell as unverified. Do not block a narrow source fix merely because an unrelated platform cannot be exercised, and do not generalize the evidence beyond the tested pair.

Automation and CI

Layer	Tool	Catches
Authoring	eslint-plugin-jsx-a11y (React) or axe-linter	Missing labels, wrong roles, bad ARIA usage
Development diagnostics	@axe-core/react	Logs runtime findings in the development console
Component tests	jest-axe	Rule checks on the rendered test state
E2E / integration	axe-core via Playwright or Cypress	Page-level violations in rendered state
CI gate	Lighthouse or Pa11y	Score regression and critical issues

Automation does not replace keyboard walkthroughs, screen-reader validation, or judgment on content order, announcement quality, and alt-text quality.

A clean scan covers only the rules and rendered states exercised. Report the tool, route/state, violations and manual evidence; it does not establish WCAG conformance.

When Automation Is Enough vs When a Human Must Check

Signal type	Automatable	Requires a human pass
Missing alt, label, or landmark	Yes — rule-detectable	—
Contrast ratio below threshold	Partial — supported rendered cases	Yes when gradients, images, transparency or incomplete results prevent a reliable computed check
role/state attribute present but semantically wrong for context	Partial — flags presence, not correctness	Yes — judgment on whether the role fits the interaction
Reading order matches visual order	No	Yes — screen-reader walkthrough
Live-region announcement is timely and not noisy	No	Yes — screen-reader walkthrough
Focus lands somewhere sensible after a route change or async update	No	Yes — keyboard + screen-reader walkthrough
Alt text is accurate and non-redundant (not just present)	No	Yes — content review
Keyboard operability of a composite widget (arrow keys, Home/End, typeahead)	No	Yes — manual keyboard pass

Never report an automated scan result (axe-core, Lighthouse, WAVE, Pa11y) as "accessible" or "WCAG conformant" on its own — report it as "N automated violations resolved; manual keyboard and screen-reader verification pending/complete."

Remediation Prioritization

When a scan or audit returns more issues than can be fixed at once, rank by user impact, not by rule-engine severity label alone:

1. Blocks a core task entirely (cannot submit a form, cannot open a required dialog, cannot complete checkout) — fix first regardless of how many instances exist.
2. Affects a high-traffic or legally sensitive flow (auth, checkout, account settings, any flow named in a demand letter or audit finding) — fix next.
3. Widespread pattern-level defect (e.g., every icon button sitewide is unlabeled) — fix once at the component/design-system level; this clears more violations per hour of engineering time than any single-page fix.
4. Isolated, low-traffic instances — batch these; do not let them block a release on their own merits.

Effort-vs-impact check before committing to a large remediation plan: a single shared-component fix (e.g., the button, input, or modal primitive) frequently resolves dozens of scattered violations at once — audit the design system before auditing every page.

Accessibility Overlay Warning

Do not recommend, and flag if found, third-party "accessibility overlay" scripts as a compliance solution: their marketing promise does not establish that semantics, labeling, keyboard and focus work; require implementation and assistive-technology evidence. If one is installed, fix the underlying markup and demote the overlay to an optional enhancement. Legal evidence and enforcement precedent are owned by qa-testing-accessibility.

Common Patterns

Prefer native <dialog>.showModal() for modal surfaces; use Popover API for suitable non-modal surfaces. Test forced colors and composed headless-library contracts; map ISO/IEC 40500 by its cited edition. Implementation conditions, keyboard and ARIA requirements for tabs, dialog, combobox, accordion, menu, and tree view: references/remediation-playbook.md.

Known Traps

• Route transitions in SPAs that never move focus to the new page heading or landmark.
• Dialogs that trap focus while open but fail to restore focus to the triggering control on close.
• Toasts and validation messages that update visually but never announce through a correctly scoped live region.
• Screen-reader-hidden containers that still contain focusable descendants.
• Composite widgets that handle arrow keys but forget Home/End, Escape, typeahead, or disabled-item semantics required by the pattern.
• Mobile-only testing that misses desktop screen-reader and keyboard failures.

Common Anti-Patterns

• Placeholder text used as the only label.
• Click handlers on non-interactive elements without full keyboard and semantic remediation.
• Positive tabindex used to force order instead of fixing DOM order.
• aria-label added on top of already-correct visible labels, creating redundant or conflicting names.
• aria-hidden="true" applied to visible interactive content.
• Custom selects, comboboxes, or menus built from scratch when a native control or established APG pattern would work.

AI-Generated Accessibility Risks

Pay extra attention to AI-produced code that shows div soup, broken or invented ARIA, missing form labels, skipped heading hierarchy, low-contrast styling, missing or broken focus states, or incomplete keyboard handlers.

Verification Gate

Do not call the work complete until all of these are checked:

• Keyboard walkthrough passes for the affected flow (Tab, Shift+Tab, Enter, Escape, arrow keys as required)

• Visible focus indicator present in all interactive states (never removed with outline: none alone)

• Screen-reader output checked on the risk-based matrix above; tested browser/reader/device pairs and unverified pairs are named

• Zero critical or serious axe-core violations remain; any suppressed violation has an explicit justification comment

• Heading levels express the content hierarchy and labels describe purpose; inspect skipped levels in context rather than treating every skip as an automatic WCAG failure; landmarks match intended page regions

• All form inputs have visible labels bound via for/id or aria-labelledby; errors use aria-describedby

• Task status updates announced briefly where needed; streamed content retains normal semantics and is not wrapped wholesale in a live region

• Any WCAG or legal-compliance claim is verified against W3C/WAI or official regulatory sources, not memory

• Verify current WCAG, EN 301 549, EAA, browser-support, and tool-maintenance claims before final advice.

• Prefer W3C, WAI, official tool docs, and government or regulator sources.

Scenarios

Symptom-keyed recipes S1-S5 (form label/error/focus audit, modal focus trap with inert and focus return, contrast remediation in design tokens, RSC route-change focus loss, reduced-motion fallback): references/remediation-playbook.md.

Navigation

Adjacent skills

• ../software-ui-ux-design/SKILL.md
• ../qa-testing-accessibility/SKILL.md
• ../software-frontend/SKILL.md
• ../software-mobile/SKILL.md
• ../software-localisation/SKILL.md
• ../qa-testing-playwright/SKILL.md

Sources

• data/sources.json
• references/remediation-playbook.md — APG widget patterns and remediation scenarios
• references/regulatory-traps.md — conformance mapping traps (EN 301 549, native apps, third-party components, WCAG 2.2 delta) and the overlay warning
• references/wcag-2.2-and-3.0-watchlist.md — WCAG 2.2 AA baseline, 3.0 draft watchlist, RSC focus gaps, CI coverage map

Conformance Mapping

• EU Accessibility Act: whether it applies to a product is a question for qualified counsel; law, deadlines, exemptions and enforcement live in qa-testing-accessibility. Technical mapping stays here: start from Directive 2019/882 Annex I and the national transposition; EN 301 549 is engineering evidence whose edition, cited directive and WCAG mapping must be looked up (ETSI, Official Journal) rather than named from memory. Target WCAG 2.2 AA for new builds.
• Native apps, third-party components, WCAG 2.2 delta: references/regulatory-traps.md.

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.