Skip to content

UI Text: Mark as recommended #77044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mirka merged 4 commits into from
Apr 8, 2026
Merged

UI Text: Mark as recommended #77044

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8f9770e
Docs: point typography and examples to @wordpress/ui Text
mirka Apr 3, 2026
e0689a6
Use span placeholders in component README examples
mirka Apr 3, 2026
6ff8774
Add note to Storybook
mirka Apr 3, 2026
be2b12f
Add `Text` to recommended list
mirka Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions packages/components/src/divider/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,15 @@ This feature is still experimental. “Experimental” means this is an early im
```jsx
import {
__experimentalDivider as Divider,
__experimentalText as Text,
} from `@wordpress/components`;
import { Stack } from '@wordpress/ui';

function Example() {
return (
<Stack direction="column" gap="lg">
<Text>Some text here</Text>
<span>Some text here</span>
<Divider />
<Text>Some more text here</Text>
<span>Some more text here</span>
</Stack>
);
}
Expand Down
25 changes: 10 additions & 15 deletions packages/components/src/h-stack/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,14 @@ This feature is still experimental. “Experimental” means this is an early im
`HStack` can render anything inside.

```jsx
import {
__experimentalHStack as HStack,
__experimentalText as Text,
} from '@wordpress/components';
import { __experimentalHStack as HStack } from '@wordpress/components';

function Example() {
return (
<HStack>
<Text>Code</Text>
<Text>is</Text>
<Text>Poetry</Text>
<span>Code</span>
<span>is</span>
<span>Poetry</span>
</HStack>
);
}
Expand Down Expand Up @@ -87,17 +84,16 @@ When a `Spacer` is used within an `HStack`, the `Spacer` adaptively expands to t
import {
__experimentalHStack as HStack,
__experimentalSpacer as Spacer,
__experimentalText as Text,
} from '@wordpress/components';

function Example() {
return (
<HStack>
<Text>Code</Text>
<span>Code</span>
<Spacer>
<Text>is</Text>
<span>is</span>
</Spacer>
<Text>Poetry</Text>
<span>Poetry</span>
</HStack>
);
}
Expand All @@ -109,16 +105,15 @@ function Example() {
import {
__experimentalHStack as HStack,
__experimentalSpacer as Spacer,
__experimentalText as Text,
} from '@wordpress/components';

function Example() {
return (
<HStack>
<Text>Code</Text>
<span>Code</span>
<Spacer />
<Text>is</Text>
<Text>Poetry</Text>
<span>is</span>
<span>Poetry</span>
</HStack>
);
}
Expand Down
2 changes: 1 addition & 1 deletion packages/components/src/heading/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ const meta: Meta< typeof Heading > = {
componentStatus: {
status: 'not-recommended',
whereUsed: 'global',
notes: 'Values are not aligned with the current design system. Use [typography tokens](?path=/docs/tokens-typography--page) from `@wordpress/base-styles` instead.',
notes: 'Use `Text` from `@wordpress/ui` instead, with the `render` prop set to the heading level element and the variant set to the visual heading size (e.g. `<Text render={ <h1 /> } variant="heading-2xl">`).',

@aduth aduth Apr 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is pretty clunky to implement when it's spelled out like this 😅 Maybe a <Heading /> abstraction will be useful to introduce.

@mirka mirka Apr 8, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that we don't tie the font size with the heading levels anyway, it's still going to be something like <Heading level={ 1 } variant="heading-2xl">. Not that different!

},
},
};
Expand Down
2 changes: 1 addition & 1 deletion packages/components/src/text/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ const meta: Meta< typeof Text > = {
componentStatus: {
status: 'not-recommended',
whereUsed: 'global',
notes: 'Values are not aligned with the current design system. Use [typography tokens](?path=/docs/tokens-typography--page) from `@wordpress/base-styles` instead.',
notes: 'Use `Text` from `@wordpress/ui` instead.',
},
},
};
Expand Down
25 changes: 10 additions & 15 deletions packages/components/src/v-stack/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,14 @@ This feature is still experimental. “Experimental” means this is an early im
`VStack` can render anything inside.

```jsx
import {
__experimentalText as Text,
__experimentalVStack as VStack,
} from '@wordpress/components';
import { __experimentalVStack as VStack } from '@wordpress/components';

function Example() {
return (
<VStack>
<Text>Code</Text>
<Text>is</Text>
<Text>Poetry</Text>
<span>Code</span>
<span>is</span>
<span>Poetry</span>
</VStack>
);
}
Expand Down Expand Up @@ -74,18 +71,17 @@ When a `Spacer` is used within an `VStack`, the `Spacer` adaptively expands to t
```jsx
import {
__experimentalSpacer as Spacer,
__experimentalText as Text,
__experimentalVStack as VStack,
} from '@wordpress/components';

function Example() {
return (
<VStack>
<Text>Code</Text>
<span>Code</span>
<Spacer>
<Text>is</Text>
<span>is</span>
</Spacer>
<Text>Poetry</Text>
<span>Poetry</span>
</VStack>
);
}
Expand All @@ -96,17 +92,16 @@ function Example() {
```jsx
import {
__experimentalSpacer as Spacer,
__experimentalText as Text,
__experimentalVStack as VStack,
} from '@wordpress/components';

function Example() {
return (
<VStack>
<Text>Code</Text>
<span>Code</span>
<Spacer />
<Text>is</Text>
<Text>Poetry</Text>
<span>is</span>
<span>Poetry</span>
</VStack>
);
}
Expand Down
7 changes: 2 additions & 5 deletions packages/components/src/view/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,12 @@ This feature is still experimental. “Experimental” means this is an early im
## Usage

```jsx
import {
__experimentalText as Text,
__experimentalView as View,
} from '@wordpress/components';
import { __experimentalView as View } from '@wordpress/components';

function Example() {
return (
<View>
<Text>Code is Poetry</Text>
<span>Code is Poetry</span>
</View>
);
}
Expand Down
2 changes: 1 addition & 1 deletion packages/eslint-plugin/rules/use-recommended-components.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
*/
const ALLOWLIST = {
'@wordpress/ui': {
allowed: [ 'Badge', 'Stack' ],
allowed: [ 'Badge', 'Stack', 'Text' ],
message:
'`{{ name }}` from `{{ source }}` is not yet recommended for use in a WordPress environment.',
},
Expand Down
4 changes: 4 additions & 0 deletions packages/ui/src/text/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ export const Default: Story = {
},
};

/**
* Important: Setting the `variant` prop to a `heading` variant will not automatically render a heading element.
* Use the `render` prop to render a heading element with the appropriate level.
*/
export const AllVariants: Story = {
render: () => (
<Stack
Expand Down
Loading