Accessibility in the Real Stack

Accessibility is a state requirement

WCAG 2.1 AA is not optional for state government applications. It is policy. When the accessibility office audits your application — and they will — they test with NVDA, JAWS, VoiceOver, and keyboard-only navigation. Automated scanning catches roughly 30% of issues. The rest require manual review.

The DS platform uses MUI 7 and Tailwind v4. MUI provides solid accessibility defaults: proper ARIA roles on dialogs, focus trapping in modals, keyboard-navigable menus. But the moment you layer Tailwind utility classes on top — custom colors, dark mode overrides, focus ring removals — you can break those defaults without knowing it.

This lesson covers the specific accessibility pitfalls of your stack and shows you how to use AI to find and fix them systematically.

MUI 7 accessibility: what you get and what you do not

MUI 7 handles a lot out of the box. Understanding what it covers — and where it stops — keeps you from reinventing built-in behavior or missing gaps.

What MUI handles automatically:

• role="dialog" and aria-modal="true" on Dialogs
• Focus trapping inside open modals (Tab cycles within the dialog)
• role="alert" on Snackbar content
• aria-expanded on Accordion headers
• role="listbox" and aria-selected on Select options
• aria-sort on sortable DataGrid column headers

What MUI does NOT handle — you must add it:

• aria-label on icon-only buttons (MUI renders <IconButton> without text)
• aria-describedby linking error messages to form fields
• aria-live regions for dynamic content updates (e.g., SWR data refreshes)
• Meaningful alt text on images (MUI’s Avatar defaults to empty alt)
• Skip navigation links for keyboard users

Tailwind + MUI: where contrast breaks

The DS platform uses a dark theme. MUI’s dark palette and Tailwind’s dark mode utilities coexist through CSS layer ordering (you set this up in Lesson 3). But contrast violations creep in at the intersection:

Common failures

1. Tailwind text-gray-400 on MUI dark backgrounds. Gray-400 (#9ca3af) on the DS platform’s card background (#1e293b) has a contrast ratio of 3.8:1. WCAG AA requires 4.5:1 for normal text. Fix: use text-gray-300 (#d1d5db) for a 7.2:1 ratio.

2. MUI disabled state colors. MUI’s disabled text uses rgba(255,255,255,0.3) in dark mode. On your card background, this is roughly 2.1:1 contrast — well below the 4.5:1 minimum. Fix: override the disabled color in your theme to rgba(255,255,255,0.5) minimum.

3. Focus-visible outlines. Tailwind’s focus:outline-none utility is commonly applied to clean up default browser outlines. If you do this without adding a replacement focus-visible:ring-2 style, keyboard users lose all focus indication. MUI components have built-in focus styles, but custom Tailwind buttons do not.

4. DensityGate tab indicators. The active tab uses your accent color on a dark surface. If the accent is too saturated or too dark, the active indicator fails contrast against the tab bar background. Check both the text color and the indicator underline.

Audit our Next.js 15.5 project for WCAG 2.1 AA accessibility violations.

Focus on these areas specific to our stack:

1. MUI 7 IconButtons: find every <IconButton> that does NOT have an aria-label prop
2. Color contrast: check all Tailwind text-gray-* and text-slate-* classes used
   on our dark backgrounds (#09090b, #111118, #18181b, #1e1e2a, #1e293b) for
   4.5:1 minimum contrast
3. Focus indicators: find any element with focus:outline-none that does NOT have
   a corresponding focus-visible:ring-* or focus-visible:outline-* class
4. Form fields: check that every MUI TextField has either a visible label or
   aria-label, and that helperText error messages are linked via aria-describedby
5. Images and avatars: find <Avatar> and <img> elements missing meaningful alt text
6. Dynamic content: identify SWR data fetching patterns that update visible content
   without aria-live regions

For each violation, provide:
- File path and line number
- Current code
- Fixed code
- WCAG success criterion reference (e.g., 1.4.3 Contrast)

DensityGate accessibility

DensityGate is the platform’s most complex UI component from an accessibility perspective. Three tabs control which content tier is visible. Each tier contains different widgets. A screen reader user needs to understand the structure without seeing the visual layout.

The requirements:

1. Tab panel association. Each tab must have aria-controls pointing to its panel’s id. Each panel must have role="tabpanel" and aria-labelledby pointing back to its tab.

2. Keyboard navigation. Arrow keys move between tabs (Left/Right). Enter or Space activates. Home jumps to first tab, End to last. This is the WAI-ARIA Tabs pattern.

3. Hidden panel content. Inactive panels should use hidden attribute (not display: none via CSS class alone) so screen readers skip them entirely. MUI’s TabPanel handles this if you use their component — but if DensityGate is a custom implementation, you must manage it.

4. Live region on switch. When the user switches tiers, the new content should be announced. Add aria-live="polite" to the panel container so the screen reader reads the new content after the tab switch.

// DensityGate panel with proper ARIA
<div
  role="tabpanel"
  id={`density-panel-${tier}`}
  aria-labelledby={`density-tab-${tier}`}
  hidden={activeTier !== tier}
  aria-live="polite"
>
  {activeTier === tier && children}
</div>

Integrate axe-core with Playwright

Manual testing catches nuanced issues. Automated testing catches regressions. Combine them. @axe-core/playwright integrates directly with your existing Playwright tests from Lesson 13.

Add axe-core accessibility scanning to our Playwright E2E tests.

Requirements:
1. Install @axe-core/playwright
2. Create a reusable checkAccessibility() helper in e2e/helpers.ts that:
   - Runs axe.analyze() on the current page
   - Filters to WCAG 2.1 AA rules only (tags: wcag2a, wcag2aa, wcag21aa)
   - Excludes known false positives (list them in e2e/axe-exclusions.ts)
   - Throws with violation details if any issues found
3. Add checkAccessibility() call to key page tests:
   - /dashboard (after full load)
   - /facilities (after grid renders)
   - /facilities/new (form page)
   - Each DensityGate tier on /facilities
4. Add a standalone accessibility test file: e2e/accessibility.spec.ts
   that navigates to every route and runs checkAccessibility()

import AxeBuilder from '@axe-core/playwright';
import { expect, Page } from '@playwright/test';

export async function checkAccessibility(page: Page) {
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .exclude('.known-third-party-widget') // MUI DatePicker has known issues
    .analyze();

  expect(results.violations).toEqual([]);
}

The accessibility checklist for a DS platform module

When you build a new module (Lessons 5-6), run through this before marking it complete:

Key takeaways

• MUI 7 gives you a head start, not a finish line. ARIA roles on dialogs and menus are automatic. Labels on IconButtons, contrast ratios on custom colors, and live regions for dynamic content are your responsibility.
• Tailwind dark mode and MUI dark theme interact. Every text-gray-* and text-slate-* class needs a contrast check against your actual background colors, not just theoretical Tailwind defaults.
• DensityGate must follow the WAI-ARIA Tabs pattern. Three tiers means three tabpanels with proper aria-controls, aria-labelledby, keyboard navigation, and hidden management.
• axe-core in Playwright catches regressions automatically. Run it on every page, in every pipeline. It takes 2 seconds per page and catches the violations that turn into audit findings.
• 10 minutes with a real screen reader teaches you more than reading any spec. Do it.

What’s next

You can test new code and verify accessibility. In the next lesson, you will apply everything from Lane 2 and Lane 3 to a real challenge: refactoring a legacy module that predates the platform standards — raw SQL, no response helpers, no withPermission(), no DensityGate.