Accessibility Beyond the Basics

Most candidates can say "use semantic HTML and add alt text". Senior interviews go further: "How do you handle focus after a route change in a single-page app?", "Why is role="button" on a div a promise you must keep?", "What can axe not see?" This lesson goes one level deeper than Accessibility Essentials (Frontend Depth, Lesson 6). That lesson covers semantic HTML first, focus in modals, ARIA only when needed, and a first keyboard test. I do not repeat it here. If any term below feels new, read Lesson 6 first. For the HTML and CSS basics behind landmarks, see also Full-Stack Q&A, Lesson 01. For testing tool basics (Testing Library, Playwright), see Lesson 21.

Words used in this lesson

• Accessibility (a11y) means people with disabilities can use your product. That includes people who cannot see (screen reader), cannot use a mouse (keyboard, switch), cannot hear, need larger text, or have a temporary limit like a broken arm. "a11y" is short for "a, 11 letters, y".
• WCAG (Web Content Accessibility Guidelines) is the W3C standard that most laws and contracts point to. It is made of success criteria (SC): testable rules with a number like 1.4.3 and a level: A (basic), AA (the usual legal target) and AAA (extra).
• An accessibility tree is the list of objects the browser gives to assistive tools: each has a role (button, link, heading), a name (the text a screen reader says) and states (checked, expanded).
• A screen reader is software that reads the screen aloud (or to a braille display). Examples: NVDA and JAWS on Windows, VoiceOver on Apple devices, TalkBack on Android.
• A landmark is a page region that screen reader users can jump to: banner, navigation, main, complementary, contentinfo, search, form, region.
• An accessible name is the text that identifies a control to assistive tools. It comes from a <label>, the element's own text, aria-labelledby or aria-label.
• ARIA (Accessible Rich Internet Applications) is a set of attributes (role, aria-*) that change what the accessibility tree says. It changes only the description, never the behaviour.
• Focus is the element that receives keyboard input right now. Focus order is the order Tab moves through elements. Focus management means moving focus on purpose, for example into a dialog.
• A live region is an element whose changes a screen reader announces without moving focus. Polite announcements wait for a pause. Assertive ones interrupt.
• inert is an HTML attribute that makes an element and its children not clickable, not focusable and hidden from assistive tools.
• Contrast ratio is a number from 1:1 (no difference) to 21:1 (black on white) that compares how bright two colours are.

WCAG 2.2 in plain words

WCAG has four principles: Perceivable (users can sense it), Operable (users can use it), Understandable and Robust (works with assistive tools). Version 2.2 adds new criteria and removes one: 4.1.1 Parsing is gone. The w3c/wcag repository lists the new ones. I read each wording from the source:

Older criteria that interviewers still ask about (wording checked in the repository):

Semantic HTML and landmarks, one level deeper

Lesson 6 says "use the right element". The deeper rules are about structure that screen reader users navigate by.

• One <main>, one page-level <h1>, and headings that do not skip levels (no h1 then h3). Headings are used as a table of contents, so style with CSS, not with the heading level.
• Landmarks come from elements: <header> (page level) is banner, <nav> is navigation, <main>, <aside> is complementary, <footer> (page level) is contentinfo. A <section> is a region only if it has an accessible name.
• Name repeated landmarks. Two <nav> elements need aria-label="Main" and aria-label="Footer", so a landmark list is not "navigation, navigation".
• Skip link. The first focusable element is <a href="#main">Skip to content</a>. Target <main id="main" tabindex="-1">, so focus really moves there.
• Lists, tables and buttons are semantics. A real <ul> tells "list of 5 items". A real <table> with <th scope> lets a reader say the column name for each cell. A <button> gives Enter, Space and the role for free.
• Links go places, buttons do things. Do not use <a href="#" onclick> for an action.
• Language. <html lang="en"> picks the right voice. Mark a phrase in another language with lang on that element.

I ran axe on a page full of mistakes. It found these rules (and the number of elements):

button-name (1)  heading-order (1)  html-has-lang (1)  image-alt (1)link-name (1)    list (1)           region (6)

A page with lang, <main>, one <h1> then <h2>, a named <nav>, a labelled input, a submit button and alt text returned no violations.

Forms: labels, hints, errors

A form is where most real-world failures live. The rules:

1. Every control has a visible <label for> (or wraps the input). The label text is the accessible name.
2. Group related controls with <fieldset> and <legend> (radio buttons, "Shipping address"). The legend is read before each option.
3. Hints and errors are linked with aria-describedby. The name is the label; the description is read after it.
4. Mark invalid fields with aria-invalid="true" and put the message in text next to the field. Colour alone fails 1.4.1 (use of colour) and 3.3.1.
5. Use autocomplete tokens (email, given-name, current-password). This helps people who cannot type easily and satisfies 1.3.5 (identify input purpose). Do not block paste in a password field: it breaks 3.3.8.
6. Use the right type (email, tel) for the right mobile keyboard.
7. Do not mark required fields with colour only. Use the required attribute and a visible "(required)" or a legend explaining the star.

<label for="email">Email</label><input id="email" name="email" type="email" autocomplete="email"       aria-invalid="true" aria-describedby="email-hint email-err" required><p id="email-hint">We only use it for receipts.</p><p id="email-err">Enter an email like name@example.com</p>

On submit with errors, the pattern most design systems use is an error summary: move focus to a box at the top that says "There is 1 problem" and lists links that jump to each field. Each link text matches the message. I ran axe on a page with this summary (role="alert", tabindex="-1" so script can focus it), the linked field and a fieldset of radios: no violations. Without a summary, a keyboard user who presses Submit and sees nothing happen has no way to know where the errors are.

Focus management and route changes in a single-page app

When a normal page loads, the browser resets focus and a screen reader announces the new title. In a single-page app (SPA), a link click changes the content but nothing tells the user. Focus can even stay on a link that no longer exists. You must handle three things:

1. Announce the new page. Next.js includes a route announcer. I read it in the installed package: it is an element with role="alert", and it chooses the text from document.title first, then the <h1>, then the URL path. The Next.js accessibility doc says to give every page a unique and descriptive title. It announces the title but does not move focus.
2. Place focus. A common pattern is to move focus to the new page's <h1> (give it tabindex="-1") or to the <main> after navigation. Then the next Tab starts from the top of the new content, and the reader says the heading. I ran a small helper in jsdom that focuses the h1 and document.activeElement became H1. (A real browser needs tabindex="-1" for a non-interactive element to take focus; jsdom is more forgiving, so I do not rely on that part.)
3. Restore focus when something closes. After closing a dialog, focus goes back to the control that opened it. After deleting a list item, focus goes to the next item or the list heading, not to <body>.

// run after the route has rendered (for example in an effect keyed by pathname)function focusPageHeading() {  const h1 = document.querySelector<HTMLElement>('main h1')  h1?.setAttribute('tabindex', '-1')  h1?.focus({ preventScroll: false })}

Be careful with two traps. First, do not run it on the first load (the browser already did the work). Second, do not move focus on every re-render or on a filter change the user did not expect: focus moves must follow user actions. Also do not use tabindex greater than 0: it changes the tab order for the whole page and nearly always breaks it.

Modals and dialogs

A modal dialog needs: a name, focus moved inside, focus kept inside, the page behind unreachable, Esc to close, and focus returned on close. Doing this by hand takes a lot of code. The native <dialog> element does most of it:

<button id="open">Delete project</button><dialog id="dlg" aria-labelledby="dlg-title">  <h2 id="dlg-title">Delete this project?</h2>  <p>This cannot be undone.</p>  <form method="dialog">    <button value="cancel" autofocus>Cancel</button>    <button value="delete">Delete</button>  </form></dialog><script>  const dlg = document.getElementById('dlg')  document.getElementById('open').addEventListener('click', () => dlg.showModal())  dlg.addEventListener('close', () => console.log(dlg.returnValue))</script>

From the WHATWG HTML source (I read it; I did not run a browser):

• showModal() makes the rest of the document inert and records the previously focused element. Esc is a close request and closes it. form method="dialog" closes it and sets returnValue to the clicked button's value.
• When the dialog closes, the browser runs the focusing steps for the previously focused element, so focus goes back to the button that opened it.
• The autofocus attribute on a descendant picks where focus lands first. Put it on the safest button (Cancel), not on a destructive one.
• There is a newer closedby attribute (any, closerequest, none). The default for a modal behaves like closerequest. It is in the spec text; check browser support before you depend on it.
• dialog.show() (not modal) does not make the page inert. It is for non-modal panels.

For a custom modal (a library or a drawer), you need what <dialog> gives: put inert on the app root while it is open (or use aria-modal="true" and check the readers you target; inert is more reliable than aria-modal alone), move focus in, trap Tab, close on Esc, and restore focus. Use a tested library such as Radix or React Aria instead of your own code. A popover (a small panel, menu, tooltip) is different from a modal: it does not block the page. HTML has a popover attribute for that; do not use role="dialog" for a tooltip.

Live regions and status messages

Criterion 4.1.3 says status messages must be announced without taking focus. You do it with a live region.

Rules that save you from bugs:

• The region must exist in the page before you change it. If you insert <div role="status">Saved</div> all at once, many readers say nothing. Render an empty <div role="status"></div> at page load, and later set its text.
• Keep it in the DOM and visible to the accessibility tree. display: none or hidden removes it. Hide it visually with a "visually hidden" CSS class (a 1 pixel clipped box), not with display: none.
• Do not announce everything. A live region that talks on every keystroke makes the page unusable. Debounce search results ("12 results") and announce the final count once.
• Same text twice may not announce twice. I observed in jsdom that setting textContent = 'Saved' two times produced two DOM mutations, but whether a reader says it twice depends on the reader. A known trick is to clear the text, wait a moment, then set it. I could not test this with a real reader, so treat it as something to verify on your target readers.
• role="alert" on content that is already on the page at load is often announced on load. Use it only for new errors.

ARIA rules of thumb

The ARIA Authoring Practices "Read Me First" page has two principles I use in interviews: "No ARIA is better than bad ARIA" and "a role is a promise". Writing <div role="button">Place Order</div> promises that you also wrote the keyboard code a button has (Enter and Space, focusable, disabled state). ARIA roles add no behaviour and no styling.

The usual short list:

1. Use a native element if one exists (button, a, input, select, details, dialog).
2. Do not change native meaning (<h2 role="tab"> is wrong; put the role on a wrapper).
3. Every interactive ARIA control works with the keyboard.
4. Never put aria-hidden or role="presentation" on a focusable element.
5. Every interactive element has an accessible name.

What ARIA is really for: things HTML cannot say yet, such as aria-expanded on a toggle, aria-current="page" on the current link, aria-live, aria-describedby, and widgets like tabs and comboboxes (follow the APG pattern exactly, with its keys).

I tested a page with four ARIA mistakes: role="link" on a button with aria-pressed, an empty role="menu", an aria-labelledby pointing nowhere, and a button with aria-label="Save" whose visible text was "Cancel". axe reported only aria-allowed-attr (the aria-pressed on a link role). It did not report the other three as violations in this default run. The visible-text mismatch breaks the "label in name" rule (2.5.3), which speech-control users depend on, and a tool did not catch it. Review ARIA by hand.

Colour contrast, in numbers

WCAG 1.4.3 needs 4.5:1 for normal text and 3:1 for large-scale text. 1.4.11 needs 3:1 for control borders, icons and focus rings. The ratio uses the relative luminance of each colour: (lighter + 0.05) / (darker + 0.05). I wrote the formula in 8 lines of Node and calculated:

Things to remember:

• Placeholder text, disabled-looking links, grey helper text and text on images fail most often. Brand colours often fail on white.
• Do not rely on colour alone (1.4.1). An error needs an icon and text, a link in text needs an underline, a chart needs patterns or labels.
• Dark mode is a second palette. Check both.
• A tool cannot check text over images or gradients. In jsdom, axe's color-contrast came back as incomplete, not as a failure, because jsdom does not paint. jest-axe says in its README that colour contrast checks do not work in jsdom, so it turns them off. Check contrast in a real browser (Playwright, DevTools) or in design tokens.
• Contrast checks the WCAG 2 formula. Some people think it is inaccurate for dark themes. A newer method (APCA) is a draft idea for a later WCAG; the legal target today is still the ratio above.

Motion and animation

Some people get dizzy or sick from large movement (parallax, zoom, spinning). The operating system has a setting "reduce motion", and CSS can read it:

.hero { animation: slide-in 600ms ease-out; }@media (prefers-reduced-motion: reduce) {  .hero { animation: none; }  html { scroll-behavior: auto; }}

Rules: do not remove all motion (a loading spinner still tells the user something is happening); replace big movement with a fade or no animation. Autoplaying video or a carousel that lasts more than 5 seconds needs a pause button (2.2.2). Never flash more than three times a second (WCAG 2.3.1). In JavaScript read it with window.matchMedia('(prefers-reduced-motion: reduce)').matches. Tailwind has a motion-reduce: variant. WCAG 2.3.3 (Animation from Interactions) is a AAA criterion, so it is a good practice rather than a usual legal need.

Testing: keyboard walk-through, tools, screen readers

Use three layers. They find different things.

1. Keyboard walk-through (5 minutes, no tools)

Put the mouse away. Then check:

• Can I reach every control with Tab and Shift+Tab, in an order that matches the screen?
• Can I see where focus is at all times? (Not hidden by a sticky header: 2.4.11.)
• Enter activates links and buttons, Space activates buttons and checkboxes. Arrow keys move inside radio groups, tabs, menus.
• Esc closes dialogs and menus. Focus returns to the opener.
• No keyboard trap (focus cannot leave a widget). Every drag has a non-drag option.
• After a route change, error or dialog, does focus go somewhere sensible?
• Zoom the browser to 400% and set a 320 pixel window: is anything cut off or needing two-way scroll (1.4.10)?

2. Automated checks with axe-core

axe-core is the engine behind most tools. Its README says it finds on average 57% of WCAG issues automatically and reports others as "incomplete" for manual review. In axe-core 4.14.0 there are 105 rules, and the only rule tagged wcag22aa is target-size. So most new 2.2 criteria are for humans to check.

jest-axe (works with Jest or any test runner and jsdom). I ran its axe() function in the Node test runner on <main><h1>x</h1><img src="a.png"></main> and it returned the violation image-alt. The Jest matcher is expect(await axe(html)).toHaveNoViolations() (I read this in its README; I called axe() but did not run the Jest matcher):

import { axe, toHaveNoViolations } from 'jest-axe'expect.extend(toHaveNoViolations)test('signup form has no detectable violations', async () => {  const { container } = render(<SignupForm />)  expect(await axe(container)).toHaveNoViolations()})

Playwright with axe runs in a real browser, so colour contrast, focus visibility and aria-hidden-focus can be decided. This is from the @axe-core/playwright 4.13.0 README (not run here, no browser):

import AxeBuilder from '@axe-core/playwright'test('home page', async ({ page }) => {  await page.goto('/')  const results = await new AxeBuilder({ page })    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])    .exclude('#third-party-chat')    .analyze()  expect(results.violations).toEqual([])})

A good setup: jest-axe for component states (error state, open dialog), Playwright axe for whole pages in CI, and eslint-plugin-jsx-a11y while typing (Next.js includes it by default, per its accessibility doc). Run axe on states too: open the menu, show the error, then scan. A page scan of the closed state tests nothing about the dialog.

3. Screen reader basics

Test with at least one reader on its common browser pair: NVDA with Firefox or Chrome (Windows), VoiceOver with Safari (Mac and iOS), and TalkBack with Chrome (Android). I did not run any in this lesson. A short first test with VoiceOver on a Mac: turn on with Cmd+F5, open the rotor with VO+U (VO is Control+Option) to list headings, links and landmarks, and move with VO+Right Arrow. Ask: Is every control announced with a name and role? Are headings and landmarks a sensible outline? Are errors and status messages announced? Does a dialog read its title? Different readers say things differently, so judge whether the information is there, not whether the wording matches.

Common mistakes

• Saying "we use ARIA" as proof of accessibility, with div buttons that have no keyboard code.
• A placeholder as the only label.
• Removing the focus outline (outline: none) with no replacement.
• Hiding a modal's background with aria-hidden and leaving it focusable.
• SPA route changes with no announcement and no focus move.
• Errors shown only in red, or only in a toast that disappears.
• A live region created at the moment of the message.
• Contrast checked on the design file but not on hover, disabled, dark mode or text over images.
• Trusting a green axe report and never using the keyboard.

Interview questions

Key takeaways

• WCAG 2.2 added 2.4.11 (focus not hidden), 2.5.7 (no drag-only), 2.5.8 (24 pixel targets), 3.2.6, 3.3.7 and 3.3.8 and removed 4.1.1. Know the plain meaning of each.
• Landmarks, one h1, ordered headings, named repeated nav and a skip link make a page navigable.
• Forms need real labels, fieldset/legend, aria-describedby for hints and errors, aria-invalid, autocomplete, and an error summary with focus.
• In an SPA, announce the route (Next.js does this with the title, then h1) and move focus on purpose. Never use tabindex above 0.
• Prefer native <dialog> with showModal(), and inert for custom modals. aria-hidden alone leaves controls focusable.
• Create live regions early, keep them in the accessibility tree, use status by default and alert rarely.
• ARIA changes description, not behaviour. No ARIA is better than bad ARIA.
• Know the numbers: 4.5:1 for text, 3:1 for large text and UI parts, 24 by 24 pixels for targets, 320 pixel reflow. #767676 on white is the lightest passing grey.
• Test with the keyboard, then axe (jest-axe for components, Playwright for pages), then a screen reader. Automation finds only part of the problems.

What's next

Do the 5-minute keyboard walk-through on one of your own pages today and write down what breaks. Then add one axe check for an important state (error form or open dialog) to your tests. For the first layer of this topic, go back to Accessibility Essentials (Frontend Depth, Lesson 6). The next lesson is GraphQL beyond Hasura.