# Supported Units for Typography and Dimension Tokens in DESIGN.md

> Learn about supported CSS units for typography and dimension tokens in DESIGN.md. Discover px, em, and rem for flexible design.

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

---

**DESIGN.md supports three CSS units for typography and dimension tokens: pixels (`px`), relative to the element's font size (`em`), and relative to the root element's font size (`rem`).**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository defines a strict token schema for design systems, specifying that **Dimension** type values must include a valid unit suffix. According to the Design Tokens section in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), only these three units are permitted across all typography properties and spacing definitions.

## Supported Dimension Units

In the DESIGN.md specification, a **Dimension** is defined as a string that must end with a unit suffix. The token schema explicitly restricts dimension values to:

- **`px`** — Absolute pixels
- **`em`** — Relative to the parent element's font size  
- **`rem`** — Relative to the root element's font size

This constraint applies universally to any token expecting a dimension value, from font sizing to border radius definitions.

## Typography Token Units

Typography tokens in DESIGN.md are maps containing specific fields that accept **Dimension** values where applicable. As defined in the specification, the following fields utilize dimension units:

- **`fontSize`** — Requires a dimension (e.g., `48px`, `3rem`)
- **`lineHeight`** — Accepts either a unitless number or a dimension (e.g., `1.1` or `24px`)
- **`letterSpacing`** — Requires a dimension (e.g., `-0.02em`, `0.1em`)

Other typography properties like `fontFamily`, `fontWeight`, `fontFeature`, and `fontVariation` use string or number types and do not accept dimension values.

## Spacing and Rounded Token Units

Generic dimension tokens defined under `spacing:` or `rounded:` categories also use the **Dimension** type, enforcing the same three-unit restriction. This ensures consistency across padding, margin, border radius, and gap definitions throughout the design system.

For example, spacing scales may mix units:

```yaml
spacing:
  xs: 4px
  sm: 0.25rem
  md: 1rem
  lg: 32px

```

## Practical Implementation Examples

Real-world implementations in the repository demonstrate these units in context. The [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) file illustrates typography tokens combining `px` and `em` units:

```yaml
typography:
  headline-lg:
    fontFamily: Public Sans
    fontSize: 48px          # px unit

    fontWeight: 600
    lineHeight: 1.2         # unitless multiplier (allowed)

    letterSpacing: -0.02em # em unit

  body-md:
    fontFamily: Public Sans
    fontSize: 1rem          # rem unit

    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0.05em  # em unit

```

The [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md) file shows spacing and rounded tokens utilizing both `px` and `rem`:

```yaml
spacing:
  base: 16px          # px

  sm: 0.5rem          # rem

  md: 1rem            # rem

  lg: 2rem            # rem

rounded:
  sm: 4px            # px

  md: 0.25rem        # rem

  lg: 0.5rem         # rem

```

## Summary

- DESIGN.md restricts dimension tokens to three CSS units: `px`, `em`, and `rem`
- Typography properties including `fontSize`, `lineHeight` (when dimension-based), and `letterSpacing` require these units
- Spacing and rounded tokens follow the same **Dimension** type constraints
- The specification is enforced in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and demonstrated in example projects like `totality-festival` and `paws-and-paths`

## Frequently Asked Questions

### Can I use percentage units or viewport units like vw/vh in DESIGN.md?

No. The DESIGN.md specification in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) explicitly limits dimension tokens to `px`, `em`, and `rem`. Percentage units, viewport units, and other CSS length units are not supported by the token schema validator.

### Does lineHeight always require a unit in DESIGN.md?

No. The `lineHeight` field accepts either a **unitless number** (treated as a multiplier) or a **Dimension** string with `px`, `em`, or `rem` units. For example, `lineHeight: 1.5` is valid, as is `lineHeight: 24px`.

### Are there any differences between how em and rem units behave in DESIGN.md tokens?

The units behave according to standard CSS rules. `em` is relative to the font size of the element's parent, while `rem` is relative to the root element's font size. DESIGN.md does not impose additional constraints on their usage beyond requiring valid Dimension type strings.

### Where is the dimension unit specification defined in the repository?

The dimension unit rules are defined in the **Design Tokens** section of [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) at line 84. This file serves as the authoritative schema reference for the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) project.