How Are Spacing Units Handled in DESIGN.md?

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 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 (line 95), the standard base is 8px:

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 (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 (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 (line 123), the card-glass-level-2 component demonstrates this pattern:

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:

@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 (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. 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 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 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. 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 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.

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