Supported Units for Typography and Dimension Tokens in DESIGN.md

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 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, 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:

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 file illustrates typography tokens combining px and em units:

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 file shows spacing and rounded tokens utilizing both px and rem:

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 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 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 at line 84. This file serves as the authoritative schema reference for the google-labs-code/design.md project.

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