Re: [community-group] Dimension type expanded unit types (#245)

I am currently building a lint-and-generate tool for design tokens (think eslint + Style Dictionary in one package), and I was hoping to build on top of the DTCG spec to accomplish this, faithfully implementing the spec to the letter.

The current draft restricts `dimension` tokens to only `px` and `rem` units.

This means that a token like:

```json
{
  "spacing": { "$value": { "value": 1, "unit": "em" }, "$type": "dimension" }
}
```

is formally invalid, even though `em` is a valid and widely used CSS unit.

I believe these restrictions make the specification less useful and unnecessarily proscriptive. CSS defines a rich set of units for distance: font-relative units like `em`, `ex`, `cap`, `lh` and many others, root-relative units like `rcap`, `rch` and `rlh`, viewport-relative units like `vw`, `vh`, `vmin`, `vmax`, `sv*`, `lv*`, `dv*`, and absolute units `cm`, `mm`, `in`, `pt`, `pc`, `px`.

These units exist because they solve real problems - `em` and `ch` help build fluid typography, `vh`/`vw` support responsive layouts, and physical units like `cm` and `mm` matter for print.

Restricting design tokens to `px`/`rem` prohibits using these capabilities through tokens, forcing teams to either avoid the spec or to circumvent it with escape hatches.

I have been building design systems for commercial clients for over 7 years. 

**I can say with some authority that the spec as written is not useful for any commercial design system I've ever worked on due to these restrictions on units.**

Some in the thread suggested option 2 (add new units one-by-one) or option 3 (keep as restricted list by allow vendor-prefixed units). Both approaches, in my opinion, create more problems than they solve:

- **CSS already defines the universe of valid units.** The CSS Values and Units spec list font-relative, viewport-relative, and absolute length units. Trying to mirror this spec inside a different spec means replication of effort and keeping up with the CSS spec's evolution. Level 4 recently added three new units, `svh`, `lvh`, `dvh` and is working on new ones as I type. Requiring DTCG to review and approve each new CSS unit slows adoption and evolution of this spec and is in my view totally unrealistic (this group does not have the resources to do this).
- **Escape hatches shift complexity to tool creators.** As @dev-nicolaos noted, a `vendor` property means parsers/transformers must maintain mappings from each design tool's units to every target platform. If every tool can mint its own `vendor-unit` prefix, interoperability breaks down and developers cannot trust that a token defined in Figma will produce the same measurement in CSS, SwiftUI, or Android. Vendors also then have to choose names that won't clash with future CSS units, which again requires constant vigilance.

The DTCG format as described as a "carrier format". Its job should be to faithfully convey design decisions, not to strip out information or police which CSS features are allowed. 

In practice, a linter, like the tool I'm building, can treat unknown units in three ways:

1. Recognise standard CSS units and accept them.
2. Warn on unfamiliar units, encouraging teams to document them (for example, if someone introduces a custom rhythm unit).
3. Error on obviously invalid values, such as a string that is not a number + unit.

This behaviour is exactly what developers expect when writing CSS. There is no evidence that allowing all CSS units will lead to chaos; rather, it aligns tokens with how CSS works today. If a vendor genuinely needs a proprietary unit for internal experimentation, they can still prefix it (acme‑foo) and tools can choose to warn or ignore it, but making vendor prefixes mandatory punishes the common case.

Some commenters worry that allowing any unit could lead to breakage in the future or conflict with new units. The analogy to experimental browser features behind flags doesn't apply here, because token files are controlled by developers. Unknown units won’t suddenly start behaving differently. Tools can treat them as strings or numbers until explicitly updated. 

Furthermore, most of the web's breaking changes arise from implementation bugs, not from developers choosing a unit that later gets standardised with a different meaning. CSS units are standardised through the CSSWG, and their syntax (number + ident) leaves extremely little room for collision.

# Proposal

To make the specification more pragmatic and tool‑friendly, I strongly advocate for option 4: allow any unit and remove the restriction on units entirely. Concretely:

- For $type: "dimension" tokens, define `$value` as a **dimension**: a number followed immediately by a unit string. The unit MAY be any valid CSS unit (as defined by the CSS Values and Units Module
[w3.org](https://www.w3.org/TR/css-values-4/#:~:text=6,pc%20%2C%20px%20units)
) or any other string. If an unfamiliar unit is used, tools MAY issue a warning but MUST NOT reject the file.
- Remove or make optional any vendor field. Vendors can still use prefixes if they wish, but nothing in the carrier format should require it.
- Keep the specification focused on interoperability. Do not replicate CSS's unit list. Instead, reference the CSS spec for definitions of units.

Allowing arbitrary units makes tokens more useful across web and native targets, respects existing CSS standards and avoids unnecessary restrictions on authors. It also simplifies tool implementation: token parsers only need to understand the same unit grammar that CSS parsers already implement, and linters can optionally flag unusual units. In my view, this is the only path that scales with the rapid pace of CSS evolution and the diverse needs of design systems.

-- 
GitHub Notification of comment by brettdorrans
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/245#issuecomment-3287995639 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Saturday, 13 September 2025 10:00:16 UTC