DESIGN.md generator.

Fill in your colors, fonts, corner radii and spacing, and get a DESIGN.md file that tells Codex and other coding agents how your product should look. It runs in your browser; nothing you type is uploaded or stored.

DESIGN.md

---
version: alpha
name: "Pagely"
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: 600
    lineHeight: 1.15
  body-md:
    fontFamily: "system-ui"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 8px
  md: 16px
  lg: 22px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
---

## Overview

The visual identity of Pagely. Every screen uses only the tokens in this file.

## Colors

- **primary (#1F3D2B):** Main actions and the most important elements.
- **on-primary (#FAF6EE):** Text and icons on primary.
- **secondary (#E8735A):** Supporting accents, used sparingly.
- **tertiary (#F2C14E):** Highlights such as badges and progress.
- **neutral (#FAF6EE):** The page background.
- **surface (#FFFFFF):** Cards, sheets and inputs.
- **on-surface (#1F2A22):** Body text and icons on surfaces.

## Typography

Georgia for headlines, system-ui for everything else. Use the sizes defined above and no others.

## Layout

Spacing follows the scale: 8px between related items, 16px inside components, 24px between sections.

## Shapes

Corners are 8px on small elements, 16px on buttons and inputs, 22px on cards.

## Components

Primary buttons use the primary color with on-primary text. Use one primary button per screen.

## Do's and Don'ts

- Do keep text contrast at WCAG AA (4.5:1) or better.
- Do reuse these tokens instead of inventing new values.
- Don't introduce colors that aren't defined here.
- Don't mix more than two type sizes in one card.

Runs in your browser. Nothing you add here is uploaded or stored.

How to make a DESIGN.md

Name your product and, if you like, describe in a sentence or two how it should feel. That description becomes the file’s description and its Overview.
Set the seven colors: primary, on-primary, secondary, tertiary, neutral, surface and on-surface. Pick them from the swatches or paste HEX codes. If text on one of the pairs would be hard to read (below 4.5:1), the form names the pair.
Set the type: a headline font and a body font, with a size for each.
Set the corner radius and spacing, each as a small, medium and large step (sm, md and lg).
Copy or download the file. It updates as you type, and it starts as a complete example: Pagely, the reading app from our DESIGN.md guide.

The file follows the DESIGN.md format from Google Labs:

Tokens in YAML front matter: your seven colors, a headline-lg and a body-md type style, the corner radius and spacing scales, and a button-primary component that references them.
Prose sections in the order the format sets: Overview, Colors, Typography, Layout, Shapes, Components, and Do’s and Don’ts, with a note on what each color is for and four rules to follow.

Use it with Codex

Save the file as DESIGN.md at the root of your project, next to AGENTS.md. Codex reads AGENTS.md automatically but doesn’t 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.

Then ask for screens as usual:

Design with DESIGN.md

Following DESIGN.md, design the [home] screen as one self-contained HTML file. Use only the colors, type sizes, corner radii and spacing it defines, and list anything you needed that it doesn't.

As your product grows, so can the file. Add more type styles, components such as cards and inputs, or an Elevation & Depth section, by hand or with Codex, and check the result with npx @google/design.md lint DESIGN.md. The DESIGN.md guide covers the full format and how to have Codex write the file from your existing code.

Frequently asked questions

What is DESIGN.md?

A plain-text file that describes your design system to AI coding agents: exact colors, type, spacing and components as YAML tokens, plus prose that explains how to use them. It’s an open format from Google Labs that started in Google Stitch, and its specification is still marked alpha.

Does Codex read DESIGN.md automatically?

No. Codex reads AGENTS.md automatically, not DESIGN.md. One line in AGENTS.md telling it to read DESIGN.md before any UI work is enough, as shown above.

Can I add more than the generator asks for?

Yes. The generator covers the tokens most screens need. The format also allows more type styles, more components and an Elevation & Depth section; add them to the file yourself or ask Codex to.

Is it free, and is what I type uploaded?

It’s free and needs no sign-up. The file is made in your browser, and nothing you type is uploaded or stored.