Applied AI-Accelerated Government Development

Accessibility: Section 508 and Title II

Updated

Intermediate

What you'll learn

~30 min
  • Identify which accessibility rule binds your agency: Section 508 (federal agencies) or ADA Title II (state and local governments), and the WCAG (Web Content Accessibility Guidelines) level each cites
  • Build to WCAG 2.1 Level AA so one codebase meets both rules, and say what a passing automated scan does not prove
  • Run an axe-core scan (an open-source accessibility rules engine) inside Playwright across routes, roles, tiers and the dark theme
  • Test keyboard navigation, focus, accessible names, and that hidden tiers stay hidden from assistive technology

One standard to build to

Two legal regimes cover government web software in the United States, and they cite different versions of the same technical standard. Federal agencies are under Section 508 of the Rehabilitation Act. State and local governments are under Title II of the Americans with Disabilities Act. This is the one lesson in the module that does not depend on which cloud you deploy to: the rules attach to who you are, not where you host.

WCAG, the W3C’s Web Content Accessibility Guidelines, is a numbered list of testable success criteria at three levels (A, AA, AAA). Both regimes ask for Level AA. They differ in the edition.

Who you areRuleEdition citedSource
Federal agency, or a contractor building for one under a contract that cites itSection 508, implemented in 36 CFR Part 1194WCAG 2.0 Level A and AA, incorporated by Appendix A, E205.4 (web content) and E207.2 (software)eCFR, 36 CFR Part 1194
State or local governmentADA Title II web rule (28 CFR 35.200)WCAG 2.1 Level AA91 FR 20902, document 2026-07663

WCAG 2.1 AA contains every Level A and AA criterion in 2.0 and adds more. Build to 2.1 AA and you meet both. A federal agency’s legal floor is 2.0, and many agencies set a higher bar by their own policy, so check your agency’s accessibility office before you assume the floor is the target.

ℹStatus checked 2026-11-04

The Title II compliance dates were moved by an interim final rule (a rule that takes effect before public comment closes) published 2026-04-20, with comments due 2026-06-22. The dates are 2027-04-26 for entities with a total population of 50,000 or more, and 2028-04-26 for entities under 50,000 and for special district governments. The technical standard, WCAG 2.1 AA, was not changed by that rule. The Section 508 text above was read in the eCFR, whose last amendment on record is 2018-03-23.

Not checked: whether a final rule has followed the interim rule, and the status of any litigation about it. Recheck the Federal Register notice and your agency counsel’s guidance before you rely on a date.

ProblemThe patternWhere your platform lesson lands itYou decide
Show the standard is metAn axe scan plus keyboard tests in CI, and a manual screen reader pass per release; a hosted scanning service or Lighthouse in CI is the alternativeNothing platform-specific; the scan runs as a pipeline step on your code host: 37Which tool runs on every pull request
Record what was testedThe test output attached to the build; an Accessibility Conformance Report (the completed VPAT template a buyer or accessibility office asks for) is the alternativeNothing platform-specific: the report is a document your agency signs, on any cloudWho signs the report
Handle a finding you cannot fix yetAn exclusion with a reason, an owner and an expiry date; a tracked issue with a due date is the alternativeNothing platform-specificHow long an exception may live

Test results support evidence for a conformance claim. The claim itself, and the report that carries it, belong to the people your agency names.


Plan the change with your agent

Open your workspace agent at the project root and switch to Plan mode (Shift+Tab, /plan, or the desktop app’s mode picker) so the session starts with a read-only audit and remediation plan (the tool modes table and Lesson 2 hold each tool’s details). Ask:

Audit our layout, vehicle-fleet components, and tier switcher for WCAG 2.1 Level AA issues that automated scans miss, and plan the fixes plus a Playwright axe sweep. Ask anything unclear.

What to check in the plan before you approve

  • The audit checks icon-only IconButton controls for accessible names, focus:outline-none classes without focus-visible replacements, form labels and aria-describedby error wiring, live regions for async updates, DensityGate tab roles and hidden attributes on inactive panels, and the skip link and single h1 in layout.tsx.
  • Text colors on dark surfaces are flagged as "needs measurement" rather than guessed from class names, leaving contrast computation to axe-core in a real browser.
  • Every finding lists the file and line, the real WCAG 2.1 success criterion number and name, and the smallest fix.

If the agent tries to calculate contrast ratios from Tailwind class names or edits files before you review the audit list, push back:

Do not guess contrast ratios from CSS class names; flag them for measurement by the browser axe scan.
SESSION Accessibility audit: report first, fixes second
  1. Typed in the terminal: claude
  2. Mode:Plan mode
  3. You type in the session: Audit our layout, vehicle-fleet components, and tier switcher for WCAG 2.1 Level AA issues that automated scans miss, and plan the fixes plus a Playwright axe sweep. Ask anything unclear.
  4. The tool replies: Findings (read-only, nothing changed): 1. src/components/VehicleRow.tsx:42: IconButton with DeleteIcon, no accessible name. 4.1.2 Name, Role, Value. Fix: aria-label="Delete vehicle". 2. src/components/Header.tsx:18: IconButton with MenuIcon, no accessible name. 4.1.2. 3. src/components/TierSwitcher.tsx:67: inactive panels are hidden with a CSS class only. They stay in the accessibility tree. 1.3.1 Info and Relationships / 4.1.2. Fix: use the hidden attribute. 4. src/components/ui/ActionButton.tsx:8: focus:outline-none with no focus-visible style. 2.4.7 Focus Visible. 5. src/app/(protected)/vehicle-fleet/page.tsx:34: TextField in the Add vehicle dialog with a placeholder and no label. 3.3.2 Labels or Instructions. 6. src/hooks/useVehicleFleet.ts: list refreshes silently. 4.1.3 Status Messages. 7. src/app/layout.tsx: no skip link. 2.4.1 Bypass Blocks. Color: 9 text utilities on dark surfaces need measurement. I did not compute ratios; axe's color-contrast rule will, in the next step.
  5. You type in the session: Fix 1 through 7. For the color items wait for the scan. Then add the axe sweep to Playwright.
  6. The tool replies: Applied fixes 1 to 7 (7 files). I did not touch the color utilities. Added e2e/a11y.spec.ts with a checkAccessibility() helper that runs axe with the wcag2a, wcag2aa and wcag21aa tags, attaches the violation list to the test report, and fails on any violation. Exclusions live in e2e/axe-exclusions.ts, and the file refuses an entry without a reason, an owner and an expiry date. I could not run it: it needs the app started with the test session seam from Lesson 13.
  7. You type in the session: Run it.
  8. The tool replies: Running 6 tests using 3 workers ✓ viewer /vehicle-fleet, every tier (3.1s) ✕ operator /vehicle-fleet, every tier (3.4s) color-contrast: 2 nodes. Helper text #6b7280 on #18181b. Ratio reported by axe: 3.6 (expected 4.5). ✓ admin /admin/users (1.9s) 1 failed, 5 passed The failure is real. The helper text token is too dark for the surface. Change the token in the theme, not the one component, and re-run.
  9. You type in the session: Change the helper-text token in the theme to meet 4.5:1 on that surface, then re-run the sweep.
  10. The tool replies: Changed --text-helper in src/theme/tokens.ts from #6b7280 to #9ca3af. Measured against #18181b: 7.0:1 by axe's own computation, not mine. I checked the other two surfaces that use the token, and both pass. Running 6 tests using 3 workers ✓ viewer /vehicle-fleet, every tier (3.0s) ✓ operator /vehicle-fleet, every tier (3.3s) ✓ admin /admin/users (1.8s) 6 passed The sweep proves no automated violation remains. The manual screen reader pass and keyboard walk-through are still yours; axe finds only the share of problems a machine can.

Illustrative session; exact output varies by tool and agency configuration.

The audit prompt asks for a report before any edit, and tells the model not to guess contrast ratios. A language model reading class names cannot measure a rendered color; a browser can.


Automate the part a machine can do

axe-core runs a set of rules against the rendered page. Its rule tags map to WCAG levels, so you select the ones that match the standard you build to: wcag2a and wcag2aa for 2.0 Level A and AA, and wcag21aa for the criteria 2.1 added at AA. (The 2.1 Level A additions have their own tag, wcag21a; include it so the sweep covers all of 2.1 A and AA.)

REFERENCE TEST e2e/a11y-helper.ts: axe-core WCAG 2.1 Level AA scan helper open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
e2e/a11y-helper.ts
import AxeBuilder from "@axe-core/playwright";
import { expect, type Page, type TestInfo } from "@playwright/test";
import { EXCLUSIONS } from "./axe-exclusions";
export async function checkAccessibility(page: Page, testInfo: TestInfo) {
let builder = new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]);
for (const e of EXCLUSIONS) builder = builder.exclude(e.selector);
const results = await builder.analyze();
await testInfo.attach("axe-violations", {
body: JSON.stringify(results.violations, null, 2),
contentType: "application/json",
});
expect(results.violations.map((v) => `${v.id}: ${v.nodes.length} node(s)`)).toEqual([]);
}

Here is the reference exclusions registry in e2e/axe-exclusions.ts that your agent generates to require a reason, owner, and expiry date on any temporary exception:

e2e/axe-exclusions.ts
// An exclusion hides a finding from the scan. Each one needs a reason, an owner and an expiry.
export const EXCLUSIONS: { selector: string; reason: string; owner: string; expires: string }[] = [];
for (const e of EXCLUSIONS) {
if (!e.reason || !e.owner || Date.parse(e.expires) < Date.now()) {
throw new Error(`Expired or incomplete axe exclusion: ${e.selector}`);
}
}

The expiry check turns “we will fix it later” into a build failure on the date you named. An exception recorded this way is also something an assessor can read.

Now sweep every route, as every role, in every tier, in the dark theme the app ships with:

REFERENCE TEST e2e/a11y.spec.ts: Playwright axe sweep across routes, roles, and tiers open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
e2e/a11y.spec.ts
import { test } from "@playwright/test";
import { checkAccessibility } from "./a11y-helper";
const ROUTES = ["/vehicle-fleet"];
for (const role of ["viewer", "operator"] as const) {
test.describe(`${role}`, () => {
test.use({ storageState: `e2e/.auth/${role}.json` });
for (const route of ROUTES) {
test(`${route}, every tier`, async ({ page }, testInfo) => {
await page.goto(route);
const tabs = await page.getByRole("tab").all();
if (tabs.length === 0) return checkAccessibility(page, testInfo);
for (const tab of tabs) {
await tab.click();
await checkAccessibility(page, testInfo);
}
});
}
});
}

colorScheme: "dark" in the Playwright config from Lesson 13 means this sweep runs on the dark theme, which is the one most users see. If your app offers a light theme, add a second pass with test.use({ colorScheme: "light" }).

⚠A clean scan is not a conformance claim

Automated rules find the failures a program can recognize: a missing name, a contrast ratio below the threshold, a form control with no label. They cannot judge whether alt text is meaningful, whether focus order makes sense, or whether a screen reader announces something useful. A failing scan proves a defect. A passing scan only removes the cheap ones, so keep a manual pass on the release checklist.


Keyboard navigation and focus

Some of the most common blockers are about moving through the page, and a scan cannot press keys. Test them directly.

REFERENCE TEST e2e/keyboard.spec.ts: skip-link, tab-key navigation, and dialog focus-return specs open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
e2e/keyboard.spec.ts
import { expect, test } from "@playwright/test";
test.use({ storageState: "e2e/.auth/operator.json" });
test("the first Tab stop is a skip link that reaches the main content", async ({ page }) => {
await page.goto("/vehicle-fleet");
await page.keyboard.press("Tab");
const skip = page.getByRole("link", { name: /skip to (main )?content/i });
await expect(skip).toBeFocused();
await page.keyboard.press("Enter");
await expect(page.locator("main")).toBeFocused();
});
test("tiers follow the tabs pattern: arrows move, Home and End jump", async ({ page }) => {
await page.goto("/vehicle-fleet");
const tabs = page.getByRole("tab");
await tabs.first().focus();
await page.keyboard.press("ArrowRight");
await expect(tabs.nth(1)).toBeFocused();
await page.keyboard.press("End");
await expect(tabs.last()).toBeFocused();
await page.keyboard.press("Home");
await expect(tabs.first()).toBeFocused();
});
test("a dialog returns focus to the control that opened it", async ({ page }) => {
await page.goto("/vehicle-fleet");
const open = page.getByRole("button", { name: "Add vehicle" });
await open.click();
await expect(page.getByRole("dialog")).toBeVisible();
await page.keyboard.press("Escape");
await expect(open).toBeFocused();
});

Three habits cause most keyboard failures in this stack. Removing the browser’s outline with a utility class and adding no replacement leaves keyboard users with no visible focus (2.4.7, Focus Visible). A dialog that does not return focus on close drops the user at the top of the page. And a custom control built from a div is not reachable by Tab at all. Prefer the native element, and let the test prove it.


Contrast in the dark theme

The reference app defaults to a dark theme, and dark themes fail contrast in two places more than any others: secondary text (helper text, captions, placeholder text) and disabled controls. Text must reach 4.5:1 against its background, or 3:1 for large text (1.4.3, Contrast Minimum), and interface component boundaries and focus indicators need 3:1 (1.4.11, Non-text Contrast, which is new in 2.1).

Do not choose colors by eye or by remembered ratios. The scan above measures the rendered pair, and the fix belongs in the theme tokens so every component that uses the token is fixed at once. Disabled controls are exempt from the contrast requirement by the standard, but a disabled control with no visible state at all is a usability defect worth a decision.


Hidden tiers must stay hidden

Lesson 11’s role-tiered disclosure shows one tier at a time. An inactive tier that is only collapsed with CSS (opacity or an off-screen position) still sits in the accessibility tree, and a screen reader reads a page the sighted user cannot see. The tier must be removed from the tree, which the hidden attribute does. Here is the reference spec in e2e/hidden-tiers.spec.ts that your agent writes to check it:

e2e/hidden-tiers.spec.ts
import { expect, test } from "@playwright/test";
test.use({ storageState: "e2e/.auth/viewer.json" });
test("inactive tiers are not in the accessibility tree", async ({ page }) => {
await page.goto("/vehicle-fleet");
await expect(page.getByRole("tabpanel")).toHaveCount(1);
const tabs = page.getByRole("tab");
await tabs.nth(1).click();
await expect(page.getByRole("tabpanel")).toHaveCount(1);
await expect(tabs.nth(1)).toHaveAttribute("aria-selected", "true");
});

Lesson 13’s tier test covers which controls each role sees; this one covers only what assistive technology can reach.


What to do by hand

CheckHowWCAG criterion
Screen reader reads each tier’s content once, in a sensible orderNVDA (free, Windows) or VoiceOver (macOS); keyboard only1.3.2 Meaningful Sequence
Alt text says what the image is forRead each one without seeing the image1.1.1 Non-text Content
Error messages tell the user what to fixSubmit an invalid form with the screen reader on3.3.1 Error Identification
Page works at 200 percent zoom without losing contentBrowser zoom1.4.4 Resize Text
Status messages are announcedTrigger a save and listen4.1.3 Status Messages

Ten minutes with a real screen reader teaches more than any rule list. Do it once per release, and record who did it and on which build.


Prove it

Terminal window
npx playwright test e2e/a11y.spec.ts e2e/keyboard.spec.ts e2e/hidden-tiers.spec.ts

Plant each fault and confirm the named failure.

Plant this faultWhat must fail
Remove the aria-label from an icon-only buttonThe sweep reports button-name
Lighten helper text below the contrast thresholdThe sweep reports color-contrast
Delete the skip linkThe first Tab stop is a skip link that reaches the main content
Hide an inactive tier with a CSS class instead of hiddeninactive tiers are not in the accessibility tree
Add an exclusion with a past expiry dateThe suite refuses to start

KNOWLEDGE CHECK

Your office is a county government and a contractor's office is building for a federal agency. Both build the same product. Which single target meets both rules?

KNOWLEDGE CHECK

The axe sweep passes on every route. What does that establish?


Key takeaway

Know which rule binds you (Section 508 for federal agencies, Title II for state and local governments), build to WCAG 2.1 AA so one codebase meets both, and run the checks a machine can run on every pull request: an axe sweep across roles, tiers and the dark theme, plus keyboard and hidden-tier tests. Keep a manual screen reader pass on the release checklist, because a passing scan removes the cheap defects and nothing more.

LEADERSHIP DECISION
Which accessibility rule binds the agency and what level the team builds to.
PRACTITIONER ACTION
Add the axe sweep and keyboard tests to the pull-request checks and schedule the screen reader pass.
SUCCESS MEASURE
Contract or revenue risk: no unresolved accessibility defect found in a pre-release review of a delivered module.

Legend: LEADERSHIP DECISION = what a leader decides · PRACTITIONER ACTION = what the engineer does next · SUCCESS MEASURE = how you know, in calendar time, assessor-hours or cost, contract or revenue risk, or audit finding avoided

Search lessons