news

DESIGN.md Specification

DESIGN.md is an open Apache-2.0 format specification from Google Labs for describing a design system to coding agents in a single, version-controllable file. It pairs machine-readable design tokens in YAML front matter with human-readable design rationale in markdown prose — so an LLM) can apply vis

Sebastien Dubois

01 May 2026 — 2 min read

Canonical version: DESIGN.md Specification.

DESIGN.md is an open Apache-2.0 format specification from Google Labs for describing a design system to coding agents in a single, version-controllable file. It pairs machine-readable design tokens in YAML front matter with human-readable design rationale in markdown prose — so an LLM can apply visual identity correctly instead of defaulting to generic UI.

It plays the same role for design context that CLAUDE.md / AGENTS.md plays for engineering context: a persistent, structured contract that survives sessions and follows the repo. Currently in alpha; the format, schema, and CLI are still moving.

Spec home: https://stitch.withgoogle.com/docs/design-md/specification — Google Stitch (Google's AI design tool) is the reference consumer.

File anatomy

---
# YAML front matter — design tokens (machine-readable)
colors:
  primary: "#1a3a52"
  background: "#f7f3ec"
typography:
  headline:
    fontFamily: "Inter"
    fontSize: 48
    fontWeight: 700
spacing:
  scale: [4, 8, 16, 24, 32]
---

## Overview         <- markdown body — design rationale
## Colors
## Typography
## Layout
## Elevation & Depth
## Shapes
## Components
## Do's and Don'ts

The ## headings are prescribed and ordered. Tokens cover colors (hex), typography (family/size/weight/lineHeight/letterSpacing), spacing, rounded-corner scales, and component-property mappings.

Token categories

Category	What it captures
Colors	Hex palettes, semantic roles
Typography	Family, size, weight, line height, letter spacing
Spacing	Scale tokens for padding/margin/gap
Rounded corners	Radius scale
Components	Named components with property mappings

Why it matters

AI-native by design. Like Tolaria for PKM or CLAUDE.md for engineering, DESIGN.md is part of the plain-text-as-AI-contract pattern: human-and-machine-readable, version-controlled, follows the repo.
Tokens + rationale together. Pure tokens (Tailwind config, DTCG JSON) give what; markdown body gives why. Agents need both to make non-trivial design decisions.
Closes the design-to-code gap for agents. Without it, agents fall back to generic Material/shadcn defaults regardless of brand. With it, "deep ink headlines, warm limestone background, Boston Clay CTAs" is reproducible.
Exportable. Designed to feed downstream toolchains: Tailwind config, DTCG (W3C Design Tokens Community Group) format, etc.

Audience

Role	How they use DESIGN.md
AI / coding agents	Primary consumer — read tokens + rationale to generate UI
Designers	Author and own the file as the design system source of truth
Developers	Consume exported tokens (Tailwind, DTCG) and the components map

Status

Alpha. Spec, schema, and CLI are under active development; format changes expected.
Apache-2.0 licensed.
Backed by Google Labs / Stitch.

Relation to other "AI-readable" specs

Spec / file	Role
DESIGN.md	Design system context for coding agents
CLAUDE.md / AGENTS.md	Engineering / project context for coding agents
MCP servers	Live, queryable context for any agent
DTCG tokens	Standardized design token interchange format

DESIGN.md sits with CLAUDE.md / AGENTS.md in the static, repo-resident, plain-text context layer — complementary to MCP's dynamic, server-mediated context layer.

References

AI Agents
Google Stitch
Model Context Protocol (MCP)
Large Language Models (LLMs)
Tolaria — same plain-text-as-AI-contract pattern, applied to PKM
Apache 2.0 License
Yet Another Markup Language (YAML)

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

📚 KM for Beginners — 10+ hours of structured video lessons
🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
💼 Knowledge Worker Kit — Complete guides + lifetime community
🦉 1-on-1 Coaching — Personalized guidance
🎯 Join Knowii — Community + ALL courses & tools