Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): TabList records its shipped contract as current (#8643)

Cindy Zhang39ed04d76f66
diff --git a/packages/core/src/TabList/Tab.spec.md b/packages/core/src/TabList/Tab.spec.md
new file mode 100644
index 0000000000..8c2e49f416
--- /dev/null
+++ b/packages/core/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.
diff --git a/packages/core/src/TabList/TabMenu.spec.md b/packages/core/src/TabList/TabMenu.spec.md
new file mode 100644
index 0000000000..91a2ce314d
--- /dev/null
+++ b/packages/core/src/TabList/TabMenu.spec.md
@@ -0,0 +1,196 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TabMenu
+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,
+ apps/storybook/stories/TabList.stories.tsx,
+ ]
+modules: []
+families: [family:overlay-dismissal]
+design_specs: [design:reduced-motion]
+architecture:
+ [
+ architecture:component-style-authoring,
+ architecture:interaction-modality,
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ ]
+contributing: []
+system_specs: []
+---
+
+# TabMenu component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `TabMenu` with `label` and `options` (`{value, label, icon?}`); targets `tab-menu`, `tab-menu-dropdown`, and `tab-menu-item`, plus `tab-indicator` when an option is selected. |
+| Behavior | A TabList entry that groups several tab values behind a menu button. Its label shows the selected option, else `label`; choosing an option selects that value and closes the menu. |
+| End-user impact | Users reach overflow tab values from one entry and see which one is selected; keyboard users get APG menu-button behavior with a single tab stop inside the menu. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact). |
+| Review checks | Reject options without `menuitemradio` and `aria-checked`, more than one tab stop in the open menu, or a closed menu that leaves focus stranded. |
+| Governing rules | `component:TabList` (strip edge geometry); `family:overlay-dismissal`; `architecture:interaction-modality`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TabMenu is a TabList entry that holds several tab values in a menu. It owns its
+trigger, the option menu, and how choosing an option selects a value. Consumer
+usage lives in `TabMenu.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`; the
+ menu's open state is internal
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **A hidden label twin reserves the selected width.** The trigger's visible
+ label renders a second, `aria-hidden` copy that reserves the label's selected
+ weight. `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 trigger's 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.
+- **The open menu repeats the label.** The menu's heading repeats `label`,
+ which the trigger also shows while no option is selected, so that text
+ renders twice while the menu is open. `architecture:component-style-authoring`
+ INV7 has content render once.
+- **Motion under reduced motion.** The chevron's turn and the trigger and item
+ color and fill transitions still animate when reduced motion is requested;
+ `design:reduced-motion` DR1–DR3 allow no travel and, for a fine pointer, no
+ animated property.
+- **The `tab-menu` and `tab-menu-item` targets reflect no state.** The trigger
+ takes selected styling and a checked option takes medium weight, but neither
+ target reflects a state. `architecture:component-theming-surface` INV6 has a
+ state that changes paint reflected on the owning target.
+- **Selection mounts extra elements.** The trigger mounts its `tab-indicator`
+ only while an option is selected, and an option mounts its check mark only
+ while checked. `architecture:component-style-authoring` INV7 has states
+ expressed through attributes, classes, and styles on existing elements, never
+ through extra elements.
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger, its label and tab stop, the option menu, and selection from it
+ (FR1–FR6).
+
+**Does not own / non-goals**
+
+- Selected value, size, and strip keyboard movement — owned by TabList and
+ uncontracted here; strip edge geometry — owned by `component:TabList`.
+- Popover hosting and light dismiss — owned by the shared popover and layer
+ runtime; Escape ordering — owned by `family:overlay-dismissal`.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The trigger is a `<button>` with `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls` naming the menu; its props type omits `role`, and caller props cannot set its tab index or popup attributes. It carries `tab-menu` and forwards `ref` and other DOM props. | Current source and tests |
+| FR2 | The trigger shows the label of the option whose value is selected, else `label`, reserving semibold width; when an option is selected it uses selected styling and shows the selected indicator. It takes part in the strip's single tab stop like a Tab (`component:Tab` FR3): it starts as the stop when one of its options is selected, and the stop moves with arrow-key focus; where the stop starts when nothing in the strip is selected, or the selected entry is disabled, is uncontracted here. | Current source and tests |
+| FR3 | Clicking the trigger toggles a non-modal popover below it and, on open, focuses the first option; a caller `onClick` runs after the toggle. | Current source and tests |
+| FR4 | The menu is a `role="menu"` named by `label`, carrying `tab-menu-dropdown`, with a presentational heading repeating `label`, then one `role="menuitemradio"` per option with `aria-checked` for the selected value, an optional icon, and a check mark when selected. | Current source and tests |
+| FR5 | Inside the menu one option is a tab stop, and ArrowUp, ArrowDown, Home, and End move it; ArrowLeft and ArrowRight are left to the strip; Enter, Space, or click on an option selects its value through the TabList and closes the menu; Escape and Tab close it. Closing returns focus to the trigger. | Current source and tests |
+| FR6 | The trigger and options paint the shared focus outline. | Current source |
+
+### Allowed variation
+
+- **AV1 — Options.** Any number of options, each with an optional icon.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| No option selected | Trigger shows `label`; while another enabled entry is selected it is not the starting stop (Tab FR3); with nothing selected, or the selected entry disabled, where the stop starts is uncontracted. | — |
+| Option selected | Trigger shows that option's label and indicator. | — |
+| Open | Named menu; first option focused; one tab stop. | — |
+
+### Transformation and precedence order
+
+- **ORD1 — Trigger label.** Selected option's label, then `label`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Menu button.** FR1 and FR5 follow the APG menu-button pattern.
+- **AR2 — Radio options.** Options are `menuitemradio` with `aria-checked`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Trigger | Tab-styled button with chevron and indicator. | Current source and public docs | Prominent | FR2 |
+| Menu | Heading, then options with a check mark on selection. | Current source | Supporting | FR4 |
+
+`TabMenu.doc.mjs` declares no anatomy of its own, so no anatomy-theming map is
+recorded.
+
+## Family and system relationships
+
+- TabList supplies value, size, and the strip; `component:TabList` contracts
+ its edge geometry.
+- `family:overlay-dismissal` owns shared Escape ordering.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | ------------------------------------------------------------------ | ------------------------------------------------- | -------------------------------------------- | ----------------------------- |
+| FR1, FR3 | `TabList.test.tsx` TabMenu and host-attribute tests | Closed, open | Lost popup attributes fail. | `audit:TabMenu/accessibility` |
+| FR2, FR4 | `TabList.test.tsx` TabMenu label, heading, and menuitemradio tests | Selected and unselected | Wrong label or missing `aria-checked` fails. | `audit:TabMenu/behavior` |
+| FR5 | `TabList.test.tsx` TabMenu keyboard navigation tests | ArrowUp, ArrowDown, Home, End, Tab, Escape, Enter | Extra tab stops or a menu left open fails. | `audit:TabMenu/accessibility` |
+
+Read from source, with no focused test yet:
+
+- FR1: the `tab-menu` target, the forwarded `ref`, and owned attributes winning
+ over caller props.
+- FR2: the reserved semibold width, the selected styling and indicator, and the
+ trigger's part in the strip's tab stop.
+- FR3: the popover's placement, focus moving to the first option on open, and
+ the caller `onClick` running after the toggle.
+- FR4: the `tab-menu-dropdown` and `tab-menu-item` targets, option icons, and
+ the check mark.
+- FR3: a second click closing the menu.
+- FR5: Space selecting, the menu closing on selection, ArrowLeft and ArrowRight
+ left to the strip, and focus returning to the trigger on close.
+- FR6.
+
+## 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.