DESIGN.md vs design tokens: choose authority and prevent drift

A design token is a named piece of structured data. It may hold a color, dimension, font family, duration, or reference to another token. Its promise is narrow: a known identifier can be resolved and transformed for a consumer. For example, a token can say that color.action.primary points to one value in light mode and another in dark mode. It cannot decide whether a page should have one primary action or five.

A DESIGN.md provides context for people and coding agents. The current published format can include tokens in YAML front matter, but the document also carries prose about visual direction, roles, components, layout, and constraints. It can explain that the primary action should remain visually scarce, that shadows are forbidden, or that a motif belongs on marketing surfaces but not dense tables.

A component contract makes a third promise. It defines the variants, states, structure, interaction, and content behavior supported by a reusable component. A button contract may specify loading behavior, disabled semantics, focus treatment, and whether an icon-only variant requires an accessible name. Neither a palette nor broad visual guidance can replace it.

Don't appoint an entire file as the universal source of truth. Authority belongs to decisions. One system may make DTCG tokens canonical for color roles, DESIGN.md canonical for layout principles, and component code canonical for supported button states. Each row needs one owner and one precedence rule.

Saying "both are the source of truth" is incomplete. If a color value appears in DTCG and in DESIGN.md, decide whether the document is generated from tokens, tokens are generated from structured front matter, or a review must approve both in one change. Never leave the direction implicit.

Synchronization starts with identity, not copying. Record the approved source version, the exact artifact versions emitted from it, and the consumers expected to receive them. Without those identifiers, people can blame a mismatch on the wrong layer, and "latest" can mean something different to every participant.

• Source identity: system name, version, approval state, owner, and scope.
• Artifact identity: DESIGN.md revision, token package or file revision, generation route, and content hash when available.
• Synchronization direction: which artifact governs each duplicated fact and how the other is updated.
• Supported consumers: named repositories, applications, builders, agents, or transformation pipelines.
• Mappings: the project names or variables that connect an upstream role to each consumer.
• Exclusions: surfaces, modes, components, and behaviors this handoff does not cover.
• Evidence: expected result first, then observed result, environment, date, and reviewer.
• Disposition: accept, revise, or block, with an owner and retest trigger.

Ambient Sage v1 is a useful public example because its kit page exposes several representations of one design direction. The page describes a warm-sage system with Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, light and dark semantic tokens, and a downloadable DESIGN.md. It also lists DTCG, CSS variables, Tailwind v3, Tailwind v4, and shadcn artifact families.

That public evidence establishes upstream availability. It does not establish that a repository downloaded all six families, that every export contains identical coverage, that a particular token transformer accepts the DTCG file, or that a button in a consuming application uses the intended role. Each of those claims requires evidence from the named project and consumer.

This boundary matters when evaluating any design-system generator. Producing several files can be useful, but file count is not consistency. Consistency depends on shared authority, known transformation rules, correct project mappings, component adoption, and observations from representative states.

Keep the record beside the system or in the receiving project's handoff documentation. The format matters less than completing every applicable field. Leave unknown values marked unknown instead of replacing them with assumptions.

dualArtifactContract:
  scope:
    decision: ""
    surfaces: []
    modes: []
    exclusions: []

  source:
    system: ""
    version: ""
    approvalState: "draft | approved | deprecated"
    owner: ""

  artifacts:
    designMd:
      identity: ""
      versionOrHash: ""
      role: "authority | derived | supporting"
    tokens:
      format: "DTCG | JSON | YAML | other"
      identity: ""
      versionOrHash: ""
      role: "authority | derived | supporting"
    generatedOutputs: []

  synchronization:
    governingArtifactByField: {}
    direction: ""
    updateMethod: "generated | reviewed-together | manual"
    conflictPrecedence: ""

  consumers:
    - name: ""
      version: ""
      artifactReceived: ""
      projectMapping: ""
      componentContract: ""
      approvedExceptions: []

  acceptance:
    expectation: ""
    observation: "not-run"
    environment: ""
    evidenceLocation: ""
    owner: ""
    retestTriggers: []
    disposition: "accept | revise | block | pending-evidence"

The contract stores expectations before observations on purpose. This stops a reviewer from seeing an attractive result and retroactively declaring it correct. It also preserves an honest pending-evidence state when the artifact exists but no consumer has been tested.

Consider an illustrative, unexecuted decision: a shared action.primary role should style the main action in light and dark modes. DESIGN.md says to reserve that treatment for the page's principal action and avoid competing primary buttons in the same action group. This example explains the method. It is not a claim about a tested Ambient Sage consumer.

1. 1

   Name the governing decisions

   Let canonical tokens own the exact light and dark values for action.primary. Let DESIGN.md own the selection rule that describes when the primary treatment is appropriate.

2. 2

   Identify every emitted artifact

   Record which DTCG object carries the role and which CSS, Tailwind, or registry output should represent it. Pin versions or hashes instead of referring to "the latest export."

3. 3

   Record the project mapping

   Write the exact path from the upstream role to the project's variable, theme key, utility, or component property. A delivered file without an active mapping remains only delivered.

4. 4

   Inspect the component contract

   Confirm that the button supports the required default, hover, focus, and disabled states and consumes the mapped role. The narrative rule cannot compensate for a missing state implementation.

5. 5

   Select a named consumer

   Choose one real page or flow with a principal action, plus a protected surface that should not change. Record both modes and any relevant viewport or interaction condition.

6. 6

   Write expectations before running the check

   State which element should change, which states should preserve their behavior, and which unrelated elements must remain stable. Leave observations marked not run.

Test a bounded claim instead of asking whether the whole interface "feels consistent." Pick one decision with meaningful reuse and examine each layer in order. Stop at the first divergence. Later symptoms may be real, but the first divergence owns the correction.

1. 1

   Check the approved source decision

   Is the role explicit, current, approved, in scope, and owned? If not, the source needs a decision before anyone can judge downstream files.

2. 2

   Check artifact identity and content

   Do the recorded DESIGN.md and token artifact match the approved source version? Does each contain the part it is expected to carry? A generation failure belongs here.

3. 3

   Check distribution

   Did the named project receive the intended artifact version through the recorded route? A correct upstream file that never arrived is a distribution failure.

4. 4

   Check project mapping

   Does the project map its local name to the intended upstream role in each required mode? Stale aliases, duplicated literals, and the wrong import belong here.

5. 5

   Check the component contract

   Does the shared component consume the mapping and implement the required variants and states? If the contract lacks the required behavior, changing prose or token values will not solve it.

6. 6

   Check approved exceptions

   Determine whether an apparent mismatch is deliberate, bounded, owned, and still within its review period. An undocumented override is drift, not an exception.

7. 7

   Observe representative consumers

   Inspect the named component in both modes and required states under the recorded environment. Capture what happened without promoting the observation into policy.

8. 8

   Choose a disposition

   Accept when the bounded claim is supported. Revise when the intended contract is sound but a correctable layer diverges. Block when required evidence is missing or the mismatch creates unacceptable risk.

• Default, hover, focus, and disabled states for the selected component.
• Light and dark modes when the role has mode-specific values.
• One intended consumer and one protected surface that should remain unchanged.
• A content or viewport condition likely to expose a local override.
• An agent-generated edit, when agent adherence is part of the claim.
• A stale-artifact case when the delivery route can cache or pin versions.

Don't claim that DESIGN.md or tokens "enforce consistency" unless a named mechanism actually rejects, rewrites, or reports violations. A token pipeline may transform data deterministically while an application still bypasses the output. An agent may retrieve DESIGN.md and ignore a rule. Enforcement is a property of the complete workflow, not the file extension.

This order prevents a common waste pattern: patching a page-level value when the generator emitted stale data, or rewriting DESIGN.md when the component never supported the requested state. Correct the owning layer, regenerate or redistribute downstream artifacts as required, then rerun the same bounded cases.

Choose tokens alone when the immediate problem is deterministic value distribution and the consumers already have adequate component and usage rules. Add DESIGN.md when people or agents must make contextual choices that values cannot settle. Use both when the same system needs machine-readable values and portable reasoning, but record which artifact governs every duplicated field.

Start with one reused semantic role. Name its authority, pin the two artifact identities, map it into one real consumer, write the expected result, and inspect the rendered state. Expand the contract only after that first path is traceable.

• DESIGN.md Format specification: The published specification defines DESIGN.md structure and places design tokens in YAML front matter at the beginning of the file.
• DESIGN.md vs Design Tokens: This comparison distinguishes reusable token values from the rationale and usage guidance carried by DESIGN.md.
• design.md vs Design Tokens for AI UI Workflows: This comparison frames tokens around deterministic distribution and DESIGN.md around contextual guidance for coding agents.
• Atlassian's DESIGN.md is here: Atlassian reports practical work compressing an established design system into portable agent context and discusses limits beyond one-shot prototypes.
• DESIGN.md at scale: This guide shows why token values alone do not settle component selection, states, structure, or behavior.
• Ambient Sage Design Kit: The public Ambient Sage v1 page exposes DESIGN.md and lists DTCG, CSS variables, Tailwind v3, Tailwind v4, and shadcn delivery artifacts.