ColorwayKit for Agents: DESIGN.md for Claude Code & Cursor

Why AI coding agents need a DESIGN.md

An agent that invents colors is not being creative — it is filling a gap. If your repo says nothing about which grey is a surface and which one is a border, the agent has to guess, and it will guess differently each time. The result is the classic agent-built UI: plausible, inconsistent, and unchecked for contrast.

DESIGN.md is an open format from Google Labs, adopted by AI coding tools, that closes this gap with one plain-text file. Its YAML front matter holds machine-readable design tokens — colors, component roles — and a Markdown body explains when and why to use each one. Agents read it because it is in the repo, versioned like code, and unambiguous about which value plays which role.

The workflow: one brand color to an agent-ready file

The whole loop runs in minutes, and every step is free:

• Open the Brand Theme Engine and paste your brand hex from your logo or guidelines.
• Pick light and dark variants, override any token you want, and re-run the WCAG 2.1 / APCA contrast checks until they hold.
• Export a DESIGN.md from the Take it to dev tab — alongside CSS variables, Tailwind config, Tokens Studio JSON and W3C DTCG.
• Save it as DESIGN.md in your project root and wire your agent with a template: CLAUDE.md for Claude Code, .cursorrules for Cursor, or the repo-level AGENTS.md both tools read.
• All templates and a real generated example live in the colorwaykit-for-agents repository on GitHub — copy one, adapt the paths, done.

What the exported file actually contains

The example in the repository was generated from the brand color #4F46E5 — it is real output, not a hand-written demo. The front matter defines 23 semantic color roles for the light theme and the same 23 with a dark- prefix for the dark theme: background, surface, on-surface, primary, on-primary, success, warning, error and so on. Component tokens reference these with a {colors.x} syntax, so changing one value propagates everywhere.

The Markdown body then reports what the generator measured. Every text/background pairing lists its WCAG 2.1 ratio against the threshold and its APCA Lc value against the use-case threshold. In the example, on-surface on background measures 18.97:1 (APCA Lc 103) in light mode and primary on background 6.02:1 (Lc 78) — both comfortably above the 4.5:1 requirement.

Just as important, the file reports its own failures. In the generated example, on-success on success is WCAG 4.76:1 pass but APCA Lc 36 — below the 60 threshold for body text, and marked fail. Pairs that do not hold are flagged, because the file reports what the tool computed, nothing more.

Wiring it into Claude Code and Cursor

Copy the template that matches your agent into the project root next to DESIGN.md. Claude Code reads CLAUDE.md as project memory; Cursor picks up .cursorrules; both tools also honor a repo-level AGENTS.md. The templates only describe how to consume the file — where it lives, which tokens map to which role, and that hex values outside the token list are a bug — so they stay short.

If you also ship Tailwind, keep the same tokens in your Tailwind config so runtime styles and agent-generated markup agree; the Tailwind color generator exports a matching config from the same theme. When your brand evolves, re-export DESIGN.md and the change is one file in your diff — the templates do not need to move.

Limits worth knowing

The color engine covers color. The generated file declares typography, spacing and radii as omitted — no invented values — so those stay with your framework defaults and are yours to define. The contrast values are computed automatically and serve as a design reference, not a formal accessibility certification. And the DESIGN.md specification itself is at an early version, so component token structures may evolve; the exporter follows the spec as published.

References

• DESIGN.md — Google Labs (open format spec)
• WCAG 2.1 — W3C Recommendation
• APCA — Accessible Perceptual Contrast Algorithm

FAQ