DESIGN.md: give Codex your design system.

DESIGN.md is a plain-text file that describes your design system to AI agents: exact colors, type, spacing, and components, plus the reasoning behind them. Put one in your repository and Codex designs every new screen in the same visual language.

Updated November 2, 2026 · 8 min read

What is DESIGN.md?

DESIGN.md is an open format from Google Labs for describing a visual identity to coding agents. It started in Google Stitch, is published under the Apache 2.0 license, and the specification is still marked alpha, so expect changes.

A DESIGN.md file has two layers:

Design tokens in YAML. Exact, machine-readable values: colors, typography, corner radii, spacing, and component styles. The tokens are the normative values.
Markdown prose. The reasoning: what the product should feel like, when to use each color, and what to avoid. The prose tells the agent how to apply the tokens.

Without a file like this, an agent picks a new shade of blue and a new button style every time you ask for a screen. With it, the fiftieth screen matches the first.

What goes in a DESIGN.md

The tokens can sit in YAML front matter at the top of the file, or in fenced yaml blocks inside each section. The schema has five token groups:

Group	What it holds	Example
`colors`	Any CSS color; at least `primary` is required	`primary: "#1F3D2B"`
`typography`	Font family, size, weight, line height	`body-md: { fontSize: 16px, ... }`
`rounded`	Corner radius scale	`md: 12px`
`spacing`	Spacing scale	`md: 16px`
`components`	Component styles, with references to tokens	`backgroundColor: "{colors.primary}"`

The prose uses ## sections. Any section can be left out, but the ones you include should appear in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do’s and Don’ts.

A complete example

This DESIGN.md describes the reading app used on our mobile app prompts page. Save it as DESIGN.md at the root of your repository.

---
version: alpha
name: Pagely
description: Calm, bookish UI for a reading-habit app.
colors:
  primary: '#1F3D2B'
  on-primary: '#FAF6EE'
  secondary: '#E8735A'
  tertiary: '#F2C14E'
  neutral: '#FAF6EE'
  surface: '#FFFFFF'
  on-surface: '#1F2A22'
typography:
  headline-lg:
    fontFamily: Georgia
    fontSize: 32px
    fontWeight: 400
    lineHeight: 1.15
  body-md:
    fontFamily: system-ui
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
  label-caps:
    fontFamily: system-ui
    fontSize: 13px
    fontWeight: 500
    letterSpacing: 0.12em
rounded:
  md: 16px
  lg: 22px
  full: 9999px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: '{colors.primary}'
    textColor: '{colors.on-primary}'
    rounded: '{rounded.md}'
    padding: 18px
---

## Overview

Quiet, warm, and bookish, like a café with good light. Screens feel spacious and
unhurried; one clear next step per screen.

## Colors

- **Primary (#1F3D2B):** Deep forest green for primary actions and the streak card.
- **Secondary (#E8735A):** Coral for progress and small highlights only.
- **Tertiary (#F2C14E):** Warm yellow for streak and goal indicators.
- **Neutral (#FAF6EE):** Cream background for every screen, never pure white.

## Typography

Georgia for headlines gives a literary voice. System UI for everything else keeps
body text crisp. Labels are uppercase with wide letter spacing.

## Layout

24px side margins on phones. Spacing follows an 8px scale. Primary actions sit in
the lower half of the screen, within thumb reach.

## Elevation & Depth

No heavy shadows. Depth comes from white cards with a 1px warm border on the cream
background.

## Shapes

Soft and rounded: 16px for buttons and inputs, 22px for cards.

## Components

Primary buttons are full-width, deep green, 18px padding. One primary button per screen.

## Do's and Don'ts

- Do keep text contrast at WCAG AA or better.
- Do use coral sparingly: progress bars and one highlight per screen.
- Don't use pure black or pure white.
- Don't put more than two type sizes in a single card.

How to make Codex follow it

Codex reads AGENTS.md automatically: it starts at the repository root and walks down to the folder you are working in. It does not look for DESIGN.md on its own, so point to it from AGENTS.md:

## Design

- Before any UI work, read DESIGN.md and use only its tokens.
- If a screen needs a value that DESIGN.md doesn't define, ask before inventing one.
- After editing DESIGN.md, run `npx @google/design.md lint DESIGN.md` and fix any errors.

Then ask for screens as usual. Mentioning the file in the prompt makes it explicit:

Design with DESIGN.md

Following DESIGN.md, design the [settings] screen as one self-contained HTML file at 390×844. Use only colors, type sizes, radii, and spacing from DESIGN.md, and tell me if you needed anything it doesn't define.

Write a DESIGN.md with Codex

You rarely need to write the file by hand. If you already have a product, have Codex extract it from your code:

DESIGN.md from your code

Read our Tailwind config, global CSS, and the five most-used components, then write a DESIGN.md at the repository root. Run `npx @google/design.md spec` first and follow that format: tokens in YAML front matter, then the sections Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts. Use only values that exist in the code. Finish by running `npx @google/design.md lint DESIGN.md` and fixing any errors.

For a new product, start from a direction you like, such as a mockup you approved on a canvas or a reference screenshot:

DESIGN.md from a design

Here is the screen design we approved [attach a screenshot or name the HTML file]. Write a DESIGN.md that captures its colors, type, spacing, corner radii, and button style, with a short Overview of how it should feel and five Do's and Don'ts. Follow the DESIGN.md format from `npx @google/design.md spec`.

The @google/design.md command-line tool also checks contrast ratios and broken token references with lint, compares two versions with diff, and turns your tokens into a Tailwind theme or W3C design tokens with export.

DESIGN.md vs SKILL.md vs AGENTS.md

These three files often sit in the same repository and do different jobs:

File	What it tells the agent	Example
`DESIGN.md`	What the product should look like	Colors, type, spacing, component styles
`SKILL.md`	How to do one kind of task, loaded when needed	A design review checklist or workflow
`AGENTS.md`	Standing project instructions, read every time	Build commands, conventions, “read DESIGN.md”

They work well together. A design skill can say “read DESIGN.md before designing anything”, and AGENTS.md makes sure that happens even without the skill. For more on skills, see Codex plugins vs skills.

Where to find examples

The open-source awesome-design-md collection has DESIGN.md files that describe the design systems of well-known websites, each with a preview page. They are useful for learning how others describe color, type, and components. Use them as references for structure, not as a way to copy another company’s brand.

Frequently asked questions

Is DESIGN.md an official standard?

It is an open specification from Google Labs, used by Google Stitch and published on GitHub. The specification is still alpha, and its own documentation says the format will change.

Does Codex support DESIGN.md?

Codex can read and follow any file in your repository. There is no special setting: reference DESIGN.md from AGENTS.md or from your prompt, as shown above.

Does DESIGN.md replace Figma or a design system?

No. It is a text summary of your design system that agents can read. Teams that keep their source of truth in Figma or in code can generate DESIGN.md from it and update it when the system changes.