DESIGN.md: the open spec that teaches AI design intent, not just tokens
Google Labs' David East explains DESIGN.md: a human-and-machine-readable design spec that combines rationale with exact values so AI agents can apply design systems semantically and validate accessibility before shipping.
Design system files are often machine-readable but not agent-readable in the way modern coding workflows require. The values are there, but the reasoning is missing. In this Google Labs walkthrough, David East frames DESIGN.md as the missing bridge: one structured format that stores both the intent and the exact implementation details.
Most teams have at least three parallel representations of design:
A deep dive into DESIGN.md — the spec that teaches AI agents design intent, not just tokens.
Human guidance in docs or Figma comments
Raw tokens in code (--color-primary, spacing scales, typography values)
Team conventions that live in people's heads
When AI agents edit UI code, they can see #2 clearly, but #1 and #3 are often implicit. That gap leads to familiar issues: visually plausible changes that violate brand intent, inaccessible contrast pairings, or inconsistent component behavior.
DESIGN.md proposes collapsing those layers into one portable artifact.
Why this is different from "just another token format"
The high-leverage idea in the video is this: tokens should be interpreted as semantic roles, not static variables.
color.surface.critical is not just a hex value
It carries a role, usage constraints, and context
Agents can reason about when to apply it (and when not to)
That is the shift from value substitution to design reasoning.
What goes inside DESIGN.md
As described in the talk, the format combines:
Human-readable rationale ("why this style exists")
Use DESIGN.md to define what good UI means in your system
Use SKILL.md to define how an agent should work when building or updating UI
Combine both so agents can follow process and design intent at the same time
Accessibility as a first-class check
One of the strongest workflow ideas in the video is the CLI linter that can validate design updates against WCAG constraints before an agent writes code changes.
That is operationally important because it moves accessibility from:
post-change cleanup
to:
pre-change guardrail
For teams using AI-assisted coding, this is the practical path to scaling output without scaling regressions.
Why this matters for product teams now
DESIGN.md is bigger than a single tool integration. It points to a broader pattern:
design system docs become executable context for agents
token libraries become semantic contracts
accessibility checks become automatable in the authoring loop
If your team is already using agents for UI work, this pattern can reduce "looks right, feels wrong" diffs and make design reviews more about product decisions than cleanup.
A practical adoption path
If you are evaluating DESIGN.md-style workflows, start small:
Pick one component family (buttons, forms, alerts)
Capture semantic roles plus rationale in a single structured file
Add lint checks for WCAG-critical rules
Let agents propose changes, but gate merges on linter output
Expand to broader tokens once the workflow stabilizes
The goal is not to replace design judgment. It is to make that judgment explicit enough that both humans and agents can execute it consistently.
DESIGN.md’s promise is straightforward: keep the design why and the design values together, so AI stops treating your system like a bag of variables and starts treating it like a set of product decisions.
For teams building AI-native front-end workflows, that is a meaningful upgrade from token sync to design intelligence.