Motion time, duration and delay tokens

[alex-page]

Problem

transition: transform var(--p-duration-200) var(--p-easing-ease) var(--p-duration-50);

Today we don't have a token for delay. When we update the values across the admin it is unclear if we want to link duration and delay. Re-using our current duration token is confusing for our builders as it is tied to transition-duration and not transition-delay.

Documentation on polaris.shopify.com and in VSCode Autocomplete for these values is important. The future solution should be clear to our users that they are linked/unlinked and why we made this decision. We also should make it clear what our users should be thinking about when setting duration and delay values.

Whatever our choice it's a reversible decision. It is much easier to consolidate two seperate tokens then split one into two... but it is possible.

Proposed approaches

transition: transform var(--p-duration-200) var(--p-easing-ease) var(--p-delay-50);

New delay token: Seperate duration and delay into two seperate token groups. It's not hard to update 10 values instead of 5. It gives us flexibility to make specific documentation for the values and gets our values closer to web standards. Documentation follows two seperate tracks as we explain two seperate values.

transition: transform var(--p-time-200) var(--p-easing-ease) var(--p-time-50);

Single time token: Have a single token for duration and delay called time. Users only need to learn one value but have to learn the value from the system and not from the web standards. Documentation needs to split the time variable usage with delay/duration.

[johanstromqvist]

Both seems pretty low risk, but I personally favour distinct token group, like so:

transition: transform var(--p-duration-200) var(--p-easing-ease) var(--p-delay-50);

transition-duration: var(--p-duration-200);
transition-delay: var(--p-delay-50);

Assumptions:

• time is an abstraction and it's unclear to me when and how it would have value
• time assumes one central lever for both properties. I have low confidence that it would give us the control we want.
• Mapping each property to its own token seem to make writing, auto-complete, searching, reading, etc easier. E.g. Think "delay" -> Search "delay".

[sam-b-rose]

Agreed, both approaches are low risk and could be adjusted in the future. I lean towards having a single time token:

transition: transform var(--p-time-200) var(--p-ease) var(--p-time-50);

because of the following assumptions:

• Less to learn, smaller token API
• Can be used for multiple property types (similar to color and space tokens)
• Avoids duplication of tokens with the same values
• We are currently only provides semantic distinction related to the property, not the token value
• Currently, these tokens aren't levels we can manipulate since they are tied to the token value and not semantic (ex: -100 instead of -fast)

In relation to the last two points, if we had token names that were not value-based, then I'd say having separate tokens could make sense (ex: duration-fast vs delay-fast) if we wanted to manage how duration and delay differ in speed.

time makes sense to me and conveys that the token contains a time value (ms or s) and can be used as a standardized set of values I can use for time-related properties (delay and duration).

Mapping each property to the same token would help utilize the same autocomplete or migration logic and reduce the need to distinguish between delay and duration: simple parsing of shorthand notations, -delay and -duration map to the same values.

[aaronccasanova]

This is my preference as well (e.g. having a single time token). As hinted at in your closing thoughts, introducing two distinct tokens incurs quite a bit of complexity in our migration and linting logic as we have to map our implementations to the spec.

[johanstromqvist]

Happy to proceed with that!

[heyjoethomas]

Yeah I would also separate the two. I think it is easier to understand what is happening when reading code and allows us more future control.

To @samrose3 point:

In relation to the last two points, if we had token names that were not value-based, then I'd say having separate tokens could make sense (ex: duration-fast vs delay-fast) if we wanted to manage how duration and delay differ in speed.

I think this is something worth looking at for all these tokens. I am usually a fan of this type of naming because it is so much more human and approachable. I also think we make it more difficult because we use numbers in numerous ways:

1. multiplier like on spacing
2. a scale like in the future color work
3. actual value in animation/duration

This makes it even more difficult to know if duration-50 is just a relative value in a scale or actually 50ms. Just food for thought.

[sam-b-rose]

Agreed, my above opinion was based on the assumption we wanted to keep the token naming related to value, but I would be in favor of exploring other naming conventions that gives us a lever to pull (i.e. not tied to the value and can be adjusted).

If that were the case, having separate tokens could make sense and provide more refined system leverage. However, I'm not sure we need or want to own that level of detailed control. For example, even if we had --p-duration-fast and --p-delay-fast and made tweaks, it feels odd that they could be different -fast values. I would almost still prefer the simplicity of a single time scale (ex: --p-time-fast, --p-time-faster) 🤷 not a strong opinion however

[johanstromqvist]

The value based naming was a way to move forward with motion tokens before knowing what good semantic naming looks like. Perhaps @aaronccasanova or @LauraAubin have more context or could dig up issues capturing this. The intention at the time was to use aliases for the semantics.

E.g. 100ms -> duration-100 -> duration-default

Side note: transition speed is relative to what is changing and the magnitude of the change, which I think makes slow / fast a bad convention. short long durations makes more sense logically, but I wonder how useful it is.

[johanstromqvist]

Zooming out. We might over index on this particular problem, but it might expose a higher level need; General guiding principles for all tokens that capture their priorities, constraints, accepted tradeoffs, etc. Having those could both make questions like these easy to agree on and unify the approach to all tokens. Ideal if those priorities were based on real use cases and dev X insight.

[alex-page]

Big agree @johanstromqvist ✨

[heyjoethomas]

1000% this. I think it would be very beneficial for someone/a group to look at tokens holistically as an entire set and come up with constraints, principles and aiming across that entire level of the system. Similar to how we should have a consistent way to do things across props in our components.

[sam-b-rose]

Marking this as the answer for now. Seems like we need a larger discussion around tokens. Will keep the current tokens as-is until we have bandwidth to discuss a larger token refactor.

[jesstelford]

🌶️ Hot take

Don't use tokens at all.

Completely remove the current duration tokens, and just stick with ms / s absolute values.

Reasoning

Duration / delay isn't semantic on its own

transition speed is relative to what is changing and the magnitude of the change. - @johanstromqvist

In general, my preference is semantic tokens which convey meaning beyond the absolute value. However, durations and delays on their own have very little meaning (or rather; they're only one small part of the meaning): they must be viewed in context of what property is being transitioned, how much is it being transitioned by, what is it transitioning in contrast to, etc.

Semantic tokens like fast, etc, are relative terms, and could mean a completely different thing in different frames of reference. Therefore, any names we give them will lose their meaning as soon as they're used in multiple contexts.

Delay can be relative to duration

There are instances where transitions/animations are stacked (eg; sliding in dot points one after another). When this happens, the delay is relative to the previous animation's duration. In this case, the meaning of a hypothetical --p-time-fast when used as a delay is completely different to the meaning of --p-time-fast when used as a delay for a non-stacked animation.

The big benefit of semantic tokens is the freedom for us to change the underlaying value without breaking changes across usages of the system. However, in the stacked animations case where there's a --p-duration-* and --p-delay-* set of tokens, if the delay set were ever to diverge from the duration set, animations would no longer be correctly stacked. To fix this, we could introduce a --p-delay-as-duration-* scale, but that feels unhelpful.

Why not just use --p-duration-* in those cases? Because it would appear like a mistake that could be "fixed" by accident, thereby breaking the meaning.

Eg; if the code looked like this everywhere else:

transition: left var(--p-duration-fast) var(--p-delay-slow);

But an unwitting developer (or automated migration / lint rule) comes across this:

transition: left var(--p-duration-fast) var(--p-duration-slow);

It might appear as a mistake, and the second duration changed to a delay token.

Duration & delay are order-dependent

The CSS spec says when using the transition or animation shorthand declarations, the first <time> value is always the duration, and the second <time> value is always the delay. All other values can be in any order. Ie, in all of these examples, 100ms is the duration, and 16ms is the delay:

transition: left 100ms ease 16ms;
transition: 100ms 16ms ease left;
animation: ease 100ms 16ms left;
animation: reverse 100ms both paused slidein left 16ms, 100ms paused right 16ms ease;

Given this restriction, it's always clear which value is duration and which value is delay for a human (who knows that rule, I initially did not), possibly negating the need for a differentiating token.

Time is only used for transition/animation

(I'm about 90% sure that...) The <time> tokens for duration/delay are only ever usable with transition-{delay,duration} & animation-{delay,duration} declarations (and their shorthand equivalent) per the CSS spec. So the scope of where these tokens might be used is quite narrow.

Real world cases are varied

Have a look at the all the uses of duration and delay which do not match one of our existing duration tokens today: https://github.com/Shopify/web/compare/polaris-migration-animation...polaris-migration-transition-manual (search for no matching duration).

Alternative Proposals

Do nothing

Leave the hard coded s and ms values as-is, and discourage the use of duration tokens (maybe deprecate / remove the docs pages?). Given that Time is only used for transition/animation, and we have a migration which already detects them, it's trivial to revisit in the future.

Lean on patterns and documentation

Instead of codifying these values, lean on documentation and patterns to inform and educate the design/dev/ux folks who are adding transition/animations to their work. Similar to Google's RAIL model. Then let them make their own decisions on timing from there.

Components for common animations

Solve for the whole picture of a transition/animation by providing components which bake in a set of standard animations in full control of the property, duration, delay, easing, etc. Making these animation components composable with other components (eg; <Box>) means we bake in best-practice for the whole animation, while giving the builders the freedom to apply them wherever they want.

For the avoidance of doubt: I am not suggesting we add animation props to specific components:

// This
<Animate animation="appear">
  <Card>hello</Card>
</Animate>

// NOT this
<Card animation="appear>hello</Card>

---

Given the above concerns, the ROI on using tokens might not be worth it for such a subset of usecases.

[sam-b-rose]

Sometimes the best momentary action is no action–great points and proposal! Does feel a bit odd not having a set of "guidance values" to pick from for transition/animation timing, but I agree the UX context is a huge factor and components would be an ideal composition strategy.

Should we handle motion migrations similar to how we are handling layout–swapping the need for custom SCSS styles with transition components? Creating motion components is certainly a large scope, but could be worth the initiative for a more fully-composable system.

[aveline]

Components for common animations

This fits in along the lines of something I've been thinking about. A group of design opinions (in this case a combination of values that make up an animation) should live in components, not tokens. Brought this up in a discussion about Dividers.

[aaronccasanova]

A group of design opinions (in this case a combination of values that make up an animation) should live in components, not tokens.

I don't particularly agree with this statement. I think a group of design opinions should be encapsulated in a composite design token and doesn't need to be tied to a particular entity. Encoding our design opinions in tokens allows us to generate outputs for any target e.g. classes, mixins, react components, x framework components, etc.

That said, I am a huge fan of composing animations with components as they are easy for teams to adopt and create elevated merchant experiences.

Update: For reference, I just noticed the Design Tokens Format Module includes a transition composite token example

[jesstelford]

@aaronccasanova Yes! I think we're saying the same thing. I used components as an example because within Shopify, we're opinionated about using React, and by leveraging that opinion we can reduce some of the work an engineer has to do.

Of course, "why not both!?". I could easily see an implementation that uses a composite design token under the hood (used in non-react contexts) that is wrapped in a React component with special affordances to Shopify or others who build using React for a better DX 👍

@samrose3

Creating motion components is certainly a large scope

This could be further generalised to "Creating components wrapping all tokens is a large scope". My ideas here might be just plucking at the loose thread which actually unravels the entire jacket 😅

[aveline]

The example linked of the composite design tokens makes a lot more sense than what we currently have in our tokens for composite tokens (specifically the borders). The existing shorthand format is probably not very usable in non-web contexts.