Repository navigation
UI: Update components to use Text component in place of ad hoc styles #76929
Description
What problem does this address?
Related to: #64340 (discussion starting at #64340 (comment))
The Text component added in #75870 provides a convenient abstraction for adopting design system typographical pairings, and should be the preferred way to style typography in UI components.
What is your proposed solution?
Update existing usage of typography styles to adopt the Text component instead:
-
Card.Title(Card: Use Text component for Title typography #76642) -
Breadcrumbs(@wordpress/admin-ui) (Refactor Admin UI / Breadcrumbs to use DS components and design tokens #77012)- Closest variant:
heading-lg(though note theTextvariant usesline-height-smnotline-height-lg, so the line-height pairing may need reconciling). Unclear if "heading" is correct semantics to use here.
- Closest variant:
-
Page(@wordpress/admin-ui) (Admin UI: use UI Text component in header #77372)- For title, same notes as
Breadcrumbs. For subtitle, closest match isbody-md.
- For title, same notes as
-
Badge- Exact match for
body-sm
- Exact match for
-
Notice.ActionLink(UI: use Text in Notice.ActionLink typography #77332)- Exact match for
body-md
- Exact match for
-
fieldutility styles- Exact match for
body-sm - Unclear how feasible it is to update call-sites to use
Textcomponents instead of utility styles without adding additional layer of DOM nesting, and if we're comfortable if an extra element is needed
- Exact match for
-
Dialog.Title- Closest variant:
heading-xl(current styles useline-height-xlbutText'sheading-xlisline-height-md)
- Closest variant:
This list is compiled based on existing usage of typography tokens in component stylesheets. While there's a long tail of components which could be updated to use the Text component, as well as usage of @wordpress/component's Text component, it's not considered part of the scope of this issue.
Additional candidates to consider, though unclear if they should use Text component because their typographical styling is limited and it may incur additional DOM nesting complications:
Activity
ciampo commentedon Mar 31, 2026
Maybe
Dialog.Title?aduth commentedon Mar 31, 2026
Yeah, I think that's another likely candidate. There are some complications, but I'll add it to the list in my morning.
Edit: Updated original comment.
kushagra-goyal-14 commentedon Apr 20, 2026
Hi @aduth
I started to look into field utility styles, while
Field.Descriptionhad (cleanbody-smmatch). But forField.Labelit seems that the default label usesfont-size-xs+font-weight-medium+uppercase+font-family-body, which is closest toheading-smexcept for the font-family. Theis-plainvariant is closest tobody-mdexcept for the font-weight.Is the preference to map
variantprop values toTextvariants (accepting small discrepancies), or hold off on label until variants align more cleanly? Not blocking anything — just want to avoid inventing a pattern if one's being discussed.ciampo commentedon Apr 21, 2026
I think ideally we should use only existing
Textvariants — let's check with @jameskoster if we can, and which variants should be used.jameskoster commentedon Apr 23, 2026
Adding a variant for labels doesn't seem very practical given it only really use one use case. Do we need to use
Textfor labels? Curious if it'd be simpler to just use the relevant tokens directly.ciampo commentedon Apr 23, 2026
We can definitely use the relevant tokens direclty, although I feel like it defeats the purpose of having the
Textcomponent? I assumedTextwould document and expose all of the "official" typography presetskushagra-goyal-14 commentedon Apr 23, 2026
@ciampo @jameskoster Please correct me if I’m wrong, but I have a small suggestion: Could we try a hybrid approach using the
@layeroverrides? Sinceheading-smandbody-mdmatch most of our needs, a targeted override inwp-ui-compositions(similar to the Notice.ActionLink pattern) - #77332 (comment) might fix the remaining mismatches while still leveraging the existingTextvariants.ciampo commentedon Apr 24, 2026
@kushagra-goyal-14 this is less about technicality (there are definitely ways to achieve that typography style) and more about the rules behind it.
My point of view is that if we use a certain typography preset, that preset should be documented and available through
Text. Otherwise, we're just creating custom presets, inconsistency, and fragmentation.jameskoster commentedon Apr 27, 2026
My feelings aren't strong. I see both sides of the argument. My questioning of the variant is due to what I perceive to be limited use (basically just
Form.Field.Label), and concerns about misuse by consumers—we wouldn't want random label styling applied to non-label elements in the UI. If the name was abstracted maybe that would be better, but I'm not sure there's a good one...If y'all feel the variant is the right approach then I definitely won't object!
ciampo commentedon Apr 27, 2026
Maybe we could start with a
textvariant that is accessible only from within the UI package? @aduth @mirka what do you think?mirka commentedon Apr 27, 2026
I also lean towards this. I think it would be fine to keep the
Field.Labelstyles as is (don't replace withText), until we have a use case for label-like text styling outside of the UI package whereField.Labelcan't be used for some reason.ciampo commentedon Apr 27, 2026
Sure, if y'all feel like applying styles directly, let's go for that option.
aduth commentedon Aug 10, 2026
Updating this today, the only remaining item was the field utility styling. Per previous comments, that's not something being considered for now, so let's consider this complete.
I've updated the original comment with links to pull requests that completed the replacements.