Design system field report
Design teams are converging on DESIGN.md, a plain file of tokens and rationale an agent reads before it builds anything. This week Atlassian and Builder.io reported what actually makes it stick.
The open format, built for Google's Stitch design tool, pairs YAML design tokens (exact colors, type, spacing) with markdown prose explaining why each value exists, so an agent gets both the numbers and the intent. It ships a linter that flags broken token references and contrast below WCAG AA, and exports straight to a Tailwind v4 theme.
github.com/google-labs-codeBuilder.io argues the usual fix, an ever-growing rules file, fails because a repo with five ways to build a form holds five design systems and the agent copies whichever is nearest. The durable approach is a small map of canonical folders, deterministic token enforcement in the linter, and a golden directory of reference implementations the agent can imitate.
The same instinct is turning up in products. Beaver Builder AI, this publication's publisher, builds from design kits and system tokens rather than a blank prompt, the move these files make portable.
builder.io/blogAtlassian's design-system team tested DESIGN.md and watched generic output turn recognizably Atlassian, with correct color, spacing, and elevation. As the sole source of guidance, though, a single login screen ran about 92 percent more tokens with 2.7 times the variance of their own design-system server and skills. The file is a strong portability format and a weak substitute for richer tooling.
atlassian.com/blogField note
The most useful DESIGN.md files do half their work as a list of refusals: no glassmorphism, no gradient hero, no three identical feature columns. This publication has spent a month cataloguing those tells. The shift worth noting is that the catalogue now compiles, and the agent reads it first.
Prompt lab
Design a single web page styled as a design-system reference, the spec sheet for a small visual identity. Layout: a monospace top bar with the project name, nav, and a spec tag. A masthead title block: an eyebrow, a serif headline, one deck sentence, and a row of spec metadata (issue, date, read time, section) as labeled mono cells. Below it, a framed figure showing the design system as a file. Then a tokens-and-type panel: a color token table (swatch, role name, hex) beside three type specimens (display, body, mono). Then numbered spec sections, each opened by a section number, a serif title, and a quiet role label; inside each, one guideline entry with a small clay marker, a linked headline, two sentences of context, and a source domain. Close with a field note, a prompt block, and a numbered sources list. Palette: warm espresso ground #1B1714, panel #241F1B, warm bone text #F3ECE1, one clay accent #D9764C for links and markers, a sage #8FA86B reserved for genuine approval marks, and a brick #C25A47 reserved for refusal marks. Dark, but warm and deliberate. No neon, no glow, no gradient. Type: Fraunces for the headline, section titles, and one italic pullquote; Hanken Grotesk for body at 19px with line height 1.65; Space Mono for tokens, labels, metadata, and the prompt block. Components: token tables with swatch chips, type specimens, numbered spec sections, guideline entries, a do-and-do-not list, a sources table. Card radius 14 to 16px, chip radius 5 to 6px; vary radius and padding with intent. Guardrails: every text color meets WCAG AA on its real surface, small mono labels included. Hover and focus states with 140ms easing and a prefers-reduced-motion guard. No fake search fields, toggles, or active filter pills. Any embedded specimen uses short honest text, never garbled labels.
Works in Beaver Builder AI, v0, Lovable, Cursor, and other prompt-to-page tools. Save the palette and type lines as your own DESIGN.md and the page becomes reusable.
Sources