Refactor field description components for consistent typography by kushagra-goyal-14 · Pull Request #77791 · WordPress/gutenberg

kushagra-goyal-14 · 2026-04-29T10:01:05Z

What?

Updates field utility styles in @wordpress/ui to use the Text component for typography instead of ad hoc CSS utility classes. Specifically refactors:

Field.Description
Field.Details
Fieldset.Description
Fieldset.Details

Maintains original CSS styles for Field.Label and Fieldset.Legend per design system direction to avoid creating limited-use typography variants.

Why?

This follows the design system direction in #76929 to standardize typography via Text variants. Field descriptions and details have exact matches to body-sm typography pairing, reducing CSS utility duplication and providing a consistent, documented typography system.

How?

Refactored field components to compose:

Text with variant="body-sm" (for descriptions/details)
render={ <_Field.Description|_Fieldset.Description /> } using Base UI's render prop

This approach:

Avoids extra DOM nesting via the render prop pattern
Maintains semantic HTML elements (<p> tags remain <p>)
Leverages Text component's built-in defenseStyles for cascade protection

Testing Instructions

Run focused unit tests: npm run test:unit -- packages/ui/src/form/primitives
Verify form field rendering and typography in Storybook: npm run storybook:dev
Check that Field.Description, Field.Details, and Fieldset components display correct typography and colors

Use of AI Tools

Used Claude AI to help analyze the codebase, draft migrations, and review typography token mappings.

…ent typography and remove unused styles

…tion components

github-actions · 2026-04-29T15:35:05Z

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.

Required label: Any label starting with [Type].
Labels found: [Package] UI.

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.

github-actions · 2026-04-29T15:35:08Z

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 props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: kushagra-goyal-14 <kush123@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

mirka · 2026-04-29T16:13:15Z

-			{
-				className: clsx(
-					defenseStyles.p,
-					fieldStyles.description,


Can you provide before/after screenshots? Because at first glance this looks like it dropped the color. Also unclear why we would no longer need the defense style.

mirka · 2026-04-29T16:13:29Z


-	const element = useRender( {
-		defaultTagName: 'p',
-		render,


Looks like the render prop is silently dropped.

…me management

kushagra-goyal-14 · 2026-04-29T17:12:14Z

Thanks for the review, @mirka. The color styling and render prop were accidentally removed while I was trying to get the unit tests working. I've fixed both; defense styles are actually still applied through the Text component internally.

ciampo · 2026-04-30T07:53:31Z

+		<Text
+			render={ render ?? <p ref={ ref } id={ id } { ...restProps } /> }
+			variant="body-sm"
+			className={ clsx( fieldStyles.description, className ) }
+		/>
+	);


props like ref and id should be applied to Text — see the docs

Also, no need to explicitly merge classname with clsx, we can simply forward it via ...props

We should basically copy what Card.Title does (changing the variant to "body-sm")

gutenberg/packages/ui/src/card/title.tsx

Lines 5 to 24 in 1957df1

const DEFAULT_TAG = <div />;

/**

* The title for a card. Renders as a `<div>` by default — use the `render`

* prop to swap in a semantic heading element when appropriate.

*/

export const Title = forwardRef< HTMLDivElement, TitleProps >(

function CardTitle( { render = DEFAULT_TAG, children, ...props }, ref ) {

return (

<Text

ref={ ref }

variant="heading-lg"

render={ render }

{ ...props }

>

{ children }

</Text>

);

}

);

including defaulting render to the DEFAULT_TAG

ciampo · 2026-04-30T07:54:33Z

+			<Text
+				render={ <div ref={ ref } { ...restProps } /> }
+				variant="body-sm"
+				className={ className }


Same as previous comment re. ref and className

ciampo · 2026-04-30T07:56:03Z

 	.description {
-		--_gcd-p-font-size: var(--wpds-typography-font-size-sm);
-		--_gcd-p-line-height: var(--wpds-typography-line-height-xs);
-		--_gcd-p-margin: 0;


It looks like Text doesn't include this gcd variable — @mirka , do you think we should move it to Text ?

gutenberg/packages/ui/src/text/style.module.css

Lines 4 to 6 in 1e307ab

.text {

margin: 0;

}

If I'm not misunderstanding, I believe they'd be covered by this?

gutenberg/packages/ui/src/utils/css/global-css-defense.module.css

Lines 96 to 108 in 83f8f52

p.p {

font-size: var(--_gcd-p-font-size, 13px);

line-height: var(--_gcd-p-line-height, 1.5);

margin: var(--_gcd-p-margin, 0);

}

/* Narrowed down to h[1-6] elements only, to support element multiplicity of Text component. */

:is(h1, h2, h3, h4, h5, h6).heading {

color: var(--_gcd-heading-color, var(--wpds-color-fg-content-neutral));

font-size: var(--_gcd-heading-font-size, inherit);

font-weight: var(--_gcd-heading-font-weight, var(--wpds-typography-font-weight-medium));

margin: var(--_gcd-heading-margin, 0);

}

gutenberg/packages/ui/src/text/text.tsx

Lines 23 to 24 in 83f8f52

defenseStyles.heading,

defenseStyles.p,

Oh wait, I think I get what you're saying. #77461 was incomplete, we need to add both heading and p gcd settings for all the Text style variants. I'll prepare something.

gutenberg/packages/ui/src/text/style.module.css

Lines 84 to 86 in 1e307ab

.body-sm {

--_gcd-p-font-size: var(--wpds-typography-font-size-sm);

--_gcd-p-line-height: var(--wpds-typography-line-height-xs);

Thanks for the review, if I am not wrong, and for this case, doesn't body-sm already have the --_gcd-p-* variables set (text/style.module.css lines 84-86) ?

@kushagra-goyal-14 I think it's ok remove those --_gcd-* variables in this PR, as already applied currently — @mirka will reinforce Text styles and overrides separately

Fix in #78172

ciampo · 2026-05-11T16:06:14Z

@kushagra-goyal-14 as soon as #78172 is merged, you should be able to rebase (or merge trunk) to include those fixes.

Let me know when you've done that and addressed remaining feedback, and we'll be able to take another look at this PR 🙌

kushagra-goyal-14 added 2 commits April 29, 2026 15:14

refactor: update field description components to use Text for consist…

e747fab

…ent typography and remove unused styles

refactor: simplify className usage in Description and FieldsetDescrip…

2b857d8

…tion components

github-actions Bot added the [Package] UI /packages/ui label Apr 29, 2026

kushagra-goyal-14 marked this pull request as ready for review April 29, 2026 15:34

kushagra-goyal-14 requested a review from a team as a code owner April 29, 2026 15:34

mirka reviewed Apr 29, 2026

View reviewed changes

refactor: enhance FieldsetDescription component with clsx for classNa…

bc867d7

…me management

Merge branch 'trunk' into ui/field-use-text-typography

1630a3c

kushagra-goyal-14 requested a review from mirka April 30, 2026 06:59

ciampo reviewed Apr 30, 2026

View reviewed changes

Merge branch 'trunk' into ui/field-use-text-typography

01e09ad

mirka mentioned this pull request May 11, 2026

Text: Fix render prop CSS defenses #78172

Merged

	const DEFAULT_TAG = <div />;

	/**
	* The title for a card. Renders as a `<div>` by default — use the `render`
	* prop to swap in a semantic heading element when appropriate.
	*/
	export const Title = forwardRef< HTMLDivElement, TitleProps >(
	function CardTitle( { render = DEFAULT_TAG, children, ...props }, ref ) {
	return (
	<Text
	ref={ ref }
	variant="heading-lg"
	render={ render }
	{ ...props }
	>
	{ children }
	</Text>
	);
	}
	);

	p.p {
	font-size: var(--_gcd-p-font-size, 13px);
	line-height: var(--_gcd-p-line-height, 1.5);
	margin: var(--_gcd-p-margin, 0);
	}

	/* Narrowed down to h[1-6] elements only, to support element multiplicity of Text component. */
	:is(h1, h2, h3, h4, h5, h6).heading {
	color: var(--_gcd-heading-color, var(--wpds-color-fg-content-neutral));
	font-size: var(--_gcd-heading-font-size, inherit);
	font-weight: var(--_gcd-heading-font-weight, var(--wpds-typography-font-weight-medium));
	margin: var(--_gcd-heading-margin, 0);
	}

	.body-sm {
	--_gcd-p-font-size: var(--wpds-typography-font-size-sm);
	--_gcd-p-line-height: var(--wpds-typography-line-height-xs);

Conversation

kushagra-goyal-14 commented Apr 29, 2026

What?

Why?

How?

Testing Instructions

Use of AI Tools

Uh oh!

github-actions Bot commented Apr 29, 2026

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kushagra-goyal-14 commented Apr 29, 2026

Uh oh!

ciampo Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ciampo Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ciampo commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Apr 29, 2026 •

edited

Loading

ciampo Apr 30, 2026 •

edited

Loading

ciampo Apr 30, 2026 •

edited

Loading

ciampo commented May 11, 2026 •

edited

Loading