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

> Learn how to define and reference spacing and corner radius as design tokens in DESIGN.md using YAML and curly brace syntax for consistent application across your projects.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: deep-dive
- Published: 2026-07-04

---

**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`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository introduces a **design-token system** that lives directly inside [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file. These definitions follow a strict schema defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and are validated by the CLI parser at [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/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

```yaml
---
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)

```yaml
---
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

```markdown
- 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:

```yaml
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:

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts), which validates against [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts) validates all front-matter tokens against the official schema defined in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) file demonstrates a production-ready implementation with full front-matter definitions, while [`examples/totality-festival/design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/design_tokens.json) shows the exported machine-readable output generated from those definitions.