Foundations

Accessibility for Developers

Building accessible web applications means writing markup, styles, and interactions that work for everyone — including people using screen readers, keyboard navigation, voice control, and other assistive technologies.

The NYSDS components handle many accessibility patterns for you: ARIA attributes, keyboard interactions, focus management, and screen reader announcements. But components alone do not make an accessible page. You are responsible for the structure and content that surrounds them.

What You Are Responsible For

Even when using NYSDS components, your pages need:

Logical heading hierarchy — One h1 per page, followed by h2, h3, etc. in order. Do not skip levels.
Landmark regions — Use <main>, <nav>, <header>, <footer>, and <aside> so screen readers can navigate by region.
Meaningful link text — "Apply for benefits" instead of "Click here." Links should make sense out of context.
Alternative text — Descriptive alt text on informational images. Empty alt="" on decorative images.
Visible focus indicators — Do not remove the default focus outline with outline: none unless you replace it with an equally visible indicator.
Language attribute — Set lang="en" (or the appropriate language) on the <html> element.
Page titles — Every page needs a unique, descriptive <title>.
Skip navigation — Use the nys-skipnav component to let keyboard users bypass repetitive navigation.

Testing Tools

Automated tools catch roughly 30-40% of accessibility issues. Manual testing catches the rest. Use both.

Primary Recommended Tools

Accessibility Insights (Microsoft) — The best single tool for starting accessibility testing. Accessibility Insights combines automated checks, guided manual testing workflows, and detailed reporting. It works in Chrome and Edge and includes both quick scans for common issues and comprehensive assessments. Start here.

NVDA — Free screen reader for Windows. NVDA is the most common screen reader among users and is essential for understanding how your content sounds when read aloud. Navigate your pages using only the keyboard and screen reader — do not look at the screen.

Additional Automated Testing Tools

Run these during development to catch common issues:

Deque Axe — Chrome and Firefox extension for quick in-browser accessibility scans.
Google Lighthouse — Built into Chrome DevTools. Runs accessibility audits alongside performance.
Wave — Browser extension that visually overlays accessibility errors and warnings on your page.
HTML CodeSniffer — Bookmarklet that checks the current page against WCAG criteria in real time.
a11y.css — A CSS file that highlights potential accessibility issues by flagging problematic markup visually.

CI/CD Integration

Incorporate automated checks into your build pipeline:

Pa11y — Command-line tool for running WCAG checks in CI. Supports multiple reporters.
accessibility-checker — IBM's Node.js module for automated accessibility scanning. Works in test frameworks.

Coding Techniques

Forms

NYSDS form components (Text Input, Select, Checkbox, Radio Button, Textarea) handle label association, error messaging, and required field announcements automatically. When building custom form patterns:

Always associate labels with inputs using for/id pairs or wrapping the input in a <label>.
Group related fields with <fieldset> and <legend>.
Announce errors in context — place error text next to the field and link it with aria-describedby.
Never rely on color alone to indicate errors. Include text and, where appropriate, an icon.

See Creating Accessible Forms (WebAIM) for a thorough reference.

Dynamic Content

When content changes without a full page reload:

Use aria-live regions to announce updates to screen readers. Use aria-live="polite" for non-urgent updates and aria-live="assertive" sparingly for critical alerts.
Manage focus intentionally. When a modal opens, move focus into it. When it closes, return focus to the element that triggered it. NYSDS components like nys-modal handle this automatically.
Avoid moving focus unexpectedly. If a user action triggers a content change, let the user initiate the next navigation step.

Images and Media

Informational images: <img src="chart.png" alt="Bar chart showing 2024 application processing times by county">
Decorative images: <img src="decorative-wave.svg" alt="" role="presentation">
Complex images (charts, diagrams): provide a text summary in the alt attribute and a detailed description nearby or linked.
Video: include synchronized captions and a transcript.