Accessibility in AEM components
Purpose: Build WCAG-conformant components and keep authored content accessible through authoring-time guardrails.
Who this page is for
| Audience | Why it matters to you |
|---|
| Frontend engineers | You own the markup |
| All engineers | Definition of done includes a11y |
The two halves
| Half | Owner | Mechanism |
|---|
| Component markup (semantics, ARIA, keyboard, contrast) | Engineering | HTL templates + CSS + JS |
| Authored content (alt text, heading order, link text) | Authors — with your guardrails | Dialog validation, required fields, sensible defaults |
Engineering checklist per component
- Semantic elements first (nav, button, table for the benefits table — it IS tabular data); ARIA only where semantics fall short.
- Heading level configurable via dialog/policy (Core Components pattern) so authors keep page heading order — never hardcode h2 everywhere.
- Keyboard: everything interactive reachable and operable (tabs/accordion components: arrow-key patterns per WAI-ARIA Authoring Practices).
- Focus visible (never remove outlines without replacement), focus management in JS widgets.
- Colour contrast ≥ 4.5:1 for text in every Style System variant — check the "featured" gold-on-white trap on the PHI card.
- Images: alt from dialog/DAM metadata, required; decorative images explicitly marked (empty alt).
Authoring guardrails
| Guardrail | Implementation |
|---|
| Required alt text | Dialog field validation (or "decorative" checkbox) |
| Heading level choices | Policy-restricted dropdown |
| Link text quality | RTE configuration; review checklists |
| Language of page | Page properties, feeding html lang |
Verification
Automated (axe / Lighthouse in CI on rendered pages) catches ~40% — keyboard and screen-reader passes on new components remain manual. Put both in the component definition-of-done, not the release crunch.