[community-group] Standardize on ms unit for duration values (#342)

CITguy has just created a new issue for https://github.com/design-tokens/community-group:

== Standardize on ms unit for duration values ==
### Before starting

- [x] I have searched [existing issues](https://github.com/design-tokens/community-group/issues) and there is not already an open issue on the subject.

### Summary

I propose extending the duration token type to also accept a JSON integer value in addition to the current object value.

* **duration**: Number | Object
    * **Object**
        * **value**: number
        * **unit**: string (`ms` or `s`)
    * **Number**: duration in `ms`
        * `<value>` equivalent to `{ value: <value>, unit: 'ms' }`


### Version

Third Editor’s Draft

### Problem & motivation

I get why the granularity of value vs unit was done for dimension tokens, given the variety of dimensional units and complex conversion formulas between them.  

However, a duration (i.e., length of time) has a _single_ set of globally-known ratios to be able to convert a base unit (`ms`) to a larger order unit (`s`, `min`, hour`, etc.). The vast majority of humans that can tell time know of these ratios (1000ms = 1s, 60s = 1min, etc.).

There _might_ be accuracy concerns when converting to larger and larger unit values, but I'd argue that design tokens (which are used to build UI interactions that appear for seconds; at most), should rarely ever need units large enough for accuracy to be an issue.

### Prior art

_No response_

### Pros & cons

### Pros
* backward-compatible syntax
* less-verbose syntax
    * easy to define manually for the majority of practical durations (< 5min)
    * for much larger values, software-defined values can take advantage of scientific notation to optimize the JSON definition
    * some authors may prefer this syntax

### Cons
* additional data type for tooling authors to support
* implementation of larger unit conversion (e.g., to `s`, `min`, etc.) falls on tooling authors
* very large durations are difficult to define manually without the aid of a calculator
    * (may not be a problem for most practical use cases)


### Example
```js
{
  "obj": {
    "duration1": { // 250ms
      "$type": "duration",
      "$value": {
        "value": 0.25,
        "unit": "s"
      }
    },
    "duration2": { // 5s
      "$type": "duration",
      "$value": {
        "value": 5,
        "unit": "s"
      }
    },
    "duration3": { // 5min
      "$type": "duration",
      "$value": {
        "value": 300,
        "unit": "s"
      }
    },
    "duration4": { // 1hour
      "$type": "duration",
      "$value": {
        "value": 3600,
        "unit": "s"
      }
    }
  },
  "int": {
    "duration1": { // 250ms
      "$type": "duration",
      "$value": 250
    },
    "duration2": { // 5s
      "$type": "duration",
      "$value": 5000
    },
    "duration3": { // 5min
      "$type": "duration",
      "$value": 30000 // or 3e5
    }
    "duration4": { // 1hour
      "$type": "duration",
      "$value": 3.6e5 // or 3600000
    }
  }
}
```
* The following tokens have the same equivalent values:
    * `obj.duration1` == `int.duration1`
    * `obj.duration2` == `int.duration2`
    * `obj.duration3` == `int.duration3`
    * `obj.duration4` == `int.duration4`

### Alternatives

_No response_

### Required

- [x] I have read and agree to abide by the [CODE_OF_CONDUCT](https://github.com/design-tokens/community-group/blob/CODE_OF_CONDUCT.md)

Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/342 using your GitHub account


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

Received on Tuesday, 28 October 2025 02:02:21 UTC