Theme package: Add element size design tokens#76545
Open
jameskoster wants to merge 3 commits intotrunkfrom
Open
Theme package: Add element size design tokens#76545jameskoster wants to merge 3 commits intotrunkfrom
jameskoster wants to merge 3 commits intotrunkfrom
Conversation
jameskoster
added
[Type] Enhancement
|
Size Change: +29 B (0%) Total Size: 7.66 MB
ℹ️ View Unchanged
|
|
Flaky tests detected in e776397. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23256082544
|
|
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. |
Add xs/sm/md/lg size tokens to the dimension token family for consistent element sizing across components. Made-with: Cursor
Made-with: Cursor
jameskoster
force-pushed
the
add/theme-size-tokens
branch
from
e150582 to
e776397
Compare
Contributor
|
Assuming that we can always easily add options below |
mirka
approved these changes
Mar 18, 2026
Member
mirka
left a comment
mirka
left a comment
There was a problem hiding this comment.
Assuming that we can always easily add options below
16and above40, will we ever need "middle" sizes such as20and36?
Personally I'm not too concerned about this at the moment, given that our current sizes came out of a pretty mature (?) real-life system, and they seem to be holding up.
Comment on lines
+211
to
+226
| "xs": { | ||
| "$value": "{wpds-dimension.primitive.space.40}", | ||
| "$description": "Extra small element size" | ||
| }, | ||
| "sm": { | ||
| "$value": "{wpds-dimension.primitive.space.60}", | ||
| "$description": "Small element size" | ||
| }, | ||
| "md": { | ||
| "$value": "{wpds-dimension.primitive.space.70}", | ||
| "$description": "Medium element size" | ||
| }, | ||
| "lg": { | ||
| "$value": "{wpds-dimension.primitive.space.80}", | ||
| "$description": "Large element size" | ||
| } |
Member
There was a problem hiding this comment.
Would it be helpful to include some of this usage guidance in the token descriptions?
See also the guidance for the size prop on Button:
Contributor
Author
There was a problem hiding this comment.
I had that originally, but then I realised it's possible that element sizes might change in the future (e.g. checkboxes become sm rather than xs. Granted that's unlikely, but it did give me pause to include explicit examples. I can go either way tbh :)
Member
There was a problem hiding this comment.
I guess we need a shared understanding that some tokens are semantic/prescriptive ("use this token for X"), but the t-shirt size tokens have none of that prescriptiveness ("these are the values you can choose from, but they're just relational to each other so pick whatever"). Is that closer to how we're considering these?
That's not off the table, but a downside of that model is that it's going to make ecosystem (third-party) adoption of the t-shirt tokens a more shaky proposition. If they use xs somewhere thinking it will be the same size as a checkbox, and one day we change checkbox sizes to sm, there would be no point for them to have used the token in the first place. So for third-parties to benefit from token use, we kind of need to state what each token is supposed to be used for, and to the best of our reasonable ability, try to uphold that initial statement.
Made-with: Cursor
Contributor
Author
|
I remembered that Tabs are 48px tall so I added an
I don't think we'd want 36. 20 is unlikely for interactive elements, but might be useful for creating a |
Contributor
|
Agree, 36 is not part of base-8, I'd avoid that value if we can. As a provication you should feel free to ignore: should the tabs be 40px? I can see arguments a few ways, in that if the tabs are meant to be able to hold 32 or 40px buttons inside, arguably they need to be taller, but it's not clear. And relatedly, the top toolbar is 64px. |
Contributor
Author
|
The toggle in Maybe it makes sense to start with tokens for I have a nagging suspicion that we'll want |
Contributor
I'd also start without that if we can. But we can embrace base4 and that allows it. |
Contributor
|
Adding But adding |
Contributor
Author
|
Yes line-height is the main reason I suspect we might want a |
Contributor
|
Assuming density is more about the empty space, then I don't think it should affect the content height, but more aspects like padding. I'll ask you a question in return: if we ever changed typography settings and the body text line height changed, would that affect the height of buttons / badge, etc.? Re. Button, for example, I guess we're picking the height not as a direct consequence of the text line-height (correct me if i'm wrong). For similar reasons, my instinct with badge would be to do the same — ie. decide that it's |
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.
What
Adds a
sizecategory to the dimension token family with five new design tokens:--wpds-dimension-size-xs--wpds-dimension-size-smsmallbuttons, icons)--wpds-dimension-size-mdcompactbuttons/inputs)--wpds-dimension-size-lg--wpds-dimension-size-xlWhy
Components like buttons, checkboxes, icons, tabs, and other interactive controls currently use hardcoded pixel values for sizing. A shared set of size tokens provides a consistent, predictable scale that can be referenced across components, reducing ad hoc values and making it easier to maintain visual consistency.
How
sizegroup totokens/dimension.jsonwithxs,sm,md,lg, andxlentries, each referencing an existing space primitive (space.40throughspace.90).SizeTypeScript type interrazzo.config.tsso the scale is available as a union type ('xs' | 'sm' | 'md' | 'lg' | 'xl').