Skip to content
.mdDesign.md Store

Docs / Format spec

Frontmatter

The YAML front matter block sits between the opening and closing --- delimiters. It holds all machine-readable design tokens: colors, typography, spacing, border-radius, and component styles.

The block is optional — a DESIGN.md file that contains only a markdown body is valid. But the front matter is what AI tools and the CLI use for precise, repeatable output. Without it, agents fall back to guessing from prose alone.

Top-level fields

Field
Type
Required
Description
name
string
No
Human-readable display name of the design system
version
string
No
SemVer version string, e.g. "1.0.0"
colors
object
No
Named color tokens (hex, rgb, oklch)
typography
object
No
Typography rules keyed by role (h1, body, label…)
spacing
object
No
Named spacing scale values (sm, md, lg…)
rounded
object
No
Named border-radius values (sm, md, lg, full…)
components
object
No
Component-level style rules (button-primary, card…)

Colors

Color values can be any valid CSS color string: hex, rgb(), hsl(), or oklch(). Token names should be semantic, not descriptive — prefer primary over dark-blue.

colors:
  primary:  "#1A1C1E"
  accent:   "#B8422E"
  neutral:  "#F7F5F2"
  surface:  "#FFFFFF"
  error:    "#D32F2F"
  success:  "#388E3C"

Typography

Typography tokens are keyed by role. Each role can define any combination of the supported properties below.

Property
Type
Example
fontFamily
string
"Inter", "Plus Jakarta Sans"
fontSize
string
"1rem", "2.5rem", "40px"
fontWeight
number
400, 600, 700
lineHeight
number | string
1.5, "1.6", "24px"
letterSpacing
string
"-0.02em", "0.05em"
typography:
  h1:
    fontFamily: "Plus Jakarta Sans"
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.02em
  body:
    fontFamily: "Inter"
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
  label:
    fontFamily: "Manrope"
    fontSize: 0.75rem
    fontWeight: 500
    letterSpacing: 0.06em

Spacing

A named scale of spacing values. Use any CSS length unit. These tokens can be referenced in component definitions with {spacing.md}.

spacing:
  xs:  4px
  sm:  8px
  md:  16px
  lg:  32px
  xl:  64px

Rounded

Named border-radius tokens. The special value 9999px is the canonical way to express a pill / fully-rounded shape.

rounded:
  sm:   4px
  md:   8px
  lg:   16px
  xl:   24px
  full: 9999px

Components

Component tokens define the visual style of named UI components. Each key is a component identifier (use kebab-case). Values are any combination of the allowed properties below.

Property
Type
Notes
backgroundColor
color | ref
Accepts hex or token reference
textColor
color | ref
Text color
borderColor
color | ref
Border color
borderWidth
string
e.g. "1px"
rounded
string | ref
Border-radius value or token ref
padding
string | ref
Shorthand or token ref
fontSize
string
Override for this component
fontWeight
number
Override for this component
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.full}"
    padding: "12px 24px"
    fontWeight: 600
  button-ghost:
    backgroundColor: "transparent"
    textColor: "{colors.primary}"
    borderColor: "{colors.primary}"
    borderWidth: "1px"
    rounded: "{rounded.full}"
    padding: "12px 24px"
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.lg}"
    padding: "{spacing.lg}"
    borderColor: "#E5E5E5"
    borderWidth: "1px"

Token references

Component properties can reference other tokens using curly-brace syntax: {namespace.key}. The linter will report an error if a reference points to a token that does not exist.

Reference
Resolves from
{colors.primary}
colors.primary
{spacing.md}
spacing.md
{rounded.full}
rounded.full
Lint rule: All token references must resolve. A reference to {colors.brand} where brand is not defined under colors will fail the linter with a broken reference error.
Your first fileTokens