What CSS Units Are Supported in Dimension Tokens?

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 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 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 file, ensure you use only the supported CSS units.

Valid token definitions:

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:

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

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

Invalid usage that bypasses validation:

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, the typography and spacing systems rely exclusively on pixel values for predictable layouts. Similarly, 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 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 and 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. 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 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.

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