# YAML Front Matter Structure in a DESIGN.md File: The Complete Token System > Discover the YAML front matter structure in DESIGN.md files. Learn how to define design tokens for colors, typography, spacing, and UI components in the VoltAgent/awesome-design-md repository. - Repository: [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) - Tags: deep-dive - Published: 2026-07-10 --- **Every [`DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/airtable/DESIGN.md) and [`design-md/airbnb/DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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: ```yaml 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: ```yaml 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`](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/airtable/DESIGN.md) defines: ```yaml 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: ```yaml 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`](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/airtable/DESIGN.md) demonstrates the full YAML front matter structure in a [`DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/DESIGN.md) file: ```yaml --- 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: ```yaml 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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/airtable/DESIGN.md) and [`design-md/airbnb/DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/DESIGN.md) file are available in the repository's `design-md/` directory. The [`design-md/airtable/DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/airtable/DESIGN.md) file provides a comprehensive example with extensive color palettes and typography scales, while [`design-md/airbnb/DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/CONTRIBUTING.md).