How to Define Spacing Tokens with Dimensional and Unitless Values in DESIGN.md

Design tokens for spacing in DESIGN.md support both dimensional strings (e.g., "8px", "0.5rem") and plain numbers, allowing you to mix absolute measurements with unitless counts and ratios in the same YAML front-matter block.

The google-labs-code/design.md specification enables design system authors to declare spacing tokens within YAML front-matter that accommodate both physical dimensions and abstract numeric values. This dual-type support lets you define concrete CSS measurements alongside semantic counts or multipliers within a single cohesive system. Understanding how to leverage both dimensional and unitless values ensures your design tokens remain flexible for diverse implementation contexts.

Understanding the Spacing Token Schema

According to the official token schema in docs/spec.md, the spacing section is defined as a map where each value may be either a Dimension or a number (see lines 53-55). This schema flexibility allows design systems to combine physical spacing with logical grid parameters or scale factors.

Dimensional Values

Dimensional tokens are strings that include CSS units such as px, rem, or em. These values represent absolute or relative physical measurements in your layout.

Common dimensional formats include:

• "8px" for pixel-based absolute spacing
• "0.5rem" for relative spacing based on root font size
• "1.2em" for spacing relative to the current element's font size

Use dimensional values when you need explicit measurements for properties like gutters, margins, or container widths.

Unitless Values

Unitless tokens are plain numbers without any unit suffix. These are interpreted by consuming tools as raw numeric values rather than CSS lengths.

Unitless values work best for:

• Grid column counts (e.g., 12)
• Aspect ratios or multipliers (e.g., 1.5)
• Any value where the interpretation depends on runtime calculation

When a consumer encounters a value that does not match a recognized unit, it preserves the raw string, maintaining the author's intent for downstream processing.

Declaring Spacing Tokens in DESIGN.md Front-Matter

Place your spacing map under the YAML front-matter block (delimited by ---) at the top of your DESIGN.md file. The specification allows free-form naming for scale-level tokens, so you can use semantic names like xs, sm, gutter, or margin-mobile.

---

# Minimal example of spacing tokens

spacing:
  # Dimensional tokens

  unit: 8px                 # Base spacing unit

  gutter: 24px              # Gutter between columns

  container-max: 1280px     # Max width for containers

  # Unit-less tokens

  grid-columns: 12          # Number of columns in a grid

  column-ratio: 1.5         # Ratio for a flexible column width

---

Practical Implementation Examples

The examples/totality-festival/DESIGN.md file demonstrates real-world usage where both dimensional and unitless values coexist in the same spacing system (see lines 95-100). This example mirrors production patterns where physical constraints and logical parameters must coexist.

A more complex mixed-type illustration shows how different token types serve different purposes:

---
spacing:
  # Dimensional values render directly as CSS

  padding: 0.5rem
  spacing-xs: 4px
  
  # Unit-less values for logic-driven layouts

  column-count: 6                 # Used for grid-template-columns

  line-height-multiplier: 1.4     # Multiplier for calc() operations

---

In this configuration:

• padding and spacing-xs output directly as CSS spacing values
• column-count might compile to grid-template-columns: repeat(6, 1fr)
• line-height-multiplier could calculate as calc(var(--base-line-height) * 1.4)

Summary

• Place tokens under spacing: in the YAML front-matter block of your DESIGN.md file.
• Use dimensional strings (e.g., "8px", "0.5rem") when you need explicit CSS units for physical measurements.
• Use plain numbers (e.g., 12, 1.5) for counts, ratios, or values requiring runtime interpretation.
• Reference docs/spec.md for the canonical schema definition and examples/totality-festival/DESIGN.md for production-ready examples.
• Name tokens freely using semantic labels like gutter, xs, or margin-mobile without schema restrictions.

Frequently Asked Questions

Can I mix dimensional and unitless values in the same spacing map?

Yes. The spacing section in DESIGN.md accepts a heterogeneous map where some keys hold dimensional strings like "24px" while others hold plain numbers like 12. The consumer parses each value independently, applying CSS units where present and preserving raw numbers where absent.

What happens if I use an unrecognized unit in a dimensional value?

The consumer stores the raw string representation, preserving your original intent. While standard units like px, rem, and em are recognized as dimensions, any other format remains available for custom processing by downstream tools.

How should I name my spacing tokens?

Scale-level names are free-form according to the specification. You can use t-shirt sizes (xs, sm, lg), functional descriptors (gutter, margin-mobile, container-max), or any semantic convention that fits your design system architecture.

Where can I find the official schema definition for spacing tokens?

The canonical definition resides in docs/spec.md within the google-labs-code/design.md repository, specifically lines 53-55, which define the spacing value type as <Dimension | number>. The README.md provides additional context on general token usage and file structure.

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