Why DESIGN.md doesn't survive contact with a real design system

We tried DESIGN.md as the canonical source of our design system. It did not work. Here is what happened, and what we learned to do instead.

The Google Labs DESIGN.md spec is a structured Markdown format for describing design systems in a way AI coding agents can read and use. It is part of the broader effort to give Claude Code, Cursor, and similar tools structured grounding so they stop making up styling. The spec is at version 0.1.1, alpha, as of writing. We are using it inside Talos, our internal Rails app, where we are building out an AI-aware design system pipeline.

When we started, the obvious move was to put DESIGN.md at the center. Author the system there. Generate everything else from it. CSS or SCSS for the codebase, Figma variables for the design tool, AI references for the agents. One spec, one canonical, downstream tools derive everything.

We tried this. We discovered that DESIGN.md, as a canonical source for a real design system, is structurally lossy.

The DESIGN.md schema, at v0.1.1, natively types five things:

That is the supported set. Anything not in this list is not modeled. Anything not modeled is dropped on export.

Our actual tokens file has all of the above, plus a long tail of token types that real design systems need:

Roughly half of our tokens file is in this long tail. If DESIGN.md were canonical, that half would silently disappear at export.

The alpha CLI has other practical problems too. It crashes on bare numbers (raw.match is not a function on z-dropdown: 1010). Dimensions must be quoted strings ("1rem", not 1rem). DTCG export only emits the recognized groups.

We could have worked around all of that. We could not work around half of our tokens disappearing.

The right move was not to make DESIGN.md richer. The right move was to invert the architecture.

A full-coverage canonical token source drives everything. CSS or SCSS for the codebase. Figma variables for the design tool. DESIGN.md for the AI agents. Each is a projection of the canonical, derived in the build.

The canonical we use is DTCG-in-YAML, the W3C Design Token Community Group format, authored as YAML for readability and compiled to DTCG JSON for handoff. DTCG natively types everything DESIGN.md does, plus shadows, durations, references, and the long tail. It is the more complete vocabulary, and it is the emerging interoperability format for tokens across multiple design tools and code generators.

Style Dictionary handles the canonical-to-SCSS step. The Figma MCP integration handles the canonical-to-Figma-variables step. A small script generates the DESIGN.md from the canonical, using the supported DESIGN.md schema for the supported parts (colors, typography, spacing, rounded, components) and prose for the parts that do not have a schema slot. Shadows live under an Elevation prose section. Z-index lives under Layout. The generated DESIGN.md passes the official linter and stays useful to AI agents. It just is not the source of truth.

This is not a knock on DESIGN.md.

The spec is doing real work. It gives Claude Code, Cursor, and similar tools a structured reference for the supported token types, is portable across projects and codebases, works with the official linter, and pairs with Stitch and other emerging AI-design tooling. As a target format and interchange, it is the right shape.

The schema-supported subset is enough for an AI agent to write coherent UI code. Colors, typography, and the spacing scale are all typed, and component records reference those token types. For most of what an AI coding agent needs to ship, the supported subset is sufficient.

The constraint is what happens if you treat it as canonical. Half your tokens vanish on export, and the schema becomes a ceiling on what your design system can express.

If you are building an AI-aware design system in 2026, the architecture decision that matters is whether the canonical can hold everything your design system actually has.

Canonical token source: full-coverage (DTCG-in-YAML or equivalent). DESIGN.md: generated projection, for AI tools. SCSS or CSS: generated projection, for code. Figma variables: generated projection, for the design tool.

Author once. Project everywhere. The DESIGN.md the AI tools read is always in sync with the SCSS the team is shipping and the Figma variables the designers are using, because all three come from the same source.

Round-trip the design tool back to the canonical through a 3-way merge with per-group ownership. Design tokens (color, type) let the design tool win. Engineering tokens (z-index, spacing scale) let the code win. The AI agent reads from DESIGN.md and writes against the typed schema. If it tries to use something unsupported, it fails loudly rather than silently.

The whole thing stays the boring, maintained shape: one source, many surfaces, all generated from the same canonical.

DESIGN.md is the right portable interchange for AI coding agents. It is not the right canonical source for tokens. If you put a richer canonical underneath and generate DESIGN.md as a projection, you get AI agents that read a structured spec, code that ships against the full token system, and no half-vanishing on export.

The DESIGN.md spec wants to be a face, not a source. Build the source separately and let the face stay a face.

If your team is building toward AI-aware design system tooling and wants help getting the architecture right the first time, the Design Systems service page covers the engagement shape. The Talos work this piece draws from is in flight as of mid-2026.