From 8f9770e00684d4515ed85867ea6a1646384c88ef Mon Sep 17 00:00:00 2001 From: Lena Morita Date: Sat, 4 Apr 2026 03:59:50 +0900 Subject: [PATCH 1/4] Docs: point typography and examples to @wordpress/ui Text --- packages/components/src/divider/README.md | 5 ++--- packages/components/src/h-stack/README.md | 10 ++++------ .../components/src/heading/stories/index.story.tsx | 2 +- packages/components/src/text/stories/index.story.tsx | 2 +- packages/components/src/v-stack/README.md | 10 ++++------ packages/components/src/view/README.md | 6 ++---- 6 files changed, 14 insertions(+), 21 deletions(-) diff --git a/packages/components/src/divider/README.md b/packages/components/src/divider/README.md index 8b314be13b4d6a..53cd1541b98a8f 100644 --- a/packages/components/src/divider/README.md +++ b/packages/components/src/divider/README.md @@ -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 ( - Some text here + Some text here - Some more text here + Some more text here ); } diff --git a/packages/components/src/h-stack/README.md b/packages/components/src/h-stack/README.md index 77e3c77b940f2a..c5a3a84fcb12e5 100644 --- a/packages/components/src/h-stack/README.md +++ b/packages/components/src/h-stack/README.md @@ -11,10 +11,8 @@ 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'; +import { Text } from '@wordpress/ui'; function Example() { return ( @@ -87,8 +85,8 @@ 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'; +import { Text } from '@wordpress/ui'; function Example() { return ( @@ -109,8 +107,8 @@ function Example() { import { __experimentalHStack as HStack, __experimentalSpacer as Spacer, - __experimentalText as Text, } from '@wordpress/components'; +import { Text } from '@wordpress/ui'; function Example() { return ( diff --git a/packages/components/src/heading/stories/index.story.tsx b/packages/components/src/heading/stories/index.story.tsx index bbac5776b54284..fc21947d8e0ceb 100644 --- a/packages/components/src/heading/stories/index.story.tsx +++ b/packages/components/src/heading/stories/index.story.tsx @@ -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. ` } variant="heading-2xl">`).', }, }, }; diff --git a/packages/components/src/text/stories/index.story.tsx b/packages/components/src/text/stories/index.story.tsx index 2b5d36ebb4fa5e..67241ea56d035c 100644 --- a/packages/components/src/text/stories/index.story.tsx +++ b/packages/components/src/text/stories/index.story.tsx @@ -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.', }, }, }; diff --git a/packages/components/src/v-stack/README.md b/packages/components/src/v-stack/README.md index 2f447b18015e51..3e6855faf155c5 100644 --- a/packages/components/src/v-stack/README.md +++ b/packages/components/src/v-stack/README.md @@ -11,10 +11,8 @@ 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'; +import { Text } from '@wordpress/ui'; function Example() { return ( @@ -74,9 +72,9 @@ 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'; +import { Text } from '@wordpress/ui'; function Example() { return ( @@ -96,9 +94,9 @@ function Example() { ```jsx import { __experimentalSpacer as Spacer, - __experimentalText as Text, __experimentalVStack as VStack, } from '@wordpress/components'; +import { Text } from '@wordpress/ui'; function Example() { return ( diff --git a/packages/components/src/view/README.md b/packages/components/src/view/README.md index c1e04ebd8cfff4..7a71a0600ef4ca 100644 --- a/packages/components/src/view/README.md +++ b/packages/components/src/view/README.md @@ -11,10 +11,8 @@ 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'; +import { Text } from '@wordpress/ui'; function Example() { return ( From e0689a6d3407740963d15ae6f83276e762f6d8ec Mon Sep 17 00:00:00 2001 From: Lena Morita Date: Sat, 4 Apr 2026 03:50:42 +0900 Subject: [PATCH 2/4] Use span placeholders in component README examples --- packages/components/src/h-stack/README.md | 21 +++++++++------------ packages/components/src/v-stack/README.md | 21 +++++++++------------ packages/components/src/view/README.md | 3 +-- 3 files changed, 19 insertions(+), 26 deletions(-) diff --git a/packages/components/src/h-stack/README.md b/packages/components/src/h-stack/README.md index c5a3a84fcb12e5..5961c79694ef59 100644 --- a/packages/components/src/h-stack/README.md +++ b/packages/components/src/h-stack/README.md @@ -12,14 +12,13 @@ This feature is still experimental. “Experimental” means this is an early im ```jsx import { __experimentalHStack as HStack } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code - is - Poetry + Code + is + Poetry ); } @@ -86,16 +85,15 @@ import { __experimentalHStack as HStack, __experimentalSpacer as Spacer, } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code + Code - is + is - Poetry + Poetry ); } @@ -108,15 +106,14 @@ import { __experimentalHStack as HStack, __experimentalSpacer as Spacer, } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code + Code - is - Poetry + is + Poetry ); } diff --git a/packages/components/src/v-stack/README.md b/packages/components/src/v-stack/README.md index 3e6855faf155c5..d70f6a2860d916 100644 --- a/packages/components/src/v-stack/README.md +++ b/packages/components/src/v-stack/README.md @@ -12,14 +12,13 @@ This feature is still experimental. “Experimental” means this is an early im ```jsx import { __experimentalVStack as VStack } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code - is - Poetry + Code + is + Poetry ); } @@ -74,16 +73,15 @@ import { __experimentalSpacer as Spacer, __experimentalVStack as VStack, } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code + Code - is + is - Poetry + Poetry ); } @@ -96,15 +94,14 @@ import { __experimentalSpacer as Spacer, __experimentalVStack as VStack, } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code + Code - is - Poetry + is + Poetry ); } diff --git a/packages/components/src/view/README.md b/packages/components/src/view/README.md index 7a71a0600ef4ca..d480e01f30e297 100644 --- a/packages/components/src/view/README.md +++ b/packages/components/src/view/README.md @@ -12,12 +12,11 @@ This feature is still experimental. “Experimental” means this is an early im ```jsx import { __experimentalView as View } from '@wordpress/components'; -import { Text } from '@wordpress/ui'; function Example() { return ( - Code is Poetry + Code is Poetry ); } From 6ff87747d7b40dbb32a97bdd29ac84ef9fe9740d Mon Sep 17 00:00:00 2001 From: Lena Morita Date: Sat, 4 Apr 2026 04:04:11 +0900 Subject: [PATCH 3/4] Add note to Storybook --- packages/ui/src/text/stories/index.story.tsx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/ui/src/text/stories/index.story.tsx b/packages/ui/src/text/stories/index.story.tsx index 82a0cb9cfcdc5a..1c78ce513dc9ee 100644 --- a/packages/ui/src/text/stories/index.story.tsx +++ b/packages/ui/src/text/stories/index.story.tsx @@ -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: () => ( Date: Sat, 4 Apr 2026 04:04:55 +0900 Subject: [PATCH 4/4] Add `Text` to recommended list --- packages/eslint-plugin/rules/use-recommended-components.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/eslint-plugin/rules/use-recommended-components.js b/packages/eslint-plugin/rules/use-recommended-components.js index d69c6c958d386a..e2ae74d1222253 100644 --- a/packages/eslint-plugin/rules/use-recommended-components.js +++ b/packages/eslint-plugin/rules/use-recommended-components.js @@ -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.', },