DESIGN.md Checks WCAG Contrast by Default. Here's Why That Matters.

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.

The weakness it addresses

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.

How the check works

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."
}

Design with contrast in mind

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.

Reinforce it in prose

## 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.

Why it matters commercially

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.

FAQ

Which level? WCAG AA contrast, per component pairing.
Can I extend it? Reinforce with prose for the parts a single ratio cannot capture.

Bottom line

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.