The problem: AI agents forget your design decisions
You've been here before. You ask Cursor to build a settings page. It picks a blue you've never seen. You correct it, paste your hex values, and move on. Next component — same problem. The AI has no memory of your visual identity between prompts.
This isn't a prompting failure. It's a context failure. AI coding tools process each request in isolation. Without a reference file in your repository, every generated component uses different visual decisions. You end up spending more time correcting colors than writing actual features.
The existing workarounds — .cursorrules, claude-system.md, copilot-instructions.md — help, but they're tool-specific. You write one for Cursor, a different one for Claude, another for Copilot. Same information, different formats, multiple files to maintain.
Enter DESIGN.md: one file, every tool
In April 2026, Google open-sourced the DESIGN.md specification through Google Labs. It's a single Markdown file that encodes your entire design system — colors, typography, spacing, components — in a format that any AI coding agent can read.
The format is simple: YAML front matter with machine-readable design tokens, followed by Markdown prose with human-readable design rationale. The same file works in Claude Code, Cursor, Windsurf, GitHub Copilot, Google Stitch, v0, Kiro, and Gemini CLI. Drop it in your project root and every tool reads it.
It's published under the Apache 2.0 license and is on track to become an industry standard — the OpenAPI of design systems.
What's inside a DESIGN.md file
A DESIGN.md file has two layers. The YAML front matter defines exact values that tools can parse programmatically:
---
version: "alpha"
name: "Ocean Drift"
colors:
primary: "#0F4C81"
on-primary: "#FFFFFF"
secondary: "#1A73B8"
tertiary: "#38B2AC"
surface: "#F0F9FF"
on-surface: "#1A202C"
typography:
headline-lg:
fontFamily: Inter
fontSize: 32px
fontWeight: 700
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
rounded:
sm: 4px
md: 8px
lg: 16px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.on-primary}"
rounded: "{rounded.lg}"
---Below the front matter, the Markdown body provides context that helps the AI make judgment calls — what the brand feels like, how elevation works, which patterns to follow and which to avoid.
The spec defines eight sections, in order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts. Each section gives the AI both the "what" (exact values) and the "why" (design rationale).
Why this matters more than tool-specific rules files
The key shift is universality. A .cursorrules file only works in Cursor. A claude-system.md only works in Claude. DESIGN.md works everywhere — it's the one file you maintain, and every tool in your stack reads it.
But it goes further than colors. A typical rules file gives the AI a list of hex values and says "use these." DESIGN.md gives it a complete design system: semantic color roles, typography scales, spacing units, corner radii, component definitions with variants. The AI doesn't just know your primary color — it knows what your buttons look like, how your cards are spaced, what your elevation model is.
The result is that AI-generated components are consistent from the first prompt. Not just in color, but in every visual dimension.
How kuler.ai generates DESIGN.md files
Every palette on kuler.ai now includes a one-click DESIGN.md export. Open any palette, click the Export panel, and download a spec-compliant file that includes:
- Full YAML front matter with all color tokens mapped to semantic roles (primary, secondary, tertiary, surface, on-surface)
- Typography tokens using Inter with a complete size/weight scale
- Spacing and corner radius scales on an 8px grid
- Component definitions for buttons, cards, and inputs with token references
- All eight Markdown sections with palette-specific design guidance
The mapping is intentional. kuler.ai palettes use six roles — primary, secondary, accent, background, surface, text — which map cleanly to the DESIGN.md token names. The accent becomes tertiary. The background becomes surface. Text becomes on-surface. The generator also derives on-primary (white or dark text) based on contrast ratio analysis.
DESIGN.md vs. other export formats
kuler.ai still exports to every tool-specific format — .cursorrules, .windsurfrules, Bolt, Lovable, v0, Claude, Copilot. These aren't going away. Some teams prefer the targeted format, and some tools have features that benefit from their native format.
But if you're starting fresh, or if you use multiple AI tools, DESIGN.md is the format to reach for. One file, universal compatibility, richer design context. It's the export we recommend for most projects.
Getting started
The workflow is straightforward:
- Browse the kuler.ai gallery and find a palette that matches your project's visual identity
- Open the palette detail page and click the Export panel
- Click DESIGN.md — it's the first option in the list
- Drop the downloaded file in your project root
- Every AI coding tool that reads project files now has your complete design system
That's it. No configuration. No build step. No tooling. A single Markdown file that turns every AI agent into a design-aware collaborator.
The best design system is the one your tools actually read. DESIGN.md makes that automatic.