Machine translation. This article was translated automatically from German into English and has not been reviewed. Read the German original.
The problem: AI copies the average
A language model has seen millions of websites as training material – and learned from them what “normal” code is. The problem: normal is not the same as good. The good news: you can correct this with a few lines in your project, before the first line of code is written.
Who is this article for?
For everyone who develops with AI support – whether a whole website or individual components – and wants accessibility and findability to be right from the start, instead of being patched up at the end.
How good is the average?
On the web, clickable div elements outnumber real buttons,
form fields have a placeholder instead of a label, and focus outlines have
been removed by someone for design reasons. That is exactly what an AI
reliably reproduces if you give it no other rules.
This is not a fringe problem: the WebAIM Million – an annual study of the most visited websites – finds automatically detectable failures of the accessibility guidelines (WCAG) year after year.
of the home pages tested have detectable failures – and that year after year.
compared with 2025 – in the 2026 report the figures rise again for the first time in years, instead of falling.
WebAIM Million, 2026 report (External link, opens in a new window)
If you let an AI build without rules, you will very likely get exactly this average delivered along with it – errors included.
WebAIM itself names the growing use of automated and AI-assisted coding as one possible reason for the rise. A circle that closes: the AI learns from faulty code, uses it to produce faulty code itself – and sooner or later that code ends up on the web again as training material.
The solution: a rules file instead of a prompt
The obvious first thought is to say it in the chat: “Please make it accessible.” The problem: this instruction only applies to this one conversation. In the next chat, in a new session, or when a colleague uses the same AI, you start from scratch again.
A file in the project directory solves this. It is read automatically in every conversation, by every tool and every person on the team – you do not have to mention it a second time. Depending on the AI tool, it is called:
CLAUDE.md(Claude Code)AGENTS.md(a widespread standard, used by Codex among others).github/copilot-instructions.md(GitHub Copilot)- or a rules file directly in the editor
Chances are that you already have a file like this in your project if you develop with AI – many tools now create one automatically as soon as a project is set up. Just a few targeted additions, like in the example further down, are enough to make the generated code many times better.
Once written, the file applies to the whole project – whether you use it to set up a website from scratch or only to improve individual components.
Two guidelines so that the rules actually work
1. Numbers instead of adjectives. “The focus should be clearly visible” is not a requirement but a hope – the AI interprets “clearly visible” at its own discretion. “Focus outline 3 px, offset 2 px”, on the other hand, is unambiguous: testable, repeatable, non-negotiable. The same applies to the goal as a whole: not “accessible”, but specifically WCAG 2.2 level AA.
2. Prohibitions work better than wishes. Because more than 90 per cent of the examples in the training material are faulty, a positive request is often not enough to counter them. “Accessible forms, please” leaves the AI a lot of leeway. “No placeholder as a label” rules out exactly the one pattern that would otherwise reliably turn up. A clear prohibition beats the training data – a vague request usually does not.
A reference the AI can consult itself
For details, it is worth looking at the Website Specification (External link, opens in a new window) – a freely available reference work with around 170 topics in ten categories: basics, SEO, security, accessibility, performance, privacy, multilingual sites and more.
Through the MCP server mcp.specification.website, your
AI assistant can query this reference directly itself instead of
guessing. A single line in your rules file is all it takes – see the
template below.
The finished template to copy
Put the content into your project directory as CLAUDE.md or
AGENTS.md, or add it to an existing file. Only the last section
is yours to fill in. The template is in English, like the code it refers
to.
# Project rules
## Target level
WCAG 2.2 level AA.
## Markup
- Semantic HTML first. ARIA only where no element does the job.
- Focus ring 3px, offset 2px, on every operable element (2.4.11).
- Targets at least 24 × 24 px, aim for 44 × 44 px (2.5.8).
- Visible label with for/id, plus autocomplete. A placeholder is not a label (1.3.5).
- Validate on submit only. Error summary on top, links to the fields,
aria-describedby (3.3.1).
- alt test: is information lost without the image? If not, alt="".
- Colour never carries information on its own (1.4.1). Contrast 4.5:1 / 3:1.
- Motion behind prefers-reduced-motion (2.3.3).
- No sideways scrolling at 320px, no loss of text at 200% zoom (1.4.10, 1.4.4).
- Headings form the outline. Never skip a level.
## SEO
- canonical points at the page itself, never at the main language version.
- hreflang reciprocal, including self and x-default.
- Own title and own description per page, following a fixed pattern.
- URLs are a promise. Move them only with a 301 — with and without .html.
- Indexing explicit: public pages indexable, previews noindex.
- JSON-LD only for facts that are visible on the page.
## Never
- <div onclick> where a <button> belongs
- outline: none without an equivalent replacement
- positive tabindex
- aria-label on an element that already has a visible name, or differing
from it (2.5.3)
- "here" and "read more" as link text
- status, warning or severity by colour alone
- fonts from the Google CDN — self-host them (GDPR)
- CAPTCHA — honeypot plus a server-side filter
- extra libraries without asking
## Sources
- Normative: WCAG 2.2, w3.org/TR/WCAG22
- Implementation: Website Specification, via MCP at mcp.specification.website.
Before every new page template: fetch the accessibility/required checklist.
## Project-specific
This is where everything goes that nobody can guess. For example:
- No hero images. Every page starts with text.
- Language and tone of voice, matching the lang attribute.
- Use elements which already exist.What the individual sections mean
A quick walk through the template, so that it is clear what is behind it.
Target level
Sets the shared goal that all the following points refer to. Level AA is the one that can realistically be reached for a whole website – the highest level, AAA, practically never in full. And the version explicitly belongs with it: without a version number, an AI will go by some older one, and the new criteria of version 2.2 quietly fall by the wayside.
Markup
The basic technical rules. The number in brackets refers to the matching WCAG 2.2 success criterion, in case you want to look it up:
- Semantic HTML first, ARIA only where needed – use
real elements such as
<button>or<nav>instead of rebuilding everything with<div>and ARIA attributes. - Focus outline 3 px, offset 2 px (2.4.11) – without a visible focus, a page can hardly be used with the keyboard.
- Click targets at least 24 × 24, better 44 × 44 px (2.5.8) – important for touch operation and limited fine motor skills.
- Visible label instead of placeholder (1.3.5) – placeholder text disappears while typing and is often ignored by screen readers.
- Validation only on submit, error summary on top (3.3.1) – live validation while typing interrupts the flow of writing, especially with a screen reader.
- alt test – only images that carry information need
alternative text; purely decorative ones get
alt="". - Colour never carries information on its own (1.4.1) – important for colour vision deficiencies, for example with required fields or status indicators.
- Motion behind
prefers-reduced-motion(2.3.3) – anyone who has set reduced motion gets no forced animations. - No sideways scrolling at 320 px, no loss of text at 200 % zoom – the page has to stay usable on small screens and at high magnification.
- Headings form the outline – screen reader users often jump straight from heading to heading, and a skipped level makes that unreliable.
SEO
Records the points that most often go wrong when an AI builds a multilingual or multi-page website:
- duplicate or missing
canonicalandhreflangtags - copied page titles
- URLs that are moved without a redirect
- unclear indexing
- structured data (JSON-LD) that does not match the visible content
Never
The list of patterns that most reliably turn up from the training
material unless they are explicitly prohibited – from the clickable
div instead of a button and removed focus outlines to embedding
Google Fonts, which as a CDN request is a GDPR issue. A prohibition is
deliberately worded more simply here than an explanation of why – that
would only bloat the file.
Sources
Tells the AI where to look things up instead of guessing: WCAG 2.2 as the normative text, and the Website Specification via the MCP server for the concrete implementation – including the instruction to fetch the accessibility checklist before every new page template.
What belongs in the last section
The Project-specific section looks inconspicuous, but has a
big influence on the result. This is where everything goes that applies
only to your project and cannot be guessed.
In mine, for example, it says “No hero images” – without this line, practically every AI will reliably suggest a full-screen header image, because that has been common practice for years.
Small additions to your MD file that pay off
From my own experience: even with these few lines I got really good results. Combined with the MCP server of the Website Specification and the hard rules on top, it leaves the average website behind and turns it into a “better” website.
By now there are countless accessibility skills and extensions for AI tools on the web – but anyone who does not work on accessibility full-time cannot possibly test them all in this jungle.
My tip for everyone who lets an AI help them build a website: add at least a rules file with these few points – that alone makes the result a good deal better.
That still leaves the checking: what can the AI test itself for accessibility and SEO – and what remains manual work? More on that in the next article.
Sources: W3C, Web Content Accessibility Guidelines 2.2 (External link, opens in a new window) · The Website Specification (External link, opens in a new window) · WebAIM Million (External link, opens in a new window).