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
  1. your product name
  2. one sentence: what the product is and how it should feel
  3. 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.
  4. maximum content width, for example: 1200px
  5. If you use shadows, describe the blur, spread and color here.
  6. Describe the secondary button and the hover, focus and disabled states.
  7. 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.3
Show 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

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 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.

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:

affaan-m/ecc: 211 agent files, on mdpantryagent files211