What’s in your DESIGN.md

Your DESIGN.md is written for agents first and people second. Each section answers a question an agent would otherwise guess at.

How the file is laid out#

The file opens with your product name and what it does, then runs section by section: color, dark theme, typography, spacing, shape, elevation, components, icons and voice. Every value appears once, in the section that explains what it is for, so an agent reading top to bottom never has to reconcile two copies of the same number. That keeps the file small enough to load on every UI task. The same tokens as CSS custom properties and a Tailwind @theme block are separate downloads, ready to paste into your stylesheet. Where you picked a Tailwind color, the Tailwind download points at Tailwind's own palette, so your tokens track whichever version your project runs.

Color#

Color roles come first, because they are what components should use: color-action for primary buttons, color-border for dividers, color-text-muted for metadata, and so on. Each role shows the ramp step it points at and what it is for. Below the roles, the file names the first step that holds 4.5:1 as text on white, so an agent can tell which steps are safe for text. A palette you took from Tailwind is named rather than spelled out, since the hex values are already in your project. Anything Onefold generated for you, or read off your website, is listed step by step.

Signal colors#

Success, warning, danger and info each get three roles: the color itself for text and icons, a -quiet background and a -line border. The file states that pattern once and then lists only what differs per signal, so an agent knows how to build a banner or a badge without reading twelve near-identical rows.

Dark theme#

If your product has a dark theme, the roles table carries a dark value next to every light one, and this section says how dark turns on: the system setting, a dark class or a data-theme attribute. Dark roles point at steps of the same ramps, so one brand color produces both themes. Agents keep using role tokens, and components switch themes without extra dark: styles. Any role that would be hard to read in dark is called out by name. If your product is light only, the file says that instead, so agents don't add a dark theme you never designed.

Typography#

Your typefaces for headings, body and code, and a type scale from text-xs to text-5xl, with sizes, line heights and what each step is for.

Spacing#

Your grid, 4px or 8px, and a spacing scale built on it, with names that match Tailwind: spacing-4 is p-4. Roles such as spacing-control, spacing-card and spacing-section say which step to use for padding inside a button, padding inside a card and the gap between page sections, so agents stop picking p-4 for one card and p-6 for the next. Arbitrary values such as p-[13px] are ruled out.

Shape and elevation#

The corner radius for chips, controls and cards, and four shadow levels, from resting cards to dialogs. Agents pick a shadow by layer instead of by eye.

Components#

The component library your product builds with, such as shadcn/ui on Base UI or Radix, MUI or Mantine, and the path to your own components if you have one. Agents reuse those components before creating new ones and don't install a second library. Components take their look from the tokens in the file. If your product has no component library, the file says so, and agents ask before adding a dependency.

Icons#

Your icon set with its package, license, grid and style, plus an import example. Agents use only that set instead of adding another one or drawing one-off SVGs. If your set has a filled style, the file says when to use it, such as for active and selected states. Icons are sized to the text next to them, and icon-only buttons get an accessible label.

Voice and tone#

How your product sounds, what to do and not do when writing, and example copy for a button, an empty state, an error and a success message. Lines you pasted from your own guide appear here word for word.

Avoid generic AI-generated UI#

Every DESIGN.md includes this section, whatever you chose in the wizard. It tells agents to skip the patterns that make an interface look generated: decorative gradients and glows, eyebrow labels above headings, cards inside cards, filler text, helper text that only restates the obvious, hype words, Title Case and em dashes.

Not defined yet#

Anything you skipped is listed at the end, with an instruction to ask you instead of inventing a value. Fill those gaps later in the wizard and download the file again.