DESIGN.md

Structure

A valid DESIGN.md has two layers:

1. YAML front matter — the machine-readable token snapshot (colours, typography, spacing, radii, shadows).
2. Markdown body — up to eight canonical sections, in this order. Any may be omitted if not relevant.

The eight canonical sections

1. Overview — one-paragraph design rationale plus page intent and material language.
2. Colors — palette table (role · hex · usage), neutrals, total unique count.
3. Typography — families, weights, body size, heading scale.
4. Layout — spacing base + scale, breakpoints, grid/flex primitive counts.
5. Elevation and Depth — shadow scale and z-index layers.
6. Shapes — border-radius scale.
7. Components — detected patterns and anatomy table (kind · variants · sizes · instances).
8. Do’s and Don’ts — actionable directional guidance from voice + lint.

Sections may be added (e.g. Motion, Voice, Imagery) but should appear after the eight canonical ones.

Front-matter schema

site:           string        # canonical name
url:            string        # source URL (preferred)
generated_at:   ISO 8601      # UTC timestamp
generator:      "tool@vX.Y"   # tool identifier
intent:         string        # landing | pricing | docs | blog | product | …
material:       string        # flat | brutalist | glass | soft-ui | material-you | …
library:        string?       # shadcn/ui | radix | mui | chakra | tailwind-ui | …
tokens:
  colors:
    primary:    "#hex"
    secondary?: "#hex"
    accent?:    "#hex"
    background: "#hex"
    foreground: "#hex"
  typography:
    sans:       string
    mono?:      string
    base:       integer       # px
  spacing:
    base?:      integer       # px
    scale:      integer[]
  radii?:
    xs|sm|md|lg|xl|full: integer  # px
  shadows?:
    sm|md|lg|xl: string       # raw box-shadow value

Reference implementation

designlang ships a reference emitter at src/formatters/design-md.js. Generate a sample with:

npx designlang stripe.com    # writes stripe-com-DESIGN.md

The Verified badge

Sites that publish their own DESIGN.md at /DESIGN.md may embed the SVG badge — a one-shot signal to crawlers, AI agents, and design-system tooling that the spec is honoured.

<a href="https://designlang.app/spec"><img src="https://designlang.app/badge.svg"/></a>

Compatibility

The eight-section structure follows the convention pioneered at design-extractor.com. designlang extends the front matter with a semantic layer (intent, material, library) so downstream tools have richer ground truth without sacrificing single-file portability.

Licence

The spec is published under CC BY 4.0 — copy, fork, extend, embed.