Hero image for Design Token Drift: Detecting When Generated CSS Breaks Your DESIGN.md

Design Token Drift: Detecting When Generated CSS Breaks Your DESIGN.md

When Generated CSS Breaks DESIGN.md: A Spec-Based Drift Checklist

AI-assisted UI generation has a quiet failure mode. The component renders. The layout looks roughly right. And then you grep the stylesheet and find #1A1C1E where your contract says colors.primary, 14px where the spacing scale only permits 12px and 16px, and a borderColor on a component that never declared one. Nothing crashed. The design system just stopped being true.

This guide treats that failure as a checkable contract rather than a vibe. It converts the DESIGN.md specification — read through an unofficial translation, because the official page could not be retrieved — plus the DTCG 2025.10 format module into a small set of explicit rules you can reason about, argue about, and eventually automate. It is vendor-neutral and documentation-derived: nothing below reports a measured drift rate, a benchmark, or a test run, because no retrieved source establishes any of those things.

What “generation drift” is

Define the artifact pair first, because the definition determines what you can detect.

Generation drift is the difference between the literal values emitted into CSS by a generator and the token values declared in a DESIGN.md contract. The left side is a stylesheet: hex codes, pixel values, font stacks, radii. The right side is a file with a YAML front matter block of normative tokens and a markdown body of rationale. Drift exists wherever the emitted CSS asserts a design decision the contract does not sanction.

That framing is deliberately narrow. It is not build-output drift, where you compare a token source file against the custom properties a build pipeline emits — a different artifact pair with a different failure surface. Build-output drift asks “did the pipeline faithfully transcode my tokens?” Generation drift asks “did the model faithfully obey them?” A pipeline that faithfully transcodes a token nobody uses is a build success and a generation failure.

The practical consequence: you cannot detect generation drift by inspecting your token pipeline. You have to inspect the generated artifact against the contract text. That is the whole job.

The DESIGN.md contract, as documented

The DESIGN.md specification defines a two-layer file. Per the unofficial translation of the Stitch DESIGN.md specification, the YAML front matter “contains machine-readable design tokens — the precise values agents use to enforce consistency,” while the markdown body “provides human-readable design rationale organized into ## sections.” The same page states the priority rule that makes drift checkable at all: “The tokens are the normative values; the prose provides context for how to apply them.”

That sentence is the entire legal basis for a drift check. Prose is context. Tokens are law.

A caveat on provenance before we go further: the official Google Stitch documentation page for the DESIGN.md format failed to retrieve on 2026-11-21, on both extraction engines attempted. Everything attributed to the specification in this article comes from that independent, unofficial translation, which labels itself as such. Treat spec-level claims here as accurate-to-the-translation, not verified against the origin.

Front matter: the shape a parser must expect

The front matter “must begin with a line containing exactly --- and end with a line containing exactly ---.” The documented schema, reproduced in shape:

version: <string>      # optional, current version: "alpha"
name: <string>
description: <string>  # optional
colors: <token-name>: <Color>
typography: <token-name>: <Typography>
rounded: <scale-level>: <Dimension>
spacing: <scale-level>: <Dimension | number>
components: <component-name>: <token-name>: <string | token reference>

Two details matter for drift detection. First, version is optional and the current documented value is the string "alpha" — there is no numeric version to gate on. Second, components is a two-level map: component name, then property, then value or reference. That nesting is where most real drift hides, because a component can carry a perfectly valid token reference for a property the contract never authorised.

Values, types, and references

The specification’s type table is small enough to implement against directly:

  • Color — "#" plus a hex code in sRGB, e.g. #1A1C1E.
  • Dimension — a number plus a unit, one of px, em, rem.
  • Token reference — {path.to.token}.
  • Typography — a composite object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, and fontVariation.

The reference rule is the sharpest edge in the whole spec: “For most token groups, the reference must point to a primitive value (e.g., {colors.primary-60}), not a group. Within the components section, references to composite values (e.g., {typography.label-md}) are permitted.” So a reference has a resolution contract that varies by section — primitives outside components, composites allowed inside it. A checker that applies one rule everywhere will produce false positives on component typography and false negatives on group references in colors.

Two more structural facts: the canonical section order is Overview (alias Brand & Style), Colors, Typography, Layout (alias Layout & Spacing), Elevation & Depth, Shapes, Components, and Do’s and Don’ts — sections may be omitted, but those present “should appear in the sequence listed.” And the recommended token names (colors primary, secondary, tertiary, neutral, surface, on-surface, error; typography headline-display through label-sm; rounded none through full) are explicitly not required. Name-based checks are therefore advisory only. Value-based checks are the ones you can enforce.

What a compliant consumer must do

The specification assigns consumer behaviour for four cases, and those four cases map almost one-to-one onto a severity ladder:

Situation Documented consumer behaviour
Duplicate section heading (two ## Colors) Error; reject the file
Unknown section heading Preserve; do not error
Unknown color token name Accept if value is valid
Unknown component property (e.g. borderColor) Accept with warning

The duplicate-heading rule is the only hard rejection in the retrieved documentation, and it is a file-level failure, not a token-level one. That distinction is worth internalising: a DESIGN.md with two ## Colors sections is not a drifted contract, it is an unparseable one. Your checker should stop before it compares anything.

The DTCG side of the bridge

DESIGN.md’s token system is described in the unofficial translation as “inspired by the W3C Design Token Format,” with tokens “easily converted to and from tokens.json, Figma variables, and Tailwind theme configs.” That inspiration is not identity. The Design Tokens Community Group Format Module 2025.10 specifies a stricter machine format, and the gaps between the two are exactly where a drift check needs a bridge rule.

The $type inheritance rule

In DTCG 2025.10, a token is marked structurally: “An object with a $value property is a token.” Type is resolved by inheritance — a token without an explicit $type inherits the type of the closest parent group that declares one. And then the hard clause, from the DTCG format specification: if none of the parent groups carry a $type property, the token’s type cannot be determined and the token “MUST be considered invalid.”

Read that as a validation gate, not a lint suggestion. Under DTCG, an untyped token is not a token with a missing nicety; it is invalid data. The same specification also warns that names differing only in case are “likely to cause identical and undesirable duplicates” in some export targets — a signal that color.Primary and color.primary are a real hazard even when your current toolchain tolerates both. The DTCG 2025.10 format module further defines $extends as “syntactic sugar for JSON Schema’s $ref,” performing a deep merge with local overrides, and gives dimension validation rules their own subsection (§8.2).

Structural mismatch: per-token typing versus per-section typing

Here is the fault line. DTCG types individual tokens through $type inheritance. The DESIGN.md schema as documented carries no $type field at all — typing is implied by which section a token lives in. colors: entries are Colors. rounded: entries are Dimensions. spacing: entries are Dimensions or bare numbers.

Aspect DESIGN.md (per unofficial translation) DTCG 2025.10
File shape YAML front matter + markdown body with ## sections Pure JSON token tree (plus a separate resolver/modes layer)
Typing model Implicit, by section membership Explicit $type, inherited from closest parent group
Token marker Section membership + key name Object containing $value
Reference syntax {path.to.token} in string values {path.to.token}-style aliases within $value
Unresolvable type Not addressed by the documented schema Token MUST be considered invalid
Duplicate handling Duplicate ## heading → error, reject file Case-only name differences: tools MAY warn; the spec calls them a likely duplicate hazard in some export targets
Maturity Described as evolving and draft-stage Published stable specification (2025.10)

The maturity row is qualitative and comes from editorial commentary, not measurement. DesignWhine’s overview of DESIGN.md states plainly that “the exact format is still evolving,” and that a draft specification “still needs adoption, stable semantics, governance and support from tools that are not controlled by Google.” The same piece frames the two formats relationally: DESIGN.md is “broader and more narrative,” while DTCG is “narrower and more formal about token data.” That is an opinion, and it is labelled as one here.

A computable drift-check contract

What follows is a specification of a check, not a description of a tool that exists. No retrieved source documents a linter that compares generated CSS to a DESIGN.md file. These are rules derived from the two specifications, stated so that you or your team can implement or argue with them.

R1–R2: Parse and index

R1 — Front matter extraction. Accept the file only if it begins and ends its front matter with lines containing exactly ---. Parse the YAML. If parsing fails, stop with a file-level error.

R2 — Token indexing. Index every token by its section path: colors.<name>, typography.<name>, rounded.<name>, spacing.<name>, and components.<component>.<property>. Preserve raw values as strings alongside parsed values, because spacing permits bare numbers and typography.fontWeight treats bare numbers and quoted strings as equivalent — a checker that normalises early loses the ability to distinguish “declared as 600” from “declared as ‘600’”.

Also index section headings and count them. Two headings that normalise to the same section name is a file-level rejection under R5, not a token-level finding.

One thing R2 cannot do: the retrieved documentation does not define a machine-checkable mapping from a DESIGN.md token to the CSS custom property name a generated stylesheet should use. So the check needs a naming map you supply — colors.primary → --color-primary, or whatever your convention is. That map is your invention, not the spec’s, and it should be versioned alongside the contract.

R3: Reference resolution

R3 — Every {path.to.token} reference must resolve to a token; outside components it must terminate at a primitive.

Walk every string value that matches the reference pattern. Resolve the path against the index from R2. Then apply the section-scoped rule:

  • Outside components, the target must be a primitive value (a Color, a Dimension, or another primitive) — not a group node and not a composite Typography object.
  • Inside components, a reference to a composite such as {typography.label-md} is permitted.

An unresolved path is hard drift. A reference that resolves to a group where a primitive is required is hard drift. A reference that resolves to a composite outside components is hard drift.

R4: Value-shape checks

R4 — Every literal in generated CSS must match a declared token value, or fail its shape check.

Take the emitted stylesheet. For each declaration whose property maps into a tokenised domain (color, spacing, radius, type), classify the literal:

  • A color literal must parse as # plus sRGB hex and must equal the value of some colors.* token (after your naming map is applied to decide which token should have been used).
  • A dimension literal must parse as number plus one of px, em, rem and must equal the value of some spacing.* or rounded.* token.
  • A bare number where a dimension is expected, or a unit outside the permitted set, fails the shape check outright.

A literal that matches no token value is hard drift. A literal that matches a token value but was emitted for a property that maps to a different token is also drift — but it is the semantic kind, which R4 cannot distinguish. Flag it and hand it to a human. More on that in the limits section.

R5: The severity ladder

Four levels, ordered by what the spec actually says:

  1. Invalid file — duplicate section heading. Reject; do not compare. This is the spec’s only documented hard rejection.
  2. Hard drift — unresolved reference, group-where-primitive reference, literal matching no token value, unit outside px/em/rem. The contract is violated.
  3. Warning — unknown component property (the spec says accept with warning), case-only token-name collisions (the DTCG spec’s duplicate hazard), and value-matches-but-wrong-token findings.
  4. Informational — unknown section heading, preserved not errored; unknown color token name with a valid value, accepted per spec.

The ladder matters because it stops the checker from becoming noise. If every unknown heading is an error, teams stop reading the output, and the duplicate-heading rule — the one rule the spec makes mandatory — gets buried.

R6: The DTCG bridge rule

R6 — Infer $type from DESIGN.md section before applying DTCG validity.

DESIGN.md, as documented, carries no per-token $type. Its typing is positional: colors: → Color, rounded: → Dimension, and so on. So the DTCG rule that an untyped token “MUST be considered invalid” cannot be applied to a DESIGN.md file directly — every token would be invalid, which is useless.

The bridge is mechanical: when you export or compare against a DTCG representation, assign $type from the source section, then run DTCG validation on the result. A token that lands in a DTCG tree with no inferable type after bridging is genuinely invalid — that happens when a token appears in a section the bridge doesn’t map, or when a nested group inherits nothing. This is the one place where the DTCG 2025.10 format module gives you a hard, quotable gate; use it after the bridge, never before.

Edge cases the spec already settles

The most useful test of any contract is whether it survives its own examples. Here is an observation about the retrieved translation’s example text, not a claim about the official specification: the sample button-primary component references {colors.primary-60} and {colors.primary-20}, while the front-matter example’s colors: block defines only primary, secondary, and tertiary. The keys primary-60 and primary-20 are never defined in the shown example.

A strict resolver — exactly the R3 rule above — fails on the specification’s own illustrative example. This is not a scandal; it is a normal artefact of hand-written documentation examples. But it teaches two practical lessons. First, run your checker against the spec’s examples before you run it against your own contract, and expect at least one finding. Second, treat unresolved-reference errors as possibly documentation bugs rather than automatically as generator bugs. The report should say “this path does not resolve in this file,” not “the model invented a token.”

The other edge cases are all settled explicitly by the consumer-behaviour table, and they collapse neatly into the severity ladder:

Drift signal Rule Severity Spec basis
Two ## Colors headings R5 level 1 Invalid file — reject Duplicate section → error
{colors.primary-60} unresolved R3 Hard drift References must point to a primitive value
{typography.body-md} used in colors R3 Hard drift Composite references permitted only in components
#1A1C1E in CSS matching no colors.* token R4 Hard drift Tokens are the normative values
borderColor on a component R5 level 3 Warning Unknown component property → accept with warning
color.Primary and color.primary both present R5 level 3 Warning Case-only duplicates “likely to cause identical and undesirable duplicates”
## Motion section present R5 level 4 Informational Unknown section → preserve; do not error
colors.brand-violet with a valid hex R5 level 4 Informational Unknown color token name → accept if value is valid

Notice what the table does not contain: any column of measured frequencies. There is no data here on how often any of these fire in the wild, and this guide does not invent any.

What this check cannot catch

Be precise about the boundary, because an over-claimed checker is worse than no checker.

Semantic misuse of correct values. If the generated CSS uses colors.primary for a destructive action, every rule above passes. The value is declared, the reference resolves, the shape is valid. DesignWhine’s commentary puts the general problem well: “A token can tell an agent that color.action.primary resolves to a particular value. It cannot necessarily explain when the primary action is appropriate.” That gap is not a limitation of your implementation; it is a limitation of token contracts as a class.

Contrast and accessibility. Nothing in the retrieved DESIGN.md documentation gives the check an accessibility oracle. A pair of individually valid tokens can combine into an unreadable result. That is a separate audit.

Design intent and hierarchy. Whether a spacing scale of 4 was appropriate for that gap is not encoded. Prose is context, and context is not machine-checkable here.

Any drift rate. No retrieved source measures how often generated UI diverges from a DESIGN.md contract. Any number you see quoted for this is not from these sources.

Whether a generator reads DESIGN.md back during generation. This guide does not assert that any shipped tool does or does not consume the file at generation time. That behaviour is unverified in the retrieved material, and it changes the meaning of a finding substantially: if a generator never reads the contract, every finding is expected; if it does, findings are deviations.

Whether a linter exists. No retrieved source documents a tool that lints generated CSS against a DESIGN.md contract. The rules above are a specification you implement, not a product recommendation.

FAQ

Is DESIGN.md stable enough to build a checker on? Per DesignWhine’s assessment, the format “is still evolving,” and the draft “still needs adoption, stable semantics, governance and support from tools.” That is editorial opinion, and it argues for building the checker around the rules the documentation states explicitly — duplicate headings, reference resolution, value shapes — rather than around anything inferred.

Does DTCG replace DESIGN.md? No, and the framing is not either/or. The DesignWhine comparison describes DESIGN.md as “broader and more narrative” and DTCG as “narrower and more formal about token data.” They solve different problems: narrative rationale for agents and humans, versus a formal exchange format for tooling. R6 is the bridge between them.

Why does a strict resolver fail on the specification’s own example? Because the example’s button-primary references {colors.primary-60} and {colors.primary-20}, and the front-matter example’s colors: block defines only primary, secondary, and tertiary. That is an observation about the retrieved translation’s example text, not a claim about the official specification. Run your checker on the examples first; expect one finding.

Can Style Dictionary run this check? The Style Dictionary homepage describes the tool as “forward-compatible with the Design Tokens Community Group spec.” That is the only claim made here. Whether its build semantics map a token name to a particular CSS custom property, and how any naming transform behaves, was not retrievable and is not asserted.

How does Tokens Studio fit? The Tokens Studio documentation describes Tokens Studio for Figma as allowing you to “integrate Tokens into your Figma designs.” That is the extent of what is claimed here. No claim is made about its format handling or its relationship to DESIGN.md.

How is this different from build-output drift? Different artifact pair. Build-output drift compares a token source against the CSS custom properties a pipeline emits — a transcoding question. Generation drift compares generated UI CSS against the DESIGN.md contract — an obedience question. A clean build tells you nothing about the second.

The Bottom Line

DESIGN.md is machine-checkable today exactly where its specification is explicit, and nowhere else. Three things are enforceable without invention: the duplicate-section rejection rule, reference resolution against the documented primitive-versus-composite rules, and value-shape conformance to the documented Color and Dimension types. Those give you a real drift check with a defensible severity ladder.

Everything else requires you to supply something the spec does not: a naming map from token path to CSS custom property, a section-to-$type bridge if you want DTCG’s validity gate to mean anything, and a human for every finding that is a correct value in the wrong place. The typing gap is structural — DTCG types tokens, DESIGN.md types sections — and R6 is the honest way across it.

Treat maturity expectations accordingly. A format described as still evolving, in an unofficial translation because the official page was unreachable, is a format you check conservatively and version carefully. Build the rules that the documentation states, mark the rest as warnings, and keep the human review step. The failure mode to avoid is a checker that produces confident output about things the contract never said.

How This Guide Was Built

This post is based entirely on the specifications and articles listed below. It was not run hands-on: no checker was implemented, no generated CSS was compared against a DESIGN.md file, and no results, rates, or benchmarks are reported. Every factual claim about the DESIGN.md format traces to the unofficial translation of the Stitch DESIGN.md specification; every factual claim about token typing traces to the DTCG Format Module 2025.10.

Provenance and retrieval failures, stated plainly:

  • The official Stitch DESIGN.md documentation page could not be retrieved on 2026-11-21 — both extraction engines failed. All DESIGN.md specification facts in this article come from an independent, unofficial translation, which labels itself as translated from the official documentation and not authoritative. Spec details here are accurate to that translation and unverified against the origin.
  • The DTCG Format Module 2025.10 was retrieved in full and is the source for $value, $type inheritance and invalidity, case-collision wording, $extends, and the dimension validation section.
  • The Style Dictionary homepage and Tokens Studio documentation returned stub content only. Each is cited for exactly one descriptive claim, and no build-behaviour or naming-transform claim is made from either.
  • DesignWhine’s article is editorial commentary and is attributed as opinion wherever used, particularly on format maturity and on the narrative-versus-formal contrast with DTCG.
  • The unresolved-reference observation in the spec’s own button-primary example is an observation of the retrieved translation’s example text, labelled as such, not a claim about the official specification.

The drift-check contract (R1–R6), the severity ladder, and the two tables are this guide’s synthesis of those documents. They are a specification for a check, not a description of an existing tool.