How to use DESIGN.md in Google Stitch and other design tools

DESIGN.md is a single file that carries your visual identity between design tools and AI coding agents. Google Stitch reads and writes it natively through Settings, Figma plugins and browser generators produce it from styles you already have, and coding agents pick it up from your project root. This covers the full round trip and the four things that break along the way.

The format came out of Google Stitch and was published as an open specification by Google Labs in April 2026. It is not tied to any one tool.

What’s inside the file

Two layers. YAML front matter at the top holds the design tokens — the exact values. Below it, a Markdown body organised into ## sections explains what those values are for.

The specification is explicit about which layer wins: the tokens are the normative values, and the prose provides context for how to apply them. That distinction decides most of the decisions you’ll make when editing the file by hand.

---
name: Roxy Tech Modernism
colors:
  primary: "#3525CD"
  on-primary: "#FFFFFF"
  surface: "#F9F9FF"
  surface-dim: "#D3DAEA"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 1rem
rounded:
  sm: 4px
  md: 12px
spacing:
  base: 4px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

Corporate modernism leaning into minimalism. Generous whitespace and a
restricted palette, so the interface reads as calm and controlled.

The body uses a fixed set of section headings in a fixed order: Overview (or Brand & Style), Colors, Typography, Layout, Elevation & Depth, Shapes, Components, then Do’s and Don’ts. Sections are optional, but the ones you include should appear in that sequence. Two sections with the same heading will be rejected.

Where the file comes from

You rarely need to write one from scratch. There are four practical starting points, and none of them requires a terminal.

Some Figma plugins emit a SKILL.md alongside the DESIGN.md. That’s a separate format aimed at agent instructions rather than visual identity; you don’t need it for this workflow.

Importing into Stitch and checking it landed

Support in Stitch is native, since the format originated there. Open your project and go to Settings → Design System → Import DESIGN.md, then either select the file or paste its contents. Stitch validates the file and applies the rules.

The step people skip is the one that matters. After importing, Stitch shows a summary of what it read:

• The colour palette, as swatches
• The typographic scale
• The spacing scale
• Component patterns
• Constraints from your Do’s and Don’ts

Read that summary against your actual design system before generating anything. A file can import cleanly and still be missing half of what you intended, because a value the parser couldn’t interpret is simply absent rather than flagged. The swatch grid is the quickest tell: count the colours.

Once imported, the rules apply to every generation in that project. You don’t reference the file in each prompt.

Create a dashboard with sidebar, header, and a grid of cards

The four things that go wrong

Import problems cluster into four causes, and only one of them announces itself. They’re listed here in order of how much time they tend to cost rather than how often they happen.

The design system is stale

This is the one that costs the most time, because nothing looks broken. Stitch does not watch the file for changes. Edit your DESIGN.md in Figma, in a browser generator, or by hand, and the project carries on using the version you imported.

The design system in your project is the one you last imported, not the one in your file.

Re-import after every edit. If you’re iterating on the palette, make re-import part of the loop rather than something you remember to do.

The import fails outright

Almost always the section headings. Stitch expects the standard structure — ## Colors, ## Typography and so on — to parse the file. Renamed headings, translated headings, or a body that’s one long block of prose without ## sections will fail.

Keep the headings in English and in the spec’s spelling even if the rest of your documentation is in another language. They’re part of the format, not copy.

Colours aren’t recognised

Use hex. A colour described only by name — “dark blue”, “warm limestone” — may not be picked up, because there’s no value attached to it. Evocative names are useful in prose, but they need the hex beside them.

## Colors

- **Primary (#3525CD):** Deep Indigo, the sole driver for interaction.
- **Surface (#F9F9FF):** Near-white ground for page and card fills.
- **Surface Dim (#D3DAEA):** Recessed panels and disabled fills.

Naming the value, the label and the token together means a tool has nothing left to infer.

Components aren’t applied

The Components section needs concrete values. “Rounded button with brand colour” is a description; it isn’t something a tool can execute. Give it the radius, the padding and the token.

Writing values a tool can act on

Three habits separate a file that changes the output from one that gets read and largely ignored.

Name tokens by role, not appearance. primary, surface, surface-dim, border-subtle and text-muted all say where the value goes. blue, gray-1 and brand-color-2 describe what something looks like, which is no help in deciding where to put it — and they become misleading the first time the brand shifts hue. Forcing every colour into a role also works as a palette audit: values you can’t assign a role to are usually unused, near-duplicates, or mistakes that shipped.

Give every interactive component its states. Most files describe only the default. The format expresses variants as separate component entries with a related key name, so hover, active and disabled each get their own entry rather than a sentence.

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-container}"
  button-primary-disabled:
    backgroundColor: "{colors.surface-dim}"
    textColor: "{colors.text-muted}"

Component properties are a fixed set: backgroundColor, textColor, typography, rounded, padding, size, height, width. Anything outside it is accepted rather than rejected, which means an invented borderColor will sit in your file looking correct and do nothing. Put those in the Shapes or Elevation & Depth prose instead.

Write the boundaries, not just the intent. Do’s and Don’ts is the last section and the one most files omit. It’s where you say where a value must not appear, which is the guidance that actually prevents drift.

## Do's and Don'ts

- Do use `primary` for a single dominant action per view.
- Don't use `primary` for large background fills or decorative
  illustration — at that surface area it overpowers the layout.
- Don't introduce a colour outside the palette for state changes.
  Derive states from `surface-dim` and `primary`.

Referencing tokens inside prose keeps the two layers tied together, so a tool reading the sentence can resolve it to a value.

Where the tools and the written spec diverge

Worth knowing before you debug something that isn’t broken. The published specification treats the YAML front matter as the normative layer. Stitch’s importer, going by its own documentation, parses the Markdown body and extracts structured values from the sections — which is why its troubleshooting guidance is about headings and hex values in prose rather than about token syntax.

In practice this argues for redundancy rather than choosing a side. Define the token in the front matter, and state the value in the prose too. A file written that way survives both parsers, and the duplication costs you nothing except a little discipline when values change.

The format is at version alpha and under active development, so expect this gap to move.

Handing the file to coding agents

Export from Settings → Design System → Export DESIGN.md. Save the result at the root of your project, where agents look for it. Claude Code, Cursor, Kiro and Windsurf all read repository files, and the format is the same one Stitch wrote — there’s no conversion step.

Keep the file in version control even if you never leave Stitch. You get change history on the design system itself, and the same file can be used by tools outside the Google ecosystem at the same time.

Browser-based generators can also export the tokens to Tailwind config or to the W3C DTCG tokens.json format if your front-end build consumes tokens directly. There’s a command-line validator published alongside the specification as well, which is only worth setting up if you want the file checked automatically in a build pipeline — nothing in this workflow needs it.

Before you generate anything

1. Confirm the file has a primary colour and at least one typography definition. Missing either, and the tool supplies its own.
2. Check every colour has a hex value attached, not just a name.
3. Read the import summary and count the swatches against your palette.
4. Make sure component descriptions carry values, not adjectives.
5. Add hover, active and disabled for anything interactive.
6. Re-import after any edit to the file.

Common questions