# How to Define Spacing Tokens with Dimensional and Unitless Values in DESIGN.md > Learn how to define spacing tokens in DESIGN.md using dimensional and unitless values. Mix absolute measurements with unitless counts and ratios in your YAML. - Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md) - Tags: how-to-guide - Published: 2026-07-01 --- **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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`. ```yaml --- # 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`](https://github.com/google-labs-code/design.md/blob/main/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: ```yaml --- 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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) for the canonical schema definition and [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) within the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository, specifically lines 53-55, which define the spacing value type as ``. The [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) provides additional context on general token usage and file structure.