What is DESIGN.md? The design file AI coding agents read (with free mobile app examples)

DESIGN.md is a Markdown file that describes a product's visual identity for AI coding agents. The Google Labs format pairs optional YAML design tokens with written guidance on how to use them. It gives an agent concrete colors, typography, spacing, and component rules to read before generating an interface.

For mobile app developers, the useful part is being able to carry those choices into the next screen. Start with a file from our free mobile DESIGN.md library, inspect the screens beside it, and adapt the rules to your app.

Who made DESIGN.md?

Google Labs publishes the DESIGN.md format used by Stitch. Google introduced DESIGN.md import and export in its March 2026 Stitch announcement, then open-sourced the draft specification in April. The official repository still labels the format alpha, so check its current spec when building an integration.

A file named DESIGN.md can also be an ordinary project document. When sharing one, say which format it uses and keep the raw text available for inspection.

What goes in a DESIGN.md file?

The Google Labs specification describes a Markdown body with optional YAML frontmatter. Token groups cover colors, typography, rounded corners, spacing, and components. The body explains decisions such as where an accent belongs or how buttons differ from cards. Exact values and written guidance serve different jobs.

The spec accepts CSS color strings, including hex values. Quote hex colors in YAML: an unquoted hash starts a comment. A reference such as {colors.primary} points to another token in the file. Sleek's library exposes hex swatches alongside the original text so you can check the palette before downloading it.

What does a minimal DESIGN.md example look like?

A starter DESIGN.md can describe one small visual system: a palette, a body style, a spacing value, and a button. The example below is written for this guide. Save it as DESIGN.md, then add rules as your mobile app needs them. It is a starting point, not a finished component library.

---
version: alpha
name: Quiet Blue Mobile
colors:
  primary: "#2459C4"
  on-primary: "#FFFFFF"
  surface: "#FAF8F3"
  on-surface: "#20242B"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  md: 12px
spacing:
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
---
## Overview
A quiet mobile interface with cream surfaces and blue actions.

## Colors
Use primary for actions. Keep reading surfaces cream.

## Typography
Use body-md for reading text. Keep labels short.

## Layout
Use spacing.md for screen gutters and related content groups.

## Shapes
Use rounded.md on cards and buttons.

## Components
Primary buttons use button-primary. Keep one main action per view.

## Do's and Don'ts
Keep text readable at larger system font sizes.
Do not use color as the only signal for an error.

Check your own additions with the repository's lint command. Its findings can help you catch broken references and color-pair contrast issues. Still inspect the rendered screen: a text file cannot show you a clipped label, a confusing control, or a keyboard covering a form.

npx @google/design.md lint DESIGN.md

How do you use DESIGN.md with Claude Code?

Keep DESIGN.md in your project and ask Claude Code to read it for UI tasks. Anthropic's memory documentation explains that CLAUDE.md imports load at session startup. Use a plain path reference for on-demand reading, or a rule in .claude/rules/ with paths patterns matching your UI files.

For example, add this instruction to CLAUDE.md without an @ import:

For UI tasks, read DESIGN.md before creating or changing app screens.

Then ask for a specific screen and its states. For example, ask for a task list with an empty state and a failed-sync state. Review whether the generated UI follows the file's values, and update the file when you deliberately change the design. Our guide to designing with Claude covers the broader workflow.

How do you use DESIGN.md with Cursor or Stitch?

In Cursor, explicitly attach DESIGN.md to the task or reference it from a project rule. In Stitch, use its DESIGN.md import and export workflow to carry design rules between projects. The distinction matters: a coding agent needs the file in its context, while Stitch provides a workflow built around the format.

For Cursor, the rules documentation explains project rules and file references. A rule can instruct the agent to read DESIGN.md for UI changes. Choose when the rule applies so that unrelated backend tasks do not carry a long design document.

For Stitch, Google's DESIGN.md announcement confirms that you can import and export design rules between projects. After importing, compare a generated screen with the source and adjust the rules where needed.

How does Sleek use DESIGN.md for mobile app styles?

Sleek stores a design file with each remixable featured reference. When you choose Use this style and describe your app, Sleek passes that file together with your brief into generation. The file describes the aesthetic; your brief determines the app's purpose and content. You can inspect both the screens and the file first.

The reference gallery and DESIGN.md library use the same featured projects. Sleek uses the Google Labs structure and adds component properties such as borders and shadows, which the linter reports as warnings. It also adds guidance for iconography, illustration, hierarchy, and distinctive visual details. The style file records visual choices for generating a new app.

Open a style in the library to copy or download its DESIGN.md, or choose Use this style in Sleek to enter your app idea. If you want to drive Sleek from your coding environment, the agent setup guide explains that separate integration.

DESIGN.md FAQs