DESIGN.md examples

In the DESIGN.md file format, the tokens sit in YAML, either as front matter between two --- lines (as in these files) or in fenced yaml blocks: colors, typography, rounded, spacing and components. Components point to other tokens with references such as {colors.primary}, so a button is built from the palette and the type scale. Markdown sections follow in a set order, though any may be left out: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. The tokens are the values to obey; the prose says where and why.

Google keeps the spec and its command line tool in the design.md repository under the Apache-2.0 license. Google says Stitch, its AI design tool, can export and import the format, and a coding agent reads it as plain text, so a person, a design tool and an agent can all work from the same rules.

The files here keep that order and add one heading the spec does not define, ## Motion, before Do's and Don'ts; the spec tells readers to keep an unknown section rather than reject the file. Each has 4 to 13 colour tokens, 8 or 9 type levels, 8 or 9 components and 8 to 10 do and don't rules.

The top of the print studio file shows the shape: four colours, the display level of a two-family type scale, then, much further down, one line of the Motion section.

---
version: alpha
name: "Print studio template by 8B"
description: "Two flat inks, ultramarine and fluorescent pink, with CSS halftone dots and rolling drums for a risograph studio, print shop or small press. Free HTML template by 8B, MIT."
colors:
  primary: "#11138d"
  secondary: "#ed008e"
  tertiary: "#07061f"
  neutral: "#f3f3fa"
typography:
  headline-display:
    fontFamily: Gabarito
    fontSize: 210px
    fontWeight: 900
    lineHeight: 0.86
    letterSpacing: -0.035em
  headline-lg:
    fontFamily: Gabarito
    fontSize: 84px
    fontWeight: 800
    lineHeight: 0.95
    letterSpacing: -0.025em
  headline-md:
  ...
---

## Motion

- **Inks:** the tilted blue and pink plates slide together into a 4 by 4 chart.
...

These files work as design system templates for Claude Code and the other coding agents. Save one in the root of your project; the slug is the last part of the template's page address.

curl -LO https://8b.com/templates/<slug>/DESIGN.md

• Claude Code: add the line @DESIGN.md to CLAUDE.md. Claude Code loads CLAUDE.md as each session begins, along with any file imported this way (its memory docs describe both); without that line, name the file in your prompt.
• Codex: it reads AGENTS.md before it starts work, so a line there that points to DESIGN.md is the simplest hook, for example "Follow DESIGN.md for colours, type, corners, spacing and motion."
• Cursor, Windsurf or Gemini CLI: name DESIGN.md in the prompt, or point to it from the instructions file you already keep for the project.
• Stitch: Google says Stitch can import DESIGN.md files, so bring the file in through Stitch's own import, then ask for screens. The spec has no motion tokens, so the Motion section stays a note for whoever writes the code.

Then ask for one new thing at a time:

Read DESIGN.md first. Build pricing.html for <my product> in this style: only the colours, type levels, radii, spacing and components DESIGN.md defines, and its Do's and Don'ts. Animate it as the Motion section describes, behind a prefers-reduced-motion check. Add no fonts, colours or shadows the file does not list. Show me the page at 1440px and 390px wide.

Used as a Claude Code design system template, the file is enough for new pages. The quickest way to a DESIGN.md website, though, is the HTML it was read from: keep the template's index.html as the first page and hand the agent DESIGN.md for each page after it. The format's tool can also export the tokens as a Tailwind theme or as DTCG tokens.

Read the tokens before the prose: they show at a glance how strict a system is.

• One family, seven files. Fitness club, vet clinic, accountancy practice, accounting firm, app landing, brasserie and festival set every level in one face, so hierarchy comes from size, weight, tracking and case alone. The accountancy practice file runs its headline from 44px on a phone to 118px wide, tracked to -0.055em. A brand font swaps in most easily here.
• A display face and a text face, nine files. The display face often runs condensed or stretched: Mozilla Headline at 75 percent width in the architecture file and at 125 percent and weight 300 for the agency. The construction file is the odd one: Host Grotesk carries nearly everything and TikTok Sans sets a single word.
• Three faces, four files. Pet boarding, community and florist add a Playwrite handwriting face for letters, a signature or large script lines; the trampoline park uses Playpen Sans for its wordmark and stickers. Each keeps the script to a few places, and the pet boarding file bars it from navigation and buttons.
• Corners. Four files, construction, architecture, agency and accountancy practice, declare a single radius, none: 0px. Six more stay square but keep a full radius for pills, circles or drawn shapes, and the repair shop rounds to 2px. The soft end is the vet clinic file, with six radii running from 10px through a 220px corner to fully round, and arched photo frames.
• Ground and depth. The brewery, repair shop, pet boarding and festival files are built on a dark or crimson ground (the repair shop alternates it with off-white sections). The print studio and design studio files alternate full bands of blue or black with paper white. The other fourteen set the page on a light ground such as paper, cream, white, grey, pale sky or blush. Fifteen build depth without soft drop shadows, from flat layers, overlaps, colour steps or hard offsets with no blur. The product launch file is the reverse: its raised and pressed shadows are the style.
• Motion. All twenty load GSAP 3.13 with ScrollTrigger and Lenis; ten add SplitText, and the trampoline park also needs MotionPathPlugin. Each Motion section names its idea in a few words (a press, a print run, pouring, dusk) and then walks the page section by section. For the techniques, see how the scroll effects are made.

Each file sits next to its template's page, so the address is the page address plus DESIGN.md. Pick the business type closest to yours, or the look you want, and fetch that one.

• Accountant: https://8b.com/templates/tallyhouse/DESIGN.md
• Accounting firm: https://8b.com/templates/evenkeel/DESIGN.md
• App: https://8b.com/templates/linea/DESIGN.md
• Architecture: https://8b.com/templates/midblock/DESIGN.md
• Brewery: https://8b.com/templates/loud-kettle/DESIGN.md
• Community: https://8b.com/templates/softlife/DESIGN.md
• Construction company: https://8b.com/templates/ashlar/DESIGN.md
• Coworking: https://8b.com/templates/isoline/DESIGN.md
• Creative agency: https://8b.com/templates/sillage/DESIGN.md
• Design studio: https://8b.com/templates/onda/DESIGN.md
• Event: https://8b.com/templates/ondo/DESIGN.md
• Fitness: https://8b.com/templates/arcline/DESIGN.md
• Florist: https://8b.com/templates/moth-marigold/DESIGN.md
• Pet boarding: https://8b.com/templates/sill/DESIGN.md
• Print studio: https://8b.com/templates/dotdrum/DESIGN.md
• Product: https://8b.com/templates/hushkey/DESIGN.md
• Repair shop: https://8b.com/templates/reflow/DESIGN.md
• Restaurant: https://8b.com/templates/ombrelle/DESIGN.md
• Trampoline park: https://8b.com/templates/hopla/DESIGN.md
• Veterinary: https://8b.com/templates/burrow/DESIGN.md

• A SaaS or mobile app marketing site: the file of the live captioning app, with one family, warm neutrals and a green kept for what is yours or can be tapped. Weak spot: its components are buttons, a nav bar, caption bubbles, a review card and a field, so pricing tables and dashboards need parts it does not define.
• A finance product or a plain B2B site: the bookkeeping firm file, in black, white, greys and one red, with square panels and fields drawn as a 1px bottom line. Weak spot: headings run from 34px to 112px on one vertical rule, so app screens need a smaller scale you set yourself.
• A dark developer tool or tech service: the phone and laptop repair file, grained near-black against off-white, with tiny condensed uppercase labels for table heads and rows. Weak spot: its one accent, pure #0000ff, marks selection and hover and doubles as the error colour, and no token covers success or warning states.
• Hardware or a calm smart-home product: the wall pad launch file, whose shadows are sized in em, so they scale with any key or card. Weak spot: the palette is greys only and its rules forbid accent colours, so a brand colour has nowhere to go.
• A playful family brand, a game or a kids' venue: the indoor jump park file, with pills, 12px to 30px corners, tilts of 2 to 12 degrees and a hard offset shadow. Weak spot: three faces to load, two of them at weight 800, and one GSAP plugin more than any other file.
• Print, zines or band merch: the risograph studio file, four colour tokens and heavy Gabarito. Weak spot: the halftone dots, duotone photos and multiply blending live in CSS, so the tokens name the inks while the effects must come from the HTML.

• The spec is alpha. Google says the DESIGN.md format, its token schema and the tool are under active development, so names and rules may change. These files follow version alpha as of October 2026.
• Values are desktop values. Where the CSS uses clamp(), a token holds the wide-screen size and the prose usually gives the smaller sizes, so an agent that reads only the YAML could put 118px headings on a phone. Ask it to read the Typography section too.
• Motion is our addition. The spec has no motion tokens, so the section is prose for an agent writing the GSAP or CSS, not values a tool can apply.
• Fonts come from Google Fonts. A file names families and weights, not the stylesheet link, so a new page needs the same link or falls back to system faces.
• Look, not content. A DESIGN.md carries no copy, photos or scripts, at most a few notes on the attributes the scripts read. The template's index.html has all of that, and its demo names, prices and addresses are invented.

If you own the CSS, you can write the file yourself. For a DESIGN.md file template to fill in, copy the one closest to your site in structure, keep its section order and replace the values.

1. List the custom properties in :root and every colour the page really uses, each with a role: primary is required; surface, on-surface or plain names such as night are fine.
2. Pick 5 to 9 type levels from real elements (hero heading, section headings, body, labels, buttons) with family, size, weight, line height and letter spacing; for clamp(), write the desktop value and the range in prose.
3. Note the radii in use, the gutter, the section padding and the maximum width, then define 4 to 8 components with references such as {typography.button}.
4. Write the prose in the spec's order, add a Motion section and close with 6 to 10 do and don't rules.
5. Run npx @google/design.md lint DESIGN.md and fix what it reports.

All 20 templates