tl;dr
One plain file that explains how your design system works, for people and agents alike.
For when your system lives in a docs site, some Figma files and a few people's heads. You end up with a DESIGN.md at the root of the repo that agents read first.
Why
I wrote one for my own design system. Agents read files in the repo, not your documentation site, so this is the first thing they open. It links to the real tokens and components instead of copying their values, which keeps it from going stale. Once it existed, what the agents built came out more streamlined and consistent.
DESIGN.md is becoming a common name for this file, and that helps. An agent that has seen one before knows what to look for.
Don’t paste token values in. Within a month they won’t match the real ones.
Below the drop is the one for this site, filled in from the same template.
Example
Here’s an illustration of the Layout section. Pages use the 12-column grid (layout/grid). Content never touches the viewport edge; use space-page for margins. Do: stack cards with space-section between groups. Don’t: nest cards inside cards; use list-item instead.
How to use it
- Write it in under 300 lines; split into linked files if it grows.
- Link to token and component files; never paste values.
- Write rules as do and don't, naming the component each applies to.
The drop: DESIGN.md
A template or a section of a file
# DESIGN.md
## What this system is
Who it's for and which products use it, in three lines.
## Principles
3–5 principles, each with a "this means" example.
## Where things live
- Tokens: [path] (a JSON token file in the W3C design tokens format, with descriptions)
- Components: [path], contracts in [path]
- Patterns: [path]
## Foundations
Colour, type, spacing, layout, motion: one paragraph each on how they're used, linking to the tokens.
## Components
The 10 most-used components, one line each on when to use it, linking to its contract.
## Rules
Do and don't pairs, each naming a component or token.
## Accessibility
The guarantees the system makes, and what's left to product teams.
## Changing the system
How to propose a change, and who decides.What you get
My own DESIGN.md, for the design system behind this site. It's the template filled in, so you can see how much goes in each section.
# DESIGN.md
## What this system is
The design system behind mlynarz.com, Dawid Młynarz's portfolio, and Grist.
One site, built in Astro with plain CSS. Light and dark themes from day one.
## Principles
- Tokens only. This means no hex, no raw px for spacing or radius, outside tokens.css.
- Reuse before creating. This means a new variant before a near-duplicate component.
- Complete without JavaScript. This means motion is extra, never needed to read the page.
## Where things live
- Tokens: src/styles/tokens.css, mirrored by name in the Figma file "mlynarz.com — Foundations"
- Components: src/components/ (layout, ui, blocks), all shown on /styleguide
- Patterns: CLAUDE.md (hard rules) and DECISIONS.md (why things are the way they are)
## Foundations
Colour is black and white. Emphasis comes from the inverse surface, and the only colour is --color-danger, for errors. Every --color-* token uses light-dark(), so components never check the theme.
Type is fluid, from the 375 to the 1440 mode in Figma, through --text-* tokens.
Spacing and radius use --space-* and --radius-*. Layout uses Container, Grid, Stack and Section.
Motion lives in one module (src/scripts/motion.ts) and respects reduced motion.
## Components
- Container, Stack, Grid, Section: page layout. Use these before writing layout CSS.
- Button: actions. Variants for primary, secondary and ghost.
- Link: text links, with the hairline underline.
- Figure, Video, BeforeAfter: case study media. Alt text required.
- Tag: short labels on cards.
- Nav, Footer, ThemeToggle: site chrome. One of each per page.
## Rules
- Do use semantic tokens (--color-text). Don't use primitives (--gray-900) in components.
- Do put component CSS in a scoped style inside @layer components. Don't write unlayered CSS.
- Do name classes in BEM (block__element--modifier). Don't copy Webflow classes.
- Do add every new component to /styleguide. Don't ship one that isn't there.
## Accessibility
The system gives visible focus (--color-focus), semantic HTML and reduced motion support.
Product pages still owe alt text and a heading order that makes sense.
## Changing the system
Change a token in tokens.css and in Figma, under the same name. Log anything non-obvious in DECISIONS.md. Dawid approves.