How should a Shopify store write up accessibility findings so developers actually fix them?
Developers fix findings they can reproduce in under a minute and ignore findings they cannot. The writeup is the difference. Every accessibility finding should follow the same five-line format: where it is, what is wrong, how to reproduce it in one minute, what the fixed state looks like, and which standard it violates. Anything longer gets skimmed; anything vaguer gets deprioritized.
Write for the fixer, not the buyer
Most accessibility reports are written for the person who paid for the audit: executive summary, risk language, conformance tables. That report then gets forwarded to a developer who needs something completely different. The fixer's question is narrow: what exactly do I change, and how do I know when it is right. If the writeup does not answer that in the first screen, it will sit in the backlog until the next audit rediscovers it.
This does not mean dumbing the findings down. It means structuring them for action. Keep the executive summary for the buyer, but give every finding its own self-contained writeup that a developer can act on without reading the rest of the report. The best audits produce findings that work as tickets.
The five-line finding format
Use the same five lines for every finding, in the same order. One: location, the exact page and element, with a URL and a selector or a description precise enough to find it. Two: the problem, in one sentence of plain language, saying what a user experiences. Three: reproduction, the shortest path to see it yourself, ideally under a minute with a keyboard or a free tool. Four: the fix, what the correct state looks like, with a concrete example. Five: the standard, the WCAG criterion it violates, so the fixer knows this is not a preference.
The discipline of the format matters more than the content of any single finding. When every finding looks the same, developers learn to scan them fast, estimate effort fast, and trust that nothing is hidden in paragraph three. Consistency is a kindness to the person doing the work.
Reproduce in one minute or it gets skipped
The reproduction step is the whole game. "The mobile menu is not keyboard accessible" is a claim. "Open the site, press Tab until you reach the menu button, press Enter, then press Tab again: focus disappears into the page behind the menu" is a finding. The second version takes forty seconds to verify, and a developer who verifies it is halfway to fixing it. Time the reproduction yourself before writing it down. If it takes you three minutes, simplify it.
Include the environment when it matters: browser, viewport, assistive tech. "Fails in Safari with VoiceOver" is different from "fails everywhere," and the fixer needs to know which. But do not pad with environment detail when the issue is universal. Precision, not volume.
Show the fix, not just the failure
A finding that describes the problem without describing the solution pushes the design work onto the developer, who will then guess, often wrongly. For each finding, state what the fixed state looks like in concrete terms: "the button needs an accessible name, for example aria-label='Close menu', and focus must move into the menu on open." If there are two acceptable fixes, say so and name the simpler one first. Developers under time pressure take the first clear path.
Link to one good reference per finding, not five. The WCAG understanding page for the criterion is usually enough. A link farm signals that the auditor was unsure. One link signals confidence.
Rank by user impact, then by legal risk
Order the findings the way the fixer should work through them. User impact first: anything that blocks a core task, checkout, account creation, product discovery, goes to the top. Then legal risk: issues that commonly appear in demand letters, like missing form labels or inaccessible modals. Then everything else. Say this ordering explicitly at the top of the report so nobody has to guess why finding 3 outranks finding 12.
Separate the quick wins into their own section. Findings fixable in under an hour, a missing alt attribute, a contrast tweak, a label addition, should be listed together at the top. Teams that clear the quick wins in week one build momentum for the hard fixes in week four. Burying them in a 60-finding list guarantees they wait just as long as the hard ones.
Keep the audit trail short
Every finding should record three dates: found, fixed, verified. That is the audit trail. It does not need screenshots of every state, though one screenshot of the failure helps. It does not need a narrative of the fix. Found, fixed, verified, with the verifier named. When the next audit runs, this trail is what prevents re-litigating the same findings, and when a demand letter arrives, it is the evidence that the store takes this seriously.
Finally, write the report so it can be re-run. Note the pages tested, the tools used, the assistive tech versions. A writeup that lets next quarter's auditor test the same pages the same way turns each audit into a measurement instead of a surprise. That is the real goal: not a perfect report, but a repeatable one.