There are two related jobs in a design system. One is to say what a value is. The other is to say why and when to use it. Design tokens are good at the first job. A design brief is good at the second. The current DESIGN.md wave often places both jobs in one Markdown file, which is practical, but it has also recreated a problem token tooling already solved.
The World Wide Web Consortium (W3C) Design Tokens Community Group (DTCG) defines a portable token format built around $type, $value, and $description. The field is not waiting to decide whether that shape is useful. As of September 2026, our open source software (OSS) survey found DTCG implemented or actively adopted by Style Dictionary, Tokens Studio, Terrazzo, Sugarcube, and a standalone TypeScript implementation. Style Dictionary, at 4,823 stars as of September 2026, transforms tokens for Cascading Style Sheets (CSS), iOS, Android, and other targets. Tokens Studio, at 1,608 stars, is a common authoring route from Figma. Terrazzo, at 459 stars, takes DTCG tokens into web, mobile, and native code.
This is not a claim that every design system is now easy. It is a narrower observation: the data layer has a language. The new DESIGN.md ecosystem should use it instead of treating a token file as a fresh schema-design exercise.
The two shapes on the page
Consider the format example in Design Extractor’s documentation:
colors:
primary: "#2665fd"
typography:
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
rounded:
md: 8pxIt is readable. It is also local vocabulary. A consumer has to infer that colors.primary is a color, that rounded.md is a dimension, and that body-md is a typography object with several fields. The names work in this document because the reader recognizes the convention. They do not give a generic token processor enough explicit structure to act safely without custom rules.
The public generator prompt in designmd.supply describes the same general approach. It calls for YAML Ain’t Markup Language (YAML) frontmatter with keys such as version, name, description, colors, typography, rounded, spacing, and components. It also tells the model to prefer precise values in the extracted styleguide and, when data is missing, to infer conservatively and state uncertainty in prose rather than in token values. That is thoughtful guidance for document generation. It still produces a local schema rather than a direct DTCG token source.
Now compare a DTCG-shaped representation:
tokens:
color:
primary:
$type: color
$value: "#2665fd"
$description: Primary interactive color.
radius:
medium:
$type: dimension
$value: "8px"
typography:
body:
fontSize:
$type: dimension
$value: "16px"
fontWeight:
$type: fontWeight
$value: 400The second shape is not prettier. It is more explicit. A transformer can see the type. A tool can validate a value. A target can receive the token without first learning the vocabulary of one extractor. An alias can retain a path instead of being copied into a second set of values. The prose may still say that primary is reserved for the most important action. The data does not need to carry that whole sentence.
Why the split matters for agents
Agents do not only read a design file once. They may modify a component, add a page, inspect a CSS variable, or answer a question about which values can be reused. A document that mixes canonical values and advice needs to help the agent distinguish those tasks.
An agent can use prose for the judgment call: should this button be quiet or primary? It can use typed data for implementation: what is the primary color, and is it an alias or a direct value? The distinction also matters for review. A change from #2665fd to another color is a data change. A change from “use sparingly” to “use for every call to action” is a policy change. Keeping those things legible makes a design system easier to maintain.
The present ecosystem often makes the reverse trade. It gives an agent a generous, readable brand narrative but emits a token shape that cannot directly travel downstream. A generator may be good at summarizing a website and still leave the developer to re-enter values in a Figma library, CSS file, Tailwind configuration, or token build pipeline. This is a loss of interoperability, not a criticism of Markdown.
The research found only tokextract in the OSS survey explicitly targeting DTCG as an extractor output. It extracts tokens from “vibe-coded” iOS apps into DTCG tokens, a brand-narrative DESIGN.md, and an audit report. That project had 3 stars as of September 2026, so it is not evidence of broad adoption. It is evidence that the two outputs can coexist without conflict.
DTCG is not a replacement for DESIGN.md
It would be a mistake to respond by deleting the prose. A DTCG file cannot tell an agent why an interface uses a restrained accent, which component patterns are structural, or what visual tradeoffs matter in a new route. A fully typed token inventory can be technically correct and still produce a generic user interface (UI).
This is where DESIGN.md is useful. The standard eight sections are an efficient mental model. Overview gives a working description. Colors explain roles. Typography explains hierarchy. Layout & Spacing, Elevation & Depth, and Shapes make the system visible beyond a color palette. Components and Do’s and Don’ts carry the guidance that prevents a token list from becoming an instruction to paint every surface with a brand color.
The Google Labs repository itself already points in this direction. Its command-line interface (CLI) provides linting, diffing, Tailwind export, and export to the W3C Design Token Format. Design.md Store tells users to validate a file with npx @google/design.md lint DESIGN.md, including Web Content Accessibility Guidelines (WCAG) AA contrast checks. The source format does not need to be an isolated island. The opportunity is to make the bridge native to the profile rather than an afterthought.
There is a practical reason to keep a single file as well. A developer can inspect it in a pull request. An agent can load it from a repository root. A human can read the rationale without opening a generated artifact. The proposal is not to replace DESIGN.md with JavaScript Object Notation (JSON). It is to make the data in a DESIGN.md portable enough to be useful outside that one file.
The false comfort of familiar keys
Ad hoc keys feel harmless when a design system is small. primary, surface, body-md, and rounded.md are obvious to the person who wrote them. The trouble begins as soon as a system has aliases, themes, composite typography values, or several implementation targets.
Take a semantic color. A system may have a base blue, a primary interactive blue, a disabled primary blue, and an on-primary text color. A simple frontmatter map can represent all four strings. It does not make their relationships explicit. If an agent changes the base blue, should it update all four? If a dark theme maps surface differently, is that a new source or an override? If an output needs a CSS variable and an iOS asset, which names are stable?
These are ordinary token problems. DTCG is not magic, but it is designed to hold typed values and references across the systems that need them. Reusing that foundation means a DESIGN.md author spends less time inventing names and more time explaining the product-specific decisions that cannot be standardized.
It also makes validation less ambiguous. A planned lint rule can resolve {path.to.token} aliases. It can reject a dimension stored where a color is expected. It can distinguish a malformed value from a subjective design choice. Contrast checking is still contextual, but a linter at least knows which declared colors it is comparing.
A bridge should be modest and inspectable
Velofy’s draft profile proposes DTCG-shaped token groups inside YAML frontmatter, followed by the existing eight sections. It does not claim the entire file is DTCG. Markdown recommendations, component descriptions, and do/don’t guidance remain prose. It does claim that the declared tokens should be structured enough to export without reverse-engineering them again.
The accompanying lint rules are planned, not shipped. There is no @velofy/design-md package or Model Context Protocol (MCP) server today. If one is built, the useful behavior would be small and inspectable: require the provenance block, validate token references, check declared contrast pairs, and explicitly transform tokens to DTCG or Tailwind outputs. The bridge should not hide interpretation behind an export command.
That final point is important for extractors. A token can be valid DTCG and still be wrong for the source website. Data portability does not establish fidelity. The file should carry both facts: this value has a portable type, and this value was recorded by hand, scraped from the page’s Document Object Model (DOM), or inferred by a large language model (LLM), with a stated confidence.
The boring layer is the one to reuse
The token format war is not where design engineering needs more novelty. DTCG is the boring layer that has already accumulated implementers. It is the part of the stack where interoperability is more valuable than branding.
DESIGN.md can remain the human and agent-facing layer above it. A document can have a short opening paragraph, a component note, and a warning against a visual habit that would be technically valid but wrong for the product. It can be the README for visual identity. It should not require every new generator to invent its own package format for colors and dimensions.
The best result is less dramatic than a new standard: an agent reads one file, a human reviews one file, and the values inside can move into the tools that already understand them.
What Velofy is doing next
Velofy intends to keep the draft profile aligned with the existing DESIGN.md body and DTCG-shaped token fields. We intend to publish any future export behavior as a proposal before calling it a tool. We also intend to label manually recorded and inferred values separately, because a portable token is not automatically a verified token.