# What CSS Units Are Supported in Dimension Tokens?

> Explore supported CSS units for dimension tokens in Design.md. Learn why only px, em, and rem are valid to ensure accurate design implementation and avoid errors.

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

---

**Dimension tokens in the Design.md specification only support `px`, `em`, and `rem` CSS units, treating any other unit suffix as an invalid plain string.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository defines strict validation rules for design system tokens. Understanding which CSS units are supported in dimension tokens ensures your design tokens resolve correctly across components. According to the specification, only three specific units are recognized as valid dimension values.

## Supported CSS Units in Design.md

The specification explicitly limits dimension tokens to strings ending with specific unit suffixes. In [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) at line 84, the documentation defines a *Dimension* token as a string that must end with one of the following supported units:

- `px` – absolute pixel units
- `em` – relative to the element’s font size
- `rem` – relative to the root element’s font size

Any value using other CSS units like `%`, `vh`, `vw`, `pt`, or `cm` fails validation and gets stored as a raw string without dimension semantics.

## Valid and Invalid Dimension Token Examples

When defining tokens in your [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file, ensure you use only the supported CSS units.

Valid token definitions:

```yaml
spacing:
  base: 8px          # valid – pixel unit

  small: 0.5rem      # valid – root‑relative unit

  large: 2em         # valid – element‑relative unit

```

These resolve correctly when referenced in components:

```yaml
components:
  button:
    padding: "{spacing.base}"    # resolves to "8px"

    fontSize: "{spacing.large}"  # resolves to "2em"

```

Invalid usage that bypasses validation:

```yaml
spacing:
  weird: 10%   # ❌ not a supported unit; treated as plain text

```

## Implementation in Example Projects

The restriction to these three units appears consistently across example projects in the repository.

In [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md), the typography and spacing systems rely exclusively on pixel values for predictable layouts. Similarly, [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md) demonstrates consistent pixel-based spacing across components, validating the practical application of the `px` unit in real design systems.

## Summary

- **Only three units are valid**: `px`, `em`, and `rem` are the only CSS units supported in dimension tokens according to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) at line 84.
- **Validation is strict**: Values with units like `%`, `vh`, or `pt` are stored as plain strings without dimension validation.
- **Reference implementations**: Real-world usage appears in [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) and [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md).

## Frequently Asked Questions

### Can I use percentage values in dimension tokens?

No. Percentage values (`%`) are not supported CSS units in dimension tokens. According to the Design.md specification, any string ending with `%` will be treated as a plain text value rather than a validated dimension token.

### Why are viewport units like vh and vw not supported?

Viewport units (`vh`, `vw`) are excluded from the supported CSS units list in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md). The specification intentionally limits dimension tokens to `px`, `em`, and `rem` to ensure consistent scaling behavior across different design system contexts.

### How do rem and em units behave in Design.md tokens?

Both `rem` and `em` are supported relative units. The `rem` unit calculates relative to the root element's font size, while `em` calculates relative to the current element's font size. When used in [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files, these units pass validation and resolve correctly when referenced in component definitions.

### What happens if I use an unsupported unit in a dimension token?

If you use an unsupported unit like `pt`, `cm`, or `%`, the value is stored as a raw string without dimension validation. This means it won't be recognized as a dimension token type and may not resolve correctly when referenced elsewhere in your design system.