@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

package/src/Stepper/Stepper.tsx

@@ -0,0 +1,258 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Stepper.tsx
+ * @input Uses React, stylex, theme tokens, StepperContext
+ * @output Exports Stepper component and StepperProps
+ * @position Core container component; consumed by index.ts
+ *
+ * Besides the props it is given, this component tracks the `activeStep` it
+ * last rendered with and publishes it on the context. Steps need the distance
+ * and direction of a change to choreograph their connector fill; see the
+ * CONNECTOR FILL block in Step.tsx.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Stepper/Stepper.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Stepper/index.ts (exports if types change)
+ * - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)
+ * - /packages/cli/assets/templates/blocks/components/Stepper/ (showcase blocks)
+ */
+
+import {useCallback, useMemo, useRef, useState, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {spacingVars} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {themeProps} from '../utils';
+import {useTranslator} from '../i18n';
+import {
+  StepperContext,
+  type StepperOrientation,
+  type StepperIndicatorPosition,
+  type StepperContextValue,
+} from './StepperContext';
+
+export interface StepperProps extends BaseProps<HTMLOListElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLOListElement>;
+  /**
+   * Zero-based index of the active step.
+   */
+  activeStep: number;
+  /**
+   * Step elements to render.
+   */
+  children: ReactNode;
+  /**
+   * Layout direction of the stepper.
+   * @default 'horizontal'
+   */
+  orientation?: StepperOrientation;
+  /**
+   * Called when a step indicator is clicked. Enables non-linear navigation.
+   * When provided, completed and current steps become clickable.
+   */
+  onStepClick?: (index: number) => void;
+  /**
+   * Accessible label describing the set of steps. Defaults to a translated
+   * "Progress" when unset.
+   */
+  label?: string;
+  /**
+   * Controls density (padding) of all steps.
+   * @default 'balanced'
+   */
+  density?: 'compact' | 'balanced' | 'spacious';
+  /**
+   * Controls where each step's indicator sits relative to the connector track.
+   * - 'separated': indicator lives in the label row, distinct from the progress
+   *   bar (the original Astryx layout).
+   * - 'on-track': indicator is slotted into the connector line as a node on the
+   *   track (the on-track indicator design).
+   * @default 'separated'
+   */
+  indicatorPosition?: StepperIndicatorPosition;
+}
+
+const styles = stylex.create({
+  root: {
+    display: 'flex',
+    width: '100%',
+    listStyleType: 'none',
+    margin: 0,
+    padding: 0,
+  },
+  horizontal: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: spacingVars['--spacing-0-5'],
+  },
+  vertical: {
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-0-5'],
+  },
+  // On-track: steps must abut so their connector segments form one continuous
+  // line, so the inter-step gap collapses to zero.
+  horizontalOnTrack: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: 0,
+  },
+  verticalOnTrack: {
+    flexDirection: 'column',
+    gap: 0,
+  },
+});
+
+/**
+ * A stepper component for multi-step workflows. Displays numbered steps
+ * with visual indicators for completed, active, and upcoming states.
+ *
+ * Each Step child must provide a `step` prop (zero-based index) so it
+ * can derive its state from the parent's activeStep. The on-track layout
+ * hides the leading connector on the first step and the trailing connector
+ * on the last step structurally, from each step's own `<li>` position, so
+ * it works regardless of how the steps are grouped.
+ *
+ * Rendered as an ordered list (`<ol>`/`<li>`) rather than a `nav`
+ * landmark: a stepper communicates *progress through a sequence*, not a
+ * set of site navigation links. The active step is marked with
+ * `aria-current="step"` (handled per-step) and the list carries an
+ * accessible `label`. This follows the WAI-ARIA pattern for steppers /
+ * progress sequences and avoids polluting the page's landmark map.
+ *
+ * @example
+ * ```
+ * <Stepper activeStep={1}>
+ *   <Step step={0} label="Account" />
+ *   <Step step={1} label="Profile" />
+ *   <Step step={2} label="Review" />
+ * </Stepper>
+ * ```
+ */
+export function Stepper({
+  activeStep,
+  children,
+  orientation = 'horizontal',
+  onStepClick,
+  label: labelFromProps,
+  density = 'balanced',
+  indicatorPosition = 'separated',
+  xstyle,
+  className,
+  style,
+  ref,
+  ...rest
+}: StepperProps) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@astryx.stepper.label');
+
+  // Dev-mode duplicate step index detection. Steps register on mount and
+  // deregister on unmount; a Map tracks count per index so we can warn when
+  // two Steps share the same `step` value (which breaks aria-current).
+  const stepCountsRef = useRef<Map<number, number>>(new Map());
+  const registerStep = useCallback((index: number) => {
+    const counts = stepCountsRef.current;
+    const prev = counts.get(index) ?? 0;
+    counts.set(index, prev + 1);
+    if (process.env.NODE_ENV !== 'production' && prev + 1 > 1) {
+      console.warn(
+        `[Stepper] Duplicate step index ${index}: two <Step> elements share the same \`step\` value. ` +
+          `This breaks \`aria-current="step"\` and causes both to show as active simultaneously.`,
+      );
+    }
+    return () => {
+      const cur = counts.get(index) ?? 1;
+      if (cur <= 1) {
+        counts.delete(index);
+      } else {
+        counts.set(index, cur - 1);
+      }
+    };
+  }, []);
+
+  // The step we came *from*. Steps need it to stagger their connector fill:
+  // the distance and direction of the change decide which segment moves first
+  // and how long the whole sweep may take (see Step.tsx's CONNECTOR FILL).
+  //
+  // Derived during render from state rather than written in an effect. An
+  // effect runs after paint, so the browser would already have committed the
+  // new fill states with last render's delays — the first frame of the sweep
+  // would be wrong, and on a jump of one that is the entire animation. React
+  // discards and re-runs a render that sets its own state before committing,
+  // so this costs a re-render but never a wrong frame.
+  //
+  // Seeding both halves from the current `activeStep` is what suppresses the
+  // cascade on mount: a stepper that opens on step 3 has no previous step to
+  // have travelled from, so its completed segments paint filled at once. That
+  // also makes the first render pure and identical on the server, so there is
+  // nothing for hydration to disagree about. Storing the pair in one state
+  // object keeps the update idempotent under StrictMode's double render — both
+  // invocations read the same `seen` and queue the same successor.
+  const [seen, setSeen] = useState(() => ({
+    current: activeStep,
+    previous: activeStep,
+  }));
+  if (seen.current !== activeStep) {
+    setSeen({current: activeStep, previous: seen.current});
+  }
+  const previousActiveStep =
+    seen.current === activeStep ? seen.previous : seen.current;
+
+  const ctxValue = useMemo<StepperContextValue>(
+    () => ({
+      activeStep,
+      previousActiveStep,
+      orientation,
+      isNonLinear: onStepClick != null,
+      onStepClick: onStepClick ?? null,
+      density,
+      indicatorPosition,
+      registerStep,
+    }),
+    [
+      activeStep,
+      previousActiveStep,
+      orientation,
+      onStepClick,
+      density,
+      indicatorPosition,
+      registerStep,
+    ],
+  );
+
+  const isOnTrack = indicatorPosition === 'on-track';
+  const orientationStyle =
+    orientation === 'horizontal'
+      ? isOnTrack
+        ? styles.horizontalOnTrack
+        : styles.horizontal
+      : isOnTrack
+        ? styles.verticalOnTrack
+        : styles.vertical;
+
+  return (
+    <StepperContext value={ctxValue}>
+      <ol
+        ref={ref}
+        aria-label={label}
+        {...rest}
+        {...mergeProps(
+          themeProps('stepper', {orientation, indicatorPosition}),
+          stylex.props(styles.root, orientationStyle, xstyle),
+          className,
+          style,
+        )}>
+        {/* Each step renders its own progress bar segment; no child
+            introspection needed — steps derive state from context. */}
+        {children}
+      </ol>
+    </StepperContext>
+  );
+}
+
+Stepper.displayName = 'Stepper';

package/src/Stepper/StepperContext.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StepperContext.ts
+ * @input Uses React createContext/use
+ * @output Exports StepperContext, useStepperContext, and context types
+ * @position Context for Stepper <-> Step communication
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs
+ * - /packages/core/src/Stepper/index.ts
+ */
+
+import {createContext, use} from 'react';
+
+export type StepperOrientation = 'horizontal' | 'vertical';
+export type StepperDensity = 'compact' | 'balanced' | 'spacious';
+
+/**
+ * Controls where each step's indicator sits relative to the connector track.
+ * - 'separated': indicator lives in the label row, distinct from the progress
+ *   bar (Astryx's original layout).
+ * - 'on-track': indicator is slotted *into* the connector line as a node on the
+ *   track, with the label beside (vertical) or below (horizontal). Aligns with
+ *   the on-track stepper design.
+ */
+export type StepperIndicatorPosition = 'separated' | 'on-track';
+
+export interface StepperContextValue {
+  activeStep: number;
+  /**
+   * The `activeStep` this stepper last rendered with, so a Step can tell
+   * whether the change it is reacting to was a single step forward — the one
+   * change that animates the connector fill — and which span that change
+   * crossed (see the CONNECTOR FILL block in Step.tsx). Equal to `activeStep`
+   * on the first render, which is what keeps a stepper that mounts mid-flow
+   * from animating its way to the step it opened on.
+   *
+   * Internal: not part of the public API, and deliberately not a Stepper prop.
+   * When the connector animates is behaviour the stepper owns, not something a
+   * consumer configures.
+   */
+  previousActiveStep: number;
+  orientation: StepperOrientation;
+  isNonLinear: boolean;
+  onStepClick: ((index: number) => void) | null;
+  density: StepperDensity;
+  indicatorPosition: StepperIndicatorPosition;
+  /**
+   * Dev-mode index registration. Each Step calls this on mount with its `step`
+   * index. The Stepper tracks the set and warns if two Steps share the same
+   * index. Returns a cleanup function to call on unmount.
+   */
+  registerStep: (index: number) => () => void;
+}
+
+export const StepperContext = createContext<StepperContextValue | null>(null);
+StepperContext.displayName = 'StepperContext';
+
+export function useStepperContext(): StepperContextValue {
+  const ctx = use(StepperContext);
+  if (ctx == null) {
+    throw new Error(
+      'useStepperContext must be used within Stepper. ' +
+        'Wrap your Step in <Stepper>.',
+    );
+  }
+  return ctx;
+}

package/src/Stepper/index.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+export {Stepper} from './Stepper';
+export type {StepperProps} from './Stepper';
+
+export {Step} from './Step';
+export type {StepProps, StepIndicatorPreset} from './Step';
+
+export type {StepStatus} from './StepStatus';
+
+export {useStepperContext} from './StepperContext';
+export type {
+  StepperContextValue,
+  StepperOrientation,
+  StepperIndicatorPosition,
+} from './StepperContext';

package/src/Stepper/stepper.stylex.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stepper.stylex.ts
+ * @input StyleX marker system
+ * @output stepMarker — a scoped marker applied to each Step's <li>
+ * @position Shared StyleX marker consumed by Step for structural selectors
+ *
+ * Applied to each Step's root `<li>` so the on-track connector segments can
+ * key their first/last-node visibility off `stylex.when.ancestor(':first-child'
+ * | ':last-child', stepMarker)` — matching only the parent step row, never the
+ * outer `<ol>`. This replaces counting children in the parent, so steps behave
+ * correctly regardless of how the consumer groups them (arrays, fragments).
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const stepMarker: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();

package/src/Switch/Switch.tsx

@@ -41,7 +41,7 @@ import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {switchScope} from './switch.markers.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -49,6 +49,7 @@ import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const wrapperSizeStyles = stylex.create({
   sm: {
     width: 32,
@@ -551,7 +552,7 @@ export function Switch({
   const switchElement = (
     <div {...stylex.props(styles.switchWrapper, wrapperSizeStyles[size])}>
       <input
-        ref={mergeRefs(ref, disabledMessageTooltip.positionRef)}
+        ref={useMergedRefs(ref, disabledMessageTooltip.positionRef)}
         id={id}
         type="checkbox"
         role="switch"

package/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. 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, and a development warning says so.',
     },
     {
       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, and a development warning says so.',
+    },
     {
       name: 'as',
       type: 'LinkComponentType',

package/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,20 @@ export interface TabProps extends BaseProps<HTMLButtonElement> {
   isLabelHidden?: boolean;
   /**
    * URL to navigate to. When provided, renders as an anchor element.
+   *
+   * Ignored 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 — a development warning says so.
+   */
+  panelId?: string;
   /**
    * Icon element shown when tab is not selected.
    */
@@ -228,6 +242,7 @@ export function Tab({
   label,
   isLabelHidden = false,
   href,
+  panelId,
   icon,
   selectedIcon,
   endContent,
@@ -242,6 +257,9 @@ export function Tab({
   const isSelected = tabListCtx.value === value;
   const size: TabListSize = tabListCtx.size;
   const isFill = tabListCtx.layout === 'fill';
+  const isTabsPattern = tabListCtx.pattern === 'tabs';
+  const isLink = href != null && !isTabsPattern;
+  const isTabRole = isTabsPattern && !isLink;
   const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
   const hasVisibleLabel = !isLabelHidden && label !== '';
 
@@ -249,6 +267,34 @@ export function Tab({
     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 for the ' +
+      'navigation 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'];
+
+  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 && controls == null,
+  );
+
+  useDevWarning(
+    'Tab',
+    'panelId does nothing outside a role="tablist" TabList — the navigation ' +
+      'pattern has no panel to associate. Give the TabList role="tablist", ' +
+      'or drop the panelId.',
+    !isTabsPattern && panelId != null,
+  );
+
   const iconElement = displayIcon ? (
     <span {...stylex.props(styles.icon, iconSizeStyles[size])}>
       {displayIcon}
@@ -260,7 +306,25 @@ export function Tab({
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',
     'data-tab-value': value,
-    'aria-current': isSelected ? ('page' 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
@@ -317,7 +381,7 @@ export function Tab({
     <span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
   ) : null;
 
-  if (href != null) {
+  if (isLink) {
     return (
       <LinkComponent
         ref={ref}

package/src/TabList/TabList.doc.mjs

@@ -16,6 +16,8 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-tab-list', visualProps: ['size']},
+      {className: 'astryx-tab-strip'},
+      {className: 'astryx-tab-scroll-button'},
       {className: 'astryx-tab', states: ['selected']},
       {className: 'astryx-tab-indicator', states: ['selected']},
       {className: 'astryx-tab-menu'},
@@ -26,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; a nav landmark, or the WAI-ARIA tabs pattern where role="tablist" asks for it.',
   props: [
     {
       name: 'value',
@@ -58,10 +60,21 @@ 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 is a nav landmark marking the current tab with aria-current. Any other value is passed through to the element unchanged.",
+    },
+    {
+      name: 'overflow',
+      type: "'auto' | 'scroll' | 'visible'",
+      description: "What happens when the tabs are wider than the strip. 'auto' lets the component choose, which today always scrolls. 'scroll' scrolls the tabs horizontally, with edge fades and arrow affordances for pointers that can hover. 'visible' turns overflow handling off and lets the tabs spill out of the strip. The selected tab is always scrolled back into view.",
+      default: "'auto'",
+    },
     {
       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',
@@ -88,8 +101,9 @@ export const docs = {
       '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: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+      { 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: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },
       { 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.' },
@@ -109,8 +123,9 @@ export const docsZh = {
       '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: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+      { 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: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },
       { 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.' },
@@ -125,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; 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.',
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
-      { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+      { 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: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },
       { 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.' },