Toegankelijke code met Cursor, Claude Code en andere…

Codeerassistenten zoals Cursor, Claude Code, GitHub Copilot en Windsurf werken in je eigen codebase. Ze lezen je bestanden, voeren commando’s uit en stellen wijzigingen voor die jij nakijkt. Dat geeft je meer controle dan een sitebouwer in een chatvenster, maar het betekent ook dat toegankelijkheid van hetzelfde afhangt als de rest van je codekwaliteit: duidelijke regels, automatische controles en een menselijke review. Deze gids is voor ontwikkelaars en behandelt alle drie, plus het controleren van het gepubliceerde resultaat met ibin.

Wat codeerassistenten vaak fout doen

Assistenten kopiëren de patronen die ze zien, in je codebase en in hun trainingsdata. Het grootste deel van het web is niet toegankelijk: de analyse van WebAIM uit 2026 van een miljoen startpagina’s vond op 95,9% ervan automatisch detecteerbare fouten. Typische resultaten zonder regels:

Een div of span met een onClick-handler in plaats van een button, waardoor je hem niet met het toetsenbord bereikt.
Knoppen met alleen een icoon en zonder toegankelijke naam, zodat een schermlezer (software die het scherm voorleest) alleen “knop” zegt.
outline: none om een focusrand weg te halen die de ontwerper niet mooi vond, zonder vervanging.
Eigen keuzelijsten, comboboxen en modale vensters van nul opgebouwd, zonder toetsenbordondersteuning of focusbeheer.
ARIA-attributen om een probleem op te lossen dat een native element nooit had gehad. Verkeerde ARIA is vaak erger dan geen.
Hardgecodeerde kleuren die je design tokens omzeilen en niet genoeg contrast halen.
Routewissels aan de clientkant waarbij documenttitel en focus blijven staan waar ze waren.

Waar de regels staan per tool

Elke tool heeft een bestand dat hij aan het begin van een taak leest. Kijk in de documentatie van je tool, want deze locaties veranderen.

Cursor: projectregels zijn .mdc-bestanden in .cursor/rules, met frontmatter die bepaalt wanneer ze gelden. Gebruik alwaysApply: true voor regels die in elke chat moeten tellen. Cursor leest ook AGENTS.md als alternatief in gewone markdown. Zie de documentatie over rules van Cursor.
Claude Code: CLAUDE.md in de hoofdmap van het project (of .claude/CLAUDE.md), geladen aan het begin van elke sessie. Is er geen CLAUDE.md, dan leest Claude Code AGENTS.md, en een CLAUDE.md kan dat bestand importeren met de regel @AGENTS.md. Zie de documentatie van Claude Code.
GitHub Copilot: instructies voor de hele repository in .github/copilot-instructions.md, en instructies per pad in .github/instructions/NAAM.instructions.md met een applyTo-patroon. De agents van Copilot lezen ook AGENTS.md. Zie de documentatie van GitHub.
Windsurf (sinds 2026 Devin Desktop): workspaceregels zijn markdownbestanden in .devin/rules, en de oudere map .windsurf/rules wordt nog gelezen. Zet trigger: always_on in de frontmatter. Een AGENTS.md in de hoofdmap geldt altijd. Zie de documentatie over rules.
AGENTS.md: een open formaat voor instructies aan agents, beheerd door de Agentic AI Foundation onder de Linux Foundation en gelezen door veel tools, waaronder OpenAI Codex, Gemini CLI, Cursor, Copilot en Windsurf.

Een praktische opzet voor een team met verschillende tools: zet de regels in AGENTS.md en laat de toolspecifieke bestanden ernaar verwijzen. Voor Claude Code volstaat een CLAUDE.md met één importregel:

@AGENTS.md

Wil je in Cursor liever een aparte regel dan AGENTS.md, maak dan .cursor/rules/accessibility.mdc aan die begint met deze frontmatter:

---
description: Toegankelijkheidseisen voor alle UI-code
alwaysApply: true
---

Het regelblok

Zet dit in AGENTS.md of in het regelbestand van je tool. Pas de namen van tokens en commando’s aan je project aan.

## Toegankelijkheid (WCAG 2.2 AA)

- Kies native elementen: button voor acties, a href voor navigatie, label voor velden, fieldset/legend voor groepen, dialog of de Dialog van het designsysteem voor modale vensters. Zet nooit onClick op een div of span.
- Gebruik ARIA alleen als geen native element past. Overschrijf nooit een native rol.
- Elk interactief element heeft een toegankelijke naam. Knoppen met alleen een icoon krijgen aria-label; decoratieve iconen krijgen aria-hidden="true".
- Elk invoerveld heeft een zichtbaar label dat er in de code aan gekoppeld is. Fouten worden gekoppeld met aria-describedby en als tekst getoond.
- Verwijder nooit een focusrand zonder zichtbare vervanging via :focus-visible met minstens 3:1 contrast.
- Gebruik alleen kleurtokens uit het designsysteem. Teksttokens halen 4.5:1 op de achtergronden waar ze gebruikt worden (3:1 voor grote tekst en UI-onderdelen). Geen hardgecodeerde kleuren.
- Focusbeheer: zet de focus in dialoogvensters, houd hem erin zolang ze open zijn en zet hem terug bij het sluiten. Werk bij routewissels aan de clientkant document.title bij en zet de focus op de hoofdkop.
- Respecteer prefers-reduced-motion voor alle niet-essentiële animatie.
- Eén h1 per pagina en koppen in volgorde. Zet lang op het html-element.
- Klikdoelen zijn minstens 24x24 CSS-pixels.
- Voer voor je een UI-wijziging afrondt de linter en de toegankelijkheidstests uit (npm run lint, npm run test:a11y) en los nieuwe fouten op.

Automatische controles in CI

Regels maken goede code waarschijnlijker; controles vangen op wat er toch doorglipt. Twee lagen werken goed samen.

Een linter voor je templates. Voor React en andere JSX-code markeert eslint-plugin-jsx-a11y ontbrekende alt-teksten, klikbare divs, labels zonder veld en vergelijkbare fouten terwijl je typt. Vue-projecten kunnen eslint-plugin-vuejs-accessibility gebruiken. Met de flat config van ESLint (kijk of de plugin je ESLint-versie ondersteunt):

import jsxA11y from "eslint-plugin-jsx-a11y";

export default [
  jsxA11y.flatConfigs.recommended,
  // your other configs
];

Een browsertest voor gerenderde pagina’s. axe-core is een opensource-engine die een gerenderde pagina toetst aan veel WCAG-regels. Playwright, een tool voor browsertests, kan hem op je belangrijkste pagina’s draaien met het pakket @axe-core/playwright:

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("home page has no detectable accessibility violations", async ({ page }) => {
  await page.goto("/");
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
    .analyze();
  expect(results.violations).toEqual([]);
});

Laat beide bij elke pull request in CI draaien en noem de commando’s in AGENTS.md, zodat de assistent ze uitvoert voor hij zegt dat hij klaar is. Assistenten zijn goed in het oplossen van een falende controle als ze de foutmelding zien.

Controleer de gepubliceerde preview met ibin

Tests draaien op je lokale build en op de pagina’s die je zelf hebt gekozen. Een controle van de gepubliceerde site vangt op wat ze missen: scripts van derden, cookiebanners, inhoud uit je CMS en pagina’s waar niemand een test voor schreef.

Publiceer een preview. De meeste hostingdiensten maken bij elke pull request een preview-adres. Is de preview afgeschermd met een login, gebruik dan een stagingadres zonder afscherming of het productieadres na het mergen; een controletool kan niet inloggen.
Controleer de preview met ibin. Het rapport toont de problemen in duidelijke taal, gerangschikt naar wat je eerst oplost, met een close-up van elke plek. De technische details staan onder “Code voor je ontwikkelaar”.
Geef de oplossing aan je assistent. Bij elk probleem staat de knop “Instructies voor een AI-tool kopiëren”. De prompt werkt in Cursor, Claude Code of Copilot net zo goed als in een sitebouwer: plak hem en bekijk de diff.
Controleer de hele site. Meld je aan om tot 200 pagina’s te controleren, en zet wekelijkse controles aan zodat regressies in je mailbox verschijnen.

Automatische tools, axe-core en ibin inbegrepen, vinden ruwweg een derde tot de helft van alle toegankelijkheidsproblemen. Doe de toetsenbordtest van 10 minuten op nieuwe flows, en probeer een schermlezer op je belangrijkste formulier.

Wat geen assistent of test kan beoordelen

Of een alt-tekst klopt, of linkteksten los van hun context begrijpelijk zijn, of een foutmelding helpt en of je tekst duidelijk is: dat hangt allemaal af van betekenis. Een assistent kan een alt-tekst voorstellen, maar weet niet waarom de afbeelding op de pagina staat. Kijk deze punten met de hand na als de inhoud verandert. De optionele tweede blik van AI in ibin geeft beschrijvingen van afbeeldingen, linkteksten, toetsenbordgebruik en taal een score van 1 tot 5, als aanwijzingen voor een menselijke review.

Voor de niet-technische versie van deze aanpak, zie het overzicht voor AI-bouwers. De herstelgidsen leggen elk probleem uit, bijvoorbeeld over linkteksten.

Controleer je gepubliceerde site

Publiceer een preview en controleer gratis een pagina met ibin. Plak de instructies bij elk probleem in je codeerassistent, bekijk de wijziging en controleer opnieuw.

Kijk hoe je eigen site scoort

Controleer gratis een pagina, zonder account. Je krijgt een duidelijke lijst van wat je eerst oplost, met afbeeldingen van waar elk probleem zit.