DESIGN.md for Design Systems: What Fits in the File
Nezar Mansour · 3 November 2026
Read the originalNezar Mansour of Supernova, a design-system documentation company, found a DESIGN.md file for Skyscanner's design system held 32 of 434 tokens, so AI agents need the system for exact values.
Nezar Mansour, a content writer at Supernova, which makes software that documents design systems for teams and AI agents, wrote about a new file format. DESIGN.md, from Google Labs, is a text file that describes a product's visual identity to AI coding agents, and its specification is still a draft. Mansour wrote one by hand for Backpack, the public design system of the travel search company Skyscanner, to see what fits.
- Backpack's web foundations package has 434 design tokens, and the hand-written file kept 32 of them, including 14 colours, 5 type styles and 3 button entries.
- The draft specification has no field for themes, so the 205 tokens with separate day and night values had no place, and dark mode was left out.
- Each component entry holds eight style properties, so none of the button's 16 named options, such as a loading state, could go in except as prose.
- Values copied into the file can go out of date without warning: Backpack's foundations package had 12 releases in 2026 by early October.
A design-system team can use a DESIGN.md file for what a token list cannot hold, such as colour roles and rules on what to avoid. AI agents can then read exact values from the design system itself. This is the author's advice, and Supernova sells a product that serves design-system values to AI agents.
Write a design system's DESIGN.md file mainly as an overview, colour roles and rules on what to do and avoid, and name the package version its values came from.
Let AI coding agents look up current colour values and component options directly from the design system, instead of from a summary file that goes out of date.
Derived by Working Surface from the article; more in the Playbook. Source line: A DESIGN.md is good at telling an agent what a product should feel like.
7 November 2026: teams using AI agents are judging work by evidence they can check, and are naming the people who decide what counts as good.