1) Two layers: what's measured, and what's judged

Every evaluation runs two engines in the same pass. axe-core scans the live DOM and returns deterministic, verifiable violations — a missing alt attribute either exists or it doesn't. Claude never re-evaluates or second-guesses that data. The system prompt instructs it to treat scan results as verified fact and explain them, not judge them. Heuristic evaluation is the opposite case: there's no scanner for whether a page's structure matches user expectations, so that's where the model actually interprets, against the framework described above.

Keeping those two roles separate, rather than asking one model call to estimate everything from a screenshot, is what makes the accessibility tab's citations trustworthy: every WCAG reference on that tab traces back to a real, reproducible scan finding, not a visual guess.

2) Constraining output with a schema

Every response is returned through Claude's tool-use API against a defined JSON schema, not parsed out of free-text. Severity, confidence, and rating fields are all constrained to fixed enums — Critical / Severe / Moderate / Minor, High Confidence / Confident / Suspected / Uncertain — so the model can't drift into inconsistent wording across evaluations, and the frontend never has to guess what shape a response will take. This is a trust decision as much as an engineering one: a badge system only works if the vocabulary behind it is actually fixed.

Confidence tagging is deliberately scoped to heuristic findings only. Accessibility findings come from a deterministic scan and are already verified fact — a confidence badge there would just be noise. The distinction between "measured" and "interpreted" is made once, structurally, rather than repeated on every card.

3) When the schema wasn't enough on its own

A schema constrains the field type, not necessarily the exact word choice inside it. axe-core labels one of its own severity levels "serious." Despite the prompt and the schema enum both instructing the model to report that as AUGUR's own "Severe" label, the raw word occasionally leaked straight through into the badge. The screenshot alongside this is that bug, live, from mid-build testing.

The fix wasn't a bigger prompt — it was a second, independent layer: a small server-side normalization step that remaps any known alias before the response ever reaches the frontend, plus a client-side fallback style so that any future unrecognized value degrades gracefully instead of rendering an invisible badge. Prompting for correctness and verifying it in code aren't the same thing, and this is the specific case that proved it.

4) Making confidence show its work

A badge alone is still just a rating with no reasoning attached. "Suspected" tells a reader the model isn't fully sure, but not why — and a confidence label that can't explain itself is asking to be trusted on faith. Every confidence badge now carries a required one-sentence explanation underneath it: whether the finding is something directly visible in the screenshot, or an inference about intent or composition that can't be verified from the image alone. It's a small addition to the schema, but it turns confidence from a static rating into a piece of reasoning a reader can actually check against the evidence.

One related wording change alongside it: the Uncertain badge now reads "Uncertain: needs review" — display-only, done in the badge-rendering component via a small lookup table, so the underlying value, schema, and styling keys are all untouched. A lone word doesn't obviously suggest what to do with it; a short phrase does.

1) The empty state teaches first

Most of AUGUR's likely first-time visitors won't know what "heuristic evaluation" means, or why WCAG 2.2 specifically. A tool built on AI judgment has an extra burden most tools don't: explaining why its output should be trusted before it's produced any. The pre-submission state isn't a blank placeholder. It's a short, plain-language explanation of both frameworks and why each was chosen, written to be read before a single URL is entered.

2) An honest loading state

A real evaluation launches a browser, screenshots the live page, runs a full accessibility scan, and waits on a Claude response — realistically tens of seconds, not milliseconds. Rather than a generic spinner, a slow cross-fading sequence of phrases keeps the wait legible and on-brand, timed deliberately (a slow fade in, a long hold, a slow fade out) so it reads as considered rather than anxious.

3) One component system behind every card

Every card in the interface is a Figma component built on the same token set the app's CSS uses directly. The header bar's color and icon are driven entirely by the severity or rating value, so a "Critical" issue and an "Excellent" working-well finding are visually unmistakable from across the room, not just on close reading. Two card types share the same shell: an issue card (severity, description, recommendation) and a working-well card (rating, confidence) — different content, same visual grammar.

Testing against sites designed to break assumptions

A novelty single-purpose site answers one question and nothing else — exactly the kind of page a rigid rubric might penalize for "missing" navigation or content it was never meant to have. AUGUR's evaluation of a one-word answer site correctly identified it as, arguably, one of the most efficient websites in existence: question in, answer out, zero clicks required. It didn't ding the page for the empty nav it was never going to need. Recognizing restraint as a legitimate design choice, not a deficiency, is a genuinely harder judgment call than flagging an actual violation. A blank, single-color page is the opposite stress test: confirming the tool reports "nothing here to evaluate" honestly, rather than inventing plausible-sounding findings to fill space.

What broke only in production

The gap between "works locally" and "works deployed" showed up hard on first launch. Vercel's build silently dropped the accessibility scanner's script file. It's read via a runtime-constructed path rather than a static import, deliberately, to route around a separate Next.js dev-bundler bug. But that meant the build's automatic file tracing couldn't detect it as a dependency, so it never shipped. Fixed by explicitly declaring the file in next.config.js, confirmed by inspecting the actual build trace manifest rather than guessing.

The next deploy broke differently: Vercel has no browser pre-installed at all, and the serverless-Chromium package's bundled binary — 64.8MB on its own — silently exceeded the platform's function size limit. The fix was a variant of that same package that downloads its binary from a hosted release at cold start instead of bundling it. A third, harder-to-see bug followed once that was live. Warm serverless containers get reused across requests, so Chromium's default profile directory was never cleaned up between invocations, intermittently crashing the browser mid-navigation. Traced to a documented issue in the library itself, and fixed by giving every invocation its own disposable profile directory.