First Lap: Prompting for Accessibility Checks in HTML

What a model can spot in raw HTML

When you ask an AI model to check accessibility, you are handing it markup rather than a screenshot. That one fact shapes everything else in this guide. A model reads tags, attributes, roles and text, so the wins come mostly from problems written into the markup itself. Missing alt attributes, empty buttons, inputs without labels, headings that skip a level, and links that all say 'click here' are exactly the kind of issue a model can see on the page source.

The markup checks a model handles well usually include:

• Alternative text that is missing, empty for meaningful images, or stuffed with filenames.
• Heading order that jumps from an h2 to an h5 or hides the real structure inside styled divs.
• Names for links and buttons, so a control still makes sense when it is read out of context.
• Form labels properly tied to their inputs, including groups such as radio sets and checkboxes.
• Landmarks and page basics such as the lang attribute, a descriptive title, and clear main and nav regions.
• ARIA misuse, such as roles that fight native HTML, or aria attributes pointing at ids that do not exist.
• Tables and lists built with real th, caption, ul and li elements instead of styled layout markup.

What the model sees poorly is what it cannot render. Colour contrast, visible focus rings, animation timing and the feel of tab order live in the finished page. So add a note to every check asking the model to flag anything that needs a human eye or a real screen reader, and then go and look at those items yourself.

Set the scene before you ask for findings

A vague prompt gets vague findings. Give the model the standard, the scope and the output format before it judges anything. A solid starting prompt looks like this: 'Review the HTML below against WCAG 2.2 Level AA. Focus only on markup. List each issue with the element, a plain-language description, a severity of high, medium or low, and a corrected snippet. Quote the attribute that causes each issue. Do not report problems that are not visible in the markup.'

Then add the context only you have. Tell the model what the page is for, since a checkout flow and an article have different risks. Say which images are decorative. State the page language. If you already know a library injects markup at runtime, mention that so the model does not chase a phantom gap.

Ask for one list with one entry per issue, in severity order. That turns the reply into a work queue you can tick off, instead of a wall of prose you have to parse. If the file is large, run the check one component at a time, or ask for issues inside a single section, so nothing gets summarised away.

You can point that prompt at whichever model you prefer. SwiftRelay is a pay-as-you-go relay for Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok and other models, and it works with Claude Code, Codex, Gemini CLI and any OpenAI-compatible SDK. Claude Code and Gemini CLI take the bare host, https://api.fastapirelay.com, while OpenAI-style SDKs add /v1 to it. New accounts get a small gift credit, inviting friends earns 14% of their top-ups, and billing is per token. Sign up for SwiftRelay and run your first accessibility pass in minutes.

Prompts for the checks newcomers miss most

Once the general pass is done, run short, focused prompts for the details that quietly fail audits. Each prompt below assumes you paste the relevant HTML under it.

• Alt text: 'For every img element, explain what the alt text should describe, and mark which images should use an empty alt attribute because they are decorative.' The empty alt is a valid, deliberate choice, and models are good at naming which images qualify.
• Link and button names: 'List every anchor and button whose accessible name would be unclear to someone hearing it out of context, and rewrite the text.' This catches the repeated 'read more' links that all sound identical.
• Form fields: 'Check that every input, select and textarea has a label associated with it, that grouped controls use fieldset and legend, and that required fields are announced in text as well as in markup.'
• Headings: 'Give me the outline this page would read as, one heading per line, and mark any level jumps or headings used only for visual sizing.'
• ARIA and focus: 'Point out ARIA that is unnecessary, aria-label values that contradict visible text, positive tabindex values, and any interactive element built from a div or span.'
• Tables and lists: 'Check that data tables have th cells with scope, a caption where it helps, and no layout tables, and that lists use real ul, ol and li elements.'
• Page basics: 'Verify the lang attribute, the title, one main landmark, a skip link target, and that headings and landmarks do not repeat confusingly across the page.'

Keep these prompts in a file beside your project. Reusing the exact same wording each time makes the results comparable from one run to the next.

Separate real problems from model guesses

Models are generous with warnings, and some of them are wrong for your page. A checker may flag an image that is genuinely decorative, ask for captions on a table that holds layout data, or suggest extra ARIA where plain HTML already announces the control correctly. Treat every finding as a lead to check, not a verdict.

Ask for evidence. A follow-up prompt such as 'For each issue, quote the exact attribute or line that causes it, then state what you would need to see rendered to confirm it' pulls the reasoning into the open. When the model cannot name the attribute, the finding is often a habit rather than a problem.

Fix what is real, then run the original prompt again on the corrected markup and compare the two lists. Good signs are a shorter list and no new high severity items. If a finding keeps reappearing after you fixed it, read the element yourself before changing code again.

Nothing replaces the ground truth. Walk the page with a keyboard only, listen to part of it with a screen reader, run an automated scanner such as axe or Lighthouse, and, when you can, watch someone use the page. The model narrows the search; people confirm it.

A short checklist before the green light

Use this as your pit stop list before you ship a page or a component.

• Every meaningful image has accurate alt text, and decorative images use an empty alt attribute.
• Headings form a logical outline, one h1 on the page, and no level skipped for style reasons.
• Every link and button has a unique, descriptive accessible name.
• All form inputs have labels, groups have legends, and errors are described in text next to the field.
• Landmarks, the lang attribute, the title and a working skip link are in place.
• ARIA only appears where native HTML cannot do the job, and all aria targets exist.
• Tables use header cells and captions, lists use real list markup, and no layout is faked with tables.
• The whole flow works with the keyboard, and focus is visible and moves in a sensible order.
• Contrast and focus styling have been checked in the rendered page by a human.

Two models make a good pairing for this work. Claude Sonnet 5.5 is helpful when you want clear explanations and careful rewrites of alt text and labels, and Gemini 3.1 Pro is a useful second reader when you want a fresh opinion on the same markup. Run both, keep what holds up under manual checks, and keep your prompts in version control next to the HTML they review. That habit turns accessibility from a one-off scramble into a normal lap in every sprint.