DESIGN.md: the open spec that teaches AI design intent, not just tokens

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.

Watch: YouTube - DESIGN.md overview with David East

The core problem DESIGN.md addresses

Most teams have at least three parallel representations of design:

1. Human guidance in docs or Figma comments
2. Raw tokens in code (--color-primary, spacing scales, typography values)
3. 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")
• Precise code-facing values (hex, spacing, typography, states)
• Structured organization tools can parse reliably

This makes the file useful to both:

• Designers and developers who need clarity and maintainability
• AI agents that need deterministic, machine-actionable guidance

DESIGN.md vs SKILL.md (quick comparison)

DESIGN.md and SKILL.md are complementary, not competing formats:

In practical terms:

• 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:

1. Pick one component family (buttons, forms, alerts)
2. Capture semantic roles plus rationale in a single structured file
3. Add lint checks for WCAG-critical rules
4. Let agents propose changes, but gate merges on linter output
5. 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.

Related reading on explainx.ai

• What is CLAUDE.md? Persistent Memory for Claude Code - how to give Claude Code project context and preferences
• What is MEMORY.md? The Long-Term Brain for AI Agents - deep dive on agent memory patterns and the 4-level hierarchy
• What are agent skills? A complete guide - deep dive on SKILL.md, triggering, and production workflows
• What is MCP? Model Context Protocol explained - how agents connect to tools and data
• Introducing MCP servers on explainx.ai - directory-level view of the MCP ecosystem

Bottom line

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.

Source video: YouTube - DESIGN.md with Google Labs' David East