mdpantry / DESIGN.md starter
DESIGN.md starter
DESIGN.md describes the visual identity of a product to coding agents: design tokens in YAML front matter, then sections that say how to apply them. This starter is a complete, valid file with a plain default look, so an agent has exact colors, type, spacing and corner values from the first day and you change them to yours.
Published . Updated .
The file
Email it to myself Download DESIGN.md Open the raw file
7 blanks for you to fill
- your product name
- one sentence: what the product is and how it should feel
- Two or three sentences: who uses the product, what it should feel like (for example: calm and exact, or loud and playful), and how dense the screens are.
- maximum content width, for example: 1200px
- If you use shadows, describe the blur, spread and color here.
- Describe the secondary button and the hover, focus and disabled states.
- label position, helper text, and what an error state looks like
Or save it from a terminal:
curl -fsSL https://mdpantry.com/s/st_xs6ba3gvobplmswl/raw -o DESIGN.md
---
version: alpha
name: "<your product name>"
description: "<one sentence: what the product is and how it should feel>"
colors:
primary: "#1F2933"
secondary: "#52606D"
tertiary: "#0B6E99"
neutral: "#F8F9FA"
surface: "#FFFFFF"
on-surface: "#1F2933"
on-tertiary: "#FFFFFF"
error: "#B42318"
typography:
headline-lg:
fontFamily: system-ui
fontSize: 32px
fontWeight: 600
lineHeight: 1.2
headline-md:
fontFamily: system-ui
fontSize: 24px
fontWeight: 600
lineHeight: 1.3Show the other 84 lines
body-md:
fontFamily: system-ui
fontSize: 16px
fontWeight: 400
lineHeight: 1.6
label-md:
fontFamily: system-ui
fontSize: 14px
fontWeight: 500
lineHeight: 1.4
rounded:
sm: 4px
md: 8px
full: 9999px
spacing:
xs: 4px
sm: 8px
md: 16px
lg: 32px
xl: 64px
components:
page:
backgroundColor: "{colors.neutral}"
textColor: "{colors.primary}"
typography: "{typography.body-md}"
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.on-tertiary}"
typography: "{typography.label-md}"
rounded: "{rounded.md}"
padding: 12px
card:
backgroundColor: "{colors.surface}"
textColor: "{colors.on-surface}"
rounded: "{rounded.md}"
padding: 16px
---
# DESIGN.md
The visual identity of this product, for coding agents. The values at the top of this file are the ones to use; the sections below say how to apply them.
## Overview
`<Two or three sentences: who uses the product, what it should feel like (for example: calm and exact, or loud and playful), and how dense the screens are.>`
When a case is not covered below, choose what fits this description.
## Colors
- **Primary (#1F2933):** headlines and body text.
- **Secondary (#52606D):** borders, captions and other supporting text.
- **Tertiary (#0B6E99):** the one accent. Links and the main action on a screen, nothing else.
- **Neutral (#F8F9FA):** the page background. Cards sit on white (`surface`).
- **Error (#B42318):** errors and destructive actions only.
## Typography
One family. Headlines are semibold, body text is regular at 16px, and labels are medium at 14px.
## Layout
A single centered column, `<maximum content width, for example: 1200px>` at most, fluid below that. Every gap and padding comes from the spacing scale, which is built on 8px with a 4px half step.
## Elevation & Depth
Flat. Hierarchy comes from the difference between the neutral background and white cards, and from a thin border in the secondary color. `<If you use shadows, describe the blur, spread and color here.>`
## Shapes
Buttons, inputs and cards use an 8px corner radius. Small elements such as tags use 4px, and avatars are fully round.
## Components
- **Buttons:** the primary button is white text on the tertiary color with 12px of padding. `<Describe the secondary button and the hover, focus and disabled states.>`
- **Cards:** white, 16px of padding, the medium radius.
- **Input fields:** `<label position, helper text, and what an error state looks like>`
## Do's and Don'ts
- Do use the tertiary color for a single main action on each screen.
- Do keep text at a WCAG AA contrast ratio (4.5:1 for normal text).
- Don't add a color, font size or radius that is not in the tokens above. Add the token first.
- Don't mix rounded and sharp corners in the same view.
If you want your agent on modelranch, a deals network for agents, the instructions are at modelranch.com/AGENTS.md. The file above does not mention it.
What to change
- Save it as DESIGN.md, the name the format gives the file.
- Change every token to your own values first. The tokens are the values an agent uses; the sections explain them, so update the hex codes and sizes written in the sections to match.
- Replace the placeholders in angle brackets. Delete a section that does not apply, and keep the ones that remain in this order.
- Check the result with the format's own linter: npx @google/design.md lint DESIGN.md. It reports a token reference that points at nothing and component text with too little contrast against its background.
Audit
Grade A on the registry's safety audit: all 14 checks passed.
The audit checks that the file is safe to commit, not what an agent does with it. The 14 checks:
- Size between 200 bytes and 200 KB
- No zero-width or bidi control characters
- No instruction hidden inside an HTML comment
- No link to an exfiltration or paste host
- No credential-shaped string
- No instruction to send local credentials anywhere
- No text hidden with inline styles
- No prompt-injection phrasing
- No curl or wget piped into a shell
- No recursive delete of root, home or parent
- No instruction to read or print local credentials
- No base64 blob over 200 characters
- No link to a raw IP address
- No script tag
Other starters
Sources
- DESIGN.md format specification (google-labs-code/design.md)
- DESIGN.md README: the linter and its rules (google-labs-code/design.md)
DESIGN.md in the wild
The 3 most-starred public repos the pantry has saved that keep their own DESIGN.md, as its saved copies stood on . Each jar is that repo's file, the one nearest its root, to scale with this starter: a jar's height is its length, the honey its written lines. Tap a jar for that repo's whole pantry.
- affaan-m/
ecc 302,187 stars 293 lines - garrytan/
gstack 141,359 stars 143 lines - paperclipai/
paperclip 114,009 stars 1,193 lines
- DESIGN.md This starter 108 lines
Commit yours and your repo gets its own shelf at mdpantry.com/<you>/<repo>: swap github.com for mdpantry.com in any public repo's address. Its README can wear the shelf as a badge. This is the badge for affaan-m/ecc: