Blog

How to Make a Website ADA Compliant: A Developer's Complete Guide

TestParty

January 20, 2026

Key Takeaways
Step 1: Assess Where You Stand
Step 2: Fix Common Code-Level Violations
Step 3: Integrate Accessibility into Your Workflow
Step 4: Document and Defend
Common Implementation Patterns
FAQ
Related Resources

Making a website ADA compliant means meeting the Web Content Accessibility Guidelines (WCAG) that courts and regulators recognize as the technical standard for accessibility. While the ADA doesn't specify exact technical requirements, DOJ guidance and legal precedent consistently reference WCAG 2.1 AA (and increasingly WCAG 2.2) as the expected conformance level. The good news: achieving compliance aligns with solid engineering practices you likely already value.

The scope of the challenge is significant but manageable. WebAIM's 2024 Million analysis found that 95.9% of homepages have detectable WCAG failures, with an average of 56.8 errors per page. The most common issues—missing alt text (54.5%), low contrast text (81%), and missing form labels (48.6%)—are exactly the violations that trigger 8,800 ADA lawsuits annually. Addressing these core issues eliminates the majority of legal risk.

This guide provides a practical four-step process: assess your current state, fix the most common violations, integrate accessibility into your development workflow, and document your compliance for defensibility. The result is a website that serves more users, performs better, and doesn't become a lawsuit target.

Key Takeaways

A structured approach makes ADA compliance achievable for development teams of any size.

ADA compliance means WCAG conformance – Courts reference WCAG 2.1/2.2 AA as the technical standard; meeting these criteria satisfies accessibility requirements
Common violations are fixable – Missing alt text, form labels, and contrast issues cause most failures and have straightforward solutions
Automation prevents regressions – Embedding accessibility checks in CI/CD catches 30-40% of issues before they reach production
Manual testing validates usability – Keyboard and screen reader testing confirms real-world accessibility that automated tools can't verify
Documentation supports defense – Records of compliance efforts provide evidence of good faith if legal questions arise

Step 1: Assess Where You Stand

Before writing any fixes, establish a baseline understanding of your site's current accessibility state.

Automated Scanning

Start with automated tools to identify detectable violations quickly:

Browser-based scanning:

Run WAVE on your homepage and key pages
Use Chrome DevTools Lighthouse accessibility audit
Install axe DevTools browser extension for detailed violation reporting

What to document:

Total error count per page
Error types and frequencies
Pages with highest violation counts
Patterns indicating systemic issues (same error across all product pages)

Automated scans catch approximately 30-40% of WCAG issues but provide an efficient starting point.

Manual Keyboard Testing

Keyboard accessibility is critical—many users can't use a mouse. Test your site using only keyboard:

Tab through your pages – Does focus move to every interactive element? Can you see where focus is?
Test interactive elements – Can you activate buttons with Enter? Open dropdowns with Space/Arrow keys?
Check for keyboard traps – Can you Tab out of modals, menus, and other components?
Verify focus order – Does Tab order follow visual layout logically?

Document any elements that aren't keyboard accessible or have invisible focus indicators.

Screen Reader Quick Test

Even brief screen reader testing reveals significant issues:

On Mac (VoiceOver built-in):

Press Cmd+F5 to enable VoiceOver
Navigate with VO+Right Arrow through content
Listen for: Are images described? Are form fields announced with labels? Do headings provide structure?

On Windows (NVDA free download):

Download and install NVDA
Navigate with arrow keys and Tab
Press H to jump between headings—is there logical structure?

Document issues where content is unclear, unlabeled, or confusingly ordered.

Contrast Checking

Verify text contrast meets WCAG requirements:

Normal text: 4.5:1 minimum ratio
Large text (18pt+ or 14pt+ bold): 3:1 minimum ratio
UI components and graphics: 3:1 minimum ratio

Use browser DevTools (inspect element → check color contrast) or dedicated tools like the WebAIM Contrast Checker.

Prioritize by Impact

After assessment, categorize issues by severity:

+--------------+------------------------------------+------------------------------------------------+
|   Priority   |              Criteria              |                    Examples                    |
+--------------+------------------------------------+------------------------------------------------+
|   Critical   |    Blocks users from core tasks    |     Inaccessible checkout, keyboard traps      |
+--------------+------------------------------------+------------------------------------------------+
|     High     |   Major barriers in common flows   |    Missing form labels, no focus indicators    |
+--------------+------------------------------------+------------------------------------------------+
|    Medium    |   Significant but workaroundable   |   Poor heading structure, missing skip links   |
+--------------+------------------------------------+------------------------------------------------+
|     Low      |            Minor issues            |   Decorative image alt text, minor contrast    |
+--------------+------------------------------------+------------------------------------------------+

Focus initial remediation on critical and high-priority issues.

Step 2: Fix Common Code-Level Violations

Address the violations that cause most accessibility failures and lawsuit triggers.

Add Text Alternatives for Images

The most common WCAG failure—54.5% of pages have missing alt text. Every image needs appropriate alternative text:

Informative images – Describe the content:

<!-- Bad -->
<img src="team-photo.jpg">

<!-- Good -->
<img src="team-photo.jpg" alt="TestParty engineering team at 2025 company retreat">

Functional images (icons, buttons) – Describe the function:

<!-- Bad -->
<button><img src="search-icon.svg"></button>

<!-- Good -->
<button><img src="search-icon.svg" alt="Search"></button>
<!-- Or better -->
<button aria-label="Search"><img src="search-icon.svg" alt=""></button>

Decorative images – Use empty alt to skip:

<!-- Decorative background pattern -->
<img src="decorative-swirl.png" alt="">

Complex images (charts, infographics) – Provide detailed description:

<img src="sales-chart.png" alt="Q4 sales increased 23% from Q3, reaching $4.2M">
<!-- For complex diagrams, consider linking to full text description -->

For comprehensive alt text guidance, see our Alt Text Best Practices Guide.

Associate Form Labels with Inputs

Every form field needs a programmatically associated label:

<!-- Bad - no label -->
<input type="email" placeholder="Email">

<!-- Bad - label exists but not associated -->
<label>Email</label>
<input type="email">

<!-- Good - explicit association -->
<label for="email">Email address</label>
<input type="email" id="email">

<!-- Good - implicit association -->
<label>
  Email address
  <input type="email">
</label>

For icon buttons without visible labels:

<button aria-label="Close dialog">
  <svg><!-- X icon --></svg>
</button>

For grouped inputs (like phone numbers):

<fieldset>
  <legend>Phone number</legend>
  <label for="area">Area code</label>
  <input type="text" id="area">
  <label for="number">Number</label>
  <input type="text" id="number">
</fieldset>

Enable Complete Keyboard Navigation

All functionality must be operable via keyboard (WCAG 2.1.1):

Use semantic elements:

<!-- Bad - div doesn't receive keyboard focus -->
<div onclick="submitForm()">Submit</div>

<!-- Good - button is keyboard accessible by default -->
<button onclick="submitForm()">Submit</button>

If you must use non-semantic elements:

<div role="button" tabindex="0" onclick="submitForm()" onkeydown="handleKeyDown(event)">
  Submit
</div>

<script>
function handleKeyDown(event) {
  if (event.key === 'Enter' || event.key === ' ') {
    event.preventDefault();
    submitForm();
  }
}
</script>

Ensure visible focus indicators:

/* Don't do this */
*:focus { outline: none; }

/* Do this - visible custom focus */
:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* Or for specific styling */
:focus-visible {
  outline: 3px solid #005fcc;
  box-shadow: 0 0 0 4px rgba(0, 95, 204, 0.3);
}

Structure Content with Proper Headings

Use headings to create a logical document outline:

<!-- Bad - heading levels skipped, used for styling -->
<h1>Product Name</h1>
<h4>Description</h4>  <!-- Skipped h2, h3 -->
<h4>Specifications</h4>

<!-- Good - logical hierarchy -->
<h1>Product Name</h1>
<h2>Description</h2>
<h2>Specifications</h2>
<h3>Dimensions</h3>
<h3>Materials</h3>

Rules:

One `<h1>` per page (usually the main title)
Don't skip levels (h1 → h3)
Headings should describe section content, not just be styled text

Fix Color Contrast

Ensure text meets contrast requirements:

/* Bad - 2.5:1 ratio fails for body text */
body {
  color: #999999;
  background-color: #ffffff;
}

/* Good - 7:1 ratio exceeds requirements */
body {
  color: #333333;
  background-color: #ffffff;
}

Quick fixes:

Darken light gray text
Lighten dark backgrounds slightly
Add text shadow or background for text on images

Use our Contrast Color Picker to find compliant alternatives.

Provide Skip Links

Allow keyboard users to bypass repetitive navigation:

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <nav><!-- Navigation --></nav>
  <main id="main-content">
    <!-- Page content -->
  </main>
</body>

<style>
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px;
  background: #000;
  color: #fff;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}
</style>

Step 3: Integrate Accessibility into Your Workflow

One-time fixes aren't enough—accessibility must become part of standard development practice.

Automated Testing in CI/CD

Add accessibility checks to your continuous integration pipeline:

Using axe-core with Jest:

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('homepage has no accessibility violations', async () => {
  const html = await renderHomepage();
  const results = await axe(html);
  expect(results).toHaveNoViolations();
});

Using Lighthouse CI:

# .github/workflows/accessibility.yml
name: Accessibility Tests
on: [push, pull_request]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v9
        with:
          urls: |
            https://staging.example.com/
            https://staging.example.com/products
          budgetPath: ./lighthouse-budget.json

ESLint for React/JSX:

// .eslintrc.js
module.exports = {
  plugins: ['jsx-a11y'],
  extends: ['plugin:jsx-a11y/recommended'],
  rules: {
    'jsx-a11y/alt-text': 'error',
    'jsx-a11y/label-has-associated-control': 'error',
    'jsx-a11y/no-noninteractive-element-interactions': 'warn',
  },
};

For complete CI/CD integration guidance, see Accessibility Testing in CI/CD.

Acceptance Criteria for User Stories

Include accessibility in your definition of done:

## Acceptance Criteria
- [ ] All images have appropriate alt text
- [ ] All form fields have visible, associated labels
- [ ] All functionality is keyboard accessible
- [ ] Focus indicators are clearly visible
- [ ] Color contrast meets WCAG AA (4.5:1 for text)
- [ ] Page passes automated accessibility scan
- [ ] Tested with keyboard navigation

Code Review Checklist

Add accessibility items to code review:

Are new images given meaningful alt text?
Do new form fields have proper labels?
Are new interactive elements keyboard accessible?
Is focus managed correctly for dynamic content?
Does new styling maintain adequate contrast?

Component Library Standards

If using a component library, ensure accessibility is built-in:

// Good - Button component with built-in accessibility
function Button({ children, onClick, disabled, ariaLabel }) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      aria-label={ariaLabel}
      className="button"
    >
      {children}
    </button>
  );
}

// Enforce required props
Button.propTypes = {
  children: PropTypes.node,
  ariaLabel: PropTypes.string, // Required when children is icon-only
};

Use established accessible component libraries like Radix UI, Headless UI, or React Aria for complex components (modals, menus, tabs).

Step 4: Document and Defend

Maintain records that demonstrate ongoing compliance efforts.

Track Issues and Fixes

Document accessibility work in your issue tracker:

Tag issues as "accessibility" for filtering
Record remediation details (what was fixed, how, when)
Link to specific WCAG success criteria addressed
Note testing verification performed

This creates an audit trail showing proactive compliance.

Create Internal Guidelines

Document your team's accessibility standards:

Alt text conventions – How your team writes alt text, with examples
Color palette – Approved colors verified for contrast
Component patterns – How to implement accessible modals, menus, forms
Testing procedures – Required checks before code merge

New team members can reference these guidelines immediately.

Publish an Accessibility Statement

An honest accessibility statement shows commitment:

## Accessibility Statement

[Company Name] is committed to ensuring our website is accessible to people 
with disabilities. We aim to meet WCAG 2.2 Level AA standards.

### Current Status
We regularly test our site using automated tools, keyboard navigation, and 
screen readers. We address issues as they're identified.

### Known Issues
[List any known limitations honestly]

### Feedback
If you encounter accessibility barriers, please contact us at 
accessibility@example.com. We take all feedback seriously and will 
respond within 2 business days.

Last updated: [Date]

For complete guidance, see How to Write an Accessibility Statement.

Consider a VPAT/ACR

For enterprise or government sales, you may need a Voluntary Product Accessibility Template (VPAT) or Accessibility Conformance Report (ACR):

Documents conformance against WCAG criteria
Required by many government procurement processes
Demonstrates compliance to enterprise customers

Fill out using the ITI VPAT template, honestly reporting conformance levels for each criterion.

Common Implementation Patterns

Certain components require specific accessibility patterns.

Accessible Modal Dialog

<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm Purchase</h2>
  <p>Complete your order for $49.99?</p>
  <button>Cancel</button>
  <button>Confirm</button>
</div>

Requirements:

Focus moves into modal when opened
Focus is trapped within modal (Tab cycles through modal elements)
Escape key closes modal
Focus returns to trigger element when closed
Background content is inert (aria-hidden or inert attribute)

Accessible Dropdown Menu

<nav>
  <button aria-expanded="false" aria-controls="products-menu">
    Products
  </button>
  <ul id="products-menu" hidden>
    <li><a href="/widgets">Widgets</a></li>
    <li><a href="/gadgets">Gadgets</a></li>
  </ul>
</nav>

Requirements:

Button announces expanded/collapsed state
Arrow keys navigate between menu items
Escape closes menu and returns focus to button
Menu items are focusable

Accessible Form Errors

<form>
  <label for="email">Email address</label>
  <input 
    type="email" 
    id="email" 
    aria-describedby="email-error"
    aria-invalid="true"
  >
  <p id="email-error" role="alert">
    Please enter a valid email address
  </p>
</form>

Requirements:

Error messages associated with fields via aria-describedby
Invalid fields marked with aria-invalid="true"
Errors announced immediately (role="alert" or aria-live)
Clear instructions for correction

For more patterns, reference W3C ARIA Authoring Practices.

FAQ

How long does it take to make a website ADA compliant?

Timeline depends on current state and site complexity. Sites with minor issues (missing alt text, some contrast problems) might achieve compliance in weeks. Sites with significant structural issues (keyboard traps, inaccessible custom components) may require months. The key is establishing ongoing processes—compliance isn't a one-time fix but continuous practice.

Do I need to hire an accessibility expert?

Not necessarily for initial compliance, though experts help with complex issues. Development teams can address most common violations using resources like this guide, W3C documentation, and automated testing tools. Consider expert consultation for complex custom components, comprehensive audits, or if you've received legal action.

What WCAG level do I need to meet?

WCAG 2.1 Level AA is the most commonly referenced standard in legal contexts and DOJ guidance. WCAG 2.2 AA is increasingly expected. Level A is the minimum but leaves significant barriers; Level AAA is ideal but often impractical for all content. Target AA conformance.

Can automated tools make my site compliant?

No. Automated tools catch approximately 30-40% of WCAG issues—the objective, code-level violations. The remaining issues require human judgment: Is this alt text meaningful? Is this interaction intuitive? Automated testing is essential but insufficient alone.

How do I handle accessibility for third-party content?

You're responsible for the entire user experience on your site. For third-party widgets (chat, reviews, payments), test them as part of your flows. Choose vendors who provide accessibility documentation. Include accessibility requirements in vendor contracts. If third-party content is inaccessible, consider alternatives.

Should I add an accessibility overlay to my site?

No. Overlays don't achieve actual compliance—they're JavaScript widgets that can't fix underlying code issues. The National Federation of the Blind opposes overlays, and over 1,000 businesses with overlays were sued in 2023-2024. Invest in real fixes instead.

Internal Links

External Sources

This article was written by TestParty's editorial team with AI assistance. All statistics and claims have been verified against primary sources. Last updated: January 2026.

Stay informed

Accessibility insights delivered
straight to your inbox.

Automate the software work for accessibility compliance, end-to-end.

Empowering businesses with seamless digital accessibility solutions—simple, inclusive, effective.

Book a Demo

How to Make a Website ADA Compliant: A Developer's Complete Guide

TABLE OF CONTENTS

Key Takeaways

Step 1: Assess Where You Stand

Automated Scanning

Manual Keyboard Testing

Screen Reader Quick Test

Contrast Checking

Prioritize by Impact

Step 2: Fix Common Code-Level Violations

Add Text Alternatives for Images

Associate Form Labels with Inputs

Enable Complete Keyboard Navigation

Structure Content with Proper Headings

Fix Color Contrast

Provide Skip Links

Step 3: Integrate Accessibility into Your Workflow

Automated Testing in CI/CD

Acceptance Criteria for User Stories

Code Review Checklist

Component Library Standards

Step 4: Document and Defend

Track Issues and Fixes

Create Internal Guidelines

Publish an Accessibility Statement

Consider a VPAT/ACR

Common Implementation Patterns

Accessible Modal Dialog

Accessible Dropdown Menu

Accessible Form Errors

FAQ

How long does it take to make a website ADA compliant?

Do I need to hire an accessibility expert?

What WCAG level do I need to meet?

Can automated tools make my site compliant?

How do I handle accessibility for third-party content?

Should I add an accessibility overlay to my site?

Related Resources

Internal Links

External Sources

Stay informed

Accessibility insights delivered straight to your inbox.

Automate the software work for accessibility compliance, end-to-end.

Accessibility insights delivered
straight to your inbox.