# How Are Spacing Units Handled in DESIGN.md?

> Learn how DESIGN.md handles spacing units with semantic tokens like gutter or lg, anchored to a base 8px unit and resolved by the CLI.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-06-25

---

**DESIGN.md treats spacing as a first-class design token group anchored to a base unit (typically `8px`), using semantic names like `gutter` or `lg` that are referenced via `{spacing.<token>}` syntax and resolved at export time by the CLI.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) specification establishes spacing as a deterministic, token-driven system that maintains visual rhythm across design systems. Rather than scattering magic numbers throughout component definitions, DESIGN.md centralizes spacing units in a dedicated token hierarchy anchored to a single base value, enabling designers to adjust the entire rhythm by changing one variable.

## Base Unit Architecture

Every DESIGN.md file defines a `unit` value that serves as the atomic building block for all spatial relationships. According to the Totality Festival example in [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) (line 95), the standard base is `8px`:

```yaml
spacing:
  unit: 8px               # ← base rhythm

  container-max: 1280px
  gutter: 24px            # 3 × unit

  margin-mobile: 16px     # 2 × unit

  margin-desktop: 64px    # 8 × unit

```

All other spacing values derive from this base unit as multiples, creating a consistent mathematical relationship between elements. This approach ensures that padding, margins, and gaps remain harmonically related throughout the interface.

## Semantic Token Definitions

The specification encourages semantic naming conventions over arbitrary values. As documented in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 53–60), the spacing block accepts a token map where keys describe the intent rather than the measurement:

- **Layout tokens**: `gutter`, `margin-mobile`, `margin-desktop`
- **Scale tokens**: `xs`, `sm`, `md`, `lg`, `xl`

The type system defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 225–231) validates these entries as `map<string, Dimension | number>`, permitting both pixel-based dimensions and dimension-less numeric values for grid-based ratios.

## Token Reference Syntax

Within component definitions, you reference spacing tokens using the `{spacing.<token>}` placeholder syntax. The CLI resolves these placeholders at export time, substituting the exact pixel value from the token map.

In [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) (line 123), the `card-glass-level-2` component demonstrates this pattern:

```yaml
components:
  card-glass-level-2:
    backgroundColor: rgba(52, 52, 58, 0.2)
    rounded: "{rounded.xl}"
    padding: "{spacing.gutter}"   # → resolved to 24px

```

When the CLI processes this file for Tailwind export, the token becomes a CSS custom property:

```tsx
@layer utilities {
  .p-gutter { padding: var(--spacing-gutter); }   /* 24px */
}

```

## Value Flexibility and Types

The spacing system permits **raw numbers** (e.g., `12px`) alongside **base-unit multiples**, allowing designers to express both precise pixel measurements and grid-based ratios within the same token map. This flexibility supports scenarios where strict adherence to the 8px grid would create awkward layouts, while maintaining the majority of spacing as rhythmic multiples.

## Design System Conventions

Real-world implementations follow documented conventions for spatial hierarchy. As noted in [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md) (line 186), vertical and horizontal spacing serve distinct purposes:

- **Vertical spacing**: Larger values (`6–8 units`) separate distinct sections, creating an "airy" feel between content blocks
- **Horizontal/internal spacing**: Tighter values (`1–2 units`) keep nested components cohesive and readable

These conventions standardize the application of tokens like `lg` and `xl` for section separation versus `sm` or `md` for component internals.

## Validation and Linting

The CLI enforces spacing token correctness through the linter configuration in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts). This validation ensures that:

1. All spacing tokens conform to the `Dimension | number` type signature
2. Reference syntax `{spacing.<token>}` points to defined keys in the token map
3. Base `unit` values are present before derived tokens are calculated

## Summary

- **Base unit**: Spacing tokens originate from a single `unit` value (typically `8px`) defined in the `spacing` block
- **Semantic naming**: Use descriptive keys like `gutter` or `margin-desktop` rather than raw pixel values
- **Reference syntax**: Access tokens within components via `{spacing.<token>}` placeholders resolved by the CLI
- **Type flexibility**: The spec accepts both dimensional values (`24px`) and unitless numbers for grid ratios
- **Validation**: The linter in [`spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/spec-config.ts) ensures token integrity and valid reference syntax

## Frequently Asked Questions

### What is the default base unit for spacing in DESIGN.md?

While the specification does not mandate a specific value, the canonical examples in [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) consistently use `8px` as the base unit. This value provides sufficient granularity for fine adjustments while maintaining a clear mathematical relationship between tokens (multiples of 8 scale cleanly to 16, 24, 32, 64, etc.).

### How do I reference a spacing token inside a component definition?

Use the bracketed placeholder syntax `{spacing.<token-name>}`. For example, to apply the gutter spacing to a card component, you would write `padding: "{spacing.gutter}"`. The CLI substitutes this with the actual pixel value during the export process, generating CSS custom properties or static values depending on your target platform.

### Can I use arbitrary pixel values instead of the base unit multiples?

Yes. The spacing token map accepts any valid `Dimension` or `number` value according to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md). While the system encourages base-unit multiples for consistency, you may define tokens like `custom-gap: 12px` when the 8px grid does not satisfy specific layout requirements. The linter validates format but does not restrict values to multiples of the base unit.

### How does the CLI validate spacing tokens?

The linter configuration in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts) validates that spacing tokens conform to the expected type signatures and that all `{spacing.<token>}` references within component definitions point to existing keys in the token map. This prevents broken references and ensures that exported design tokens contain resolvable values.