DEV Community: Romain

The Shopify Store Accessibility Checklist (WCAG 2.2)

Romain — Tue, 19 May 2026 18:42:52 +0000

Shopify's Dawn theme (and most marketplace themes) ships with several WCAG 2.2 issues out of the box. Here's a checklist we use when auditing Shopify stores, in priority order.

Critical (fail an audit on their own)

Color contrast on sale price tags (red on light pink), placeholder text in inputs, and the cart drawer headers. Threshold: 4.5:1 normal text, 3:1 large/bold.
Buttons without accessible names: the icon-only quantity steppers (+ / −) often have no aria-label.
Form labels on the checkout: most "floating label" implementations fail when the label moves outside the input's accessible name.

Serious

Carousel autoplay with no pause control.
Keyboard trap in the predictive search drawer (focus stays inside even after closing).
Modal product quick-view returns focus to the top of the page instead of the trigger.

WCAG 2.2-specific

Target size 2.5.8: social icons in the footer are typically 16×16. Bump to 24×24 minimum.
Drag movements 2.5.7: any custom slider or sortable wishlist needs a click/tap fallback.
Accessible authentication 3.3.8: Shopify's default checkout is fine; custom checkouts that ban paste in the password field fail this.

Quick wins

Audit your theme.liquid for hardcoded colors against your background tokens.
Add aria-label to every `` that contains only an icon or SVG.
Set focus styles globally: :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
Test the keyboard tab order through a full checkout. If you can't complete a purchase keyboard-only, the score doesn't matter.

AccessProof scans Shopify stores out of the box (we follow redirects through the storefront) and groups findings by template so your dev team can fix them theme-wide instead of page-by-page.

Originally published on access-proof.com.

axe-core vs. Lighthouse: Which Catches More Accessibility Issues?

Romain — Tue, 19 May 2026 18:42:21 +0000

Lighthouse and axe-core are the two automated accessibility scanners most teams reach for. They share a heritage (Lighthouse's a11y category embeds axe-core), but they catch different things in practice. We ran both against 50 production websites — here's what we found.

The setup

50 sites, mix of e-commerce, SaaS, and content (avg 8 issues/site between the two).
Lighthouse 11 (default a11y category, mobile preset).
axe-core 4.9 with rules at wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa.

Results

MetricLighthouseaxe-core 4.9

Avg issues found per site4.27.8

Unique rules triggered2756

WCAG 2.2 coveragepartialfull

False positive rate (manual review)~5%~3%

What axe-core catches that Lighthouse misses

WCAG 2.2 target-size violations (2.5.8).
ARIA misuse on custom widgets (axe is much stricter on role/state mismatch).
Region/landmark issues on complex layouts.
Color contrast on text inside images (axe has better OCR-aware checks).

What Lighthouse adds

Performance correlation: an accessibility score next to LCP/CLS gives leadership a single dashboard.
Crawl-style scoring out of 100, easier to track over time at a high level.

Verdict

Use both. Lighthouse is great for tracking a top-line score in CI dashboards. axe-core is what you want when you need to fix issues — its rule set is broader, its node-level reporting is more actionable, and it's the engine behind most professional audits. AccessProof runs axe-core under the hood, mapped to WCAG 2.2 and exportable as PDF.

Originally published on access-proof.com.

You Got an ADA Demand Letter. Now What?

Romain — Tue, 19 May 2026 18:36:39 +0000

ADA-related demand letters targeting websites have grown roughly 14% year-over-year since 2018. If you just received one, here's what to do — and what not to do — in the first 72 hours.

First 24 hours

Don't reply directly. Forward to your lawyer (or get one) before any written communication. Anything you send becomes evidence.
Preserve the page state. Take a full HTML + screenshot snapshot of the URL(s) cited in the letter, today's date. Their claims are time-bound; you need proof of what was live when.
Run a baseline scan. axe-core, WAVE, AccessProof — anything that produces a date-stamped issue list. This becomes the starting point of your remediation log.

Day 2–7

Triage findings: critical/serious first (color contrast, missing labels, keyboard traps).
Document each fix with a commit / ticket / dated entry. The paper trail matters more than the speed.
Add an accessibility statement page (publicly linked from the footer) describing your standard, conformance level, contact, and remediation plan.

What reduces risk long-term

Most plaintiffs settle out of court if you can show continuous, dated remediation activity. A single audit means nothing; quarterly automated scans + a public statement + a contact form do.

Common mistakes

Negotiating directly with the plaintiff before counsel.
Removing the offending page (looks like evidence destruction).
Using an "accessibility overlay" widget. Courts increasingly view them as cosmetic; they don't fix underlying issues and may add new ones.

How AccessProof helps

Each scan produces a dated, exportable PDF report. Schedule weekly or monthly scans, archive the PDFs, and you have the contemporaneous documentation that turns "we tried" into "we proved we tried".

Originally published on access-proof.com.

WCAG 2.2: Every New Success Criterion Explained

Romain — Tue, 19 May 2026 18:36:09 +0000

WCAG 2.2 (published October 2023) introduced 9 new success criteria. Most of them target real-world friction points — touch targets, focus visibility, drag operations — rather than purely conceptual rules. Here's what each one means in practice.

The 9 new criteria

2.4.11 Focus Not Obscured (Minimum) — AA

When an element receives focus, it must not be entirely hidden by sticky headers, banners, or modals. Common offender: a sticky cookie banner that covers the focused link in the menu just below.

Fix: scroll-padding-top equal to the sticky header height, or move focus to a position that accounts for the overlay.

2.4.12 Focus Not Obscured (Enhanced) — AAA

Same as above, but the focused element must be fully visible (no partial occlusion).

2.4.13 Focus Appearance — AAA

The focus indicator must have a minimum area (2 CSS px around the perimeter) and a 3:1 contrast ratio against the unfocused state. Killing the default outline without replacing it fails this.

2.5.7 Dragging Movements — AA

Anything done with a drag must be doable with a single pointer (click/tap). Sliders, kanban boards, signature pads — all need a non-drag fallback.

2.5.8 Target Size (Minimum) — AA

Interactive targets must be at least 24×24 CSS px (with exceptions for inline text and spacing-based equivalents). Tiny social icons in footers are the most common failure.

3.2.6 Consistent Help — A

If a help mechanism is repeated across pages (chat widget, contact link), it must appear in the same relative location. Don't hide the chat on some pages.

3.3.7 Redundant Entry — A

Within the same process, don't ask for information the user has already entered. Pre-fill or offer to reuse.

3.3.8 Accessible Authentication (Minimum) — AA

Cognitive function tests (memorize, transcribe a captcha, identify objects) must have an alternative. Allow paste in password fields. Offer SSO or magic links.

3.3.9 Accessible Authentication (Enhanced) — AAA

No cognitive function test at all, even with alternatives. Object-recognition CAPTCHAs disqualify you.

How AccessProof helps

Of these, the criteria reliably catchable by automated tooling (axe-core 4.9+) are 2.5.8 (target size) and partial coverage of 2.4.11 (focus obscured). The rest require manual review or process audit. AccessProof flags the automatable ones automatically and prompts you for the manual checks at the end of each scan.

Originally published on access-proof.com.

What is axe-core and Why It Powers Real Accessibility Audits

Romain — Tue, 19 May 2026 18:30:27 +0000

If you've looked at any professional accessibility tool — Deque's axe DevTools, Microsoft's Accessibility Insights, Google's Lighthouse, WAVE's engine, or AccessProof — you've already touched axe-core. It's the open-source rules engine that quietly powers most evidence-based audits today. Here's what it actually does, why it's the standard, and how it compares to the “AI accessibility” overlay claims you've probably seen.

What axe-core is

axe-core is an MIT-licensed accessibility testing engine maintained by Deque Systems. It runs in any environment that has a DOM — browsers, headless Chromium, Node — and returns a structured list of accessibility violations, each tied to a specific WCAG success criterion and DOM node.

The source lives at github.com/dequelabs/axe-core. It ships rules for WCAG 2.0, 2.1, 2.2 (Level A, AA, AAA), plus Section 508 and best-practice checks. As of axe-core 4.9 (released 2024), the engine implements approximately 90 individual rules.

What it actually checks

axe-core works by walking the rendered DOM and evaluating each node against its rule set. Each rule produces one of four outcomes:

Violations: definitively fails a WCAG criterion (e.g. color-contrast, label, button-name).
Needs review: cannot be determined automatically; flagged for manual review.
Passes: rule was checked and the node passed.
Inapplicable: the rule doesn't apply (e.g. no images on the page → no alt-text rule fires).

Examples of categories axe-core reliably catches:

Color contrast against computed background (including against background images via canvas sampling).
Missing or incorrect ARIA attributes and roles.
Form fields without programmatic labels.
Buttons and links without accessible names.
Heading structure and landmark misuse.
Keyboard traps detectable from static DOM analysis.
WCAG 2.2 target size (Success Criterion 2.5.8).

And the categories it deliberately doesn't cover (these need humans):

Whether alt text is meaningful (it can only check presence/absence).
Whether headings describe the section they precede.
Reading order in complex visual layouts.
Whether a control's name is appropriate to its function.
Live region behavior over time.

This honesty about scope is exactly why axe-core became the trust anchor of the industry. Deque publicly documents that fully automated testing can catch a meaningful share of issues, but the precise share depends on the site. Some sites have mostly automatable issues (forms, content); others rely heavily on custom widgets where manual review is essential. axe-core scopes the half it can handle — accurately — instead of overclaiming.

Why “AI accessibility” overlays don't replace it

Overlay widgets (accessiBe, UserWay, AudioEye) promise to “fix” accessibility by injecting JavaScript that mutates the page at runtime. The promise sounds appealing; the practical issues are well documented:

Overlays operate downstream of the underlying HTML/CSS. They can't fix a button that has no semantic role; they can only paper over it. Screen readers can still expose the broken markup beneath.
The Overlay Fact Sheet — signed by 800+ accessibility professionals including the authors of axe-core — lists technical reasons overlays often introduce new issues (keyboard focus stealing, ARIA conflicts, autoplay sounds).
Courts have allowed lawsuits to proceed against sites that installed an overlay as their primary remediation. The widget's presence is not a defense.
Most overlays don't produce an auditable, dated report of what they fixed. Plaintiff counsel asks for one. You don't have it.

The alternative is to measure the underlying site — axe-core's job — and fix what's actually broken in the source code. See our side-by-side comparison vs. overlay vendors.

How AccessProof uses axe-core

We vendor axe-core 4.9.1 — the version is pinned, the file is shipped with our scanner image, and we don't fetch it from a CDN at scan time. This matters because:

Reproducibility: the same scan today and 6 months from now uses the same engine version. The deltas in your reports reflect changes to your site, not engine drift.
CSP-friendly: vendoring lets us run axe-core inside a headless Chromium even on sites with strict Content Security Policies that would block an external CDN script.
Auditable: anyone inspecting a PDF report can verify which axe-core version produced it.

We run axe-core with the wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa rule sets enabled, then translate the violation list into a scored report (critical / serious / moderate / minor), and render it to a dated PDF. The PDF is the artifact you keep in your remediation log.

Want to see a real one? Run a free scan — no signup needed for the first one.

How to interpret axe-core impact levels

Each violation comes with an impact level: critical, serious, moderate, or minor. These are not WCAG-defined — Deque assigns them based on user impact severity. A rough mapping:

Critical: blocks a user from completing core tasks (missing button label, keyboard trap, empty links).
Serious: degrades the experience significantly (insufficient contrast, missing form labels).
Moderate: noticeable but not blocking (ARIA attribute on wrong element, redundant landmarks).
Minor: edge case or convention (page region missing).

For triage, fix critical and serious before anything else. AccessProof's scoring algorithm weights them critical × 4 + serious × 2 + moderate × 1 + minor × 0.5 on a 100-point scale — the same weighting Deque suggests in its documentation.

The other engines, briefly

WAVE (WebAIM) is an excellent rules engine in its own right, with a strong visual UI. We've found it slightly more lenient on color contrast edge cases than axe-core but generally aligned on critical violations.
Lighthouse's accessibility category uses axe-core under the hood but runs a curated subset. Treat the Lighthouse score as a starting indicator, not an audit.
Accessibility Insights (Microsoft) also uses axe-core, paired with an assisted manual test workflow. Recommended for in-team adoption.

How widely it's actually used

axe-core sits inside the accessibility tooling of many of the largest software organizations. Some confirmed integrations:

Google Lighthouse uses a curated axe-core rule subset in its Accessibility category.
Microsoft Accessibility Insights (web and desktop) is built on axe-core with manual-assist workflows added on top.
Deque axe DevTools, both the free browser extension and the paid enterprise products, all run the same axe-core engine.
Salesforce, IBM, GitHub, and many other major SaaS vendors use it in CI per public talks and engineering posts.
Web framework starter kits and accessibility linters (eslint-plugin-jsx-a11y, etc.) frequently cite axe-core's rule definitions as their reference.

Open-source rules engines benefit from network effects: the more eyes on the rules, the faster false positives are caught and the faster new WCAG criteria get covered. Closed engines invariably trail.

How axe-core decides what is a violation

Each axe-core rule is a function that runs against a node and returns pass/fail/needs-review. The rules are versioned in the GitHub repo and discussed openly in issues and PRs. When the W3C publishes a new WCAG version, Deque maintainers and community contributors implement supporting rules — that's how WCAG 2.2 support landed in axe-core 4.8 and 4.9.

For a concrete example, here's the kind of result axe-core produces for a single contrast violation:

{
  "id": "color-contrast",
  "impact": "serious",
  "tags": ["cat.color", "wcag2aa", "wcag143"],
  "description": "Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds",
  "nodes": [{
    "target": ["#hero p.subtitle"],
    "html": "Get started in 60 seconds
",
    "failureSummary": "Element has insufficient color contrast of 3.21 (foreground color: #9ca3af, background color: #ffffff, font size: 14.0pt, font weight: normal). Expected contrast ratio of 4.5:1"
  }]
}

That single record gives you the rule, the WCAG mapping, the impact level, the exact CSS selector, the computed ratio, the colors involved, the font size, and the threshold it failed against. This level of specificity is what makes axe-core useful for engineers and credible in audit reports — the “evidence” is right there in the artifact.

What it costs to use directly

axe-core is MIT-licensed and free. If you're comfortable with Node and Playwright/Puppeteer, you can integrate it into your CI in an afternoon:

npm install @axe-core/playwright
// in a Playwright test
const accessibilityScanResults = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])
  .analyze();
expect(accessibilityScanResults.violations).toEqual([]);

What you don't get out of the box: scheduling, history, scoring, PDF export, multi-page crawl, evidence retention. That's the layer hosted services like AccessProof add on top. The engine itself is identical; the operational glue is where vendors differ.

Versioning and the audit-trail question

Because axe-core evolves — new rules ship, existing rules get stricter — anyone who keeps long-term audit history should record which version produced each report. A 2024 PDF that says “axe-core 4.9.1” in the footer is reproducible: you can re-run the same version against an archived copy of your site and get the same answer.

Vendors that hide their engine version (or use a custom unpublished rule set) make this kind of reproducibility impossible. Ask for the version in every PDF or HTML report your tool generates. AccessProof prints it on every page.

Summary

axe-core is the rules engine that turns “accessibility” from a vague aspiration into a measurable set of pass/fail checks. It's open source, transparent about what it can't check, and used by the people who set the standard. If your accessibility tool isn't built on it (or one of the open engines with comparable transparency), ask what it's built on — and what its false positive rate is on your stack.

AccessProof uses axe-core because the alternative — running our own opaque scorer or, worse, an overlay — wouldn't produce evidence anyone could trust. See pricing if you'd like to add scheduled, dated, axe-core-backed audits to your remediation log.

Originally published on access-proof.com.

ADA Web Accessibility Lawsuit Checklist for 2026

Romain — Tue, 19 May 2026 18:29:57 +0000

In 2024, U.S. federal courts saw more than 4,000 ADA Title III website-accessibility lawsuits — UsableNet's annual report counted 4,536 filings against 2,452 unique defendants. Plaintiffs continue to target small and mid-size online businesses alongside enterprise. This checklist tells you what to put in place before a demand letter arrives.

Why 2026 looks different

April 2024 DOJ Title II rule: the Department of Justice finalized a rule requiring state and local government web content to meet WCAG 2.1 Level AA. Title II is for public entities, but it sets a public conformance bar plaintiffs cite when arguing about Title III (private businesses).
European Accessibility Act (EAA) enforcement began 28 June 2025. Many U.S. businesses with EU customers (e-commerce, SaaS, banking) are now in scope under EU law in parallel with ADA at home. See the EU Commission resources for sector applicability.
Courts continue to look unfavorably on “accessibility overlay” widgets as a sole remediation. Several 2023–2024 decisions allowed cases to proceed despite an overlay being installed.

The 2026 checklist

1. Pick a target standard and write it down

WCAG 2.1 Level AA is the de facto bar referenced by the DOJ. WCAG 2.2 (October 2023) adds 9 success criteria you should adopt; conforming to 2.2 AA implies 2.1 AA. Publish your chosen standard in your accessibility statement so plaintiffs and courts know what you're aiming at.

2. Publish an accessibility statement

A statement should include: target standard (e.g. “WCAG 2.2 AA”), conformance level (full / partial), date of last audit, contact method (email + phone), and a remediation timeline. Link it from your footer on every page. Templates and guidance: W3C WAI.

3. Run a dated baseline audit

Use an automated scanner (axe-core, WAVE, AccessProof) plus at least one manual screen reader pass. Export the result with a timestamp and store it. Today's baseline is tomorrow's evidence that you started.

If you don't have a baseline yet, AccessProof's free scanner produces a dated PDF in under 90 seconds.

4. Fix the critical and serious issues first

Plaintiff firms cite a relatively small set of patterns repeatedly:

Missing alt text on informative images (WCAG 1.1.1).
Form fields without labels (WCAG 1.3.1, 3.3.2).
Color contrast failures (WCAG 1.4.3).
Keyboard inaccessible controls (WCAG 2.1.1).
Missing or duplicate page titles (WCAG 2.4.2).
Empty or unclear link text (“click here”) (WCAG 2.4.4).

These are the ones automated tooling catches and plaintiffs screenshot. Address them first, regardless of WCAG level.

5. Document remediation with dates

Commit messages, ticket IDs, before/after screenshots, dated PDF reports — every fix should leave a paper trail. Courts and counsel are persuaded by continuous, dated activity far more than by “we did an audit once.”

6. Schedule recurring scans

Monthly minimum, weekly preferred. The 2018 Robles v. Domino's outcome and most subsequent settlements reinforce the same expectation: regressions are inevitable, and the standard is whether you detect and fix them quickly. AccessProof runs scans automatically on a schedule and archives every PDF — starter plans begin at weekly cadence.

7. Train at least one developer to use a screen reader

30 minutes per release using NVDA (Windows / Firefox) or VoiceOver (Mac / Safari) catches issues no automated tool can — reading order, live region announcements, custom widget patterns. Free, no certifications required.

8. Have counsel on speed dial

Pre-identify counsel familiar with ADA Title III litigation in your state. If a demand letter arrives, do not negotiate directly. Forward to counsel within 24 hours.

9. Avoid overlay widgets as a sole remedy

An overlay can be one layer of defense in depth, but courts now scrutinize them. The Overlay Fact Sheet (signed by 800+ accessibility professionals) catalogs the limitations. Don't rely on an overlay as your only remediation.

10. Review your third-party widgets

Chat widgets, video players, payment iframes, signup forms — third-party code accounts for a significant share of failures on e-commerce and SaaS sites. Audit each integration and request accessibility statements from vendors. Cite them in your own statement (“Component X is provided by vendor Y; their conformance status: Z”).

What a court-ready audit trail looks like

If you receive a demand letter and have all of these on file, you start the conversation from a defensible position:

An accessibility statement on every page, dated within the last 12 months.
A series of dated PDF audit reports (monthly or weekly cadence).
A public remediation log or changelog showing fixes shipped.
A documented incident response process for accessibility complaints.

The difference between a $20,000 settlement and a $5,000 settlement is often the strength of this documentation alone.

Common mistakes

One-time audit, no follow-up. A single audit ages fast; the site changes, the standards evolve, regressions creep in.
Removing the offending page. Looks like evidence destruction. Fix it instead.
Overlay-only remediation. Documented in court rulings as insufficient.
Treating accessibility as a project, not a process. The expectation is ongoing conformance.

Where AccessProof fits

AccessProof runs axe-core 4.9+ against your site on a schedule, scores it against WCAG 2.2, and produces a dated PDF after every scan. The PDFs are designed to be exportable as part of a remediation log. Compared to overlay widgets, we don't inject JavaScript into your site — we measure it. See our comparison vs. accessiBe for the detail.

A short timeline of how we got here

Understanding the trajectory helps explain why 2026 looks different from 2018:

1990: ADA signed into law. Title III applies to “places of public accommodation”; the question of whether websites count was unresolved.
2018: Robles v. Domino's Pizza — the Ninth Circuit held that the ADA applies to Domino's website because it had a nexus to a physical place. SCOTUS declined to review.
2019–2023: Federal filings of Title III website cases stabilized around 2,000–4,000 per year per UsableNet's annual reports. New York and California remain dominant venues.
2024: DOJ finalizes its Title II web rule for state and local government. Title III rulemaking remains pending, but the Title II rule defines “technical standard” as WCAG 2.1 AA, signaling DOJ's view.
June 2025: European Accessibility Act enforcement begins. U.S. businesses serving EU consumers in covered sectors are now in scope.

The macro trend is consistent: courts and regulators expect WCAG conformance, plaintiffs file at scale, and overlay-only remediation is increasingly disfavored.

Sector-specific notes

E-commerce: highest volume of lawsuits. The product page → cart → checkout flow is the path plaintiffs test most. Audit that flow weekly.
SaaS: dashboards and onboarding flows are commonly cited. Trial signup pages get tested before paying-customer flows.
Hospitality / travel: room-selection widgets, date pickers, and PDF menus are frequent flagged elements.
Healthcare: patient portals are subject to both ADA and HHS Section 504/1557 standards. Multi-standard compliance is essential.
Government contractors: Section 508 compliance is its own statute; the technical standard is WCAG 2.0 AA per the 2017 refresh.

Cost of doing nothing vs. cost of compliance

Typical settlement amounts for ADA web Title III cases reported in trade press range from a few thousand to mid-five-figures, plus mandatory remediation. Annual programmatic compliance — automated scans, a part-time accessibility engineer or service, periodic manual audits — generally costs less than a single contested case. The ROI argument writes itself; the question is operational discipline.

What plaintiffs actually look for

Demand letters and complaints we've seen cite a remarkably consistent set of evidence:

Screenshots of the homepage and product/service pages with annotations showing missing alt text or contrast failures.
Automated scanner output (often WAVE or axe DevTools) included as appendix.
Specific quotes from your accessibility statement (or absence thereof) used against you.
Comparison against your competitor's site if they have better conformance.
Records of past complaints unanswered or unresolved.

This shapes the defense strategy: if the same scanner the plaintiff used produces a clean (or rapidly-improving) report on your dated audits, you neutralize the strongest evidence early.

Vendor and procurement considerations

If you sell to enterprise or government, your accessibility posture is a procurement input:

VPAT (Voluntary Product Accessibility Template) using ITI's template — increasingly required by procurement.
ACR (Accessibility Conformance Report) — the executive summary that wraps a VPAT.
Section 508 conformance for U.S. federal contracts (WCAG 2.0 AA per the 2017 refresh).
EN 301 549 for European procurement (incorporates WCAG 2.1 AA + non-web criteria).

If you don't have a VPAT, you'll lose deals before you ever hear about a lawsuit. A current VPAT typically requires a documented audit, which is the same artifact your remediation log needs anyway.

Documentation cadence

The defensible operational rhythm:

Weekly: automated scan of critical flows (homepage, signup, checkout, account).
Monthly: review the scan deltas, file tickets, close the previous month's.
Quarterly: manual screen-reader walkthrough of the same critical flows.
Annually: third-party audit (paid). Refresh VPAT.
Continuously: open contact channel for accessibility complaints, monitored by a named owner.

The cadence doesn't need to be heavy. It needs to be documented and actually executed.

The simplest first step

If you have nothing in place today, start here:

Run a free baseline scan. AccessProof free scanner gives you a dated PDF in 90 seconds.
Publish an accessibility statement (W3C templates are free). Add it to your footer.
Triage the top 10 critical/serious findings with your dev team.
Schedule a recurring scan — weekly minimum. Starter plans at AccessProof cover this.

That sequence — baseline + statement + remediation + recurring scan — is the difference between “we tried” and “we have evidence we tried.”

This article is general guidance, not legal advice. Always consult counsel for your specific situation.

Originally published on access-proof.com.

How to Fix Common WCAG Color Contrast Failures

Romain — Tue, 19 May 2026 18:24:15 +0000

Color contrast is the most frequently reported WCAG violation in automated audits. WebAIM's 2024 analysis of the top 1,000,000 home pages found that low-contrast text was detected on 81.0% of sites. The good news: 90% of contrast failures fall into 6 repeatable patterns. Fix those and your scan score jumps overnight.

1. Placeholder text that disappears into the input

Default browser placeholders render at roughly #757575 on #ffffff, which clocks 4.48:1 — fails WCAG 2.1 SC 1.4.3 (AA, needs 4.5:1). Most design systems override placeholders to a lighter grey and silently break compliance.

Before (fails, 3.5:1):

input::placeholder { color: #9ca3af; } /* Tailwind gray-400 on white */

After (passes, 4.83:1):

input::placeholder { color: #6b7280; } /* Tailwind gray-500 on white */

Tailwind users: placeholder:text-gray-500 passes on white backgrounds. placeholder:text-gray-400 does not.

2. Brand-colored buttons with white text

Brand greens, oranges, and yellows are the usual offenders. A primary call-to-action like #22c55e (Tailwind green-500) on white text returns 2.18:1 — failing both normal and large text thresholds.

Quick fix: shift the brand color down 100–200 steps in your scale for any button surface that contains text.

/* Fails: 2.18:1 */
.btn-primary { background: #22c55e; color: white; }

/* Passes: 4.54:1 */
.btn-primary { background: #15803d; color: white; }

If marketing won't let you darken the brand color, dark text on a light tint of the same hue is a frequent compromise:

.btn-primary { background: #dcfce7; color: #14532d; } /* 9.4:1, AAA */

3. Sale price tags (red on pink)

Especially common on e-commerce templates. The default red #ef4444 on a pink chip #fee2e2 returns 3.4:1 — fails for normal text. This pattern accounts for a measurable share of e-commerce contrast failures in the audits we run.

Fix: use a darker red for the text, keep the chip light:

.sale-tag { background: #fee2e2; color: #991b1b; } /* 6.6:1, AA */

If you want to scan your site for this pattern and 50+ other WCAG checks, try AccessProof's free scanner — it points to the exact node, the computed ratio, and the WCAG level that fails.

4. Disabled states that lie about being disabled

WCAG 1.4.3 explicitly exempts disabled UI components from the contrast rule (Understanding SC 1.4.3, “inactive” clause). But the exemption only applies if the disabled state is unambiguously communicated to assistive tech.

If your “disabled” button is just visually greyed out with no aria-disabled or disabled attribute, screen reader users still treat it as interactive — and the contrast rule applies again.


Submit

Submit

5. Text over hero images

Contrast is measured pixel-by-pixel against the actual background — not the average. A white heading on a hero photo can pass on the dark left third and fail on the bright right third. Automated scanners often flag this even when it “looks fine” in design review.

Reliable fix: a semi-transparent dark overlay on the image. rgba(0,0,0,0.4) brings most photos under control without crushing the visual.

.hero {
  background-image:
    linear-gradient(rgba(0,0,0,.45), rgba(0,0,0,.45)),
    url(/hero.jpg);
}
.hero h1 { color: white; } /* now reliably >7:1 */

For text-heavy sections, prefer a solid background block behind the text rather than relying on the image to behave.

6. Focus rings that vanish

WCAG 1.4.11 (Non-text Contrast, AA) requires UI components — including focus indicators — to have at least 3:1 contrast against adjacent colors. Removing the default outline without replacing it is the single most common keyboard-accessibility failure.

/* Catastrophic: removes focus indication entirely */
*:focus { outline: none; }

/* Compliant: visible, high contrast, matches brand */
:focus-visible {
  outline: 2px solid #1142ff;
  outline-offset: 2px;
}

Use :focus-visible (not :focus) so mouse users don't see the ring on click while keyboard users still get it on Tab.

How to verify your fixes

WebAIM Contrast Checker (free, single pair) — sanity check the ratio you computed.
axe DevTools browser extension — find every failing node on a page.
AccessProof — scan the whole site against WCAG 2.2, get a dated PDF with every node and computed ratio. Re-scan after the fix to confirm. See pricing.

One pattern to adopt: a contrast-aware design token set

Rather than chasing failures, define your palette so failures are impossible. For every accent color, ship at least one paired text color that hits 4.5:1 and one that hits 3:1 — and use only those pairings in components.

/* tokens.css */
:root {
  --accent: #1142ff;          /* brand */
  --accent-on-light: #0b2fb8; /* 7.0:1 on white */
  --on-accent: #ffffff;       /* 8.2:1 on --accent */
}

Reviewers stop asking “is this readable?” because the system can't produce an unreadable combination.

Testing a fix in 30 seconds

Before re-running a full scan, sanity-check a fix with the WebAIM Contrast Checker or your browser's DevTools color picker (Chrome and Firefox both display the computed ratio inline when you select a foreground color in the Inspector). If the ratio meets the threshold in the inspector, the change will hold at scan time.

One subtlety: the inspector shows the ratio for the styled foreground/background pair. If your background is actually an inherited color or a stacked semi-transparent surface, the inspector and the scanner may compute different effective backgrounds. axe-core walks the layout to find the actual rendered background pixel; that's why a fix that “looks fine” in DevTools can still fail an audit. When that happens, simplify the stack: replace stacked transparencies with a single opaque color, or place a wrapper with an explicit background behind the text.

The math behind the ratios

The WCAG contrast ratio is a relative luminance calculation defined in WCAG 2.1 §1.4.3. The formula:

ratio = (L1 + 0.05) / (L2 + 0.05)
where L1 = luminance of the lighter color, L2 of the darker.

Luminance itself is computed by linearizing each sRGB channel and weighting them 0.2126·R + 0.7152·G + 0.0722·B. You don't need to do this by hand — every modern tool implements it — but understanding it explains two common surprises:

Green contributes ~72% of perceived brightness. That's why brand greens often pass thresholds that brand blues fail.
The + 0.05 term means very dark and very light pairs plateau. Going from #000 to #0a0a0a against white barely moves the ratio.

Common Tailwind pairings that pass and fail

For teams that live in Tailwind, here's a quick reference (background → text):

BackgroundTextRatioWCAG AA normal

whitegray-4003.0:1fail
whitegray-5004.83:1pass
whitegray-6007.0:1pass (AAA)
whiteblue-5004.0:1fail
whiteblue-6005.2:1pass
green-500 (#22c55e)white2.18:1fail
green-700 (#15803d)white4.54:1pass
red-100red-8006.6:1pass

If your design system standardizes on these pairings, contrast violations stop appearing in your audits.

The 24-pixel rule for touch targets (related but distinct)

Strictly speaking, target size is WCAG 2.5.8 (AA), not a contrast rule — but it's the issue that hides next to contrast failures on most automated reports, so we cover it here. Interactive elements must be at least 24×24 CSS pixels.

The most common offender: social media icons in the footer rendered at 16×16. Even when the contrast of the icon itself passes, the target size fails, and screen-pixel-level tools group them in the same “low-impact UI” bucket.

/* Fails 2.5.8 */
.social-icon { width: 16px; height: 16px; }

/* Passes — uses padding to reach 24x24 without resizing the icon */
.social-icon-wrap {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 24px;
  height: 24px;
}

If your social icons live in tight footer rows, the padding-based approach keeps the visual size intact while meeting the rule.

Patterns we keep seeing in real audits

Across hundreds of scans, six anti-patterns account for the lion's share of contrast failures:

Gray-on-gray secondary text — designers reaching for “subtle” tones without checking the ratio.
Pastel buttons with white text — pastels saturate but don't darken; white text always loses.
Underline-less link colors matching surrounding text within 3:1 — fails WCAG 1.4.1 (color isn't the only differentiator) if you also rely on color alone.
Translucent overlays in modal headers that drop the effective contrast below threshold.
Toast notifications with colored text on colored backgrounds — green success on light green is the canonical example.
Form helper text below inputs in #9ca3af. Bump to #6b7280 or darker.

Train one designer and one engineer on these patterns and you'll prevent ~40% of contrast issues at the design-review stage.

What about dark mode?

Most contrast bugs hide in dark mode because designers eyeball it less. Run the same six checks in your dark theme. A typical failure: bright accent colors that worked on white are now too saturated against a near-black background, especially blues and purples that lose perceived contrast on dark surfaces.

If you toggle dark: variants in Tailwind, make sure every text-* color in a component has a corresponding dark mode pair tested against your bg-gray-900 or whatever your dark surface is.

Summary

Color contrast is solved by patterns, not heroics. Fix placeholders, brand buttons, sale tags, disabled states, hero text, and focus rings — you'll close the majority of contrast issues a typical audit will find. Adopt a contrast-aware token set and the issue stops recurring. Re-scan, generate a dated report, and move on to the harder stuff.

Originally published on access-proof.com.

How to Write a VPAT (Accessibility Conformance Report)

Romain — Tue, 19 May 2026 18:23:44 +0000

A VPAT (Voluntary Product Accessibility Template) is the procurement-standard document for declaring accessibility conformance of a software product. Government buyers, large enterprises, and increasingly mid-market customers require one. Here is how to write one that holds up.

What a VPAT is (and is not)

A VPAT is a structured self-disclosure of how your product conforms to specific accessibility standards. It is NOT a certification — there is no certifying body. It is a vendor-issued statement, completed using the ITI/INCITS template (current version: VPAT 2.5 Rev 508, published by the Information Technology Industry Council).

An ACR (Accessibility Conformance Report) is the completed VPAT for a specific product version. The terms are often used interchangeably.

The four standards a VPAT 2.5 covers

Section 508 — US federal procurement (mandatory for federal contracts)
WCAG 2.0 + 2.1 + 2.2 — Web Content Accessibility Guidelines, Level A, AA, AAA
EN 301 549 — EU equivalent (EAA, public sector)
Section 504 — Rehabilitation Act program accessibility

For each applicable criterion across these standards, you declare a conformance level.

The five conformance levels

LevelMeaning

SupportsThe product fully meets the criterion.

Partially SupportsThe product has some support but with known limitations. Remarks must describe them.

Does Not SupportThe product does not meet the criterion.

Not ApplicableThe criterion does not apply (e.g. video criteria on a product with no video).

Not EvaluatedNot assessed (acceptable only for AAA criteria; not acceptable for A or AA).

The five steps to write a VPAT

1. Download the current template

From itic.org/policy/accessibility/vpat. Use VPAT 2.5 Rev 508 (the latest stable version as of 2026). Word format is the standard.

2. Run a thorough accessibility audit

This is the substantive work. Pair automated scanning (AccessProof, axe-core, Lighthouse) with manual review (keyboard navigation, screen reader testing) for every criterion. Automated catches ~30-40%; manual catches the rest.

Document evidence per criterion: WCAG 1.4.3 contrast — link to the AccessProof PDF showing contrast pass. WCAG 2.1.1 keyboard — link to a video or test report.

3. Fill in product details

Product name, version, vendor info, date of evaluation, evaluator info (in-house team, external consultant, or both). Be specific about the product version — VPATs need updates per major release.

4. Complete each applicable table

Three tables to fill: WCAG 2.x, Section 508 chapter 5, Section 508 chapter 6. For each criterion: conformance level + remarks (explanations, especially for "Partially Supports" or "Does Not Support").

Be honest. Procurement teams and disability advocates routinely cross-check VPAT claims against the actual product. False claims of "Supports" damage credibility and legal posture more than honest "Partially Supports" with a remediation timeline.

5. Add remediation plan for known issues

"Partially Supports" criteria deserve a remarks line with the planned fix and target date. This is what procurement teams want to see — not just current state, but trajectory.

Common mistakes

Claiming "Supports" without testing. Procurement teams cross-check.
Outdated VPAT. Updates are needed per major release, at minimum annually.
"Not Evaluated" for AA criteria. Acceptable for AAA only. AA must be assessed.
Missing remarks for "Partially Supports". Always explain.
VPAT for the wrong scope. Each product gets its own VPAT — not the whole company.

How AccessProof fits into the VPAT workflow

AccessProof produces the underlying WCAG audit evidence — timestamped PDF, per-element selectors, criterion-mapped findings — that goes into the WCAG section of a VPAT. Many SaaS teams use AccessProof for the automated portion and pair with a freelance accessibility specialist for manual review on critical flows.

Run a free WCAG audit on your product to see what AccessProof captures. For scheduled scans and PDF archives for ongoing VPAT maintenance, see Starter and Pro plans.

Originally published on access-proof.com.

How to Test Your Website with a Screen Reader (Beginner Guide)

Romain — Tue, 19 May 2026 18:01:41 +0000

You don't need certifications to run useful screen reader tests. 30 minutes with NVDA or VoiceOver will catch issues no automated tool can. Here's how to start.

Setup

Windows: install NVDA (free). Use Firefox — best NVDA compatibility.
macOS: VoiceOver is built in. Toggle with Cmd-F5. Use Safari — best VoiceOver compatibility.
Headphones recommended; the synthetic voice gets fatiguing fast over speakers.

The 5-minute first pass

Load the homepage. Listen to the first announcement: it should give you the page title and a sense of structure.
Tab through every interactive element on a critical page (e.g. product → cart → checkout). Note any control that announces nothing or just "button".
Use the heading shortcut (NVDA: H; VoiceOver: VO + Cmd + H) to navigate by headings. The structure should make sense out of context.
Open a form. Each field should announce its label, current value, and any error state.
Trigger a modal. Focus should land inside the modal; closing it should return focus to the trigger.

Things automated tools miss

Reading order: visually correct ≠ DOM order. A floated sidebar can be read before the main article.
Live regions: cart updates, form validation messages — are they announced?
Custom widgets: tabs, accordions, comboboxes. Most fail because the ARIA pattern is incomplete.
"Skip to content" links: they exist in 60% of sites we audit but only work in 30%.

What to log

For every issue: URL, element selector, what was announced, what should have been announced, WCAG criterion. Keep a running spreadsheet — patterns will emerge (e.g., "every product card swallows the price").

Going further

Once you're comfortable, repeat with mobile screen readers (TalkBack on Android, VoiceOver on iOS). Mobile gestures change everything; many "accessible" sites break on touch.

AccessProof handles the automated scan layer; pair it with this 30-minute manual ritual once per release and you're ahead of 90% of sites.

Originally published on access-proof.com.

Color Contrast in Web Design: The Complete Guide

Romain — Tue, 19 May 2026 18:01:11 +0000

Color contrast is the single most common WCAG failure. Roughly 40% of issues we find on first scan are contrast-related. Here's how to get it right without making your site look like a hospital signage system.

The ratios

Normal text: 4.5:1 against the background (WCAG AA).
Large text (≥18pt regular or ≥14pt bold): 3:1.
UI components (button borders, input outlines, focus rings): 3:1 against adjacent colors.
AAA bumps to 7:1 / 4.5:1 — required in some public-sector contracts.

Common traps

Light grey on white for placeholder text. Almost always fails.
Brand color buttons with white text — many brand greens and oranges fail at 4.5:1 unless darkened.
Disabled states are exempt from contrast rules, but only if the state is unambiguously communicated through other means.
Text on imagery: the contrast must be measured against the actual underlying pixels at the worst spot, not just the average.

Tools

WebAIM Contrast Checker — fastest single-pair check.
Stark (Figma plugin) — runs across an entire frame.
axe-core — analyzes computed styles + image fallbacks at scan time.

Design without sacrificing aesthetics

Build a contrast-aware palette: each accent has at least one paired text color that hits 4.5:1.
Use semitransparent overlays on hero images (e.g. rgba(0,0,0,.4)) before placing text.
For SaaS dashboards: keep secondary text at 4.5:1 minimum, not the trendy 3:1 grey.
Test against your dark mode if you have one — most contrast bugs hide there.

AccessProof flags every contrast violation with the exact node, the computed ratio, and the WCAG level it fails. Fix it and re-scan to confirm.

Originally published on access-proof.com.

Shopify Plus ADA Compliance for Enterprise Stores

Romain — Tue, 19 May 2026 17:56:34 +0000

Shopify Plus stores face the same ADA Title III exposure as regular Shopify stores — and operate at higher transaction volumes, higher visibility, and with more customization. The audit and remediation playbook tuned for Plus merchants.

What changes at the Plus tier

Compared to standard Shopify, Plus adds:

Checkout extensibility (Checkout UI Extensions) — your branding lives in checkout
Custom theme freedom (no plan-tier restriction on Liquid customization)
Multiple storefronts (B2B, regional, brand splits)
Higher SLA, dedicated support, custom integrations

For accessibility, the implication is: more surface area you control, more customization that can introduce bugs.

The recurring Plus-specific issues

Checkout UI extensions accessibility

Plus merchants can inject custom UI into checkout (Cart, Information, Shipping, Payment pages) via Checkout UI Extensions. These extensions render in the Shopify checkout iframe context with Shopify's base UI components — which are themselves accessibility-baselined. But custom logic, error messages, conditional rendering can introduce accessibility bugs.

Multi-storefront accessibility drift

A Plus merchant operating B2B, regional, and brand storefronts often has theme variations per storefront. Accessibility issues fixed in one theme do not propagate. Audit each storefront separately.

Complex custom checkouts (rare, but exists)

Plus merchants with the deprecated checkout.liquid customization face the largest accessibility surface — full checkout HTML control. Migrate to Checkout Extensibility (mandatory by 2026 for new stores) to inherit Shopify's accessibility baseline.

B2B portal accessibility

Shopify B2B portals (customer accounts with B2B features) have a separate UI from the storefront and often less accessibility polish. Audit explicitly.

The audit workflow for a Plus store

List every storefront. Plus merchants often have 3-8 storefronts under one organization. Each gets its own audit.
Audit theme + apps per storefront. Most accessibility issues come from app injections (reviews, upsells, AB testing). Disable apps one at a time on a development store to identify each app's contribution.
Audit Checkout UI Extensions. Each extension renders on the published checkout. Test with keyboard only and a screen reader.
Audit the customer account / B2B portal. The post-login experience needs the same WCAG conformance as the public storefront.
Schedule continuous scans. Plus stores publish frequently (daily price/inventory updates, weekly promotions). Daily AccessProof scans (Pro plan, $79/mo for 25 sites) catch regressions early.

Procurement signal for B2B sales

Plus merchants with B2B businesses face increasing accessibility procurement questions from enterprise buyers — especially government and education customers. An AccessProof PDF audit attached to RFP responses is a positive signal that wins deals.

What changes after a demand letter

For a Plus merchant served with an ADA demand letter:

Engage ADA-defense counsel (specialists exist, often within 24 hours)
Preserve site state at the date of the letter
Run a baseline AccessProof scan on every storefront listed in the letter
Establish a continuous scan cadence post-letter — most cases settle when ongoing remediation is documented

Multi-channel exposure

Plus merchants often sell through additional channels: Shop app, Google Shopping feeds, social commerce, marketplace integrations. ADA Title III primarily applies to the public web storefront, but customer-facing assistive experiences across channels should be audited periodically.

Run a baseline accessibility scan on your Plus storefront — free, no signup, 42 seconds. For multi-store and CI/CD-integrated auditing, see AccessProof Pro and Business plans.

Originally published on access-proof.com.

Accessibility Testing with Playwright (and Cypress)

Romain — Tue, 19 May 2026 17:56:04 +0000

Playwright (and Cypress, and similar e2e tools) can run axe-core against your live app on every commit. The integration is straightforward; the value is catching accessibility regressions before they ship.

Why automated e2e accessibility testing matters

Unit tests check individual components; e2e tests check the whole rendered page in a real browser. Accessibility issues often emerge from the composition (header + main + modal all interacting) — exactly what e2e catches and unit tests miss.

Setting up axe-core in Playwright

Install @axe-core/playwright:

npm install --save-dev @axe-core/playwright

In your test:

import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test('homepage has no critical accessibility violations', async ({ page }) => {
  await page.goto('/')
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22a', 'wcag22aa'])
    .analyze()

  const critical = results.violations.filter((v) => v.impact === 'critical' || v.impact === 'serious')
  expect(critical).toEqual([])
})

Strategies that work

Scan critical pages, not every page

Pick 5-10 representative pages: homepage, signup, dashboard, settings, checkout. Scanning every page on every commit slows CI without finding much extra.

Block on critical and serious only

Default axe categorizes by severity: critical, serious, moderate, minor. Block deploys on critical and serious. Log moderate and minor for backlog grooming.

Scan key user flows mid-interaction

The most interesting accessibility bugs appear after interaction: modal open, form errors visible, dropdown expanded. Tell Playwright to perform the action then scan.

await page.click('button:has-text("Open dialog")')
await page.waitForSelector('[role="dialog"]')
const results = await new AxeBuilder({ page }).include('[role="dialog"]').analyze()
expect(results.violations).toEqual([])

Use disableRules sparingly

Axe has rules you may legitimately disable (e.g. color-contrast on a page intentionally low-contrast for a design demo). Document each disabled rule with a TODO.

What axe-in-Playwright catches

Missing alt text, missing labels, missing accessible names
ARIA validity (invalid roles, required attributes missing)
Color contrast (computed in headless Chromium)
Skipped headings, missing landmarks
Empty buttons / links

What it does NOT catch (use AccessProof for these)

Behavior over time. A scheduled scan that runs daily catches the regression introduced after the e2e suite passes.
Multi-page consistency. CSS or JS changes that affect every page silently.
Real network conditions. Tests run in fixed environments; AccessProof scans production exactly as users see it.
Court-ready evidence. CI logs are not great evidence. A timestamped PDF report is.

Pair Playwright + axe (catch on every commit) with AccessProof (scheduled scans of production + PDF reports). Different layers of the same coverage strategy.

Cypress is the same idea

Use cypress-axe with the same patterns. The API differs slightly but the strategy is identical.

Originally published on access-proof.com.