Compare
Four ways to hand over a design system.
Tokens, a Figma library, a registry item and a DESIGN.md are not competitors; they answer different questions. The table says which, and every claim about ours links to the live file it is about.
| DESIGN.md | Design tokens (DTCG) | Figma library | shadcn registry item | |
|---|---|---|---|---|
| Who reads it | A coding agent, then a person | A build step (Style Dictionary, Tokens Studio) | A designer in Figma | The shadcn CLI, once |
| Carries the values | Yes, in hex and OKLCH, both modes | Yes, that is all it carries | Yes, as variables and styles | Yes, as CSS variables |
| Carries the rules for using them | Yes: eight numbered, checkable constraints | No | By convention, in a designer's head | No |
| Carries measured contrast | Yes, every pair an agent will produce, WCAG 2.1 | No | Only if a plugin adds it | No |
| Says where it came from | Yes: source link, default mode, fingerprint | Only via $extensions, if the author bothers | No | Homepage field only |
| Can prove a copy is still current | Yes: fingerprint fnv1a-b613a475 + verify_design_md | No | Library versioning, inside Figma only | No |
| Installs into a codebase | Via the registry item it links to | Via your build pipeline | No | Yes, one command |
| Readable by a human | Yes, it is Markdown | Barely | Yes, visually | No |
| URL you can hand an agent | https://csscreme.com/d/deep-ocean.md | https://csscreme.com/d/deep-ocean.tokens.json | A file behind a login | https://csscreme.com/r/deep-ocean.json |
The DESIGN.md column is checkable: Deep Ocean is the live file every row describes, its DTCG tokens and registry item come from the same source, and the fingerprint above is the one printed in the file today.
When to use which
Use tokens
when a build pipeline is the reader. Style Dictionary, Tokens Studio and Figma Variables all speak DTCG, and values are all they need.
Use the registry item
when you want the tokens in globals.css right now. One command, done. It carries no rules, so pair it with the file that does.
Use Figma
when the system is still being designed. When it ships, decode the shipped site instead of trusting the file to still match.
Use the DESIGN.md
when an AI is about to write UI. It is the only one of the four that carries the rules, the measured contrast, and a way to prove the copy is current.
Questions
Do I need a DESIGN.md if I already have design tokens?
If a build step is the only reader, no. If an AI is about to write UI, yes: tokens tell it the values and nothing about how to use them, so it will still invent a second radius or a third font. The DESIGN.md carries the tokens and the rules, and every CSS Crème theme publishes both from the same source, so they cannot disagree.
Is a DESIGN.md a replacement for Figma?
No. Figma is where a system is designed; a DESIGN.md is how a shipped or curated system is handed to an agent. The DTCG tokens file bridges them: import it into Tokens Studio or Figma Variables and the Figma side matches the file the agent reads.
Why does the URL matter?
An agent can fetch a URL. It cannot open a Figma file. Every CSS Crème artefact lives at a readable, stable URL with the theme name in it, so a person can read the address and an agent can pull it without an account or a key.
Related: the DESIGN.md specification · what galleries charge to submit · the MCP server