feat(core): TabList reads its role and speaks the ARIA tabs pattern

The strip could only be a nav landmark with aria-current, so a consumer with real panels below it had to reimplement it to get role=tablist, aria-selected and aria-controls.

No new prop: TabList declares role?: AriaRole and reads it, the way LayoutHeader and LayoutPanel already declare theirs. role="tablist" asks for the tabs pattern, any other role passes through untouched, and left unset the strip picks from what it renders — tabs when it holds nothing but tabs, the nav landmark when it holds a menu, a link, or anything else. That changes the default for a strip of plain tabs.

The pick reads the rendered DOM rather than children, so a menu behind a conditional, inside a map, or wrapped in a consumer's own component counts, and it follows the strip if the contents change later. It settles because the markers it reads do not depend on the answer, and the wrapper stays a <nav> — role="none" takes the landmark away — so a change of pattern never remounts the tabs.

An href is only ignored where the role was asserted, and so is the warning for a tab that controls nothing; either panelId or a hand-written aria-controls satisfies it, and a hand-written one is never overwritten.

Author: cixzhang

.changeset/tablist-aria-role.md

@@ -0,0 +1,13 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TabList: the strip now speaks the WAI-ARIA tabs pattern — `role="tablist"` on the strip, `role="tab"` and `aria-selected` on the tabs, and `aria-controls` pointing at the panel each tab opens, from a new `panelId` prop on `Tab`. There is no new prop for it: `TabList` declares `role?: AriaRole` and reads it. `role="tablist"` asks for the pattern, any other role passes through to the element untouched, and **left unset the strip picks for itself** — the tabs pattern when it holds nothing but tabs, the navigation landmark when it holds anything else. The keyboard behaviour the pattern asks for was already there: arrows move between tabs, Tab leaves the strip.
+
+**This changes the default.** A strip of plain tabs is a `<nav>` landmark today and becomes a tablist: the selected tab is announced as a selected tab rather than the current item, `aria-current` gives way to `aria-selected`, and — because a tablist reports itself as horizontal — ArrowUp and ArrowDown stop moving between tabs and scroll the page instead. ArrowLeft, ArrowRight, Home, End, Tab and the roving tab stop are unchanged, as is everything the strip looks like. A strip that really is page navigation keeps the landmark by saying so with `role="navigation"`.
+
+Two things the strip will not do to you on its own. A tab with an `href` navigates, so a strip holding one stays navigation — an `href` is only ignored where `role="tablist"` was asked for explicitly, and then a development warning says so. And a tab that controls nothing is only worth mentioning to a consumer who asked for the pattern, so that warning too is limited to the explicit role; either `panelId` or an `aria-controls` you wrote yourself satisfies it, and a hand-written one is never overwritten. `aria-controls` is emitted only when you supply the id: pointing at a panel that does not exist is an invalid attribute value, which is worse than saying nothing.
+
+The pick is made from the rendered DOM rather than from `children`, so a menu behind a conditional, inside a `.map`, or wrapped in a component of your own still counts, and it follows the strip if its contents change later — without remounting the tabs.
+
+@cixzhang

apps/storybook/stories/TabList.stories.tsx

@@ -22,6 +22,10 @@ const meta: Meta<typeof TabList> = {
 export default meta;
 type Story = StoryObj<typeof TabList>;
 
+/**
+ * With no `role`, a strip of nothing but tabs speaks the WAI-ARIA tabs
+ * pattern: `role="tablist"` / `role="tab"` and `aria-selected`.
+ */
 export const Default: Story = {
   args: {
     size: 'md',
@@ -38,6 +42,32 @@ export const Default: Story = {
   },
 };
 
+/**
+ * A strip that really is page navigation says so with `role="navigation"`,
+ * and stays a `<nav>` landmark marking the current item with `aria-current`
+ * however few or many tabs it holds.
+ */
+export const NavigationLandmark: Story = {
+  render: () => {
+    const [value, setValue] = useState('overview');
+    return (
+      <TabList
+        value={value}
+        onChange={setValue}
+        role="navigation"
+        aria-label="Project sections">
+        <Tab value="overview" label="Overview" />
+        <Tab value="activity" label="Activity" />
+        <Tab value="members" label="Members" />
+      </TabList>
+    );
+  },
+};
+
+/**
+ * A menu is not a tab, so a strip holding one stays a `<nav>` landmark with
+ * `aria-current` — the tabs pattern would be invalid markup here.
+ */
 export const WithMenu: Story = {
   args: {
     size: 'md',
@@ -404,3 +434,62 @@ export const OverflowNone: Story = {
     );
   },
 };
+
+/**
+ * `role="tablist"` asks for the WAI-ARIA tabs pattern: `role="tablist"` /
+ * `role="tab"`, `aria-selected`, and each tab pointing at the panel it
+ * controls. A screen reader announces "tab 2 of 3, selected" and can move to
+ * the panel it opens. A strip of nothing but tabs reaches the same pattern on
+ * its own — the explicit role is how you keep it when the strip also holds
+ * something else, and how you ask to be warned when it does.
+ */
+export const TabsPattern: Story = {
+  render: () => {
+    const [value, setValue] = useState('overview');
+    const panels = {
+      overview: 'Everything at a glance.',
+      activity: 'What happened recently.',
+      members: 'Who has access.',
+    };
+    return (
+      <div style={{display: 'grid', gap: '12px', maxWidth: '400px'}}>
+        <TabList
+          value={value}
+          onChange={setValue}
+          role="tablist"
+          aria-label="Project views"
+          hasDivider>
+          <Tab
+            value="overview"
+            label="Overview"
+            id="tab-overview"
+            panelId="panel-overview"
+          />
+          <Tab
+            value="activity"
+            label="Activity"
+            id="tab-activity"
+            panelId="panel-activity"
+          />
+          <Tab
+            value="members"
+            label="Members"
+            id="tab-members"
+            panelId="panel-members"
+          />
+        </TabList>
+        {Object.entries(panels).map(([key, text]) => (
+          <div
+            key={key}
+            id={`panel-${key}`}
+            role="tabpanel"
+            aria-labelledby={`tab-${key}`}
+            tabIndex={0}
+            hidden={key !== value}>
+            {text}
+          </div>
+        ))}
+      </div>
+    );
+  },
+};

packages/core/src/Layout/__tests__/edgeCompensation.test.tsx

@@ -64,18 +64,17 @@ describe('Edge Compensation', () => {
           <Tab value="tab1" label="Tab 1" />
         </TabList>,
       );
-      const tab = screen.getByRole('button', {name: 'Tab 1'});
+      const tab = screen.getByRole('tab', {name: 'Tab 1'});
       expect(tab).toHaveAttribute(EDGE_COMP_ATTR);
     });
 
     it('applies edge comp attribute to TabList wrapper', () => {
-      render(
+      const {container} = render(
         <TabList value="" onChange={() => {}} aria-label="Tabs">
           <Tab value="tab1" label="Tab 1" />
         </TabList>,
       );
-      const nav = screen.getByRole('navigation', {name: 'Tabs'});
-      expect(nav).toHaveAttribute(EDGE_COMP_ATTR);
+      expect(container.querySelector('nav')).toHaveAttribute(EDGE_COMP_ATTR);
     });
   });
 

packages/core/src/TabList/Tab.doc.mjs

@@ -40,7 +40,13 @@ export const docs = {
       name: 'href',
       type: 'string',
       description:
-        'URL to navigate to; when provided, the tab renders as an anchor element.',
+        'URL to navigate to; when provided, the tab renders as an anchor element and keeps the strip on the navigation pattern. Ignored in a TabList given an explicit role="tablist".',
+    },
+    {
+      name: 'panelId',
+      type: 'string',
+      description:
+        'Id of the panel this tab controls, wired up as aria-controls where the TabList speaks the tabs pattern. Put the same id on the panel element. No effect under the navigation pattern.',
     },
     {
       name: 'as',
@@ -138,6 +144,12 @@ export const docsZh = {
       type: 'string',
       description: '要导航到的 URL；提供时，标签渲染为锚点元素。',
     },
+    {
+      name: 'panelId',
+      type: 'string',
+      description:
+        'Id of the panel this tab controls, wired up as aria-controls where the TabList speaks the tabs pattern. Put the same id on the panel element. No effect under the navigation pattern.',
+    },
     {
       name: 'as',
       type: 'LinkComponentType',

packages/core/src/TabList/Tab.tsx

@@ -7,7 +7,8 @@
  * @input Uses React, StyleX, TabListContext
  * @output Exports Tab component and TabProps type
  * @position Core tab item; renders as button or anchor in navigation with a
- *   divider-overlay selected indicator
+ *   divider-overlay selected indicator. Where the TabList speaks the tabs
+ *   pattern it is a button with role="tab".
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TabList/TabList.doc.mjs
@@ -35,6 +36,7 @@ import {tabScope} from './tab.markers.stylex';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {mergeProps} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -64,8 +66,21 @@ export interface TabProps extends BaseProps<HTMLButtonElement> {
   isLabelHidden?: boolean;
   /**
    * URL to navigate to. When provided, renders as an anchor element.
+   *
+   * A tab that navigates keeps the strip on the navigation pattern. Ignored
+   * only in a TabList given an explicit `role="tablist"`: activating a tab
+   * there swaps a panel in place, so a tab that navigates would be a false
+   * statement.
    */
   href?: string;
+  /**
+   * Id of the panel this tab controls, wired up as `aria-controls` where the
+   * TabList speaks the tabs pattern. Put the same id on the panel element.
+   *
+   * Has no effect under the navigation pattern, where there is no panel to
+   * associate.
+   */
+  panelId?: string;
   /**
    * Icon element shown when tab is not selected.
    */
@@ -228,6 +243,7 @@ export function Tab({
   label,
   isLabelHidden = false,
   href,
+  panelId,
   icon,
   selectedIcon,
   endContent,
@@ -242,13 +258,43 @@ export function Tab({
   const isSelected = tabListCtx.value === value;
   const size: TabListSize = tabListCtx.size;
   const isFill = tabListCtx.layout === 'fill';
+  const isTabsPattern = tabListCtx.pattern === 'tabs';
+  // An href gives way to the tabs pattern only where the consumer asked for
+  // that pattern. Where the strip picked it, the link stays a link: the strip
+  // reads its own children back and settles on the navigation pattern, so a
+  // tab that navigates never ends up inside a tablist.
+  const isLink = href != null && (!isTabsPattern || tabListCtx.isPatternAuto);
+  const isTabRole = isTabsPattern && !isLink;
   const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
   const hasVisibleLabel = !isLabelHidden && label !== '';
 
   const handleSelect = useCallback(() => {
     tabListCtx.onChange(value);
   }, [tabListCtx, value]);
 
+  useDevWarning(
+    'Tab',
+    'href is ignored in a role="tablist" TabList — a tab swaps a panel in ' +
+      'place rather than navigating. Drop the href, or drop the role and let ' +
+      'the strip pick its own pattern.',
+    isTabRole && href != null,
+  );
+
+  // A consumer who wired aria-controls by hand already said which panel this
+  // is, so panelId is the sugar, not the only way in.
+  const controls = panelId ?? restProps['aria-controls'];
+
+  // Only where the tabs pattern was asked for: a strip left to pick reaches it
+  // through tabs that were written for the navigation pattern, and scolding
+  // the consumer for a panel they were never asked for is noise.
+  useDevWarning(
+    'Tab',
+    'a tab in a role="tablist" TabList controls nothing: pass panelId with ' +
+      'the id of the panel it opens, so assistive technology can associate ' +
+      'the two.',
+    isTabRole && !tabListCtx.isPatternAuto && controls == null,
+  );
+
   const iconElement = displayIcon ? (
     <span {...stylex.props(styles.icon, iconSizeStyles[size])}>
       {displayIcon}
@@ -260,11 +306,25 @@ export function Tab({
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',
     'data-tab-value': value,
-    // Generic `true` ("the current item within a set"), not `page`: the strip
-    // switches views in place at least as often as it navigates, and claiming
-    // "current page" when no page changed is a false statement to a screen
-    // reader. Stays truthful for the `href` case too, just less specific.
-    'aria-current': isSelected ? ('true' as const) : undefined,
+    ...(isTabRole
+      ? {
+          role: 'tab' as const,
+          'aria-selected': isSelected,
+          // Only when there is a panel to point at: an aria-controls whose
+          // target does not exist is an invalid attribute value, which is a
+          // worse state than saying nothing. The dev warning above asks for
+          // the id instead.
+          'aria-controls': controls,
+        }
+      : {
+          // Generic `true` ("the current item within a set"), not `page`: the
+          // strip switches views in place at least as often as it navigates,
+          // and claiming "current page" when no page changed is a false
+          // statement to a screen reader. Stays truthful for the `href` case
+          // too, just less specific. A tab role states this with
+          // aria-selected instead.
+          'aria-current': isSelected ? ('true' as const) : undefined,
+        }),
     // Roving tabindex: the tab strip is a single Tab stop. The selected tab is
     // the tabbable one; the rest are reachable via arrow keys (handled by
     // TabList's onKeyDown). When no tab is selected, TabList's repair effect
@@ -321,7 +381,7 @@ export function Tab({
     <span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
   ) : null;
 
-  if (href != null) {
+  if (isLink) {
     return (
       <LinkComponent
         ref={ref}

packages/core/src/TabList/TabList.doc.mjs

@@ -28,7 +28,7 @@ export const docs = {
       {name: '--_tab-indicator-bottom', description: 'Vertical offset of the selected-tab indicator from the tab bottom edge. A host that draws its own bottom divider (Toolbar) sets this so the indicator sits on the divider instead of above it.', default: '-1px', private: true},
     ],
   },
-  description: 'Nav wrapper that provides TabListContext (value, onChange, size) to Tab and TabMenu children.',
+  description: 'Tab strip that provides TabListContext (value, onChange, size) to Tab and TabMenu children, speaking either the WAI-ARIA tabs pattern or the navigation one.',
   props: [
     {
       name: 'value',
@@ -60,6 +60,11 @@ export const docs = {
       description: 'Whether to show a bottom border divider under the tab list.',
       default: 'false',
     },
+    {
+      name: 'role',
+      type: 'AriaRole',
+      description: "ARIA role for the strip. 'tablist' asks for the WAI-ARIA tabs pattern: role=\"tablist\" / role=\"tab\" and aria-selected, with each tab pointing at the panel it controls via its panelId; only tabs may live in a tablist strip, and an href on a tab is ignored there. Left unset, the strip picks the pattern from what it renders: the tabs pattern when it holds nothing but tabs, and a nav landmark with aria-current when it holds anything else — a menu, a link, a control of your own. Pass 'navigation' to keep the landmark whatever the strip contains. Any other value is passed through to the element unchanged.",
+    },
     {
       name: 'overflow',
       type: "'auto' | 'scroll' | 'none'",
@@ -69,7 +74,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Tab and TabMenu items to render inside the nav.',
+      description: 'Tab and TabMenu items to render inside the strip.',
       slotElements: [
         {
           __element: 'Tab',
@@ -98,6 +103,7 @@ export const docs = {
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
       { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
+      { guidance: true, description: 'Give each panel an id and point its tab at it with panelId: a strip of plain tabs is announced as a tablist, and that link is how a screen reader gets from a tab to the content it opens.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
@@ -119,6 +125,7 @@ export const docsZh = {
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
       { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
+      { guidance: true, description: 'Give each panel an id and point its tab at it with panelId: a strip of plain tabs is announced as a tablist, and that link is how a screen reader gets from a tab to the content it opens.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
@@ -133,14 +140,15 @@ export const docsZh = {
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Tab navigation w/ overflow menu support; semantic nav landmark w/ button or anchor tab items.',
+  description: 'Tab strip w/ overflow scrolling; ARIA tabs pattern by default, nav landmark w/ anchor or menu items.',
   usage: {
     description:
       'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
       { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
+      { guidance: true, description: 'Give each panel an id and point its tab at it with panelId: a strip of plain tabs is announced as a tablist, and that link is how a screen reader gets from a tab to the content it opens.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },