{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "tabs", "name": "Tabs", "category": "Controls", "contract_status": "preview", "contract_kind": "source-derived", "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." }, "approval": "required", "visual_reference": { "stories": [ { "id": "cloaked-design-system-controls-tabs--playground", "name": "Playground", "title": "Cloaked Design System/Controls/Tabs", "exportName": "Playground", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--playground&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--middle-active", "name": "Middle Active", "title": "Cloaked Design System/Controls/Tabs", "exportName": "MiddleActive", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--middle-active&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--many-tabs", "name": "Many Tabs", "title": "Cloaked Design System/Controls/Tabs", "exportName": "ManyTabs", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--many-tabs&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Controls/Tabs", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--dark-theme&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--content-fit", "name": "Content Fit", "title": "Cloaked Design System/Controls/Tabs", "exportName": "ContentFit", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--content-fit&viewMode=story" } ], "name": "Tabs", "id": "tabs", "category": "Controls" }, "stories_source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "code": "import React, { useState } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl, hapticArgType } from '../../../storybook/controlOptions';\nimport { Tabs, type TabItem } from './Tabs';\n\nconst THREE_ITEMS: TabItem[] = [\n { id: 'all', label: 'All' },\n { id: 'monitoring', label: 'Monitoring' },\n { id: 'guard', label: 'Guard' },\n];\n\nconst FIVE_ITEMS: TabItem[] = [\n { id: 'overview', label: 'Overview' },\n { id: 'activity', label: 'Activity' },\n { id: 'settings', label: 'Settings' },\n { id: 'members', label: 'Members' },\n { id: 'billing', label: 'Billing' },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Controls/Tabs',\n component: Tabs,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A horizontal tab strip (role tablist) for switching between sibling content panels — ' +\n 'Overview / Activity / Settings. Scales to more items than a `SegmentedControl`, which is the ' +\n 'right choice for a compact 2–4 option switch that re-filters one view rather than swapping ' +\n 'panels.',\n },\n },\n },\n args: {\n items: THREE_ITEMS,\n activeId: 'all',\n ariaLabel: 'Dashboard sections',\n testId: 'controls-tabs',\n },\n argTypes: {\n items: { ...disabledControl, description: 'Tabs rendered in order; each is a `TabItem`.' },\n activeId: { control: 'text', description: 'Controlled: `id` of the selected tab.' },\n onSelect: { ...disabledControl, description: 'Called with the selected tab `id`.' },\n ariaLabel: { control: 'text', description: 'Accessible name for the tablist.' },\n haptic: {\n ...hapticArgType,\n description: 'Haptic on tab change. Defaults to `true` (`selection`).',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nfunction TabsPlayground() {\n const [activeId, setActiveId] = useState(THREE_ITEMS[0].id);\n\n return (\n \n );\n}\n\nexport const Playground: Story = {\n parameters: { docs: { description: { story: 'Interactive — `onSelect` drives `activeId` through React state.' } } },\n render: () => ,\n};\n\nexport const MiddleActive: Story = {\n args: { activeId: 'monitoring' },\n parameters: { docs: { description: { story: 'A non-first tab selected.' } } },\n};\n\nexport const ManyTabs: Story = {\n args: { items: FIVE_ITEMS, activeId: 'settings' },\n parameters: {\n docs: { description: { story: 'Five tabs — beyond this, prefer a picker over cramming the strip.' } },\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: { docs: { description: { story: 'Tab strip on the dark theme surface.' } } },\n};\n\n// Ids mirror a real consumer's camelCase domain keys; `testId` keeps the derived selectors\n// kebab-case.\nconst CONTENT_FIT_ITEMS: TabItem[] = [\n { id: 'popular', label: 'Most popular' },\n { id: 'riskiest', label: 'Worst offenders' },\n { id: 'safest', label: 'Safer picks' },\n { id: 'sellsData', label: 'Sells your data', testId: 'sells-data' },\n { id: 'recentlyBreached', label: 'Recently breached', testId: 'recently-breached' },\n];\n\nfunction ContentFitPlayground() {\n const [activeId, setActiveId] = useState(CONTENT_FIT_ITEMS[0].id);\n\n return (\n \n );\n}\n\nexport const ContentFit: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Interactive — each tab sizes to its label and the strip scrolls; selecting a tab tracks ' +\n 'the underline to the new label and scrolls it into view instead of resizing a computed ' +\n 'column width.',\n },\n },\n },\n render: () => ,\n};\n" }, "specification": { "$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." } ] }, "specification_source": "packages/design-system/src/components/controls/Tabs/Tabs.spec.json", "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." }, "links": { "human": "/component-tabs", "json": "/data/visual/components/tabs.json", "storybook": "/storybook/?path=/story/cloaked-design-system-controls-tabs--playground" } }