Add support for simple duration values

[CITguy]

Before starting

• I have searched existing 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 number 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)

Examples

250ms

(all tokens are equivalent)

{
  "tok1": {
    // most explicit / user-friendly
    "a": {
      "$type": "duration",
      "$value": {
        "value": 250,
        "unit": "ms"
      }
    },
    "b": {
      "$type": "duration",
      "$value": {
        "value": 0.25,
        "unit": "s"
      }
    },
    // most efficient
    "c": {
      "$type": "duration",
      "$value": 250
    }
  }
}

1.5s

(all tokens are equivalent)

{
  "tok2": {
    // most explicit / user-friendly
    "a": {
      "$type": "duration",
      "$value": {
        "value": 1.5,
        "unit": "s"
      }
    },
    "b": {
      "$type": "duration",
      "$value": {
        "value": 1500,
        "unit": "ms"
      }
    },
    // most efficient
    "c": {
      "$type": "duration",
      "$value": 1500
    }
  }
}

3 3/8min

This example may not be practical, but it's possible.

(all tokens are equivalent)

{
  "tok3": {
    // most explicit / user-friendly
    "a": {
      "$type": "duration",
      "$value": {
        "value": 202.5,
        "unit": "s"
      }
    },
    "b": {
      "$type": "duration",
      "$value": {
        "value": 202500,
        "unit": "ms"
      }
    },
    "c": {
      "$type": "duration",
      "$value": {
        "value": 2.025e5,
        "unit": "ms"
      }
    },
    "d": {
      "$type": "duration",
      "$value": 2.025e5
    },
    // most efficient
    "e": {
      "$type": "duration",
      "$value": 202500
    }
  }
}

Alternatives

No response

Required

• I have read and agree to abide by the CODE_OF_CONDUCT

[drwpow]

Thanks for raising! I just want to say this is a fantastic proposal—I understand the problem, proposed solution, and potential impact all from one comment. Will bring this to the next editor’s meeting.

This week we are focused on backwards-compatibility but if we are able to keep this as an alternate “shorthand” I think the advantages would be clear.

[Shrinks99]

One of the things I try to keep in mind in spec creation is how this will be implemented. A stricter, more verbose spec may require more work for tooling creators to support all the different duration types correctly. Inversely, a shorthand may allow them to cut corners leading to a less complete experience for users.

In this instance, imagine that developers want to save some time and only implement the simple duration values (ms). Users of their app can only define values in ms as a result and it is spec complaint so this is not expanded upon. Meanwhile another application might support multiple duration units and will only receive ms from application 1. Is this a serious issue? Not really, time is easy to convert, but it does lead to a fragemented implementation and a less-predictable output format. If everyone only chooses to implement the simple duration value, perhaps the organizational value of the others could be completely lost.

I think you've done a good job of outlining the pros and cons here, but for me the "less verbose syntax" isn't meaningfully relevant if we assume that most people will be using tools like Pinwheel and won't be authoring tokens by hand. I tend to be in favour of more rigid specs to keep developers accountable, and therefore would not be in favour of this change.

[nubley]

I’ve been exploring motion tokens lately, and this discussion around duration made me think about how it could relate to transition.

In my experiments, pairing the two (duration for timing and transition for easing or delay) has worked well. It provides more clarity when defining motion across both design and code, and keeps things flexible for different interaction types.

{
  "motion": {
    // Duration tokens define how long an animation runs
    "duration": {
      "short": { "$type": "duration", "$value": 200 },   // micro-interactions
      "medium": { "$type": "duration", "$value": 400 },  // standard UI transitions
      "long": { "$type": "duration", "$value": 1000 }    // larger or page-level motion
    },

    // Transition tokens describe the easing curve or motion behavior
    "transition": {
      "linear": { 
        "$type": "transition", 
        "$value": "linear" // constant speed — rarely used for natural motion
      },
      "ease-in": { 
        "$type": "transition", 
        "$value": "cubic-bezier(0.4, 0, 1, 1)" // accelerates quickly then stops
      },
      "ease-out": { 
        "$type": "transition", 
        "$value": "cubic-bezier(0, 0, 0.2, 1)" // decelerates smoothly
      },
      "ease-in-out": { 
        "$type": "transition", 
        "$value": "cubic-bezier(0.4, 0, 0.2, 1)" // balanced acceleration/deceleration
      },
      "gentle": { 
        "$type": "transition", 
        "$value": "cubic-bezier(0.4, 0, 0.23, 1.38)" // slightly elastic, feels organic
      }
    }
  }
}

Mainly curious how duration and transition might work together in the motion spec moving forward.

[CITguy]

I tend to be in favour of more rigid specs to keep developers accountable, and therefore would not be in favour of this change.

Developer accountability shouldn't be the responsibility of the spec authors. It's the spec itself that defines the baseline of what tools need to support, not the other way around. If tools wish to remain competitive and relevant, maintainers will need to plan on keeping up with the spec throughout the lifespan of the tool. While it's not always practical to maintain 100% compatibility, the tool will eventually need to support newer versions of the spec, in order to remain competitive.