YAML Front Matter Structure in a DESIGN.md File: The Complete Token System

Every DESIGN.md file in the VoltAgent/awesome-design-md repository begins with a YAML front-matter block delimited by triple dashes (---) that defines design-system tokens for colors, typography, spacing, rounded corners, and reusable UI components.

The YAML front matter structure in a DESIGN.md file serves as the single source of truth for design tokens, enabling consistent theming across components while allowing the @google/design.md lint tool to validate references, contrast ratios, and orphaned entries. This structured data block appears at the very start of the markdown file and follows a hierarchical six-section pattern.

Core Sections of the YAML Front Matter

The front matter in files like design-md/airtable/DESIGN.md and design-md/airbnb/DESIGN.md follows a consistent hierarchy. Each section uses specific key naming conventions and value types.

Metadata Section

The metadata section establishes general document properties using three standard keys:

• version: Design system version (e.g., "alpha")
• name: Identifier for the design analysis (e.g., "Airtable-design-analysis")
• description: Human-readable summary of the design philosophy and visual approach

Colors Section

The colors section defines the core palette and semantic color tokens. As implemented in design-md/airtable/DESIGN.md, this includes:

• Base colors: primary, primary-active, ink, canvas, body, muted
• Surface variants: surface-soft, surface-strong, surface-dark, surface-dark-elevated
• Semantic colors: info, info-border, success, success-border, link, link-active
• Brand accents: signature-coral, signature-forest, signature-cream, signature-peach, signature-mint, signature-yellow, signature-mustard
• Contrast colors: on-primary, on-dark (for text on dark backgrounds)

All color values use hexadecimal notation wrapped in quotes (e.g., "#181d26").

Typography Section

Typography tokens use nested objects with five required properties. For example, the display-xl token in the Airtable design file specifies:

typography:
  display-xl:
    fontFamily: "Haas Groot Disp, Haas, sans-serif"
    fontSize: 48px
    fontWeight: 500
    lineHeight: 1.1
    letterSpacing: 0

Standard token names include display-xl, display-lg, title-md, body-sm, body-md, button, and caption. Each token must define fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing.

Rounded Section

The rounded section defines border-radius tokens using pixel values or special constants:

rounded:
  none: 0
  xs: 2px
  sm: 6px
  md: 10px
  lg: 12px
  xl: 16px
  full: 9999px
  pill: 9999px

Spacing Section

Spacing tokens establish a base unit system ranging from xxs (4px) to section (96px). The Airtable implementation in design-md/airtable/DESIGN.md defines:

spacing:
  xxs: 4px
  xs: 8px
  sm: 12px
  md: 16px
  base: 16px
  lg: 24px
  xl: 32px
  xxl: 48px
  section: 96px

Components Section

The components section references tokens from previous sections using interpolation syntax. According to the repository source code, components like button-primary, top-nav, search-bar-pill, and property-card map design decisions to token values:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button}"
    rounded: "{rounded.lg}"
    padding: 16px 24px
  top-nav:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"

Token Reference Syntax

Components reference design tokens using the format {section.key}. This string interpolation enables the linter to validate that referenced tokens exist. For example:

• "{colors.primary}" resolves to the value defined in the colors section
• "{typography.button}" inherits all five typography properties
• "{rounded.full}" applies the 9999px radius value

Complete Front Matter Example

The following excerpt from design-md/airtable/DESIGN.md demonstrates the full YAML front matter structure in a DESIGN.md file:

---
version: alpha
name: Airtable-design-analysis
description: A sober, editorial workflow-software interface anchored on white canvas

colors:
  primary: "#181d26"
  primary-active: "#0d1218"
  ink: "#181d26"
  body: "#333840"
  muted: "#41454d"
  hairline: "#dddddd"
  border-strong: "#9297a0"
  canvas: "#ffffff"
  surface-soft: "#f8fafc"
  surface-strong: "#e0e2e6"
  surface-dark: "#181d26"
  surface-dark-elevated: "#1d1f25"
  signature-coral: "#aa2d00"
  signature-forest: "#0a2e0e"
  signature-cream: "#f5e9d4"
  signature-peach: "#fcab79"
  signature-mint: "#a8d8c4"
  signature-yellow: "#f4d35e"
  signature-mustard: "#d9a441"
  on-primary: "#ffffff"
  on-dark: "#ffffff"
  link: "#1b61c9"
  link-active: "#1a3866"
  info: "#254fad"
  info-border: "#458fff"
  success: "#006400"
  success-border: "#39bf45"
  pricing-ink: "#1d1f25"

typography:
  display-xl:
    fontFamily: "Haas Groot Disp, Haas, sans-serif"
    fontSize: 48px
    fontWeight: 500
    lineHeight: 1.1
    letterSpacing: 0

rounded:
  xs: 2px
  sm: 6px
  md: 10px
  lg: 12px
  pill: 9999px
  full: 9999px

spacing:
  xxs: 4px
  xs: 8px
  sm: 12px
  md: 16px
  lg: 24px
  xl: 32px
  xxl: 48px
  section: 96px

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button}"
    rounded: "{rounded.lg}"
    padding: 16px 24px
  top-nav:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
---

Creating Custom Components with Token References

To define new components that follow the front-matter pattern, reference existing tokens using the interpolation syntax. For example, extending the system with a badge-alert component:

components:
  badge-alert:
    backgroundColor: "{colors.error}"
    textColor: "{colors.on-primary}"
    typography: "{typography.caption}"
    rounded: "{rounded.full}"
    padding: 4px 8px

Validation and Linting

The front-matter is written in plain YAML to enable validation by the @google/design.md lint tool. This linter checks for:

• Orphaned entries: Tokens defined but never referenced
• Invalid references: Interpolations pointing to non-existent keys
• Contrast violations: Insufficient color contrast between text and background combinations

Summary

• Delimiter format: YAML front matter in a DESIGN.md file uses triple dashes (---) as opening and closing delimiters
• Six core sections: Metadata, colors, typography, rounded, spacing, and components
• Token syntax: References use {section.key} format (e.g., "{colors.primary}") to link components to design tokens
• Typography properties: Every typography token requires fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing
• Source examples: Reference implementations exist in design-md/airtable/DESIGN.md and design-md/airbnb/DESIGN.md
• Tooling support: The structure supports linting via @google/design.md lint for validation of token references and contrast ratios

Frequently Asked Questions

What delimiter marks the beginning and end of YAML front matter in DESIGN.md files?

The YAML front matter starts and ends with triple dashes (---) on their own lines. The opening delimiter must appear at the very first line of the file, and the closing delimiter marks the transition to standard Markdown content.

How do I reference a color token inside a component definition?

Use the interpolation syntax {colors.keyname}. For example, to apply the primary color to a button background: backgroundColor: "{colors.primary}". This syntax applies to all token categories, including typography ({typography.button}), rounded ({rounded.lg}), and spacing ({spacing.md}).

What are the required sections in a DESIGN.md front-matter block?

While the specification supports six standard sections (metadata, colors, typography, rounded, spacing, and components), only the YAML structure following the opening --- delimiter is strictly required. However, for full compatibility with the @google/design.md lint tool, you should define metadata (name, version) and any sections referenced by your components to avoid validation errors.

Where can I find full examples of DESIGN.md implementations?

Complete implementations demonstrating the YAML front matter structure in a DESIGN.md file are available in the repository's design-md/ directory. The design-md/airtable/DESIGN.md file provides a comprehensive example with extensive color palettes and typography scales, while design-md/airbnb/DESIGN.md shows the same structure applied to a different brand identity. Additional guidelines for extending the front matter appear in CONTRIBUTING.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}