Adopt surface-width design tokens for Dialog, Notice, and Modal widths#76494
Merged
jameskoster merged 11 commits intotrunkfrom Mar 17, 2026
Merged
Adopt surface-width design tokens for Dialog, Notice, and Modal widths#76494jameskoster merged 11 commits intotrunkfrom
jameskoster merged 11 commits intotrunkfrom
Conversation
Align component width constraints with the --wpds-dimension-surface-width-* tokens from @wordpress/theme, replacing hardcoded pixel values in the UI Dialog and updating SCSS variables for the components Modal to match the token scale. Made-with: Cursor
jameskoster
added
[Type] Enhancement
jameskoster
added
Design System
github-actions
bot
added
[Package] Base styles
Made-with: Cursor
|
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. |
|
Flaky tests detected in fcb71f0. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23207913834
|
mirka
reviewed
Mar 13, 2026
Remove $modal-min-width, $modal-width-small, $modal-width-medium, and $modal-width-large SCSS variables and reference --wpds-dimension-surface-width-* tokens directly in Modal, link-control, url-popover, and page-patterns styles. Made-with: Cursor
…lity Keep $modal-min-width, $modal-width-small, $modal-width-medium, and $modal-width-large with updated token-aligned values and a deprecation notice, since third-party code may depend on them. Made-with: Cursor
…ns are available Keep using the deprecated $modal-width-* SCSS variables in block-editor and edit-site packages since the design token CSS custom properties are not yet loaded in those contexts. Added TODOs to migrate once available. Made-with: Cursor
Made-with: Cursor
github-actions
bot
added
[Package] Block editor
…ing widths Made-with: Cursor
jameskoster
commented
Mar 16, 2026
| position: relative; | ||
| min-width: $modal-min-width; | ||
| // TODO: Replace with var(--wpds-dimension-surface-width-sm) once design tokens are available. | ||
| min-width: 350px; |
Contributor
Author
There was a problem hiding this comment.
I replaced this with a hard-coded value for now because the new modal min-width value caused a small visual regression:
Contributor
There was a problem hiding this comment.
This comment may be confusing, given that the token is already available?
Contributor
Author
There was a problem hiding this comment.
I thought they weren't available in this context? 🤔
Either way the surrounding code will need a small refactor to fix this regression. I guess the comment could be simplified though. What do you think? Something like:
Replace with var(--wpds-dimension-surface-width-*) token.
Contributor
There was a problem hiding this comment.
Maybe they are not and I'm getting confused. Anyway, the shorter comment sounds good to me.
The bigger question is: are the new DS tokens compatible with these designs, or are these exceptions likely stay as exceptions? In other words, this PR is a good test for the values that we picked for our tokens.
Contributor
Author
There was a problem hiding this comment.
I think its more a case of this design not being compatible with any tokens that have smaller values than the current ones. But that's due to a hard-coded min-width value on the search control, and not really a failing of the tokens. The link-control UI should be capable of adapting to different widths, and it could do this easily if that min-width was calculated based on the token rather than hard-coded. But there's a separate question about which token to use for the link-control UI. That's why it feels like something to address separately.
Contributor
There was a problem hiding this comment.
It would be good to get this resolved with LinkControl. Let's try and adjust the design in a follow up 🙏
Member
There was a problem hiding this comment.
I thought they weren't available in this context?
To clarify, design tokens are now available for use in any packages built in this repo, at least in a minimally viable way. The design-tokens stylesheet doesn't have to be loaded for it to work (due to fallback values being injected at build time), and accent colors shades will be roughly appropriate for the colors set by --wp-admin-theme-color.
ciampo
reviewed
Mar 16, 2026
ciampo
reviewed
Mar 16, 2026
Made-with: Cursor
ciampo
reviewed
Mar 16, 2026
|
Size Change: +121 B (0%) Total Size: 8.75 MB
ℹ️ View Unchanged
|
Contributor
I think this is something to consider carefully — having a set of DS tokens, but using them only partially, may be a sign that our DS tokens are not comprehensive (or don't suit our needs), or otherwise, a sign that our UIs are using too many widths and should be aligned to fewer values instead. |
Made-with: Cursor
Contributor
Author
|
@ciampo would you prefer to update any component with a hard-coded width in this PR? |
Contributor
I'm definitely ok with working on those components in follow-ups, as far as we can still somehow apply the current tokens. What I want to avoid is having a set of tokens that don't suit our needs. So I think we're aligned? |
ciampo
approved these changes
Mar 17, 2026
Contributor
ciampo
left a comment
ciampo
left a comment
There was a problem hiding this comment.
Looking good overall 🚀
And acknolwedging that there is follow-up work to do:
- refactor more components (such as
GuideandSnackbar) - rework the
LinkControlUI to work better with narrower (or, in general, more flexible) widths
… and link-control Made-with: Cursor
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
4 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.
Follow-up to #76047.
What
Adopt
--wpds-dimension-surface-width-*design tokens for component width constraints in the UI and components packages.Why
The
@wordpress/themepackage recently added asurface-widthtoken scale to standardize surface/container widths across the design system. Several components -- Dialog, Notice, and Modal -- were using hardcoded pixel values for their width constraints. Aligning these with the token scale ensures consistency, makes future width adjustments easier to coordinate, and reduces the risk of drift between the newer UI package and the legacy components package.How
packages/ui/src/dialog/style.module.css): Replaced five hardcoded pixel values withvar(--wpds-dimension-surface-width-*)custom properties. Updated JSDoc intypes.tsaccordingly.packages/ui/src/notice/style.module.css): Resolved a TODO about replacing320pxwith a theme token. Since container queries don't supportvar()(womp womp), the value remains hardcoded with a comment documenting its alignment with--wpds-dimension-surface-width-sm.packages/base-styles/_variables.scss): Updated the$modal-width-*SCSS variables to match the token scale values. Added comments referencing the corresponding tokens. Downstream consumers (link-control, url-popover, page-patterns) inherit these changes with minor visual adjustments.Dialog/Modal width changes
--wpds-dimension-surface-width-sm--wpds-dimension-surface-width-md--wpds-dimension-surface-width-lg--wpds-dimension-surface-width-2xlNote
I can go either way between mapping
largetoxl(720px) or2xl(960px), with a slight preference for2xl.Note: Other components in the
componentspackage (e.g. Snackbar, Guide) also have hardcoded widths that could potentially align with this token scale. I'm open to adopting the tokens for these components in this PR too, we'll just need to decide on the values.Testing instructions
npm run storybook:dev