Accessibility Engineering: Beyond Compliance Checklists

You run Lighthouse on your application and it returns a 94 accessibility score. The team marks accessibility as done. Ship it.

Six months later, a screen reader user files a support ticket. They cannot complete your checkout flow. The address autocomplete dropdown is invisible to their assistive technology. The quantity stepper has no accessible name. Pressing Escape in the payment modal dumps focus back to the top of the page instead of the button that opened it. Three separate failures in a single user journey. None of them showed up in Lighthouse because Lighthouse cannot navigate your application the way a real user does.

This is the trap that catches every team eventually. Automated accessibility scanners analyze the DOM at a single point in time. They check for alt attributes, contrast ratios, form label associations, and ARIA attribute validity. They are good at this. But they cannot evaluate whether a screen reader’s announcement sequence makes sense during a multi-step workflow. They cannot tell if keyboard focus moves logically through a dynamically rendered component. They cannot determine whether a custom combobox is operable using only arrow keys and Enter. The 30-40% of issues that automated tools catch are the easy ones. The 60-70% they miss are the ones that actually prevent people from using your product.

The ARIA Paradox: More Is Worse

ARIA (Accessible Rich Internet Applications) exists to fill gaps where HTML semantics fall short. A custom dropdown built from div elements has no inherent semantics. ARIA attributes like role="listbox", aria-expanded, and aria-activedescendant communicate the widget’s state and behavior to assistive technology. Used correctly, ARIA makes custom widgets accessible. Used incorrectly, it makes them worse than having no ARIA at all.

The first rule of ARIA is documented in the spec itself: do not use ARIA if you can use a native HTML element with the semantics you need. A <button> is a button. Adding role="button" to a <div> creates a button that does not respond to Enter and Space keypresses, is not focusable by default, and does not appear in the accessibility tree as a form control unless you also add tabindex="0" and keyboard event handlers. You have re-implemented what the browser gives you for free. And you have almost certainly done it wrong.

Here is the pattern that breaks most often in production: ARIA attributes that conflict with native semantics. An <input type="text"> already has an implicit role of “textbox.” Adding role="searchbox" changes the announced role, which may or may not match the user’s expectation. An <a href="/page"> already announces as “link.” Adding role="button" turns it into a button that navigates on click. That is confusing because buttons do not navigate and links do. Screen readers announce what ARIA tells them, not what the element actually does.

Audit your component library for ARIA attribute density. Components with more than 3-4 ARIA attributes per element are almost certainly over-specified. The accessibility tree should reflect the widget’s actual structure and state, not a verbose description of everything the developer thought the screen reader might need. Each unnecessary attribute is a potential source of conflicting announcements across different screen reader and browser combinations.

So that handles the semantics layer. But semantics without keyboard support is just decoration for assistive technology.

Keyboard Navigation Architecture

Keyboard accessibility is not adding tabindex="0" to everything. Stop doing that. It is an architecture decision about how focus flows through your application, and it requires the same intentional design as your routing or state management.

The tab order must follow visual reading order. In a left-to-right language, that means top-to-bottom, left-to-right through interactive elements. When your layout uses CSS Grid or Flexbox to reorder elements visually, the DOM order and visual order diverge. A keyboard user tabbing through your page hits elements in DOM order, which jumps erratically across the visual layout. The fix is not tabindex values. It is aligning your DOM order with your visual reading order. If your CSS layout requires DOM reordering to look correct, the layout is wrong.

Within composite widgets like tab panels, menu bars, and data grids, the roving tabindex pattern manages focus efficiently. The composite widget itself gets a single tab stop. Arrow keys move focus between items within the widget. This means a tab list with eight tabs consumes one tab stop instead of eight, keeping the overall tab count manageable. The WAI-ARIA Authoring Practices define the expected keyboard behavior for every standard widget type.

Focus management in single-page applications is where most frameworks fall short. When a user clicks a link and the router renders new content without a full page load, the browser does not move focus. The keyboard user is still focused on the navigation link they clicked. They have no indication that the page content changed. They have to Tab through the entire navigation again to reach the new content. Every single time.

The fix is explicit focus management on route changes. Move focus to the main content heading or a skip-link target when the route changes. Use aria-live="polite" on a visually hidden element to announce the new page title to screen readers. React Router, Vue Router, and SvelteKit do not handle this by default. None of them. It requires a route change hook that programmatically sets focus.

For a deep dive into building component libraries that handle keyboard patterns correctly from the start, the guide to design systems engineering covers the component architecture side, where accessibility testing becomes a quality gate on every component PR.

Focus Trapping in Modals and Overlays

Modal dialogs require a focus trap: Tab and Shift+Tab must cycle only through interactive elements inside the modal. The user must not be able to Tab to content behind the modal. When the modal closes, focus must return to the element that triggered it. Get any of these wrong and keyboard users are trapped in your UI or lost outside it.

The <dialog> element handles this natively when opened with showModal(). It creates a top layer that traps focus automatically and returns focus to the previously focused element on close. Use it. If your modals use <div> elements with CSS positioning, you have to implement focus trapping manually, and it is harder than it looks.

Manual focus trapping requires knowing all focusable elements inside the modal, handling Tab on the last element to jump to the first, handling Shift+Tab on the first element to jump to the last, and handling Escape to close and restore focus. It also requires handling dynamically added focusable elements. If your modal lazily loads content that includes a form, the focus trap must update to include the new form fields. Miss that edge case and your lazy-loaded form fields are outside the trap.

The inert attribute is the modern solution for disabling background content. Apply inert to the main content wrapper when a modal is open, and the browser removes all background elements from the tab order and accessibility tree. No JavaScript focus trap logic needed. Browser support for inert crossed 95%+ in late 2023. If you are building new modals today and not using inert, you are solving a problem the platform already solved for you.

Color Contrast Beyond WCAG AA

Keyboard navigation handled. Now for the visual side, where “passing WCAG” and “actually readable” are not the same thing.

WCAG AA requires a 4.5:1 contrast ratio for normal text and 3:1 for large text (18px+ or 14px bold). These are minimum thresholds, and building to the minimum creates three problems.

First, WCAG contrast ratios are computed against the sRGB color space using a relative luminance formula. The formula does not perfectly model human perception, especially for saturated colors. Blue text on a black background can pass the mathematical contrast check while being genuinely hard to read because the luminance formula underweights the perceptual difficulty of distinguishing dark saturated blues from black. This is a known limitation of the WCAG 2.x algorithm. WCAG 3.0’s APCA (Advanced Perceptual Contrast Algorithm) addresses this but is not yet a compliance standard.

Second, the 4.5:1 threshold assumes ideal viewing conditions: a calibrated display, ambient lighting that does not wash out the screen, and a user with standard visual acuity. Screen glare, low brightness settings, aging displays with reduced color accuracy, and the 8% of males with color vision deficiency all degrade effective contrast below the computed ratio. Building to AAA ratios (7:1 for normal text, 4.5:1 for large text) creates headroom for real-world conditions.

Third, contrast is not just text. Interactive element states (focus indicators, selected states, disabled states) all need sufficient contrast from their surroundings. WCAG 2.1 added a 3:1 non-text contrast requirement for UI components and graphical objects, which means your focus outline, your checkbox borders, and your toggle switch tracks all need contrast checking against their background.

Use a color contrast analyzer that tests against both AA and AAA thresholds and simulates color vision deficiency modes (protanopia, deuteranopia, tritanopia). Chrome DevTools includes this in the color picker. And never rely on color alone to communicate state. A red error border and a green success border look identical to someone with red-green color blindness. Pair color with icons, text labels, or pattern changes. Always.

Good contrast is necessary but insufficient. The real work is preventing regressions from undoing it all.

CI Pipeline Accessibility Gates

Accessibility regressions ship the same way performance regressions do: incrementally, one PR at a time, with nobody noticing until the cumulative damage is significant. Teams regularly lose six months of accessibility work in a single quarter of unguarded PRs. CI gates are the only reliable way to prevent this.

The baseline tooling is axe-core integrated into your test runner. Axe-core runs against rendered DOM and catches the 30-40% of issues that are automatically detectable. In a React application, jest-axe runs axe against rendered component output in unit tests. For integration tests, Playwright’s @axe-core/playwright runs axe against full pages in a real browser. Both should be mandatory checks on every PR.

The step most teams skip is component-level accessibility testing in Storybook. The @storybook/addon-a11y runs axe-core against every story variation. A button component might pass accessibility checks in its default state but fail when rendered in its disabled state (insufficient contrast) or loading state (missing aria-busy announcement). Each story represents a component state, and each state needs its own accessibility check. Skip this and you are testing the happy path while shipping broken states.

Beyond automated scanning, accessibility acceptance criteria belong in your definition of done for interactive components. “Focus moves to modal content on open and returns to trigger on close” is a testable requirement. “Screen reader announces option selection in combobox” is a testable requirement. Put these in the PR template as manual verification checkboxes. The PR does not merge until they are checked. No exceptions.

Effective DevOps pipeline design treats accessibility gates the same as security scanning and linting. They run on every PR, they block merge on failure, and they have clear ownership for triage and resolution.

Screen Reader Testing That Catches Real Issues

Automated tools cannot replace testing with actual screen readers. The screen reader experience is not “are ARIA attributes present?” It is “does the sequence of announcements make sense for someone navigating without vision?” Those are fundamentally different questions.

NVDA on Windows with Chrome and VoiceOver on macOS with Safari are the two mandatory test combinations. They cover roughly 85% of screen reader usage. JAWS on Windows is third but is a commercial product, making it less practical for routine testing. Each screen reader interprets ARIA attributes differently, handles live regions with different timing, and announces dynamic content changes with different verbosity. What works in NVDA will surprise you in VoiceOver.

The testing workflow for a new interactive component is systematic. Open the page in the target browser with the screen reader active. Navigate to the component using only keyboard. Listen to every announcement. Does the screen reader announce the component’s role, name, and state? When you interact with it, does the announcement update? When content changes dynamically, does the live region announce the change? When you leave the component, is the next announcement the element you expect?

Document what each screen reader announces at each step. The announcement transcript is your accessibility specification. If NVDA says “button, Submit Order, expanded” and VoiceOver says “Submit Order, collapsed, button,” you have a state synchronization bug that no automated tool will ever detect. These transcripts become test documentation that reviewers can verify.

For teams scaling accessibility UX engineering across multiple product teams, a shared library of screen reader test transcripts per component type eliminates the need for every team to discover the same NVDA/VoiceOver behavior differences independently.

The Cost of Retrofitting

Building accessibility into a new component adds roughly 10-15% to initial development time. That is it. Semantic HTML, keyboard handlers, ARIA states, and focus management are straightforward when designed from the start. The component’s DOM structure is built to support assistive technology. The interaction model accounts for keyboard and screen reader users from the first commit.

Retrofitting accessibility into an existing component is a completely different beast. The DOM structure was not designed for assistive technology. A custom dropdown built from nested div elements with click handlers needs its entire markup restructured to support role="listbox", aria-activedescendant, keyboard arrow navigation, and type-ahead search. That is not adding attributes. That is rewriting the component while maintaining backward compatibility with every consumer.

The cost multiplier is 5-10x, and it compounds across a design system. A design system with 80 components that were not built accessible needs each component audited, rebuilt, and regression tested. The components’ consumers need updating to pass new required props (accessible names, keyboard handlers). The integration tests need rewriting to verify the new behavior. Teams that retrofit on a deadline typically fix the automated scan findings (missing labels, contrast issues) and leave the harder keyboard and screen reader issues untouched. That creates a false sense of compliance that is worse than no effort at all, because now leadership thinks the problem is solved.

The economic argument is straightforward: every week of accessible development from the start avoids a month of remediation later. Build it right the first time. Effective web application engineering treats accessibility as an architectural requirement, not a feature to be added later.

Live Regions and Dynamic Content

Single-page applications change content without page loads. When a form submission succeeds, when a search returns results, when a notification appears, sighted users see the change immediately. Screen reader users hear nothing. Absolute silence. Unless you explicitly announce the change via an ARIA live region.

aria-live="polite" announces changes when the screen reader finishes its current task. Use it for non-urgent updates: search results loaded, form saved, new content available. aria-live="assertive" interrupts the current announcement immediately. Reserve it for errors and urgent alerts: session expiring, form validation failed, destructive action confirmation.

Here is the implementation pattern that works reliably: maintain a visually hidden live region element in your application root. When you need to announce something, set its text content. The screen reader detects the text change and announces it. Do not add and remove live region elements dynamically. Some screen reader and browser combinations do not detect live regions that are added to the DOM after page load. The element must exist in the DOM before its content changes. This catches teams every single time.

Announcement timing matters. If you update a live region at the same moment you move focus, some screen readers announce the focus change and swallow the live region update. Add a small delay (100-200ms) between the focus change and the live region update to ensure both announcements are heard. This is one of those behaviors that only surfaces when testing with actual assistive technology.

The continuous integration and delivery pipeline can automate live region presence checks (verifying the element exists and updates on expected actions), but the announcement timing and content quality require manual screen reader testing.

Building the Accessibility Culture

Tooling alone does not produce accessible products. Axe-core in CI catches regressions. Screen reader testing catches interaction bugs. But the fundamental shift is treating accessibility as an engineering discipline, not a compliance task.

Every engineer on the team should be able to navigate a page using only a keyboard. Not as a theoretical skill. As something they do routinely during development and code review. Tab through the page. Does focus move logically? Can you reach everything? Can you operate everything? Can you see where focus is? If an engineer cannot answer these questions for the code they wrote, the code review is incomplete. Send it back.

Screen reader testing does not need to be every engineer’s responsibility. But at least two people per team should be proficient with NVDA and VoiceOver. They review every PR that touches interactive components. They run through the screen reader workflow and document what they hear. This is the accessibility equivalent of security review. Not everyone needs to be an expert, but every team needs someone who can verify the work.

The organizations that treat accessibility as a checkbox run Lighthouse, fix the red flags, and ship products that 15-20% of their users struggle with. The organizations that treat it as a discipline build it into their component architecture, test it with real assistive technology, enforce it in CI, and ship products that work for everyone. The difference is measured in months of remediation that never have to happen. Build it in from the start, or pay for it later. There is no third option.