# What DESIGN.md is > DESIGN.md is a Google Labs format that gives coding agents a design system they can read. It is at version alpha. Here is what it defines. Source: https://umairalikhatri.com/work/what-is-design-md/ Author: Umair Ali Khatri Updated: 2026-08-29 --- [← Back to work](https://umairalikhatri.com/work/) The format # What DESIGN.md is 29 August 2026 ยท 5 min read DESIGN.md is a file format that tells a coding agent what your design system looks like. One file. YAML tokens at the top, prose underneath. The agent reads it and stops guessing. It came out of Google Labs. It was built for Stitch, Google's design tool, and then open-sourced. The spec lives at github.com/google-labs-code/design.md. The repository calls it "a format specification for describing a visual identity to coding agents" and says it gives them "a persistent, structured understanding of a design system." Persistent is the word doing the work. A prompt lasts one session. A file in the repo lasts as long as the repo does. It is also a draft. The spec header says version: alpha. I will come back to that, because it changes what you should do with it. ## The shape A DESIGN.md has two halves and they do different jobs. YAML frontmatter between --- delimiters carries the tokens. The markdown body below carries the reasoning. The spec is direct about the split. "The tokens are the normative values; the prose provides context for how to apply them." That one sentence is the whole design. Machines read the top half. People argue in the bottom half. ## The keys There are nine frontmatter keys. version, name, description, omitted, colors, typography, rounded, spacing, components. Only name is required. Every other key is optional. The content bar sits lower than most people expect. In the spec's words, "at least the primary color palette must be defined, and additional color palettes may be defined as needed." A name and a primary colour is a valid DESIGN.md. The token keys are plain maps. colors maps a token name to a value. rounded and spacing map scale names to dimensions. typography maps a role like h1 to fontFamily, fontSize, fontWeight, lineHeight and letterSpacing. components is the one that composes. It maps a component name to sub-tokens, and a value can point back at a token defined above, like {colors.primary-60}. ## The sections The body has eight ## sections in a defined order. Overview (or Brand & Style). Colors. Typography. Layout (or Layout & Spacing). Elevation & Depth (or Elevation). Shapes. Components. Do's and Don'ts. The order is defined, not suggested. Three of the eight carry an alternate name, so the format bends on wording and not on sequence. ## The omitted array This is the part worth your attention. omitted is an array where you declare the sections you left out. The spec calls it "an array of sections that are intentionally omitted from the design system. This suppresses linter warnings for missing sections." Read that twice. The format expects you to be incomplete. It only asks you to say so. Most design systems are incomplete. Elevation never got decided. The component list covers four things while the product ships forty. That is normal. Every team pretends otherwise in the documentation. Without omitted, a reader cannot tell a gap from a decision. With it, a missing elevation scale is on the record as a choice. That turns an incomplete design system into an honest one instead of a broken one. It also does something quieter. It stops an agent inventing the missing part. An agent handed a system with no elevation scale will invent shadows. An agent handed a system that declares elevation omitted has been told where the edge is. I use the same move in skill-kit. Files with no canonical source carry status: stub-no-source instead of plausible filler. That was [the curation step](https://umairalikhatri.com/work/how-i-built-a-577-file-design-knowledge-graph/), and it took longer than the build. A declared gap is a work list. Invented content is a lie you cannot grep for. ## The file Here is a complete one. The name and the colour values are the spec's own example, extended into a full file. --- version: alpha name: Daylight Prestige description: A warm, high-contrast editorial system. omitted: - Elevation & Depth - Components colors: primary: "#1A1C1E" secondary: "#6C7278" tertiary: "#B8422E" neutral: "#F7F5F2" typography: h1: fontFamily: Public Sans fontSize: 48px fontWeight: 600 lineHeight: 1.1 letterSpacing: -0.02em body-md: fontFamily: Public Sans fontSize: 16px fontWeight: 400 lineHeight: 1.6 rounded: sm: 4px md: 8px full: 9999px spacing: base: 16px md: 16px lg: 32px gutter: 24px --- ## Overview Editorial, warm, high contrast. Near-black on off-white, one rust accent. Restraint over decoration. ## Colors `primary` is text and every solid surface. `tertiary` is the only accent and it is used once per screen. `neutral` is the page. ## Typography Public Sans throughout. Headings tighten to -0.02em. Body runs at 1.6 for long reading. ## Layout 16px base, 24px gutter. Content column caps at 72 characters. ## Shapes 4px on inputs, 8px on cards, `full` on avatars only. ## Do's and Don'ts Do keep the rust accent to one element per screen. Don't introduce a second typeface. Don't add a shadow. There is no elevation scale here yet. Two sections are missing from that body and both are declared in omitted. A linter reads that as a decision. So does an agent. ## The alpha version: alpha is in the spec header and it is not decoration. Anyone building on DESIGN.md today is building on a draft. Keys can change. The section list can change. What you tool against now may not survive the next revision. Two things the spec does not say, which get repeated as though it did. The spec document states no publication date. Google's own announcement does. Google Labs open-sourced the DESIGN.md draft on 21 April 2026, in a post on the Google blog. The GitHub repository was created on 10 April 2026, checked via the API on 29 August 2026. So the date is Google speaking, not the spec file. It states no licence. The repository is labelled Apache-2.0 on GitHub, checked 29 August 2026. That is the repo, not the document. Small distinctions. They matter when you are deciding what to ship on top. Neither one is a reason to avoid the format. They are a reason to write down which version you read and when you read it. ## The take Write one anyway. Alpha is a reason to keep it small, not a reason to wait. A name, a primary colour and an honest omitted array is twenty minutes of work. It is more than most teams hand an agent today. The rest of this cluster covers what goes in one, and how it sits next to SKILL.md. Start at [agent-ready design systems](https://umairalikhatri.com/work/agent-ready-design-systems/). If your design system needs to work with agents, say hello. Checked against the spec at github.com/google-labs-code/design.md on 29 August 2026. [Back to work](https://umairalikhatri.com/work/)