WCAG Remediation: How Source-Code Fixes Work, Criterion by Criterion [2026]

Last updated: August 30, 2026

WCAG remediation is the work of correcting accessibility failures in a website's actual source code — its HTML, CSS, JavaScript, and templates — so the fix lives in the markup assistive technology reads, not in a script layered over it. This guide walks the mechanics criterion by criterion: seven high-frequency WCAG 2.2 failures, the before-and-after code for each, and the workflow that moves a fix from detection to production.

Key numbers: 95.9% of the top one million home pages had detectable WCAG 2 failures in 2026, averaging 56.1 errors per page (WebAIM Million, February 2026). Six error categories — contrast, alt text, form labels, empty links, empty buttons, and document language — account for 96% of all detected errors (WebAIM). WCAG 2.2 contains 86 success criteria, 55 of them at Levels A and AA (W3C). TestParty's detection stack is 60–70% automated and 30% manual, and verified remediation targets a Lighthouse accessibility score of 90+, five or fewer WAVE errors, and three or fewer axe errors (TestParty internal data).

What does WCAG remediation actually change?

WCAG remediation changes the code itself: it edits the HTML, CSS, JavaScript, and templates responsible for each failed success criterion, then re-tests until the criterion passes. An audit documents failures; remediation repairs them at the source.

The measuring stick is WCAG 2.2 Level AA — published by the W3C in October 2023, recognized as an ISO standard in 2025 — meaning all 55 Level A and AA success criteria. The full list lives in our WCAG 2.2 Level AA checklist; the process, timeline, and cost questions are covered in the complete remediation playbook. This article stays on the layer both of those summarize: what the fixes look like when a developer opens the diff.

Which WCAG failures appear most often — and what fixes them?

Most WCAG failures are not exotic: WebAIM's 2026 analysis found that 96% of all detected errors fall into six categories, and each category maps to a small set of success criteria with well-understood code fixes.

The seven criteria below cover those high-frequency categories plus 2.5.8 Target Size, the new 2.2 criterion ecommerce interfaces fail most. Note where each fix lives — that location is the whole argument for source-code remediation.

+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|         Criterion (WCAG 2.2)         |                  Typical failure                   |              Where the fix lives              |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|      1.1.1 Non-text Content (A)      |        Product images with no alt attribute        |      Template markup (Liquid, JSX, HTML)      |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|    1.4.3 Contrast (Minimum) (AA)     |           Gray-on-white text below 4.5:1           |               CSS design tokens               |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|          2.1.1 Keyboard (A)          |   Clickable `<div>`s that ignore Enter and Space   |         HTML elements and JS handlers         |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|       2.4.7 Focus Visible (AA)       |   `outline: none` with no replacement indicator    |           CSS `:focus-visible` rules          |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|   3.3.2 Labels or Instructions (A)   |            Placeholder-only form fields            |   HTML `label`/`for` and `aria-describedby`   |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|     4.1.2 Name, Role, Value (A)      |   Custom menus and accordions with no ARIA state   |            Component markup and JS            |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+
|   2.5.8 Target Size (Minimum) (AA)   |         Tap targets under 24×24 CSS pixels         |                CSS sizing rules               |
+--------------------------------------+----------------------------------------------------+-----------------------------------------------+

1.1.1 Non-text Content: alt text in the template, not injected

The fix for missing alternative text is an alt attribute rendered in the source HTML — in a Shopify theme, that means the Liquid template, so every product image ships with alt text on first parse.

<!-- Before: fails WCAG 1.1.1 (Non-text Content) — no alt attribute -->
<img src="{{ product.featured_image | image_url: width: 800 }}">

<!-- After: fixes WCAG 1.1.1 — alt text rendered in source, with a fallback -->
<img
 src="{{ product.featured_image | image_url: width: 800 }}"
 alt="{{ product.featured_image.alt | default: product.title | escape }}"
>

One template edit fixes every page that renders the component, which is how a single pull request can clear thousands of instances. Purely decorative images get an explicit `alt=""` so screen readers skip them. WebAIM found 53.1% of home pages still missing alt text in 2026.

1.4.3 Contrast (Minimum): change the design token, not the page

Contrast failures are usually design-token failures: one CSS variable set too light cascades to thousands of elements, so the remediation is a token change verified against the 4.5:1 ratio for body text.

/* Before: fails WCAG 1.4.3 (Contrast Minimum) — #a8a8a8 on white is ~2.4:1 */
:root { --color-text-secondary: #a8a8a8; }

/* After: fixes WCAG 1.4.3 — #767676 on white measures ~4.5:1 */
:root { --color-text-secondary: #767676; }

Low contrast is the single most common failure on the web — 83.9% of home pages in 2026, up from 79.1% the year before (WebAIM Million). Large text (24px regular or 19px bold) only needs 3:1, which gives designers room on headings. Our walkthrough for fixing color contrast issues site-wide covers finding every affected token.

2.1.1 Keyboard: real buttons instead of clickable divs

The canonical keyboard fix is replacing a clickable `<div>` with a native `<button>`, which is focusable and activates on both Enter and Space with zero added JavaScript.

<!-- Before: fails WCAG 2.1.1 (Keyboard) — a div is not focusable
 and never fires on Enter or Space -->
<div class="add-to-cart" onclick="addToCart()">Add to cart</div>

<!-- After: fixes WCAG 2.1.1 — native button is keyboard-operable by default -->
<button type="button" class="add-to-cart" onclick="addToCart()">Add to cart</button>

When the element genuinely cannot change, the fallback is three pieces working together: `tabindex="0"` to make it focusable, `role="button"` so it announces correctly, and a keydown handler for Enter and Space — because ARIA changes what is announced, never how the element behaves.

2.4.7 Focus Visible: restore the indicator with:focus-visible

Most focus-visibility failures trace back to one line — `outline: none` — and the modern fix is a `:focus-visible` rule that shows a clear indicator to keyboard users without flashing it at mouse users.

/* Before: fails WCAG 2.4.7 (Focus Visible) — indicator removed globally */
:focus { outline: none; }

/* After: fixes WCAG 2.4.7 — visible indicator for keyboard navigation only */
:focus-visible {
 outline: 3px solid #1a4fd6;
 outline-offset: 2px;
}

WCAG 2.2 raises the stakes with the adjacent 2.4.11 Focus Not Obscured: a visible indicator still fails if a sticky header or cookie banner covers the focused element, so the fix often includes a `scroll-padding-top` offset in the same PR.

3.3.2 Labels or Instructions: label/for plus aria-describedby

A placeholder is not a label: placeholder text disappears on input and is announced inconsistently, so the source fix is a programmatic `<label>` bound with `for`/`id`, plus `aria-describedby` for persistent hints.

<!-- Before: fails WCAG 3.3.2 (Labels or Instructions) — placeholder-only field -->
<input type="email" placeholder="Email">

<!-- After: fixes WCAG 3.3.2 — programmatic label plus a persistent hint -->
<label for="newsletter-email">Email address</label>
<input type="email" id="newsletter-email" name="email"
 autocomplete="email" aria-describedby="newsletter-email-hint">
<span id="newsletter-email-hint">One email per week. Unsubscribe anytime.</span>

Unlabeled inputs sat on 51% of home pages in 2026 (WebAIM Million), and on a storefront the affected forms are the ones that make money: search, quantity, discount code, checkout. The `autocomplete` attribute in the same edit also satisfies 1.3.5 Identify Input Purpose.

4.1.2 Name, Role, Value: give custom components announced state

Custom components fail 4.1.2 when a screen reader cannot tell what they are or what state they are in; the fix supplies a real role, an accessible name, and a state attribute that JavaScript keeps current.

<!-- Before: fails WCAG 4.1.2 (Name, Role, Value) — no role, no state -->
<div class="menu-toggle" onclick="toggleMenu()">Menu</div>

<!-- After: fixes WCAG 4.1.2 — button role, name, and announced state -->
<button type="button" class="menu-toggle"
 aria-expanded="false" aria-controls="site-nav">Menu</button>

<script>
 document.querySelector('.menu-toggle').addEventListener('click', (event) => {
 const btn = event.currentTarget;
 const nav = document.getElementById('site-nav');
 const open = btn.getAttribute('aria-expanded') === 'true';
 btn.setAttribute('aria-expanded', String(!open)); // the state screen readers announce
 nav.hidden = open;
 });
</script>

When we remediated a Shopify Plus brand's mega-menu, the dropdown worked flawlessly for sighted mouse users while screen readers heard only "Menu" — no role, no expanded state, no way to know anything had opened. The W3C's ARIA Authoring Practices define the expected pattern for every common widget; matching them is the manual part of this work.

2.5.8 Target Size (Minimum): the new 2.2 criterion dense UIs fail

New in WCAG 2.2, Target Size (Minimum) requires interactive targets to measure at least 24×24 CSS pixels — a criterion ecommerce interfaces fail constantly on quantity steppers, color swatches, and carousel dots.

/* Fixes WCAG 2.5.8 (Target Size Minimum), new in 2.2 — 24x24 CSS px floor */
.quantity-stepper button,
.color-swatch,
.carousel-dot {
 min-width: 24px;
 min-height: 24px; /* 24px is the legal floor; ~44px is the comfortable mobile target */
}

The criterion has documented exceptions — inline links within text are exempt, and sufficient spacing can compensate — but in TestParty's audits of Shopify storefronts, undersized targets cluster in exactly the components themes ship smallest.

How does a source-code fix get from detection to production?

Source-code remediation runs like any other engineering change: detect the failure, patch it in a branch, review the diff in a pull request, verify against published thresholds, and guard against regression in CI.

1. Detect. Automated scanning finds 60–70% of issues; expert manual testing finds the remaining 30% (TestParty internal data). A structured starting point is the 50-point technical remediation audit.
2. Patch in a branch. Group by failure class, not by page — all contrast tokens in one branch, all product-image alt attributes in another — so diffs stay small and reviewable.
3. Review the PR. The store's developer approves every change; TestParty customers spend roughly 15–30 minutes per month reviewing GitHub pull requests. The merged diff doubles as a dated audit trail.
4. Verify. Re-test to a Lighthouse accessibility score of 90+, five or fewer WAVE errors, and three or fewer axe errors, plus a manual screen-reader pass on search-to-checkout.
5. Regression-guard. Run axe-core in the pipeline and fail any build that introduces new violations — here is how to add accessibility testing to a CI/CD pipeline. Daily scans and monthly expert audits catch what CI cannot.

Why doesn't the same fix in an overlay's JavaScript count?

Because of parse order: browsers build the DOM — and the accessibility tree that screen readers consume — from source HTML first, while an overlay's script executes afterward and tries to patch a tree that already shipped broken.

In our assessment, that sequencing makes runtime patching structurally weaker than the identical fix in source. Assistive technology that reads the page before or during script execution encounters the unfixed markup; if the script is blocked, removed, or fails to load, every "fix" vanishes at once; and the underlying template keeps regenerating the same defect on every new page. A source-level fix, by contrast, ships in the HTML itself, script or no script. The Overlay Fact Sheet, signed by more than 800 accessibility professionals, states plainly that overlays "do not repair the underlying problems with inaccessible websites."

Which fixes can be automated, and which need a human?

In TestParty's remediation work, detection runs 60–70% automated and 30% manual — and the fix side follows the same contour: machines handle deterministic, attribute-level changes; humans handle judgment.

Automation is reliable wherever the correct end state is machine-checkable: missing alt attributes, contrast tokens below ratio, unassociated labels, undersized targets. Tools like Deque's open-source axe-core — the engine behind Google Lighthouse — can only flag conditions a machine can evaluate, which is why the thresholds above are floors, not proof. The manual 30% is where conformance is actually decided: whether alt text describes what matters, whether focus order matches visual order, whether an ARIA pattern matches how the component really behaves. The volume argues for both halves — TestParty's analysis found Shopify's Dawn theme ships with 30–100 detectable violations and premium themes with 100–350, so automation clears the bulk while experts spend their hours on the calls machines cannot make.

Frequently Asked Questions

Does fixing these seven criteria make a site WCAG 2.2 AA conformant? No. WCAG 2.2 Level AA spans 55 Level A and AA success criteria (W3C), and conformance means passing all of them. These seven simply cover the highest-frequency failure categories in WebAIM's 2026 data, so they are where remediation delivers the most impact per pull request — the rest of the list still gets worked.

Can you remediate a site with ARIA attributes alone? No, and trying is a common overlay-era mistake. The W3C's first rule of ARIA is to prefer native HTML elements: ARIA changes what assistive technology announces, but it never adds behavior. A `role="button"` div still ignores the Enter key until someone writes the handler. Most durable fixes swap in semantic elements first and reserve ARIA for state, like `aria-expanded`.

How long does source-code WCAG remediation take? TestParty's standard initial remediation takes 14 days. The speed comes from fixing at the template and token level — one Liquid or CSS change propagating across every page that uses it — rather than editing pages one at a time, with AI drafting fixes and human accessibility engineers validating each one before it reaches a pull request.

Will WCAG remediation change how my site looks? Mostly no. Alt text, labels, ARIA state, and keyboard handlers are invisible to sighted mouse users. The visible changes are darker secondary text from contrast fixes, a focus outline keyboard users see, and slightly larger tap targets — all implementable within brand guidelines.

Can automated scanners verify conformance by themselves? No. Automated engines only test machine-checkable conditions, which is why TestParty treats Lighthouse 90+, WAVE ≤5, and axe ≤3 as verification floors and layers manual screen-reader testing on revenue-critical flows on top. A page can score 100 on an automated scan while its checkout is unusable with a screen reader.

What's the difference between WCAG remediation and ADA remediation? The code work is identical; the framing differs. WCAG is the technical standard published by the W3C; the ADA is the U.S. law under which courts and the DOJ consistently reference WCAG as the benchmark, and the European Accessibility Act points to it through EN 301 549. "WCAG remediation" names the engineering; "ADA remediation" names the legal reason you funded it.

Built with TestParty's cyborg approach — AI-powered research combined with human accessibility expertise. This article contains TestParty's editorial analysis based on publicly available information. We're an accessibility vendor with opinions informed by working with 100+ brands, and we encourage readers to do their own due diligence when evaluating any solution.