@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/Stepper/Step.tsx

@@ -535,18 +535,27 @@ const styles = stylex.create({
     color: colorVars['--color-accent'],
   },
   iconSuccess: {
-    color: colorVars['--color-success'],
+    color: colorVars['--color-icon-success'],
   },
   iconWarning: {
-    color: colorVars['--color-warning'],
+    color: colorVars['--color-icon-warning'],
   },
   iconError: {
-    color: colorVars['--color-error'],
+    color: colorVars['--color-icon-error'],
   },
 
   // Number badge — same box as every other indicator (see INDICATOR_SIZE).
   numberBadge: {
     display: 'grid',
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
     placeItems: 'center',
     width: INDICATOR_SIZE,
     height: INDICATOR_SIZE,
@@ -1316,6 +1325,10 @@ export function Step({
   const iconLabelNode = (
     <div {...stylex.props(styles.iconLabelRow)}>
       {(!isCompact || indicatorPosition !== 'on-track') && indicatorNode}
+      {/* A space between the indicator and the label: the row is a flex
+          container, which drops whitespace-only text, so nothing changes on
+          screen, but a text reading of the button then keeps "1 Account" as two
+          words instead of "1Account". */}{' '}
       <span
         {...mergeProps(
           labelThemeProps,
@@ -1576,6 +1589,8 @@ export function Step({
               )}
             />
           </div>
+          {/* Whitespace between the indicator column and the label, as in
+              iconLabelNode. */}{' '}
           <div {...stylex.props(styles.otBodyV)}>
             {labelLineNode}
             {otDescriptionNode}
@@ -1658,6 +1673,7 @@ export function Step({
             )}
           />
         </div>
+        {/* Whitespace between the rail and the label, as in iconLabelNode. */}{' '}
         {/* The on-track indicator remains visible as a node on the rail at
             compact widths, but the wrapper becomes presentational with its
             label. Navigation moves to the named controls in the summary row. */}

package/src/Stepper/Stepper.test.tsx

@@ -10,6 +10,7 @@ import {useStepperContext} from './StepperContext';
 import {useLayer} from '../Layer/useLayer';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 describe('Stepper', () => {
   it('renders an ordered list of steps (not a nav landmark)', () => {
@@ -2016,3 +2017,52 @@ describe('step-label and step-description theme targets', () => {
     );
   });
 });
+
+describe('clickable step text reading', () => {
+  // axe-core's Label in Name rule joins a button's text nodes with nothing
+  // between them, aria-hidden ones included, so a number badge next to a label
+  // reads as one word ("1Account") that the step's name does not contain.
+  // Whitespace between them changes nothing on screen (the rows are flex
+  // containers) and keeps the two words apart.
+  it.each([
+    ['vertical', 'separated'],
+    ['horizontal', 'separated'],
+    ['vertical', 'on-track'],
+    ['horizontal', 'on-track'],
+  ] as const)(
+    'keeps the number and label apart in a %s %s step',
+    (orientation, indicatorPosition) => {
+      render(
+        <Stepper
+          orientation={orientation}
+          indicatorPosition={indicatorPosition}
+          activeStep={0}
+          label="Steps"
+          onStepClick={() => {}}>
+          <Step step={0} label="Account" indicator="number" />
+          <Step step={1} label="Payment" indicator="number" />
+        </Stepper>,
+      );
+
+      const button = screen.getByRole('button', {name: /Account/});
+      expect(button.textContent).toMatch(/1\s+Account/);
+      expect(button.textContent).not.toMatch(/1Account/);
+    },
+  );
+});
+
+// jsdom cannot emulate forced colors, so this asserts the compiled rule the
+// number badge fill relies on (architecture:theme-tokens INV11).
+describe('Step number badge forced colors', () => {
+  it('keeps a visible boundary on the badge fill', () => {
+    render(
+      <Stepper activeStep={0}>
+        <Step step={0} label="First" indicator="number" />
+        <Step step={1} label="Second" indicator="number" />
+      </Stepper>,
+    );
+    const css = getForcedColorsRules();
+    expect(css).toContain('outline-style: solid;');
+    expect(css).toContain('outline-color: canvastext;');
+  });
+});

package/src/Switch/Switch.focusRing.source-build.test.mjs

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Switch.focusRing.source-build.test.mjs
+ * @input Uses Babel, the StyleX plugin as the package stylesheet compiles it,
+ *   and the Switch source
+ * @output Verifies the shipped focus ring follows the switch's own input
+ *   through a sibling relation, with no `:has()` ancestor scan
+ * @position Regression test for the compiled CSS of the Switch module
+ *
+ * The ring's condition once read `:has(:focus-visible)` on an ancestor of the
+ * track (`.track:where(.scope:has(:focus-visible) *)`). That shape makes the
+ * browser restyle everything under the ancestor on every DOM change. The
+ * track's preceding sibling is the focusable input, so the ring reads that
+ * input directly.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {transformAsync} from '@babel/core';
+import stylexBabelPlugin from '@stylexjs/babel-plugin';
+import {describe, expect, it} from 'vitest';
+import stylexResolution from '../../../../scripts/stylex-module-resolution.cjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function compiledCss(fileName) {
+  const file = path.join(__dirname, fileName);
+  const result = await transformAsync(await fs.readFile(file, 'utf8'), {
+    babelrc: false,
+    configFile: false,
+    filename: file,
+    presets: [
+      ['@babel/preset-typescript', {isTSX: true, allExtensions: true}],
+      ['@babel/preset-react', {runtime: 'automatic'}],
+    ],
+    plugins: [
+      [
+        stylexBabelPlugin,
+        {
+          dev: false,
+          runtimeInjection: false,
+          genConditionalClasses: true,
+          treeshakeCompensation: true,
+          unstable_moduleResolution: stylexResolution.stylexModuleResolution,
+        },
+      ],
+    ],
+  });
+  return stylexBabelPlugin.processStylexRules(
+    result?.metadata?.stylex ?? [],
+    false,
+  );
+}
+
+/** Every selector in `css`, one per rule. */
+function selectorsOf(css) {
+  return [...css.matchAll(/([^{}]+)\{[^{}]*\}/g)].map(match => match[1].trim());
+}
+
+describe('the shipped Switch focus ring', () => {
+  it('reads the input as the track\u2019s preceding sibling, never through :has()', async () => {
+    const selectors = selectorsOf(await compiledCss('Switch.tsx'));
+    const ring = selectors.filter(selector =>
+      selector.includes(':focus-visible'),
+    );
+    expect(ring.length).toBeGreaterThan(0);
+    for (const selector of ring) {
+      expect(selector).toMatch(/:focus-visible ~ \*/);
+      expect(selector).not.toContain(':has(');
+    }
+  });
+
+  it('ships no :has() followed by a descendant *', async () => {
+    const selectors = selectorsOf(await compiledCss('Switch.tsx'));
+    expect(
+      selectors.filter(selector => /:has\([^{]*\)[^{,]* \*/.test(selector)),
+    ).toEqual([]);
+  });
+});

package/src/Switch/Switch.tsx

@@ -44,7 +44,7 @@ import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs, rtlStyles} from '../utils';
-import {switchFocusScope, switchScope} from './switch.markers.stylex';
+import {switchFocusInput, switchScope} from './switch.markers.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -258,20 +258,22 @@ const styles = stylex.create({
     },
   },
   // The one ring in the system not drawn by focusOutlineStyles. The focusable
-  // input is a sibling of the track, so the condition has to reach the shared
-  // scope marker — and a marker cannot be shared across components without
-  // leaking focus state from an outer one, so it cannot live in the utility.
-  // StyleX also cannot inline a constant imported from another module, so the
-  // values are read from the tokens the utility reads.
+  // input is the track's preceding sibling, so the condition reads that input
+  // through its own marker: a sibling relation, never a `:has()` scan of the
+  // row, which would restyle everything under it on any change. A marker
+  // cannot be shared across components without leaking focus state from an
+  // outer one, so it cannot live in the utility. StyleX also cannot inline a
+  // constant imported from another module, so the values are read from the
+  // tokens the utility reads.
   trackFocus: {
     outline: {
       default: 'none',
-      [stylex.when.ancestor(':has(:focus-visible)', switchFocusScope)]:
+      [stylex.when.siblingBefore(':focus-visible', switchFocusInput)]:
         `${focusVars['--focus-outline-width']} ${focusVars['--focus-outline-style']} ${focusVars['--focus-outline-color']}`,
     },
     outlineOffset: {
       default: null,
-      [stylex.when.ancestor(':has(:focus-visible)', switchFocusScope)]:
+      [stylex.when.siblingBefore(':focus-visible', switchFocusInput)]:
         focusVars['--focus-outline-offset'],
     },
   },
@@ -686,6 +688,7 @@ export function Switch({
           inputSizeStyles[size],
           isDisabled && styles.inputDisabled,
           isBusy && styles.inputBusy,
+          switchFocusInput,
         )}
       />
       <div
@@ -773,7 +776,6 @@ export function Switch({
           isLabelHidden && styles.containerLabelHidden,
           labelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
-          switchFocusScope,
           // The touch press's strength and release live on the row the
           // controller writes to; the track and thumb inherit and paint it.
           !isDisabled && interactionOverlayStyles.pressedAlpha,

package/src/Switch/__tests__/Switch.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file Switch.a11y.chromium.spec.ts

package/src/Switch/switch.markers.stylex.ts

@@ -9,6 +9,11 @@ import * as stylex from '@stylexjs/stylex';
 export const switchScope: ReturnType<typeof stylex.defineMarker> =
   stylex.defineMarker();
 
-/** Focus-ring marker; unlike `switchScope`, it stays on while disabled. */
-export const switchFocusScope: ReturnType<typeof stylex.defineMarker> =
+/**
+ * Marks the switch's own focusable input, the track's preceding sibling, so
+ * the track's focus ring follows that input's `:focus-visible` alone. Unlike
+ * `switchScope`, it stays on while disabled (a focusable-disabled switch
+ * still shows the ring).
+ */
+export const switchFocusInput: ReturnType<typeof stylex.defineMarker> =
   stylex.defineMarker();

package/src/TabList/Tab.spec.md

@@ -0,0 +1,201 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Tab
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/TabList/TabList.test.tsx,
+    packages/core/src/TabList/__tests__/Tabs.a11y.test.tsx,
+    packages/core/src/TabList/__tests__/Tabs.a11y.chromium.spec.ts,
+    apps/storybook/stories/TabList.stories.tsx,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Tab component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `Tab` with `value`, `label`, `isLabelHidden`, `href`, `as`, `panelId`, `icon`, `selectedIcon`, and `endContent`; targets `tab` and `tab-indicator` with a `selected` state.                                                                                                          |
+| Behavior                | One TabList entry. In the navigation pattern it is a button or, with `href`, a link marked `aria-current` when selected; in the tabs pattern (`role="tablist"`) it is a `role="tab"` button that controls its panel. The strip has one tab stop, which starts on the selected entry. |
+| End-user impact         | Users select a view or destination; keyboard users meet one tab stop for the whole strip; screen-reader users hear the selected entry and, in the tabs pattern, the panel it controls.                                                                                               |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                |
+| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact).                                                                                                                                                                                     |
+| Review checks           | Reject more than one tab stop per strip, `aria-current="page"` on a navigation tab, a disabled tab that fires its handler or navigates, or a tabs-pattern tab that renders a link.                                                                                                   |
+| Governing rules         | `component:TabList` (strip edge geometry); `family:navigation-destinations`; `architecture:interaction-modality`.                                                                                                                                                                    |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Tab is one entry in a TabList. It owns its element and role in each TabList
+pattern, its selected and disabled behavior, its icon swap, label sizing, and
+its selection indicator. Consumer usage lives in `Tab.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: selection is the TabList's `value`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **A hidden label twin reserves the selected width.** Each visible label
+  renders a second, `aria-hidden` copy that reserves the label's selected
+  weight so the tab does not shift. `architecture:component-style-authoring`
+  INV7 has content render once and has CSS size or reserve it on the element
+  that shows it.
+- **Hover decoration is an element.** The hover fill is an `aria-hidden` span
+  rather than a pseudo-element; `architecture:component-style-authoring` INV7
+  has decoration without a semantic role carried by a pseudo-element.
+- **Color transitions under reduced motion.** The label color, hover fill,
+  pressed fill, and indicator fade still animate when reduced motion is
+  requested;
+  `design:reduced-motion` DR3 allows no animated property for a fine pointer.
+- **The `tab` target does not reflect disabled.** A disabled Tab drops its
+  hover and pressed treatment, but the `tab` target reflects only `selected`.
+  `architecture:component-theming-surface` INV6 has a state that changes paint
+  reflected on the owning target.
+
+## Ownership boundary
+
+**Owns**
+
+- The entry element and role per pattern, selection on activation, disabled
+  handling, the tab stop, icon swap, label, end content, and indicator
+  (FR1–FR8).
+
+**Does not own / non-goals**
+
+- Which value is selected, the pattern (`role`), size, layout, arrow-key
+  movement, and overflow scrolling — owned by TabList and uncontracted here;
+  strip edge geometry — owned by `component:TabList`.
+- Destination acceptance and blocking — owned by
+  `family:navigation-destinations`.
+- The panel a tab controls — owned by the caller.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning                                                   | Availability by variant/orientation/state | Default    | Owner   | Stability | Invalid-value behavior |
+| ------- | ----------------------- | --------------------------------------------------------- | ----------------------------------------- | ---------- | ------- | --------- | ---------------------- |
+| Pattern | navigation, tabs        | Set by the TabList `role`; decides element and semantics. | Every tab.                                | navigation | TabList | Stable    | Not settable on Tab.   |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                  | Basis                    |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | In the navigation pattern a Tab is a `<button type="button">`, or with `href` the `as` component, else the `LinkProvider` link, else `<a>`. The selected Tab carries `aria-current="true"`, never `"page"`.                                                                                                                                                | Current source and tests |
+| FR2 | In the tabs pattern a Tab is a `<button>` with `role="tab"`, `aria-selected`, and `aria-controls` from `panelId` (else a caller `aria-controls`). `href` is ignored, and development warnings name an ignored `href`, a missing panel, or a `panelId` outside the tabs pattern.                                                                            | Current source and tests |
+| FR3 | The strip has one tab stop. It starts on the selected Tab (`tabIndex=0`, every other entry `-1`), and moves to whichever entry the arrow keys, Home, or End focus, without selecting it. Where the stop starts when no entry is selected, or the selected one is disabled, is uncontracted here; the Tabs accessibility inventory leaves that policy open. | Current source and tests |
+| FR4 | Activation runs the caller `onClick`, then selects the Tab's `value` through the TabList unless the caller cancelled the event.                                                                                                                                                                                                                            | Current source and tests |
+| FR5 | A Tab with `aria-disabled="true"` does not run `onClick`, does not select, and, as a link, renders a plain `<a>` without `href`; it gets no hover or pressed treatment.                                                                                                                                                                                    | Current source and tests |
+| FR6 | `isLabelHidden` names the Tab by `label` through `aria-label` and hides the text; the visible label reserves its selected (semibold) width so selection does not shift layout. `selectedIcon` replaces `icon` while selected.                                                                                                                              | Current source and tests |
+| FR7 | Every Tab renders an indicator carrying `tab-indicator`, visible only when selected; the root carries `tab` with `selected`. The pressed overlay paints on the tab surface.                                                                                                                                                                                | Current source and tests |
+| FR8 | The root forwards the `ref` and other DOM props, merges `className`, `style`, and `xstyle` after component styles, and paints the shared focus outline.                                                                                                                                                                                                    | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Size and layout.** Height follows the TabList size; `fill` layout
+  stretches Tabs.
+- **AV2 — Theme styling.** Themes restyle `tab` and `tab-indicator` per selected
+  state.
+
+### Representative states
+
+| State             | Required invariant                              | Allowed variation  |
+| ----------------- | ----------------------------------------------- | ------------------ |
+| Navigation button | `aria-current="true"` when selected.            | Icon, end content. |
+| Navigation link   | Link; `aria-current="true"` when selected.      | Router renderer.   |
+| Tabs pattern      | `role="tab"`, `aria-selected`, `aria-controls`. | —                  |
+| Icon only         | Named by `label`.                               | Icon.              |
+| Disabled          | No selection, handler, or navigation.           | Muted styling.     |
+
+### Transformation and precedence order
+
+- **ORD1 — Element.** Tabs pattern → button; else `href` → link (disabled →
+  plain `<a>`); else button.
+- **ORD2 — Controls.** `panelId`, then caller `aria-controls`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Pattern semantics.** FR1 and FR2.
+- **AR2 — One tab stop.** FR3.
+- **AR3 — Names.** Visible label or, when hidden, `aria-label` from `label`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                   | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Tab              | Icon, label, end content; stable width on selection. | Current source and public docs | Prominent      | FR6                |
+| Indicator        | Selected-only underline.                             | Current source                 | Supporting     | FR7                |
+
+`Tab.doc.mjs` declares no anatomy of its own, so no anatomy-theming map is
+recorded. Edge and indicator geometry across the strip is `component:TabList`
+FR1–FR2.
+
+## Family and system relationships
+
+- TabList supplies pattern, value, size, layout, and keyboard movement;
+  `component:TabList` contracts its edge geometry.
+- `family:navigation-destinations` owns the accept/block decision for `href`.
+
+## Verification map
+
+| Contract | Verification                                                                                                                                      | Representative states             | Mutation or failure expectation                  | Audit section             |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------ | ------------------------- |
+| FR1, FR2 | `TabList.test.tsx` aria-current, polymorphic link, and tabs-pattern tests; `Tabs.a11y.test.tsx`; `Tabs.a11y.chromium.spec.ts` for `aria-selected` | Navigation, link, tabs            | Wrong role or state fails.                       | `audit:Tab/accessibility` |
+| FR3      | `TabList.test.tsx` single tab stop and roving tabindex tests                                                                                      | Selected                          | Extra tab stops, or a wrong starting stop, fail. | `audit:Tab/accessibility` |
+| FR4, FR5 | `TabList.test.tsx` onChange and disabled tests                                                                                                    | Click, disabled button            | Selection when disabled fails.                   | `audit:Tab/behavior`      |
+| FR6, FR7 | `TabList.test.tsx` icon, icon-only, and pressed-overlay tests                                                                                     | Icon, selected icon, hidden label | Wrong icon, name, or overlay fails.              | `audit:Tab/behavior`      |
+
+Read from source, with no focused test yet:
+
+- FR3: the stop moving with arrow, Home, and End focus.
+- FR1: the button's `type="button"`.
+- FR4: the caller `onClick` running first, and its `preventDefault()`
+  cancelling selection.
+- FR5: the absent hover and pressed treatment on a disabled Tab.
+- FR6: the reserved selected-width label.
+- FR7: the `tab` and `tab-indicator` targets and their `selected` state.
+- FR8.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or TabList strip
+behavior. It links to their owners.

package/src/TabList/Tab.tsx

@@ -247,6 +247,12 @@ const hoverSizeStyles = stylex.create({
 });
 
 const layoutStyles = stylex.create({
+  // A hugging tab keeps its label's width. Without this the strip's flex
+  // shrinks every tab below its text before overflow can scroll, and on a
+  // narrow screen the labels draw over one another.
+  hug: {
+    flexShrink: 0,
+  },
   fill: {
     flex: 1,
     justifyContent: 'center',
@@ -391,7 +397,7 @@ export function Tab({
         styles.base,
         sizeStyles[size],
         isSelected && styles.selected,
-        isFill && layoutStyles.fill,
+        isFill ? layoutStyles.fill : layoutStyles.hug,
         !isDisabled && tabScope,
         // The touch press's strength and release live on the tab the
         // controller writes to; the hover layer inherits and paints it.

package/src/TabList/TabList.doc.mjs

@@ -115,7 +115,7 @@ export const docs = {
       },
     ],
     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.',
+      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page. A strip narrower than its tabs scrolls horizontally and keeps the selected tab in view.',
     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.' },
@@ -138,7 +138,7 @@ export const docs = {
 export const docsZh = {
   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.',
+      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page. A strip narrower than its tabs scrolls horizontally and keeps the selected tab in view.',
     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.' },
@@ -162,7 +162,7 @@ export const docsDense = {
   description: 'Tab strip w/ overflow scrolling; nav landmark by default, WAI-ARIA tabs pattern under role="tablist".',
   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.',
+      'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page. A strip narrower than its tabs scrolls horizontally and keeps the selected tab in view.',
     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.' },