The agent-native design-system artifact, formalized.

A DESIGN.mdis a single Markdown file at the root of a repo (or alongside an extraction) that captures a website’s design system in a form an LLM can read and an engineer can edit. It is the design counterpart to AGENTS.md.

Structure

A valid DESIGN.md has two layers:

1. YAML front matter holding the machine-readable token snapshot — colors, typography, spacing, radii, shadows.
2. Markdown body with up to eight canonical sections, in this order, any of which may be omitted if not relevant.

The eight canonical sections

1. Overview — a 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 derived from voice + lint findings.

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 an MIT-licensed, dependency-light 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 following SVG badge — a one-shot signal to crawlers, AI agents, and design-system tooling that the spec is honored:

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

Compatibility

The spec was inspired by the DESIGN.md convention pioneered at design-extractor.com. designlang adopts the eight-section structure verbatim and extends the front matter with the v10 semantic layer (intent, material, library) so downstream tools have richer ground truth without sacrificing single-file portability.

License

The spec is published under CC BY 4.0 — copy, fork, extend, embed. Contributions welcome at github.com/Manavarya09/design-extract.