A Practical Guide to WCAG 2.2 Compliance When Using AI-Generated and Vibe-Coded Websites
 |
Look at that, they’ve finally given the AI an intelligence upgrade—it’s building things we can actually use! |
In the earlier article on this blog, the argument was made that AI coding tools — when used carelessly or under pressure — tend to reproduce the same patterns of inaccessibility that already exist on the web. They learn from what is out there. What is out there was mostly built without disabled users in mind. So the output carries the same bias forward, often faster than before.
That article explained why the problem exists. This one is about what to do instead.
The good news is that you do not have to wait for the tools to improve on their own. You can intervene. You can set conditions, write better prompts, configure your tools differently, and build habits into your workflow that make accessibility the default outcome rather than an afterthought. This is possible even if you are relatively new to web development. In fact, if you are just starting out, this is the right time to build these habits. It is far harder to unlearn poor practice than it is to start correctly.
This guide walks through the main steps. It focuses on WCAG 2.2 compliance, which is the current standard published by the World Wide Web Consortium. The four principles of WCAG are Perceivable, Operable, Understandable, and Robust. These are sometimes abbreviated as POUR. Keep that word in mind. It is a reasonable test to apply to anything you build.
Step One: Set Up Your Prompt as a Standing Instruction
Most AI coding tools allow you to write a system prompt, a custom instruction set, or a project-level configuration that gets applied to every request in a workspace. This is not a feature that most new developers use for accessibility. It should be the first thing you configure.
Before you write a single line of code, open the settings for your workspace or project and add a standing instruction along the following lines:
"All code you generate for this project must comply with WCAG 2.2 at Level AA. Every image must have a meaningful alt attribute, not a placeholder such as 'alt' or 'image'. Every interactive element must have a visible label and an accessible name. Headings must follow a logical order: one H1 per page, H2 for sections, H3 for sub-sections. Do not skip heading levels. Forms must associate every input with a label element using a 'for' attribute that matches the input's 'id'. Colour contrast must meet a minimum ratio of 4.5 to 1 for normal text and 3 to 1 for large text. All functionality must be operable by keyboard alone."
The important point is that this instruction must be present before you begin. If you add it later, you will spend considerable time correcting code that was already generated without it.
Step Two: Write Accessibility Requirements Into Every Prompt
The standing instruction sets a baseline. But it is not enough on its own. Research from the CHI Conference on Human Factors in Computing Systems has shown that developers using AI coding assistants regularly forget to request accessible output for individual components, even when they intend to follow good practice. The tool does not remind you. You have to remember.
The practical solution is to develop a habit of ending every prompt with an accessibility check. If you are asking the tool to generate a navigation menu, do not just describe the visual layout and the links you want. End the prompt with: "Ensure this component is fully keyboard-navigable, uses appropriate ARIA roles where HTML semantics are insufficient, and includes visible focus indicators on all interactive elements."
If you are generating a form, add: "Associate every label with its input using matching 'for' and 'id' values. Mark required fields in a way that does not rely on colour alone. Provide clear error messages that are programmatically associated with the relevant input using 'aria-describedby'."
If you are generating a modal or dialog, add: "The dialog must trap keyboard focus while it is open. It must return focus to the triggering element when it closes. It must be dismissible using the Escape key."
These additions cost you perhaps ten to twenty seconds per prompt. What they save is the time required to fix inaccessible output after the fact, which is considerably longer and considerably more difficult when the structure of the component is already set.
Step Three: Do Not Accept Generated Code Without Reading It
This is the step that vibe coding skips entirely. Vibe coding means you describe what you want, the AI produces code, and you paste it in. It is fast. It is also how inaccessibility gets embedded into production code at scale.
Research by Mowar and colleagues from 2024 found that developers consistently accepted AI suggestions without checking them. They accepted placeholder alt text without replacing it, heading structures that were out of order, and forms without labels. These failures are not obscure. They are visible in the code itself, provided you read it.
Develop a short review checklist to run through every time you accept generated code. Five checks will catch the most common failures.
First: look at every image tag. Is there an alt attribute? Does the alt value describe what the image actually shows? If the image is decorative, the alt value should be empty: alt="". It should not say "image" or "photo" or be absent altogether.
Second: look at the heading tags. Is there only one H1? Do the headings descend in logical order? An H3 should not appear before an H2 has introduced the section it belongs to.
Third: look at every input element in any form. Does each one have a label element? Does the label's 'for' attribute match the input's 'id'? A placeholder attribute is not a label. It disappears when the user starts typing.
Fourth: look at every button and link. Does each one have text or an accessible name that describes what it does? A button that says "Click here" or a link that says "Read more" tells a screen reader user nothing about where the link goes or what the button does.
Fifth: look at any use of colour to convey information. If something is shown in red to indicate an error, is there also a text label or an icon that conveys the same information? Colour alone is not a sufficient signal.
This review takes two or three minutes for a typical component. It is not a burden. It is the difference between producing something that works for everyone and producing something that works only for some.
Step Four: Configure Automated Checking Into Your Build Process
Manual review is necessary. It is not sufficient. Some accessibility failures are structural and not immediately visible by reading the code. Colour contrast ratios, for instance, require a calculation. Focus order depends on the rendered DOM, not the source code. ARIA relationships can be technically present but logically broken.
Automated accessibility checkers can catch a significant portion of these issues before anything reaches a user. The most commonly used tool is axe-core, available as a browser extension and also integrable into build processes for projects using Node. Another widely used option is the WAVE browser extension from WebAIM. Both are free.
If you are building with a framework such as React or Vue, linting tools can flag accessibility problems in real time during development. For React, eslint-plugin-jsx-a11y is the standard choice. It will flag missing alt attributes, improper ARIA usage, and other common violations as you write.
The limitation of automated tools is important to understand. They typically catch around thirty to forty per cent of WCAG failures. A tool can tell you whether an alt attribute is present. It cannot tell you whether the alt text is meaningful. Automated tools are a floor, not a ceiling.
Step Five: Test With a Screen Reader Before You Publish
This step is skipped more often than any other. It should not be. A screen reader test reveals problems that code review and automated tools both miss, because it shows you how the page actually behaves in use.
NVDA is a free screen reader for Windows. VoiceOver is built into macOS and iOS and needs no installation. Turn the screen reader on, navigate using only the keyboard, tab through the interactive elements, use the heading navigation shortcut to move through the page structure, fill in a form, and activate a modal. Note anything confusing, missing, or out of order. Fix it before publishing.
You can also ask your AI tool to review code from a screen reader perspective. A prompt such as "Review this component and identify elements that a screen reader user would find confusing or inaccessible" will often surface problems a general review misses. It is not a substitute for testing with an actual screen reader. It is a useful intermediate step.
Step Six: Handle Colour, Motion, and Cognitive Load
WCAG covers more than headings and labels. Three areas that AI-generated code frequently handles poorly are colour contrast, motion, and reading complexity.
For colour contrast, use a tool such as the Colour Contrast Analyser from TPGi or the contrast checker at WebAIM.org. Enter the foreground and background colours your code uses and check that the ratio meets the WCAG 2.2 requirement. If your AI tool generates CSS with colour values, check those values before accepting the suggestion. Light grey text on a white background is an extremely common failure in AI-generated designs.
For motion, any animation that plays automatically and lasts more than five seconds must have a mechanism to pause, stop, or hide it. This is a WCAG 2.2 requirement. More importantly, it is a genuine problem for people with vestibular disorders, epilepsy, and certain cognitive differences. When generating animations or transitions, add to your prompt: "This animation must respect the user's 'prefers-reduced-motion' media query setting. If the user has set their system to reduce motion, the animation should not play."
For reading complexity, consider the plain language of any text you generate alongside your code. WCAG 3.1 requires that the language of a page is identified in the HTML. More broadly, content that is written in unnecessarily complex language excludes users with cognitive differences, users for whom English or Hindi or whichever language the site uses is not their first language, and users who are reading under stress or fatigue. Ask your AI tool to generate content at a reading level that is clear and direct. Check it yourself before publishing.
The Broader Point
Accessible code is not a special category of code that you add at the end of a project. It is good code. It is code that has been built with an accurate understanding of who uses the web. That understanding includes people who navigate by keyboard, people who use screen readers, people who cannot distinguish between certain colours, people who experience seizures, people who process information differently, and people who are using older or lower-specification devices.
In India, these are not edge cases. The official count of persons with disabilities in the country is over 26 million, and independent assessments suggest the real number is considerably higher. Under the Rights of Persons with Disabilities Act 2016 and under Article 9 of the UNCRPD, which India ratified in 2007, there is a clear legal framework that places the obligation for accessible digital services on the organisations that provide them.
If you are building a website, you are providing a digital service. If that service is inaccessible, the person who cannot use it has not merely been inconvenienced. They have been excluded from something to which they have a right.
AI tools can help you build accessible websites. They can also make it very easy to build inaccessible ones very quickly. The difference is almost entirely in how you use them. Set the right instructions, write the right prompts, read the code you accept, run the checks, test with a screen reader, and fix what you find. None of this requires advanced expertise. It requires the decision to make it a habit.
Start with that decision. The rest follows.
