aduth · Apr 20, 2026 · Apr 7, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -131,6 +131,17 @@ const restrictedImports = [
 	},
 ];
 
+// Common `no-restricted-imports` configuration for `@wordpress/ui` paths,
+// which occur across multiple override configs. The exclusion here allows
+// Base UI to be imported directly in `@wordpress/ui`, which is the intended
+// abstraction layer for BaseUI components.
+const UI_RESTRICTED_IMPORTS = {
+	paths: restrictedImports.filter(
+		( { name } ) => name !== '@base-ui/react'
+	),
+	patterns: [],
+};
+
 const restrictedSyntax = [
 	{
 		selector:
@@ -663,13 +674,30 @@ export default dedupePlugins( [
 	// Override: UI src — allow base-ui imports.
 	{
 		files: [ 'packages/ui/src/**' ],
+		rules: {
+			'no-restricted-imports': [ 'error', UI_RESTRICTED_IMPORTS ],
+		},
+	},
+
+	// Override: UI stories — prevent barrel imports. Namespace re-exports cause
+	// react-docgen-typescript to resolve the wrong component when a story's
+	// component is imported via the barrel.
+	//
+	// See: https://github.com/storybookjs/storybook/issues/32839
+	{
+		files: [ 'packages/ui/src/**/stories/*.story.@(ts|tsx)' ],
 		rules: {
 			'no-restricted-imports': [
 				'error',
 				{
-					paths: restrictedImports.filter(
-						( { name } ) => ! [ '@base-ui/react' ].includes( name )
-					),
+					...UI_RESTRICTED_IMPORTS,
+					patterns: UI_RESTRICTED_IMPORTS.patterns.concat( [
+						{
+							regex: '^\\.\\.(/\\.\\.)+/?$',
+							message:
+								"Don't import from the `@wordpress/ui` barrel in stories, which break import resolution in Storybook. Use an import from the component's own directory instead (e.g. `import { Icon } from '../icon';`).",
+						},
+					] ),
 				},
 			],
 		},

@@ -3,8 +3,8 @@ import { useId, useState } from '@wordpress/element';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { action } from 'storybook/actions';
 import { fn } from 'storybook/test';
-
-import { AlertDialog, Text } from '../..';
+import * as AlertDialog from '../';
+import { Text } from '../../text';
 
 const meta: Meta< typeof AlertDialog.Root > = {
 	title: 'Design System/Components/AlertDialog',

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { search } from '@wordpress/icons';
-import { Button, EmptyState } from '../..';
+import { Button } from '../../button';
+import * as EmptyState from '../';
 
 const meta: Meta< typeof EmptyState.Root > = {
 	title: 'Design System/Components/EmptyState',

@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from '@wordpress/element';
 import { plus, reset, seen, unseen } from '@wordpress/icons';
-import { IconButton, InputControl, InputLayout, Stack } from '../../..';
+import { InputControl } from '../';
+import { IconButton } from '../../../icon-button';
+import { InputLayout } from '../../primitives/input-layout';
+import { Stack } from '../../../stack';
 import {
 	WithPrefix,
 	WithSuffixControl,

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId } from '@wordpress/element';
-import { Field } from '../../../..';
+import * as Field from '../';
 import { DETAILS_EXAMPLE } from '../../../stories/shared';
 
 const meta: Meta< typeof Field.Root > = {

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Fieldset } from '../../../..';
+import * as Fieldset from '../';
 import { DETAILS_EXAMPLE } from '../../../stories/shared';
 
 const meta: Meta< typeof Fieldset.Root > = {

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { copy } from '@wordpress/icons';
-import { IconButton, InputLayout } from '../../../..';
+import { InputLayout } from '../';
+import { IconButton } from '../../../../icon-button';
 
 const meta: Meta< typeof InputLayout > = {
 	title: 'Design System/Components/Form/Primitives/InputLayout',

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Input, InputLayout } from '../../../..';
+import { Input } from '../';
+import { InputLayout } from '../../input-layout';
 import { WithSuffixControl } from '../../input-layout/stories/index.story';
 
 const meta: Meta< typeof Input > = {

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Select } from '../../../..';
+import * as Select from '../';
 
 const meta: Meta< typeof Select.Root > = {
 	title: 'Design System/Components/Form/Primitives/Select',

@@ -2,7 +2,8 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId, useRef, useState } from '@wordpress/element';
 import { SlotFillProvider, Slot } from '@wordpress/components';
 import { close, info } from '@wordpress/icons';
-import { Popover, VisuallyHidden } from '../..';
+import * as Popover from '../';
+import { VisuallyHidden } from '../../visually-hidden';
 import { Icon } from '../../icon';
 import { IconButton } from '../../icon-button';
 import { GenericIframe, useMeasure } from './utils';

@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState, cloneElement } from '@wordpress/element';
 import { link, more, wordpress } from '@wordpress/icons';
-import { Tabs, Tooltip } from '../..';
+import * as Tabs from '../';
+import * as Tooltip from '../../tooltip';
 
 const meta: Meta< typeof Tabs.Root > = {
 	title: 'Design System/Components/Tabs',

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { formatBold, formatItalic } from '@wordpress/icons';
-import { Icon, Tooltip } from '../..';
+import { Icon } from '../../icon';
+import * as Tooltip from '../';
 
 const meta: Meta< typeof Tooltip.Root > = {
 	title: 'Design System/Components/Tooltip',

@@ -5,7 +5,11 @@ import {
 	formatUnderline,
 	info,
 } from '@wordpress/icons';
-import { Icon, IconButton, Popover, Tooltip, VisuallyHidden } from '../..';
+import * as Tooltip from '../';
+import { Icon } from '../../icon';
+import { IconButton } from '../../icon-button';
+import * as Popover from '../../popover';
+import { VisuallyHidden } from '../../visually-hidden';
 
 const meta: Meta = {
 	title: 'Design System/Components/Tooltip/Usage Guidelines',