# Tabs

A horizontal tab list for choosing one sibling content panel, with a bold underline marking the controlled active tab.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/controls/Tabs/Tabs.tsx

## Guidance

{
  "summary": "A horizontal tab list for choosing one sibling content panel, with a bold underline marking the controlled active tab.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A horizontal tab strip (`role=\"tablist\"`) for switching between sibling content panels —\nOverview / Activity / Settings."
    },
    {
      "heading": "When to use",
      "body": "Reach for `Tabs` when each option reveals a _different_ panel of content and you want them\nnavigable inline. It scales to more items than a `SegmentedControl`. In-app it splits the\nactivity views in `ActionsDetail`. The one it is most confused with is `SegmentedControl`: use that\ninstead when the options are a compact 2–4 value filter that re-slices a single view rather than\nswapping panels. Past ~5 tabs, prefer a picker over cramming the strip."
    },
    {
      "heading": "Choosing a fit",
      "body": "`equal` divides the strip evenly and suits sets that fit the width, up to roughly five panels.\n`content` sizes each tab to its label and scrolls the strip horizontally, for sets that overflow\nthe equal fit — the underline tracks the active label's width instead of a computed column."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/controls/Tabs/Tabs.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "items",
      "type": "TabItem[]",
      "declared_type": "TabItem[]",
      "required": true,
      "description": "Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker.",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 32
      }
    },
    {
      "name": "activeId",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Controlled `id` of the active tab. An id matching no item hides the underline entirely.",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 34
      }
    },
    {
      "name": "onSelect",
      "type": "((id: string) => void) | undefined",
      "declared_type": "(id: string) => void",
      "required": false,
      "description": "Called with the pressed tab's `id`. Never fires for the tab that is already active.",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 36
      }
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible name for the tablist, such as `Dashboard sections`.",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 38
      }
    },
    {
      "name": "fit",
      "type": "TabsFit | undefined",
      "declared_type": "TabsFit",
      "required": false,
      "description": "How tabs claim width. Defaults to `equal`.",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 40
      },
      "values": [
        "content",
        "equal"
      ],
      "values_complete": true,
      "default": "'equal'",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 41
      }
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for tab changes. Defaults to `true` (`selection`).",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 43
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n`TabItem.testId` included.",
      "source": {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 48
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Tabs",
    "public_path": "Tabs",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Tabs",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
          "line": 56
        },
        "props_type": "TabsProps",
        "props": [
          {
            "name": "items",
            "type": "TabItem[]",
            "declared_type": "TabItem[]",
            "required": true,
            "description": "Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker.",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 32
            }
          },
          {
            "name": "activeId",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Controlled `id` of the active tab. An id matching no item hides the underline entirely.",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 34
            }
          },
          {
            "name": "onSelect",
            "type": "((id: string) => void) | undefined",
            "declared_type": "(id: string) => void",
            "required": false,
            "description": "Called with the pressed tab's `id`. Never fires for the tab that is already active.",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 36
            }
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible name for the tablist, such as `Dashboard sections`.",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 38
            }
          },
          {
            "name": "fit",
            "type": "TabsFit | undefined",
            "declared_type": "TabsFit",
            "required": false,
            "description": "How tabs claim width. Defaults to `equal`.",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 40
            },
            "values": [
              "content",
              "equal"
            ],
            "values_complete": true,
            "default": "'equal'",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 41
            }
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for tab changes. Defaults to `true` (`selection`).",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 43
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n`TabItem.testId` included.",
            "source": {
              "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
              "line": 48
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 11,
        "name": "TabItem",
        "code": "export interface TabItem {\n    /** Matched against `activeId` and handed back by `onSelect`. Also the default test-selector suffix, so prefer kebab-case or set `testId`. */\n    id: string;\n    /** Visible tab text. Sizes the tab under the `content` fit; shares the strip under `equal`. */\n    label: string;\n    /** Overrides the id-derived test selector, for ids that are not kebab-case. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 24,
        "name": "TabsFit",
        "code": "export type TabsFit = 'equal' | 'content';"
      },
      {
        "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx",
        "line": 30,
        "name": "TabsProps",
        "code": "export interface TabsProps {\n    /** Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker. */\n    items: TabItem[];\n    /** Controlled `id` of the active tab. An id matching no item hides the underline entirely. */\n    activeId: string;\n    /** Called with the pressed tab's `id`. Never fires for the tab that is already active. */\n    onSelect?: (id: string) => void;\n    /** Accessible name for the tablist, such as `Dashboard sections`. */\n    ariaLabel?: string;\n    /** How tabs claim width. Defaults to `equal`. */\n    fit?: TabsFit;\n    className?: string;\n    /** Haptic feedback for tab changes. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    /**\n     * Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n     * `TabItem.testId` included.\n     */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Tabs",
      "status": "preview",
      "version": "1.1.1",
      "summary": "A horizontal tab list for choosing one sibling content panel, with a bold underline marking the controlled active tab."
    },
    "parts": [
      {
        "id": "tab-list",
        "label": "Tab list",
        "description": "Owns the accessible group name, horizontal spacing, divider, backdrop, and (content fit) horizontal scrolling."
      },
      {
        "id": "tab",
        "label": "Tab",
        "description": "Native button exposing tab semantics and controlled selected state."
      },
      {
        "id": "label",
        "label": "Tab label",
        "description": "Names the sibling content panel."
      },
      {
        "id": "active-indicator",
        "label": "Active indicator",
        "description": "Bottom border marking the selected tab."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "underline": {
          "label": "Underline",
          "description": "Horizontal text tabs with one bold bottom indicator."
        }
      },
      "sizes": {},
      "fits": {
        "equal": {
          "label": "Equal",
          "description": "Sibling tabs divide the strip evenly; use when the labels fit the width."
        },
        "content": {
          "label": "Content",
          "description": "Each tab is as wide as its label and the strip scrolls horizontally; use for sets too long to divide legibly."
        }
      }
    },
    "variants": [
      {
        "id": "underline",
        "label": "Underline",
        "description": "Sibling tabs with one selected underline; equal-width by default, or content-sized and scrolling under the content fit.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "tab-gap",
        "label": "Equal-fit tab gap",
        "kind": "exact",
        "token": "--cds-space-24",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "tab-list",
          "tab"
        ]
      },
      {
        "id": "tab-list-horizontal-padding",
        "label": "Equal-fit tab-list horizontal padding",
        "kind": "exact",
        "token": "--cds-space-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "tab-list"
        ]
      },
      {
        "id": "tab-vertical-padding",
        "label": "Equal-fit tab vertical padding",
        "kind": "exact",
        "token": "--cds-space-12",
        "value": 12,
        "unit": "px",
        "appliesTo": [
          "tab",
          "label",
          "active-indicator"
        ]
      },
      {
        "id": "content-tab-horizontal-padding",
        "label": "Content-fit tab horizontal padding",
        "kind": "exact",
        "token": "--cds-space-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "tab",
          "label"
        ]
      },
      {
        "id": "content-tab-vertical-padding",
        "label": "Content-fit tab vertical padding",
        "kind": "exact",
        "token": "--cds-space-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "tab",
          "label",
          "active-indicator"
        ]
      }
    ],
    "layout": {
      "alignment": "Equal-fit tabs share the available width; content-fit tabs size to their labels and scroll. Both center labels over the common bottom divider.",
      "flow": "Sibling tabs form one horizontal row with the active indicator attached to one tab.",
      "notes": [
        "Reach for Tabs when each option reveals a different panel of content and you want them navigable inline; it scales to more items than a SegmentedControl.",
        "Use SegmentedControl instead when the options are a compact 2-4 value filter that re-slices a single view rather than swapping panels.",
        "Past ~5 tabs, prefer a picker over cramming the strip."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Tab label",
          "description": "Use the body ramp for primary navigation labels.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Tab label",
          "description": "Use primary text emphasis.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Divider",
          "description": "Use the semantic divider beneath the tab strip.",
          "token": "--cds-divider"
        },
        {
          "label": "Active indicator",
          "description": "Use the bold semantic surface for the selected underline.",
          "token": "--cds-bg-bold"
        }
      ]
    },
    "states": [
      {
        "id": "inactive",
        "label": "Inactive",
        "description": "Shows a lower-emphasis label with selected false."
      },
      {
        "id": "active",
        "label": "Active",
        "description": "Shows the active underline and selected true."
      },
      {
        "id": "focused",
        "label": "Focused",
        "description": "Retains native button keyboard focus indication."
      }
    ],
    "behavior": [
      {
        "label": "Controlled selection",
        "description": "Emit a tab id only when it differs from the controlled active id."
      },
      {
        "label": "Panel ownership",
        "description": "Leave panel rendering and visibility to the integrating surface."
      },
      {
        "label": "Sibling scope",
        "description": "Use tabs only for peer content destinations within the same surface."
      },
      {
        "label": "Active tab reveal",
        "description": "When tabs are sized to their content, scroll the strip the minimum distance to bring the active tab into view — on mount, on external selection changes, and on any reflow that moves it (a font swap or a sibling widening), not only on press. Scroll the strip only; never scroll an enclosing scroll container, which would displace a surface that is mid-transition."
      }
    ],
    "accessibility": [
      {
        "label": "Tab-list name",
        "description": "Provide a stable accessible name for the tab list."
      },
      {
        "label": "Tab semantics",
        "description": "Expose every item as a tab with its selected state and visible label."
      },
      {
        "label": "Panel relationship",
        "description": "The integrating surface should connect each tab to its owned tab panel when panels are rendered."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Tab count",
        "description": "Keep labels concise and the set at roughly five or fewer. Use the equal fit while the labels fit the width and the content fit once they overflow."
      },
      {
        "label": "Parallel labels",
        "description": "Use concise peer nouns that describe the content panels."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Selection treatment",
          "description": "Move selection by updating underline and label emphasis without resizing the strip; the content fit also scrolls the newly selected tab into view."
        }
      ],
      "haptics": [
        {
          "label": "Tab feedback",
          "description": "Request the selection haptic after the active tab changes."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Tabs expose ARIA tab-list and tab roles while the integrating surface owns DOM tab panels and their relationships.",
        "rationale": "The reusable strip cannot know panel ids; native containers likewise connect the selected tab to platform-owned content."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-24",
      "light": "24px",
      "dark": "24px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-space-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-space-20",
      "light": "20px",
      "dark": "20px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-divider",
      "light": "#e0ddd6",
      "dark": "#ffffff1a"
    },
    {
      "name": "--cds-bg-bold",
      "light": "#0b0b0a",
      "dark": "#ffffff"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-controls-tabs--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx

- [Middle Active](/storybook/iframe.html?id=cloaked-design-system-controls-tabs--middle-active&viewMode=story) | export: MiddleActive | source: packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx

- [Many Tabs](/storybook/iframe.html?id=cloaked-design-system-controls-tabs--many-tabs&viewMode=story) | export: ManyTabs | source: packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-controls-tabs--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx

- [Content Fit](/storybook/iframe.html?id=cloaked-design-system-controls-tabs--content-fit&viewMode=story) | export: ContentFit | source: packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.