Remediation workflow

WCAG Remediation Checklist for Existing Websites

You have scan results — a ShipSafe report, an Axe audit, or an ADA demand letter citing specific failures. Now what? This guide gives you a prioritized fix order: from the one-line template changes that resolve the most common lawsuit triggers, to the complex keyboard navigation work that takes longer but closes the remaining gaps.

• Baseline scan first
• Priority 1: Template fixes
• Priority 2: Alt text
• Priority 3: Form labels
• Priority 4: Color contrast
• Priority 5: Keyboard nav
• Document the work
• Verify with ShipSafe
• FAQ

Step 0: Run a baseline scan before touching anything

Before making any changes, document the site as it exists now. This creates a timestamped “before” record. If a demand letter is involved, this evidence matters.

• Run ShipSafe on your homepage and each cited URL. Screenshot the results with the date visible in the browser.
• Install the Axe DevTools browser extension (free, by Deque) and run it on the same pages. Export the full violations list — this becomes your work queue.
• Save both sets of results. A screenshot with the current date and the failing item count is sufficient documentation at this stage.

Axe DevTools is the right tool for building your fix queue: it lists every failure with a specific element selector, the WCAG criterion it violates, and a “More info” link explaining the exact fix. Work through the Axe results list in the priority order below.

Priority 1: Template-level fixes — 30 minutes, no design decisions

These fixes live in your layout template (or base HTML file), which means each fix propagates automatically to every page on the site at once. They address the most commonly cited WCAG failures in ADA demand letters and require no visual design changes.

<!-- Before -->
<html>

<!-- After -->
<html lang="en">

<a href="#main" class="skip-link">Skip to main content</a>

<!-- Add id="main" to your main content wrapper -->
<main id="main">…</main>

.skip-link {
  position: absolute;
  left: -9999px;
  top: 8px;
  background: #14181f;
  color: #fff;
  padding: 10px 16px;
  border-radius: 8px;
  font-weight: 600;
  z-index: 9999;
}
.skip-link:focus { left: 12px; }

Priority 2: Alt text — 30 to 90 minutes

Every <img> element must have an alt attribute. Axe lists every image missing one. Work through the list:

• Informational images — hero images, product screenshots, team photos, charts: write alt text that describes what the image communicates, not just what it depicts. “Screenshot of the dashboard showing a risk score of 78 with three WCAG failures listed” is useful. “Image” is not.
• Decorative images — dividers, background textures, icons paired with visible text: use alt="" (empty string, not missing). This tells screen readers to skip the element entirely.
• Linked images — an image wrapped in an <a> tag: the alt text should describe the link destination, not the image. If the link goes to your pricing page, alt="View pricing", not alt="arrow icon".
• CMS-managed images — if images come from a CMS (WordPress, Contentful, Sanity): add alt text in the media library. It propagates to all uses of that asset automatically, and filling in the alt field becomes the sustainable long-term process for editors.

Priority 3: Form labels — 30 to 60 minutes

Unlabeled form inputs are among the most common ADA demand letter citations. Axe flags every <input>, <select>, and <textarea> that lacks a programmatically associated label.

The standard fix — visible label:

<label for="email">Email address</label>
<input id="email" type="email" placeholder="you@example.com">

For single-input forms where a visible label would disrupt the layout:

<input type="email" aria-label="Email address" placeholder="you@example.com">

Placeholder text alone does not satisfy the label requirement — it disappears when the user starts typing and is not reliably announced by screen readers. Don’t overlook search bars, newsletter signup fields in footers, and subscribe inputs embedded in blog posts or sidebars. Those are just as exposed as the main contact form.

Priority 4: Color contrast — 1 to 2 hours, design sign-off usually needed

ShipSafe and Axe both flag text elements failing the 4.5:1 contrast ratio (or 3:1 for large text ≥ 18pt). This fix often requires a design decision — you’re changing a color that was chosen intentionally.

Systematic approach using CSS variables

If your site uses CSS custom properties for color — --color-text-muted, --text-secondary, etc. — changing the variable value fixes every instance at once:

:root {
  /* Was #999999 (2.85:1 on white — fails) */
  --text-muted: #767676; /* 4.54:1 on white — passes */
}

Use the WebAIM Contrast Checker to find the exact value that passes. The lightest grey that passes 4.5:1 on white is #767676. Anything lighter fails. If your codebase uses hardcoded hex values throughout, do a global find-and-replace for each failing color. Check placeholder text separately — it is subject to the same contrast ratio and is frequently overlooked.

Priority 5: Keyboard navigation — 2 to 4 hours

Keyboard navigation failures are not detectable by automated scanners — they require manual testing. Unplug your mouse and Tab through your entire site.

• Replace <div onclick> with <button> — any interactive element built as a <div> or <span> with a click handler is invisible to keyboard users and screen readers. Native <button> elements come with keyboard accessibility and focus management built in.
• Remove positive tabindex values — tabindex="1", tabindex="2", etc. override the natural DOM order and almost always create a broken, unpredictable focus sequence. Search your codebase for tabindex with values above 0 and remove them. Use DOM order to control focus, not tabindex.
• Fix modal focus management — modals must: (a) move focus into the modal on open, (b) trap focus inside while the modal is open, (c) close on the Escape key, and (d) return focus to the triggering element on close. Each missing step is a WCAG 2.1.2 keyboard trap violation.
• Verify visible focus indicators — Tab through the page and confirm every focused element shows a visible ring. If you have :focus { outline: none } globally (a common CSS reset), replace it with :focus-visible { outline: 2px solid #005fcc; outline-offset: 2px; } — this shows the ring for keyboard users but not mouse clicks.

Document every fix

Documentation is the evidence that you remediated in good faith. Courts weigh documented remediation significantly more favorably than an undocumented claim.

• Write descriptive git commit messages — “Fix unlabeled form inputs on contact and newsletter forms (WCAG 1.3.1 A)” is verifiable, timestamped evidence. “Fix accessibility stuff” is not.
• Save before-and-after scan screenshots — run ShipSafe before and after each priority block and save both results with the date visible. A documented before/after showing the issue count drop from 7 to 0 is concrete evidence of remediation.
• Add an accessibility statement — a publicly accessible page stating your commitment to WCAG 2.1 AA, a contact email for reporting accessibility issues, and the date of your last review. Add a link in your site footer. Courts and regulators view this as evidence of ongoing good faith.

Verify with ShipSafe after each priority block

Re-run ShipSafe after completing Priority 1–3 to confirm those items are resolved before investing time in Priority 4–5. ShipSafe catches the four failures most commonly cited in ADA demand letters — missing language attribute, unlabeled inputs, missing alt text, color contrast — and shows you an updated risk score. A clean result on those items before you begin the harder work confirms you’ve closed the highest-exposure gaps first.

Re-scan my site with ShipSafe →

Related ShipSafe guides:

• ADA compliance checklist — 30 testable WCAG 2.1 AA items to audit your site
• WCAG compliance for AI-generated sites — the 5 most-flagged gaps
• Received an ADA demand letter? Step-by-step response guide
• Do accessibility overlays prevent ADA lawsuits?
• How to fix missing alt text on images — WCAG 1.1.1 fix guide

Frequently asked questions

Also in the Copper Bay Labs suite

Accessibility is one layer of pre-launch risk. These free tools cover the rest: