Theme package: Add surface width design tokens#76047
Merged
jameskoster merged 4 commits intotrunkfrom Mar 13, 2026
Merged
Conversation
Add `--wpds-dimension-measure-*` tokens (xs: 320px, sm: 400px, md: 560px, lg: 720px, xl: 960px) for standardizing component width constraints across Card, Dialog, and similar components. Made-with: Cursor
jameskoster
added
[Type] Enhancement
|
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. |
|
Size Change: +47 B (0%) Total Size: 6.89 MB
ℹ️ View Unchanged
|
Member
|
In relation to the naming, do you have plans to add "height" tokens, and if so, what would that be called? |
Contributor
Author
|
I think height tokens have been floated as an idea for input/button sizes. In CSS spec language, "extent" (sometimes "length") has been used to describe the block-size dimension, similar to how "measure" describes the inline-size dimension.
Do you think we're too far in the weeds here? :) |
Member
|
I'm fine with plain |
Simplifies the naming from `--wpds-dimension-measure-*` to `--wpds-dimension-width-*` for a cleaner pairing with a future `height` token family. Made-with: Cursor
Contributor
Author
|
I renamed to |
jameskoster
changed the title
|
Flaky tests detected in 5ee8d84. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/22903749999
|
Contributor
|
What about much smaller widths, as the ones we use for icons / buttons / input controls? More in general, I wonder if we're missing smaller values in the scale. Beyond that, this PR will require a lot of manual testing — @jameskoster , have you already given it a first pass? |
Contributor
Author
|
Good question. My feeling is they're a different category of token rather than an extension of the The width tokens are about constraining container widths; dialogs, cards, drawers, panels, etc. They're more about layout. Icon sizes and button min-widths are about sizing individual elements and they're generally square or near-square. If they were part of the same scale there would be a big gap between the largest 'element size' ( Perhaps that's where a
WDYT? |
Contributor
|
So, two separate families of tokens. Then maybe |
Contributor
Author
|
Maybe |
Contributor
|
Yeah, I think that |
Contributor
Author
|
Based on discussion in #76325 we might need to include a smaller value in the scale for certain popovers and menus. Something around |
Adds a 2xl step (960px) and shifts the scale down so xs starts at 240px, covering narrower UI elements like compact popovers and menus. Made-with: Cursor
mirka
approved these changes
Mar 10, 2026
Member
mirka
left a comment
mirka
left a comment
There was a problem hiding this comment.
Looks good, pending the name change.
Aligns with the surface-based naming convention used by other token categories like color (e.g. bg-surface, fg-surface). Made-with: Cursor
jameskoster
changed the title
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.
What?
Adds a new set of
surface-widthdesign tokens to@wordpress/theme:--wpds-dimension-surface-width-xs--wpds-dimension-surface-width-sm--wpds-dimension-surface-width-md--wpds-dimension-surface-width-lg--wpds-dimension-surface-width-xl--wpds-dimension-surface-width-2xlAlso adds a corresponding
SurfaceWidthSizeTypeScript type ('xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl').Why?
Components like
Dialogcurrently hardcode their width constraints (e.g.max-width: 384px,max-width: 512px). These values are scattered across component stylesheets with no shared source of truth, making it difficult to maintain consistency.Width tokens provide a standardized scale for component widths, similar to how
paddingandgaptokens standardize spacing.Examples of other components that could benefit from these tokens:
How?
surface-widthgroup to the existingdimension.jsontoken file, alongsidepaddingandgap.SurfaceWidthSizetype pattern to the Terrazzo config for TypeScript generation.Design decisions
Naming: "surface-width"
We considered "measure" (a typography term for line length, used by methodologies like Every Layout) for its writing-mode agnosticism and design-concept framing. Ultimately we chose "surface-width" for its simplicity and because it pairs cleanly with a potential future
surface-heighttoken family. It also aligns nicely with color tokens e.g.-wpds-color-stroke-surface-warning,--wpds-color-bg-surface-neutral.Token values
The scale starts at 240px to cover narrower UI elements like compact popovers and menus, and extends to 960px as a well-established content width. The intermediate values provide natural stopping points informed by common component width needs. They intentionally deviate from the current hardcoded Dialog sizes (384px, 512px, 840px) in favor of a more coherent scale. All values sit on the 4px base grid.
No density modes
Unlike
paddingandgap, width tokens don't vary across compact/comfortable density modes. Component width constraints are about content layout, not information density. We can explore adding density-responsive width values later if use cases emerge.Testing Instructions
Verify the tokens build correctly:
Confirm the new
--wpds-dimension-width-*variables appear inpackages/theme/src/prebuilt/css/design-tokens.css.