DESIGN.md vs design tokens
Why DESIGN.md complements tokens instead of replacing them.
Different jobs
Design tokens store values. DESIGN.md stores intent, hierarchy, page-level rules, component behavior, and anti-patterns that tokens alone cannot express.
Use both together
The strongest setup is tokens for implementation and DESIGN.md for interpretation. Agents need both to avoid generic UI drift.
Migration path
If you already have tokens, start DESIGN.md as a thin narrative layer on top of them.
Have a public DESIGN.md?
Create an account and submit the source URL so it can be reviewed and indexed in the directory.
Submit DESIGN.md →