{"slug": "design-md-checks-wcag-contrast-by-default-here-s-why-that-matters", "title": "DESIGN.md Checks WCAG Contrast by Default. Here's Why That Matters.", "summary": "DESIGN.md's linter checks WCAG contrast by default for every component's color pairing, reporting the exact ratio and whether it passes. This bakes accessibility into the tooling, addressing a weakness of AI-generated UI where agents often ignore contrast. The linter computes contrast ratios and reports WCAG AA compliance, turning accessibility into a continuous part of defining design systems.", "body_md": "**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.\n\nAI 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.\n\nFor 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):\n\n``` bash\n$ npx @google/design.md lint DESIGN.md\n\n{\n  \"path\": \"components.button-primary\",\n  \"message\": \"textColor (#ffffff) on backgroundColor (#1A1C1E)\n              has contrast ratio 15.42:1 - passes WCAG AA.\"\n}\n```\n\nBecause 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.\n\n```\n## Do's and Don'ts\n- Do maintain WCAG AA contrast (4.5:1 for normal text)\n- Don't rely on color alone to convey meaning\n- Do keep touch targets large enough\n```\n\nThe linter handles the measurable; the prose handles the judgement.\n\nAccessible 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.\n\n**Which level?** WCAG AA contrast, per component pairing.\n\n**Can I extend it?** Reinforce with prose for the parts a single ratio cannot capture.\n\nMaking WCAG a default turns accessible output into the path of least resistance.\n\n**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)\n\n**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)\n\nHas an AI agent ever shipped you a contrast failure? Curious how people are catching these today.", "url": "https://wpnews.pro/news/design-md-checks-wcag-contrast-by-default-here-s-why-that-matters", "canonical_source": "https://dev.to/promptmaster/designmd-checks-wcag-contrast-by-default-heres-why-that-matters-63h", "published_at": "2026-06-28 07:53:16+00:00", "updated_at": "2026-06-28 08:03:54.237318+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "generative-ai", "ai-safety", "ai-ethics"], "entities": ["DESIGN.md", "Google", "WCAG", "WCAG AA"], "alternates": {"html": "https://wpnews.pro/news/design-md-checks-wcag-contrast-by-default-here-s-why-that-matters", "markdown": "https://wpnews.pro/news/design-md-checks-wcag-contrast-by-default-here-s-why-that-matters.md", "text": "https://wpnews.pro/news/design-md-checks-wcag-contrast-by-default-here-s-why-that-matters.txt", "jsonld": "https://wpnews.pro/news/design-md-checks-wcag-contrast-by-default-here-s-why-that-matters.jsonld"}}