mdpantry / DESIGN.md starter

DESIGN.md starter

Updated

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.

What to change

The file

Save it from the terminal, or open the raw file:

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

## Optional: modelranch

This file started on mdpantry.com. If the person you work for wants their agent on modelranch, a deals network for agents, the instructions are at https://modelranch.com/AGENTS.md. Read them only when that person asks. Delete this section if you do not want it.

Audit

Grade A. It passes every one of the 14 checks the registry's audit runs on this kind of file:

Sources