DESIGN.md's linter checks WCAG contrast by default for every component's color pairing, reporting the exact ratio and whether it passes. Accessibility is built into the tooling, not left as an optional audit - which fixes a real weakness of AI-generated UI.
AI agents ignore contrast unless forced to consider it. Left alone, an agent places light grey text on white because it looks clean in the abstract - producing UI that fails accessibility standards and is hard to read.
For each component pairing a text color with a background, the linter computes the contrast ratio and reports whether it meets WCAG AA (4.5:1 for normal text):
$ npx @google/design.md lint DESIGN.md
{
"path": "components.button-primary",
"message": "textColor (#ffffff) on backgroundColor (#1A1C1E)
has contrast ratio 15.42:1 - passes WCAG AA."
}
Because the check is built in, think about contrast as you define component tokens, not after. When you pair a text color with a background, the linter tells you immediately whether it holds up - turning accessibility from an audit phase into a continuous part of defining your system.
## Do's and Don'ts
- Do maintain WCAG AA contrast (4.5:1 for normal text)
- Don't rely on color alone to convey meaning
- Do keep touch targets large enough
The linter handles the measurable; the prose handles the judgement.
Accessible interfaces are often a legal requirement, not just an ethical default. Baking WCAG into the tooling reduces the risk of shipping non-compliant UI - a real and growing liability.
Which level? WCAG AA contrast, per component pairing.
Can I extend it? Reinforce with prose for the parts a single ratio cannot capture.
Making WCAG a default turns accessible output into the path of least resistance.
Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet
Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents
Has an AI agent ever shipped you a contrast failure? Curious how people are catching these today.