The accessibility handoff: what agencies owe merchants at headless launch

A proper accessibility handoff at headless launch includes a dated test report covering the critical customer journeys, a list of known issues with owners and timelines, documentation of the accessible patterns the build uses, and monitoring wired into the deploy pipeline. Most agencies hand over the site and a verbal "it should be accessible." That is not a handoff; it is a liability transfer.

Why the handoff matters more on headless

On a standard Shopify theme, the platform carries much of the accessibility weight: the theme vendor tested the cart drawer, the form labels, the focus behavior. Going headless removes those guardrails. Every interactive pattern in a custom storefront was built by hand, which means every one of them can break in ways the theme would have prevented.

The merchant rarely knows this. They paid for a faster, more flexible storefront and assume accessibility came along with it. Six months later, a demand letter arrives citing the custom mega menu and the quick-add drawer, and the merchant discovers that the agency never tested either. The fix cost at that point is a retrofit, which runs multiples of what testing during the build would have cost.

What the handoff should contain

First, a dated accessibility test report tied to the launch commit. It should cover the journeys that make money and attract claims: homepage navigation, search, product page with variant selection, cart, checkout entry, account forms, and the mobile menu. For each journey, record what was tested, how (automated, keyboard, screen reader), and the result. A report that says "tested" without saying how is not evidence.

Second, a known-issues register. No launch is perfect, and pretending otherwise destroys trust. List each known issue with its WCAG criterion, its severity, who owns the fix, and the timeline. A merchant who knows about three medium-severity issues with fix dates is in a defensible position. A merchant who knows nothing is not.

Third, pattern documentation for the custom components. The quick-add drawer, the variant picker, the filter panel, the promo modal: for each one, document the intended keyboard behavior, focus management, and announcement behavior. This is what the merchant's future developers need to avoid breaking things, and it is the documentation that almost never exists.

Fourth, monitoring wired into the pipeline. The agency should leave the merchant with automated checks running on deploys and a production crawl on a schedule, not a recommendation to "keep an eye on it." Accessibility degrades with every release; the handoff should include the system that catches the degradation.

What merchants should ask for in the contract

Put the handoff in the statement of work before the build starts. Specify the journeys to be tested, the assistive technologies to be used, and the deliverables: report, issue register, pattern docs, monitoring. Name the WCAG conformance target explicitly, and define what happens to issues found during the build: which severity blocks launch and which can ship with a fix date.

The clause that matters most is the remediation window. A 30 to 60 day period after launch during which the agency fixes accessibility defects found by the merchant or by monitoring, at no extra cost, aligns incentives. Without it, the agency's incentive is to declare victory at launch and invoice the fixes as change requests.

What agencies gain from doing this well

Agencies resist the handoff because it looks like scope creep. In practice it is the opposite: documented testing and a known-issues register are the strongest defense an agency has when a client gets a demand letter. "We tested these journeys on this date with these results" ends the blame conversation before it starts. Agencies that hand off properly also win the monitoring and remediation work, because they are the team that understands the build's accessibility architecture.

The headless market is maturing, and accessibility is becoming a selection criterion in RFPs rather than an afterthought. The agencies that can show a real handoff process will win the enterprise deals. The ones still handing over a site and a shrug are selling a liability with a pretty frontend.