Add motion design tokens (duration and easing) to @wordpress/theme#76097
Open
jameskoster wants to merge 1 commit intotrunkfrom
Open
Add motion design tokens (duration and easing) to @wordpress/theme#76097jameskoster wants to merge 1 commit intotrunkfrom
jameskoster wants to merge 1 commit intotrunkfrom
Conversation
Introduces standardized duration and easing tokens for consistent animation timing across components. Includes a Storybook story with interactive demos and usage guidance for each token. Made-with: Cursor
jameskoster
added
Design System
|
Warning: Type of PR label mismatch To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.
Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task. |
|
Size Change: +104 B (0%) Total Size: 6.87 MB
ℹ️ View Unchanged
|
mirka
reviewed
Mar 4, 2026
Member
mirka
left a comment
mirka
left a comment
There was a problem hiding this comment.
Here's some context on why I'm hesitant to add motion tokens in this manner.
- If motion is not going to be themed dynamically through
ThemeProvider, it isn't necessary to manage as a official design token. (Which is good for avoiding token bloat in the stylesheet. But @aduth has suggested that we can manage tokens in the theme package as a central "data store", while still omitting them from the tokens stylesheet, so that could be a mitigation option.) - Most motion is already encapsulated at relatively higher levels (e.g. Tooltip/Dialog components, dropdown motion module, focus module). Which is both sufficient and easier for motion sharing across similar components.
- At the moment, there are Framer Motion usages that can't use values from CSS variables (not a blocker per se, but needs some planning on what to do).
So motion is one of those categories where I think we need to weight the cost–benefit. Maybe my intuition of the cost is overblown, and benefit underestimated.
These are just my hesitations — open to everyone's thoughts!
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Contributor
Author
|
I defer to y'all on the implementation :) What's not clear to me is how we'd ensure consistent profiles (easing, duration) across components without tokens. Is that something we'd have to maintain manually?
Could there be a world where it is theme-able? For instance would it make sense for |
Member
I think this strikes at an interesting question about what values make sense to be a design token. This interpretation reads to me as being based on the ability to customize, though I've personally approached it more as encoding design decisions that apply uniformly across components, that we can update in one place and cascade (single source of truth), and that can be used in the design process (e.g. Figma variables) for better code/design parity. In particular, the way these are being proposed feel to me like they aren't tied to any one specific component but apply generally across the system. I'm not as sure about design tooling, but it feels like a value we'd want to expose and use in motion design. Or maybe reframing: What is it about what's said about how we can manage motion through higher-level abstractions that is untrue about how we think about typography or color, for example? |
Member
I guess a large part of my skepticism is about the validity of encoding the motion design decisions at the individual CSS property level.
|
Member
|
Another fun thought that came to mind in support of higher-level encapsulation! Let's say we had an "intensity" setting for motion, where high intensity is very fun and low intensity is more calm. Could this be achieved globally by changing token values at a CSS property level? I'd say no. Each motion module (tooltips, dialogs, etc) needs to tweak itself appropriately for each intensity level, which would probably be switched by entire declaration blocks via a data attribute. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Screen.Recording.2026-03-03.at.16.33.21.mov
What
Adds motion design tokens to
@wordpress/theme— a set of duration and easing curve tokens for standardizing animation timing across components.Duration tokens
--wpds-motion-duration-xs50ms--wpds-motion-duration-sm100ms--wpds-motion-duration-md200ms--wpds-motion-duration-lg300ms--wpds-motion-duration-xl400msEasing tokens
--wpds-motion-easing-standardcubic-bezier(0.4, 0, 0.2, 1)--wpds-motion-easing-deceleratecubic-bezier(0, 0, 0, 1)--wpds-motion-easing-acceleratecubic-bezier(1, 0, 1, 1)--wpds-motion-easing-emphasized-deceleratecubic-bezier(0.29, 0, 0, 1)--wpds-motion-easing-emphasized-acceleratecubic-bezier(1, 0, 0.2, 1)Why
Animation timing is currently hardcoded across components with magic numbers. The
Dialogcomponent, for example, uses0.2s cubic-bezier(0.29, 0, 0, 1)for its entrance and0.2s cubic-bezier(1, 0, 0.2, 1)for its exit — values that were chosen thoughtfully but aren't reusable by other components.Centralizing these values as tokens:
Design decisions
Easing curve values: The
emphasized-decelerateandemphasized-acceleratecurves are taken directly from the existingDialogcomponent to maintain backward compatibility. When Dialog adopts these tokens, its animations will be unchanged.Easing vs. enter/exit naming: The tokens use descriptive physics-based names (
decelerate,accelerate) rather than semantic names (enter,exit). This is more flexible; a deceleration curve is primarily used for entrances, but could also suit other scenarios where an element needs to settle into place.Duration scale: The five-step
xs–xlscale provides enough granularity without being overwhelming. The descriptions intentionally avoid prescribing specific components to specific durations, since the right choice depends on the element's size, prominence, and context.Mapping to existing components
The easing curves were chosen to align closely with values already in use:
Dialog (
@wordpress/ui) currently uses:0.2s cubic-bezier(0.29, 0, 0, 1)→duration-md+easing-emphasized-decelerate(exact match)0.2s cubic-bezier(1, 0, 0.2, 1)→duration-md+easing-emphasized-accelerate(exact match)Dropdown menus (
@wordpress/componentsMenu and@wordpress/uidropdown-motion) currently use:200ms cubic-bezier(0, 0, 0, 1)→duration-md+easing-decelerate(exact match)80ms linear→ closest toduration-sm(100ms);lineardoesn't need a tokenAdopting these tokens in those components would require no visual change for
Dialogand only a minor fade duration adjustment (80ms → 100ms) for dropdown menus.How
packages/theme/tokens/motion.json(DTCG format, withdurationandcubicBeziertypes)terrazzo.config.tsto include the new file and generateDurationSizeandEasingTypeScript typesmotion.story.tsx) with interactive animation demos. Each token row shows the token name, usage guidance, and an animated thumb/track. The easing section includes a duration picker to preview curves at different speedsTesting
npm run --workspace @wordpress/theme buildto verify the token build succeedsdesign-tokens.css