# DESIGN.md

> One plain file that explains how your design system works, for people and agents alike.

- Drop: Spec (epic)
- Season 1 – The AI-ready Design System
- Status: Tested (used on real work)
- Published: 2026-09-18
- URL: https://www.mlynarz.com/grist/design-md
- Curated by: Dawid Młynarz

**Hint:** 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

1. Write it in under 300 lines; split into linked files if it grows.
2. Link to token and component files; never paste values.
3. Write rules as do and don't, naming the component each applies to.

## The drop

````markdown
# 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.
````