{
"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": "carousel",
"name": "Carousel",
"category": "Layout",
"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": "preview",
"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-layout-carousel--playground",
"name": "Playground",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "Playground",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--playground&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--single-slide",
"name": "Single Slide",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "SingleSlide",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--single-slide&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--with-controls-and-dots",
"name": "With Controls And Dots",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "WithControlsAndDots",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--with-controls-and-dots&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--peek",
"name": "Peek",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "Peek",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--peek&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--magnetic",
"name": "Magnetic",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "Magnetic",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--magnetic&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--loose",
"name": "Loose",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "Loose",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--loose&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--overflow-content",
"name": "Overflow Content",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "OverflowContent",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--overflow-content&viewMode=story"
},
{
"id": "cloaked-design-system-layout-carousel--autoplay",
"name": "Autoplay",
"title": "Cloaked Design System/Layout/Carousel",
"exportName": "Autoplay",
"source_path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"source_digest": "58f065687d821818acee32dec8acb0c9a841a9ba2f6b924cd507f0f3faec82e0",
"status": "preview",
"local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-carousel--autoplay&viewMode=story"
}
],
"name": "Carousel",
"id": "carousel",
"category": "Layout"
},
"stories_source": {
"path": "packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx",
"code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Card } from '../../cards/Card/Card';\nimport { Text } from '../../primitives/Text/Text';\nimport { SPACE_OPTIONS, disabledControl, hapticArgType, selectArgType } from '../../../storybook/controlOptions';\nimport {\n Carousel,\n type CarouselSlideWidth,\n type CarouselSnapAlign,\n type CarouselSnapStop,\n type CarouselSnapType,\n} from './Carousel';\n\nconst CAROUSEL_SNAP_ALIGN_OPTIONS = ['start', 'center', 'end'] as const satisfies readonly CarouselSnapAlign[];\nconst CAROUSEL_SLIDE_WIDTH_OPTIONS = ['full', 'peek', 'auto'] as const satisfies readonly CarouselSlideWidth[];\nconst CAROUSEL_SNAP_TYPE_OPTIONS = ['mandatory', 'proximity'] as const satisfies readonly CarouselSnapType[];\nconst CAROUSEL_SNAP_STOP_OPTIONS = ['normal', 'always'] as const satisfies readonly CarouselSnapStop[];\n\nconst slides = ['Privacy score', 'Exposure scan', 'Quick setup'].map((title, index) => (\n \n \n {title}\n \n Swipe between cards or use optional controls and dots.\n \n \n \n));\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Layout/Carousel',\n component: Carousel,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Horizontal snap carousel backed by native CSS scroll-snap; touch scroll works with zero ' +\n 'props, and `controls`, `dots`, `autoplay`, and `loop` are opt-in. The snap feel comes from ' +\n 'two axes: `snapType` (`mandatory` always rests on a card vs `proximity` for looser ' +\n 'free-scroll) and `snapStop` (`always` is magnetic — one card per flick — vs `normal` which ' +\n 'lets momentum skip several). Set `slideWidth=\"peek\"` with `peek` to reveal the next card. ' +\n 'For a plain non-snapping overflow row, use `HStack scroll` instead.',\n },\n },\n },\n args: {\n ariaLabel: 'Dashboard cards',\n children: slides,\n gap: 12,\n },\n argTypes: {\n children: disabledControl,\n gap: { ...selectArgType(SPACE_OPTIONS), description: 'Space between slides, in `--cds-space-*` steps.' },\n snapAlign: {\n ...selectArgType(CAROUSEL_SNAP_ALIGN_OPTIONS),\n description: 'Which edge of each slide the scroll snap rests against. Defaults to `start`.',\n },\n snapType: {\n ...selectArgType(CAROUSEL_SNAP_TYPE_OPTIONS),\n description:\n 'Snap strength: `mandatory` always rests on a card; `proximity` only snaps when a card is already close.',\n },\n snapStop: {\n ...selectArgType(CAROUSEL_SNAP_STOP_OPTIONS),\n description:\n 'Per-card stop: `always` lands every flick on the adjacent card (magnetic); `normal` lets momentum skip several.',\n },\n slideWidth: {\n ...selectArgType(CAROUSEL_SLIDE_WIDTH_OPTIONS),\n description:\n 'Slide sizing: `full` one card per view, `peek` leaves room for the next card, `auto` sizes to content.',\n },\n peek: {\n ...selectArgType(SPACE_OPTIONS),\n description: 'Visible width of the next card when `slideWidth=\"peek\"`, in `--cds-space-*` steps.',\n },\n onSelectedIndexChange: disabledControl,\n haptic: {\n ...hapticArgType,\n description: 'Haptic fired on user-driven slide changes. Defaults to `true` (`selection`).',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const SingleSlide: Story = {\n parameters: {\n docs: {\n description: {\n story: 'A single slide: controls and dots hide themselves when there is nothing to page to.',\n },\n },\n },\n args: {\n ariaLabel: 'Single dashboard card',\n children: slides.slice(0, 1),\n controls: true,\n dots: true,\n testId: 'carousel-single',\n },\n};\n\nexport const WithControlsAndDots: Story = {\n parameters: {\n docs: { description: { story: 'Opt-in `controls`, `dots`, and `loop` for a deliberate, paged experience.' } },\n },\n args: {\n ariaLabel: 'Dashboard cards',\n children: slides,\n controls: true,\n dots: true,\n loop: true,\n testId: 'carousel-controls',\n },\n};\n\nexport const Peek: Story = {\n parameters: {\n docs: {\n description: {\n story: '`slideWidth=\"peek\"` with `peek` reveals the next card to signal there is more to scroll.',\n },\n },\n },\n args: {\n ariaLabel: 'Dashboard cards',\n children: slides,\n dots: true,\n gap: 16,\n peek: 40,\n slideWidth: 'peek',\n testId: 'carousel-peek',\n },\n};\n\nexport const Magnetic: Story = {\n parameters: {\n docs: {\n description: {\n story: '`snapStop=\"always\"` forces each flick to land on the neighboring card — the most controlled feel.',\n },\n },\n },\n args: {\n ariaLabel: 'Magnetic dashboard cards',\n children: [...slides, ...slides],\n gap: 16,\n peek: 40,\n slideWidth: 'peek',\n snapStop: 'always',\n dots: true,\n testId: 'carousel-magnetic',\n },\n};\n\nexport const Loose: Story = {\n parameters: {\n docs: {\n description: {\n story: '`snapType=\"proximity\"` only snaps when a card is already near center — momentum can carry past several.',\n },\n },\n },\n args: {\n ariaLabel: 'Loose dashboard cards',\n children: [...slides, ...slides],\n gap: 16,\n peek: 40,\n slideWidth: 'peek',\n snapType: 'proximity',\n dots: true,\n testId: 'carousel-loose',\n },\n};\n\nexport const OverflowContent: Story = {\n parameters: {\n docs: {\n description: { story: 'A longer strip with a wider peek — the common dashboard-cards overflow case.' },\n },\n },\n args: {\n ariaLabel: 'Overflowing dashboard cards',\n children: [...slides, ...slides],\n dots: true,\n gap: 24,\n peek: 56,\n slideWidth: 'peek',\n testId: 'carousel-overflow',\n },\n};\n\nexport const Autoplay: Story = {\n parameters: {\n docs: { description: { story: 'Auto-advancing with `loop`; hovering the strip pauses autoplay.' } },\n },\n args: {\n ariaLabel: 'Dashboard cards',\n autoplay: true,\n autoplayInterval: 2500,\n children: slides,\n dots: true,\n loop: true,\n testId: 'carousel-autoplay',\n },\n};\n"
},
"specification": {
"$schema": "../../../specs/component-spec.schema.json",
"identity": {
"name": "Carousel",
"status": "preview",
"version": "1.0.0",
"summary": "A horizontal snap carousel backed by native scroll-snap, with optional controls, dots, autoplay, loop, and peek."
},
"parts": [
{
"id": "root",
"label": "Root",
"description": "Region wrapper carrying gap, slide width, and snap settings. Structural container.",
"required": true
},
{
"id": "strip",
"label": "Strip",
"description": "Scrolling flex track that holds the slides."
},
{
"id": "item",
"label": "Item",
"description": "One snap slide sized by the slide width."
},
{
"id": "controls",
"label": "Controls",
"description": "Optional previous/next buttons over the strip."
},
{
"id": "dots",
"label": "Dots",
"description": "Optional pagination dots below the strip."
}
],
"allowedDesignChoices": {
"variants": {
"carousel": {
"label": "Carousel",
"description": "The single horizontal snap carousel."
}
},
"sizes": {},
"snapTypes": {
"mandatory": {
"label": "Mandatory",
"description": "Always rests on a card."
},
"proximity": {
"label": "Proximity",
"description": "Only snaps when a card is already close."
}
},
"snapStops": {
"normal": {
"label": "Normal",
"description": "Momentum can skip several cards."
},
"always": {
"label": "Always",
"description": "Each flick lands on the adjacent card."
}
},
"snapAlignments": {
"start": {
"label": "Start"
},
"center": {
"label": "Center"
},
"end": {
"label": "End"
}
},
"slideWidths": {
"full": {
"label": "Full",
"description": "One slide per view."
},
"peek": {
"label": "Peek",
"description": "Leaves room for the next card's edge. Besides full and peek, slideWidth also accepts an explicit CSS flex-basis value passed through unchanged."
}
}
},
"variants": [
{
"id": "carousel",
"label": "Carousel",
"description": "Horizontal snap carousel.",
"platforms": [
"ios",
"android",
"web"
]
}
],
"sizes": [],
"measurements": [
{
"id": "slide-gap",
"label": "Slide gap",
"kind": "example-only",
"token": "--cds-space-12",
"value": 12,
"unit": "px",
"appliesTo": [
"strip"
],
"notes": "Configurable: the default slide gap is 16 (--cds-space-16) and the prop accepts any step on the spacing scale. 12 is the representative value rendered by the controls story."
},
{
"id": "control-size",
"label": "Control button size",
"kind": "exact",
"token": "--cds-size-32",
"value": 32,
"unit": "px",
"appliesTo": [
"controls"
]
}
],
"layout": {
"alignment": "Slides align to the chosen snap edge; controls overlay the strip and dots sit below it.",
"flow": "A scrolling flex track of snap slides with optional overlaid controls and pagination dots.",
"notes": [
"Use HStack scroll for a plain non-snapping overflow row."
]
},
"typographyAndColor": {
"typography": [
{
"label": "Inherited",
"description": "Carousel sets no type; slides own their text. Ramp noted for parity.",
"token": "--cds-type-body-size"
}
],
"colors": [
{
"label": "Control surface",
"description": "Control buttons sit on the raised surface.",
"token": "--cds-bg-surface"
},
{
"label": "Active dot",
"description": "The active dot uses primary text color.",
"token": "--cds-text-primary"
},
{
"label": "Inactive dot",
"description": "Inactive dots use the divider color.",
"token": "--cds-divider"
}
]
},
"states": [
{
"id": "default",
"label": "Default",
"description": "Touch-scroll snap with no controls or dots."
},
{
"id": "controls",
"label": "Controls",
"description": "Previous/next buttons and dots enabled."
},
{
"id": "peek",
"label": "Peek",
"description": "Slides sized to reveal the next card's edge."
},
{
"id": "autoplay",
"label": "Autoplay",
"description": "Auto-advancing; hover, pointer interaction and focus within the carousel pause it."
}
],
"behavior": [
{
"label": "Snap feel",
"description": "snapType sets snap strength and snapStop sets per-card stopping."
},
{
"label": "Selection",
"description": "Scrolling updates the selected index; controls and dots also drive it."
}
],
"accessibility": [
{
"label": "Region",
"description": "The carousel is a role=region named by ariaLabel."
},
{
"label": "Control labels",
"description": "Previous, next, and dot controls carry accessible labels."
},
{
"label": "Keyboard reachability",
"description": "All slide content stays exposed to assistive technology. Tab reaches interactive descendants and native scrolling brings focused controls into view. Autoplay pauses while focus remains inside."
}
],
"contentAdaptation": [
{
"label": "Peek gutter",
"description": "slideWidth=peek with peek reveals the next card to signal more content."
},
{
"label": "Custom slide width",
"description": "Beyond full and peek, slideWidth accepts an explicit CSS flex-basis value passed through unchanged."
},
{
"label": "Single slide",
"description": "Controls and dots hide themselves when there is nothing to page to."
}
],
"motionHaptics": {
"motion": [
{
"label": "Snap scroll",
"description": "Native scroll-snap drives resting positions; control taps scroll smoothly."
}
],
"haptics": [
{
"label": "Selection haptic",
"description": "User-driven slide changes request the selection haptic."
}
]
},
"platformDifferences": []
},
"specification_source": "packages/design-system/src/components/layout/Carousel/Carousel.spec.json",
"guidance": {
"summary": "A horizontal snap carousel backed by native scroll-snap, with optional controls, dots, autoplay, loop, and peek.",
"guidance": [
{
"heading": "Overview",
"body": "Horizontal snap carousel backed by native CSS scroll-snap. Touch scroll works with zero props;\n`controls`, `dots`, `autoplay`, and `loop` are opt-in.\n\nInteractive content in every slide remains reachable by Tab and Enter; native scrolling brings\nfocused controls into view. Autoplay pauses while focus is inside the carousel, as well as during\npointer interaction or hover. Provide `ariaLabel` to name the region."
},
{
"heading": "When to use",
"body": "Reach for `Carousel` when content is **paged horizontally, one (or one-plus-a-peek) card per\nview** — dashboard stat cards, an onboarding walkthrough, a news strip. The snap feel comes from\n`snapType` (`mandatory` always rests on a card vs `proximity` for looser free-scroll) and\n`snapStop` (`always` is magnetic, one card per flick, vs `normal` which lets momentum skip\nseveral). Set `slideWidth=\"peek\"` with `peek` to reveal the next card.\n\n- Just need a **plain overflowing row** with no snapping? Use `HStack` with `scroll`.\n- Laying out tiles in a **static grid** rather than a swipeable strip? Use `Grid`."
}
],
"usage": [],
"examples": [],
"source": "packages/design-system/src/components/layout/Carousel/Carousel.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-carousel",
"json": "/data/visual/components/carousel.json",
"storybook": "/storybook/?path=/story/cloaked-design-system-layout-carousel--playground"
}
}