How Spacing and Corner Radius Are Defined and Referenced in DESIGN.md

Spacing and corner radius are defined as design tokens in YAML front-matter under the spacing: and rounded: maps and referenced throughout the document using curly-brace syntax such as {spacing.md} or {rounded.sm}.

The google-labs-code/design.md repository introduces a design-token system that lives directly inside DESIGN.md files. This approach allows design specifications to remain the single source of truth for visual properties, enabling automated exports to JSON, Tailwind configs, and other tooling while keeping documentation human-readable.

Defining Design Tokens in YAML Front-Matter

Design tokens for spacing and corner radius reside in the YAML front-matter of a DESIGN.md file. These definitions follow a strict schema defined in docs/spec.md and are validated by the CLI parser at packages/cli/src/linter/spec-config.ts.

Spacing Tokens

The spacing: map defines named scale levels that correspond to dimension values. According to the schema in docs/spec.md#L53, typical keys include:

• xs: 4px
• sm: 8px
• md: 16px
• lg: 32px
• xl: 64px
• gutter: 24px
• margin: 32px

---
spacing:
  base: 16px
  xs:   4px
  sm:   8px
  md:  16px
  lg:  32px
  xl:  64px
  gutter: 24px
  margin: 32px
---

Corner Radius Tokens

The rounded: map, specified at docs/spec.md#L52, controls corner radius values for shapes and components:

• sm: 4px
• md: 8px
• lg: 12px
• full: 9999px (complete rounding)

---
rounded:
  sm:   4px
  md:   8px
  lg:  12px
  full: 9999px
---

Referencing Tokens in Component Definitions

Once defined in the front-matter, tokens are referenced using curly-brace syntax: {spacing.key} or {rounded.key}. The parser resolves these references to their concrete values at build time.

Basic Reference Syntax

- Button corner radius: `{rounded.md}`
- Card padding: `{spacing.gutter}`
- Small label margin: `{spacing.xs}`

Component Configuration Examples

Inside component definitions, tokens are embedded as string values that the toolchain resolves automatically. As shown in docs/spec.md#L12, a button component references both spacing and corner radius tokens:

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"      # Resolves to 8px

    padding: "{spacing.sm}"      # Resolves to 8px

For shapes documentation, the prose may describe default radii (e.g., "4 px corner radius" in the Shapes section at docs/spec.md#L66), while component tokens point to the specific rounded values using the reference syntax.

Advanced Token Patterns

Creating Custom Tokens

When a component requires a non-standard value, define a new token in the front-matter rather than using magic numbers:

rounded:
  sm:   4px
  md:   8px
  btn-custom: 6px   # New project-specific token

components:
  button-special:
    rounded: "{rounded.btn-custom}"

Machine-Readable Exports

The token system generates concrete outputs for downstream tools. The file examples/totality-festival/design_tokens.json demonstrates how the YAML definitions transform into JSON for consumption by build systems, while examples/totality-festival/DESIGN.md shows the complete front-matter implementation in a production project.

Schema Validation and Tooling

The repository enforces token validity through packages/cli/src/linter/spec-config.ts, which parses the front-matter and validates it against the schema documented in docs/spec.md#L30. This ensures that:

1. All referenced tokens exist in the front-matter
2. Values conform to expected dimension formats (e.g., px units or unit-less numbers)
3. Component definitions only use valid token paths

Summary

• Spacing and corner radius are defined as design tokens in the YAML front-matter of DESIGN.md files under the spacing: and rounded: maps.
• Reference syntax uses curly braces: {spacing.md}, {rounded.sm}, or {spacing.gutter}.
• Schema validation occurs through packages/cli/src/linter/spec-config.ts, which validates against docs/spec.md.
• Machine-readable exports allow the same tokens to power JSON configs, Tailwind setups, and component libraries from a single source.

Frequently Asked Questions

What file validates the spacing and rounded token syntax?

The parser located at packages/cli/src/linter/spec-config.ts validates all front-matter tokens against the official schema defined in docs/spec.md. This ensures that references like {spacing.lg} point to valid, defined keys.

Can I use arbitrary values instead of tokens?

While the system allows literal dimensions in component definitions, the preferred pattern is to define a new token in the front-matter (e.g., rounded.custom: 6px) and reference it with {rounded.custom}. This maintains consistency and enables global updates.

How do spacing tokens differ from corner radius tokens structurally?

Both use identical YAML map structures, but they serve different semantic purposes. The spacing: map typically contains dimensional values for margins, padding, and gutters (e.g., 4px, 24px), while the rounded: map contains corner radius values (e.g., 4px, 9999px). They are referenced via {spacing.key} and {rounded.key} respectively.

Where can I see a complete working example?

The examples/totality-festival/DESIGN.md file demonstrates a production-ready implementation with full front-matter definitions, while examples/totality-festival/design_tokens.json shows the exported machine-readable output generated from those definitions.

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