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

> Source: <https://dev.to/promptmaster/designmd-checks-wcag-contrast-by-default-heres-why-that-matters-63h>
> Published: 2026-06-28 07:53:16+00:00

**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):

``` bash
$ 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](https://promptmasterstore.gumroad.com/l/design-md-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](https://promptmasterstore.gumroad.com/l/design-md-guide)

Has an AI agent ever shipped you a contrast failure? Curious how people are catching these today.