Stop Fixing Broken AI UI Manually
Your AI coding tools often fail at design.
You ask for a button. The AI gives you one shade of blue. You ask for another component. The AI gives you a different shade of blue. This happens because the AI lacks a strict design system.
Google Labs released design.md to solve this.
It is a specification that lets tools like Cursor, Claude Code, and GitHub Copilot read your design rules. This prevents inconsistent spacing, wrong fonts, and drifting colors.
How it works:
design.md is a Markdown file with two parts.
- YAML Front Matter: This contains precise design tokens. You define colors, typography, spacing, and corner radii here.
- Markdown Body: This contains the design rationale. It explains why you use a color and when to avoid it.
This structure helps the AI understand both the data and the logic. It does not just see a hex code. It understands that a specific color is for headlines and should not be used for body text.
Key features of the design.md CLI:
- Linting: It checks if your tokens are correct. It even checks for WCAG AA accessibility contrast.
- Diffing: It shows you exactly which tokens changed when you update your design.
- Exporting: It converts your design file into Tailwind CSS, JSON, or W3C Design Tokens.
- Spec: It generates a guide you can give to your AI to teach it how to read your file.
Why this matters:
Most developers use CLAUDE.md or AGENTS.md for general rules. While helpful, these files are mostly natural language. The AI still has to guess specific values.
design.md turns your design system into machine-readable data.
To use it:
- Place DESIGN.md in your project root.
- In your CLAUDE.md or Cursor rules, add this line: "For UI tasks, read DESIGN.md first and strictly follow the tokens and rationale."
Stop repeating "wrong color" to your AI. Give it a single source of truth.
Optional learning community: https://t.me/GyaanSetuAi