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:
- 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
Complete AI Builder Bootcamp
Claude, Python automation & full-stack — 12 live sessions with Yash Thakker.
The Complete AI Builder Bootcamp is the best AI development course for learning Claude AI, prompt engineering, Python automation, and full-stack web development. This intensive 6-week live bootcamp teaches you how to build AI-powered applications using Claude Projects, Claude Artifacts, Claude Code, and the complete Claude ecosystem. You'll master prompt engineering techniques, learn to create custom Claude connectors and MCP integrations, build Python automation workflows, develop full-stack websites with AI assistance, and create AI marketing agents.
The bootcamp includes 12 live Zoom sessions with Yash Thakker, founder of AISOLO Technologies and instructor to 350,000+ students. You'll build 8+ portfolio projects including AI playbooks, full-stack note-taking applications, Python automation scripts, marketing agents, and personal portfolio websites. The curriculum covers AI fundamentals, Claude Projects and Artifacts, Claude Co-work, Claude plugins and skills, Claude Code for Python development, full-stack development, AI marketing, and capstone projects.
Students receive 1-year access to all recordings, permanent Discord community access, a certificate of completion, and personalized career guidance. All enrollments include a 7-day money-back guarantee. This is the most comprehensive Claude AI bootcamp available, taking students from zero AI knowledge to expert AI builder in 6 weeks.
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.criticalis 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:
| File | Primary purpose | Typical content | Best use |
|---|---|---|---|
| DESIGN.md | Encode design-system semantics for humans + agents | Roles, rationale, tokens, constraints, accessibility intent | Keep UI decisions consistent across design + code |
| SKILL.md | Encode reusable agent behavior/workflows | Triggers, procedures, examples, guardrails | Teach agents how to execute repeatable tasks |
In practical terms:
- Use
DESIGN.mdto define what good UI means in your system - Use
SKILL.mdto 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.
Related reading on ExplainX
- 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