{
  "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",
  "summary": "A horizontal snap carousel backed by native scroll-snap, with optional controls, dots, autoplay, loop, and peek.",
  "documentation": {
    "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."
  },
  "source": {
    "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
    "code": "import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { cn } from '../../../utilities';\nimport { useHaptic } from '../../../hooks/useHaptic';\nimport type { HapticFeedback } from '../../../tokens/CdsHaptic';\nimport type { CdsSpace } from '../../../tokens/CdsSpace';\nimport { Icon } from '../../primitives/Icon/Icon';\nimport { buildCarouselStyle, getChildTestId, clampIndex, getNextSlideIndex, scrollToSlide } from './carouselUtils';\nimport type { CarouselSlideWidth } from './carouselUtils';\nimport { useCarouselHorizontalGestureGuard } from './useCarouselHorizontalGestureGuard';\nimport { useCarouselInteractionGuards } from './useCarouselInteractionGuards';\nimport { useCarouselScrollSelection } from './useCarouselScrollSelection';\nimport styles from './Carousel.module.scss';\n\nexport type CarouselSnapAlign = 'start' | 'center' | 'end';\n/** Snap strength: `mandatory` always rests on a card, `proximity` only snaps when already close. */\nexport type CarouselSnapType = 'mandatory' | 'proximity';\n/** Per-card snap stop: `always` lands every flick on the adjacent card, `normal` lets momentum pass several. */\nexport type CarouselSnapStop = 'normal' | 'always';\nexport type { CarouselSlideWidth } from './carouselUtils';\n\n/**\n * Props for `Carousel`. Each child is one slide. Selection stays uncontrolled unless `selectedIndex`\n * is passed, and every layout prop below feeds native scroll snap rather than a JS animation.\n */\nexport interface CarouselProps {\n    children: React.ReactNode;\n    /** Space between slides, in `--cds-space-*` steps. */\n    gap?: CdsSpace;\n    /** Enables native CSS scroll snap. Defaults to `true`. */\n    snap?: boolean;\n    /** Snap strength. Defaults to `mandatory`; use `proximity` for looser, free-er scrolling. */\n    snapType?: CarouselSnapType;\n    /** Hard snap stop per card. Defaults to `normal`; `always` is more magnetic — each swipe lands on the neighbor. */\n    snapStop?: CarouselSnapStop;\n    /** Snap alignment for each slide. Defaults to `start`. */\n    snapAlign?: CarouselSnapAlign;\n    /** Slide width. `peek` leaves room for the configured next-card peek. Defaults to `full`. */\n    slideWidth?: CarouselSlideWidth;\n    /** Visible next-card width when `slideWidth='peek'`, in `--cds-space-*` steps. */\n    peek?: CdsSpace;\n    /** Cancels one page gutter so the strip bleeds to the screen edges while items stay aligned to the gutter. */\n    fullBleed?: boolean;\n    /** Leading/trailing inset on the scroll strip, in `--cds-space-*` steps (snap-aware edge bleed). */\n    inset?: CdsSpace;\n    /** Shows pagination dots below the strip. */\n    dots?: boolean;\n    /** Shows previous/next controls over the strip. */\n    controls?: boolean;\n    /** Automatically advances slides, pausing while hovered, interacting or focused within. Defaults to `false`. */\n    autoplay?: boolean;\n    /** Autoplay interval in milliseconds. Defaults to `3000`. */\n    autoplayInterval?: number;\n    /** Wraps previous/next/autoplay around both ends. */\n    loop?: boolean;\n    /** Controlled selected slide index. */\n    selectedIndex?: number;\n    /** Initial selected slide index for uncontrolled usage. */\n    defaultSelectedIndex?: number;\n    /** Fires on every selection change — swipe, control, dot, or autoplay — controlled or not. */\n    onSelectedIndexChange?: (index: number) => void;\n    /** Haptic feedback for user-driven slide changes. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    /** Accessible label for the carousel region. */\n    ariaLabel?: string;\n    className?: string;\n    style?: React.CSSProperties;\n    /**\n     * Root selector. Children derive from it: `-strip`, `-previous`/`-next`, `-item-${index}`, and\n     * `-dot-${index}`.\n     */\n    testId?: string;\n}\n\nconst DEFAULT_AUTOPLAY_INTERVAL = 3000;\n\n/**\n * Horizontal carousel backed by native scroll snap; controls, dots, autoplay, and loop stay prop-driven.\n */\nexport function Carousel({\n    children,\n    gap = 16,\n    snap = true,\n    snapType = 'mandatory',\n    snapStop = 'normal',\n    snapAlign = 'start',\n    slideWidth = 'full',\n    peek = 40,\n    fullBleed = false,\n    inset = 0,\n    dots = false,\n    controls = false,\n    autoplay = false,\n    autoplayInterval = DEFAULT_AUTOPLAY_INTERVAL,\n    loop = false,\n    selectedIndex,\n    defaultSelectedIndex = 0,\n    onSelectedIndexChange,\n    haptic = true,\n    ariaLabel,\n    className,\n    style,\n    testId,\n}: CarouselProps) {\n    const slides = useMemo(() => React.Children.toArray(children), [children]);\n    const maxIndex = Math.max(slides.length - 1, 0);\n    const isControlled = selectedIndex !== undefined;\n    const [uncontrolledIndex, setUncontrolledIndex] = useState(() => clampIndex(defaultSelectedIndex, maxIndex));\n    const [focusWithin, setFocusWithin] = useState(false);\n    const selected = clampIndex(selectedIndex ?? uncontrolledIndex, maxIndex);\n    // Mirrors the selected index so setIndex and the autoplay interval stay stable across slide changes.\n    const previousSelectedRef = useRef(selected);\n    const stripRef = useRef<HTMLDivElement>(null);\n    const itemRefs = useRef<Array<HTMLDivElement | null>>([]);\n    const fireHaptic = useHaptic('selection');\n    const {\n        endPointerInteraction,\n        markProgrammaticScroll,\n        paused,\n        setPaused,\n        shouldFireObservedScrollHaptic,\n        startUserInteraction,\n    } = useCarouselInteractionGuards();\n\n    // Returns whether selection moved; useCarouselScrollSelection uses it to fire one haptic per gesture.\n    const setIndex = useCallback(\n        (nextIndex: number, options?: { feedback?: boolean; scroll?: boolean }) => {\n            const next = clampIndex(nextIndex, maxIndex);\n            if (next === previousSelectedRef.current) return false;\n            previousSelectedRef.current = next;\n            if (!isControlled) setUncontrolledIndex(next);\n            if (options?.feedback) fireHaptic(haptic);\n            onSelectedIndexChange?.(next);\n            if (options?.scroll) {\n                markProgrammaticScroll();\n                scrollToSlide(stripRef.current, itemRefs.current[next]);\n            }\n            return true;\n        },\n        [fireHaptic, haptic, isControlled, markProgrammaticScroll, maxIndex, onSelectedIndexChange]\n    );\n\n    useEffect(() => {\n        if (!isControlled) return;\n        previousSelectedRef.current = selected;\n        markProgrammaticScroll();\n        scrollToSlide(stripRef.current, itemRefs.current[selected], 'auto');\n    }, [isControlled, markProgrammaticScroll, selected]);\n\n    useEffect(() => {\n        if (!autoplay || paused || focusWithin || slides.length <= 1) return;\n        const timer = window.setInterval(() => {\n            setIndex(getNextSlideIndex(previousSelectedRef.current, maxIndex, 1, loop), { scroll: true });\n        }, autoplayInterval);\n        return () => window.clearInterval(timer);\n    }, [autoplay, autoplayInterval, focusWithin, loop, maxIndex, paused, setIndex, slides.length]);\n\n    useCarouselScrollSelection({\n        itemRefs,\n        setIndex,\n        shouldFireObservedScrollHaptic,\n        slideCount: slides.length,\n        stripRef,\n    });\n    useCarouselHorizontalGestureGuard({ stripRef });\n\n    const canMoveBack = loop || selected > 0;\n    const canMoveForward = loop || selected < maxIndex;\n    const carouselStyle = buildCarouselStyle(gap, slideWidth, peek, inset, style);\n\n    return (\n        <div\n            className={cn(styles.carousel, fullBleed && styles.fullBleed, className)}\n            style={carouselStyle}\n            role='region'\n            aria-label={ariaLabel}\n            data-testid={testId}\n            onMouseEnter={() => setPaused(true)}\n            onMouseLeave={() => setPaused(false)}\n            onFocusCapture={() => setFocusWithin(true)}\n            onBlurCapture={event => {\n                if (!event.currentTarget.contains(event.relatedTarget)) setFocusWithin(false);\n            }}\n            onPointerDown={startUserInteraction}\n            onPointerUp={endPointerInteraction}\n            onPointerLeave={endPointerInteraction}\n            onPointerCancel={endPointerInteraction}\n        >\n            <div\n                ref={stripRef}\n                className={cn(styles.strip, snap && styles[`snap-${snapType}`])}\n                data-testid={getChildTestId(testId, 'strip')}\n            >\n                {/* Native scrolling can show several slides; keep their controls exposed to keyboard and assistive technology. */}\n                {slides.map((child, index) => (\n                    <div\n                        key={React.isValidElement(child) && child.key != null ? child.key : index}\n                        ref={node => {\n                            itemRefs.current[index] = node;\n                        }}\n                        className={styles.item}\n                        style={{ scrollSnapAlign: snapAlign, scrollSnapStop: snapStop }}\n                        data-testid={getChildTestId(testId, `item-${index}`)}\n                    >\n                        {child}\n                    </div>\n                ))}\n            </div>\n\n            {controls && slides.length > 1 && (\n                <div className={styles.controls} aria-hidden='false'>\n                    <button\n                        type='button'\n                        className={cn(styles.control, styles.previous)}\n                        onClick={() =>\n                            setIndex(getNextSlideIndex(selected, maxIndex, -1, loop), { feedback: true, scroll: true })\n                        }\n                        disabled={!canMoveBack}\n                        aria-label='Previous slide'\n                        data-testid={getChildTestId(testId, 'previous')}\n                    >\n                        <Icon name='arrow-left' size='small' />\n                    </button>\n                    <button\n                        type='button'\n                        className={cn(styles.control, styles.next)}\n                        onClick={() =>\n                            setIndex(getNextSlideIndex(selected, maxIndex, 1, loop), { feedback: true, scroll: true })\n                        }\n                        disabled={!canMoveForward}\n                        aria-label='Next slide'\n                        data-testid={getChildTestId(testId, 'next')}\n                    >\n                        <Icon name='arrow-right' size='small' />\n                    </button>\n                </div>\n            )}\n\n            {dots && slides.length > 1 && (\n                <div className={styles.dots} aria-label='Carousel pagination'>\n                    {slides.map((_, index) => (\n                        <button\n                            key={index}\n                            type='button'\n                            className={cn(styles.dot, index === selected && styles.dotActive)}\n                            onClick={() => setIndex(index, { feedback: true, scroll: true })}\n                            aria-label={`Go to slide ${index + 1}`}\n                            aria-current={index === selected ? 'true' : undefined}\n                            data-testid={getChildTestId(testId, `dot-${index}`)}\n                        />\n                    ))}\n                </div>\n            )}\n        </div>\n    );\n}\n"
  },
  "spec": {
    "$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": []
  },
  "spec_source": "packages/design-system/src/components/layout/Carousel/Carousel.spec.json",
  "guidance_source": {
    "path": "packages/design-system/src/components/layout/Carousel/Carousel.mdx",
    "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './Carousel.stories';\nimport carouselSpec from './Carousel.spec.json';\n\n<Meta of={Stories} />\n\n# Carousel\n\nHorizontal 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.\n\n<Canvas of={Stories.Playground} />\n\n## When to use\n\nReach 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`.\n\n<Canvas of={Stories.Peek} />\n\n## Design Guidelines\n\n<ComponentSpec spec={carouselSpec} />\n\n## Props\n\n<Controls of={Stories.Playground} />\n"
  },
  "props": [
    {
      "name": "children",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 26
      }
    },
    {
      "name": "gap",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Space between slides, in `--cds-space-*` steps.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 28
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true,
      "default": "16",
      "default_kind": "source-expression"
    },
    {
      "name": "snap",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Enables native CSS scroll snap. Defaults to `true`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 30
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "snapType",
      "type": "CarouselSnapType | undefined",
      "declared_type": "CarouselSnapType",
      "required": false,
      "description": "Snap strength. Defaults to `mandatory`; use `proximity` for looser, free-er scrolling.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 32
      },
      "values": [
        "mandatory",
        "proximity"
      ],
      "values_complete": true,
      "default": "'mandatory'",
      "default_kind": "source-expression"
    },
    {
      "name": "snapStop",
      "type": "CarouselSnapStop | undefined",
      "declared_type": "CarouselSnapStop",
      "required": false,
      "description": "Hard snap stop per card. Defaults to `normal`; `always` is more magnetic — each swipe lands on the neighbor.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 34
      },
      "values": [
        "always",
        "normal"
      ],
      "values_complete": true,
      "default": "'normal'",
      "default_kind": "source-expression"
    },
    {
      "name": "snapAlign",
      "type": "CarouselSnapAlign | undefined",
      "declared_type": "CarouselSnapAlign",
      "required": false,
      "description": "Snap alignment for each slide. Defaults to `start`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 36
      },
      "values": [
        "center",
        "end",
        "start"
      ],
      "values_complete": true,
      "default": "'start'",
      "default_kind": "source-expression"
    },
    {
      "name": "slideWidth",
      "type": "CarouselSlideWidth",
      "declared_type": "CarouselSlideWidth",
      "required": false,
      "description": "Slide width. `peek` leaves room for the configured next-card peek. Defaults to `full`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 38
      },
      "default": "'full'",
      "default_kind": "source-expression"
    },
    {
      "name": "peek",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Visible next-card width when `slideWidth='peek'`, in `--cds-space-*` steps.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 40
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true,
      "default": "40",
      "default_kind": "source-expression"
    },
    {
      "name": "fullBleed",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Cancels one page gutter so the strip bleeds to the screen edges while items stay aligned to the gutter.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 42
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "inset",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Leading/trailing inset on the scroll strip, in `--cds-space-*` steps (snap-aware edge bleed).",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 44
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true,
      "default": "0",
      "default_kind": "source-expression"
    },
    {
      "name": "dots",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Shows pagination dots below the strip.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 46
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "controls",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Shows previous/next controls over the strip.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 48
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "autoplay",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Automatically advances slides, pausing while hovered, interacting or focused within. Defaults to `false`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 50
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "autoplayInterval",
      "type": "number | undefined",
      "declared_type": "number",
      "required": false,
      "description": "Autoplay interval in milliseconds. Defaults to `3000`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 52
      },
      "default": "DEFAULT_AUTOPLAY_INTERVAL",
      "default_kind": "source-expression"
    },
    {
      "name": "loop",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Wraps previous/next/autoplay around both ends.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 54
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "selectedIndex",
      "type": "number | undefined",
      "declared_type": "number",
      "required": false,
      "description": "Controlled selected slide index.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 56
      }
    },
    {
      "name": "defaultSelectedIndex",
      "type": "number | undefined",
      "declared_type": "number",
      "required": false,
      "description": "Initial selected slide index for uncontrolled usage.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 58
      },
      "default": "0",
      "default_kind": "source-expression"
    },
    {
      "name": "onSelectedIndexChange",
      "type": "((index: number) => void) | undefined",
      "declared_type": "(index: number) => void",
      "required": false,
      "description": "Fires on every selection change — swipe, control, dot, or autoplay — controlled or not.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 60
      }
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for user-driven slide changes. Defaults to `true` (`selection`).",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 62
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible label for the carousel region.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 64
      }
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 65
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 66
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Root selector. Children derive from it: `-strip`, `-previous`/`-next`, `-item-${index}`, and\n`-dot-${index}`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 71
      }
    }
  ],
  "prop_shapes": {},
  "examples": [],
  "tokens": [
    {
      "name": "--cds-space-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-size-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-divider",
      "light": "#e0ddd6",
      "dark": "#ffffff1a"
    }
  ],
  "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": [
    {
      "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"
    }
  ],
  "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    <Card key={title} surface={index === 1 ? 'highlight' : 'default'}>\n        <Card.Body gap='sm'>\n            <Text variant='h4'>{title}</Text>\n            <Text variant='body-small' color='secondary'>\n                Swipe between cards or use optional controls and dots.\n            </Text>\n        </Card.Body>\n    </Card>\n));\n\nconst meta: Meta<typeof Carousel> = {\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<typeof Carousel>;\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"
  },
  "links": {
    "human": "/component-carousel",
    "json": "/data/components/carousel.json",
    "markdown": "/data/components/carousel.md",
    "storybook": "/storybook/?path=/story/cloaked-design-system-layout-carousel--playground"
  },
  "contract_status": "preview",
  "contract_kind": "source-derived",
  "approval": "required",
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Carousel",
    "public_path": "Carousel",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Carousel",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
          "line": 79
        },
        "props_type": "CarouselProps",
        "props": [
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 26
            }
          },
          {
            "name": "gap",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Space between slides, in `--cds-space-*` steps.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 28
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true,
            "default": "16",
            "default_kind": "source-expression"
          },
          {
            "name": "snap",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Enables native CSS scroll snap. Defaults to `true`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 30
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "snapType",
            "type": "CarouselSnapType | undefined",
            "declared_type": "CarouselSnapType",
            "required": false,
            "description": "Snap strength. Defaults to `mandatory`; use `proximity` for looser, free-er scrolling.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 32
            },
            "values": [
              "mandatory",
              "proximity"
            ],
            "values_complete": true,
            "default": "'mandatory'",
            "default_kind": "source-expression"
          },
          {
            "name": "snapStop",
            "type": "CarouselSnapStop | undefined",
            "declared_type": "CarouselSnapStop",
            "required": false,
            "description": "Hard snap stop per card. Defaults to `normal`; `always` is more magnetic — each swipe lands on the neighbor.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 34
            },
            "values": [
              "always",
              "normal"
            ],
            "values_complete": true,
            "default": "'normal'",
            "default_kind": "source-expression"
          },
          {
            "name": "snapAlign",
            "type": "CarouselSnapAlign | undefined",
            "declared_type": "CarouselSnapAlign",
            "required": false,
            "description": "Snap alignment for each slide. Defaults to `start`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 36
            },
            "values": [
              "center",
              "end",
              "start"
            ],
            "values_complete": true,
            "default": "'start'",
            "default_kind": "source-expression"
          },
          {
            "name": "slideWidth",
            "type": "CarouselSlideWidth",
            "declared_type": "CarouselSlideWidth",
            "required": false,
            "description": "Slide width. `peek` leaves room for the configured next-card peek. Defaults to `full`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 38
            },
            "default": "'full'",
            "default_kind": "source-expression"
          },
          {
            "name": "peek",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Visible next-card width when `slideWidth='peek'`, in `--cds-space-*` steps.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 40
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true,
            "default": "40",
            "default_kind": "source-expression"
          },
          {
            "name": "fullBleed",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Cancels one page gutter so the strip bleeds to the screen edges while items stay aligned to the gutter.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 42
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "inset",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Leading/trailing inset on the scroll strip, in `--cds-space-*` steps (snap-aware edge bleed).",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 44
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true,
            "default": "0",
            "default_kind": "source-expression"
          },
          {
            "name": "dots",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Shows pagination dots below the strip.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 46
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "controls",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Shows previous/next controls over the strip.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 48
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "autoplay",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Automatically advances slides, pausing while hovered, interacting or focused within. Defaults to `false`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 50
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "autoplayInterval",
            "type": "number | undefined",
            "declared_type": "number",
            "required": false,
            "description": "Autoplay interval in milliseconds. Defaults to `3000`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 52
            },
            "default": "DEFAULT_AUTOPLAY_INTERVAL",
            "default_kind": "source-expression"
          },
          {
            "name": "loop",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Wraps previous/next/autoplay around both ends.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 54
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "selectedIndex",
            "type": "number | undefined",
            "declared_type": "number",
            "required": false,
            "description": "Controlled selected slide index.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 56
            }
          },
          {
            "name": "defaultSelectedIndex",
            "type": "number | undefined",
            "declared_type": "number",
            "required": false,
            "description": "Initial selected slide index for uncontrolled usage.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 58
            },
            "default": "0",
            "default_kind": "source-expression"
          },
          {
            "name": "onSelectedIndexChange",
            "type": "((index: number) => void) | undefined",
            "declared_type": "(index: number) => void",
            "required": false,
            "description": "Fires on every selection change — swipe, control, dot, or autoplay — controlled or not.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 60
            }
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for user-driven slide changes. Defaults to `true` (`selection`).",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 62
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible label for the carousel region.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 64
            }
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 65
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 66
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Root selector. Children derive from it: `-strip`, `-previous`/`-next`, `-item-${index}`, and\n`-dot-${index}`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
              "line": 71
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 14,
        "name": "CarouselSnapAlign",
        "code": "export type CarouselSnapAlign = 'start' | 'center' | 'end';"
      },
      {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 16,
        "name": "CarouselSnapType",
        "code": "export type CarouselSnapType = 'mandatory' | 'proximity';"
      },
      {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 18,
        "name": "CarouselSnapStop",
        "code": "export type CarouselSnapStop = 'normal' | 'always';"
      },
      {
        "path": "packages/design-system/src/components/layout/Carousel/Carousel.tsx",
        "line": 25,
        "name": "CarouselProps",
        "code": "export interface CarouselProps {\n    children: React.ReactNode;\n    /** Space between slides, in `--cds-space-*` steps. */\n    gap?: CdsSpace;\n    /** Enables native CSS scroll snap. Defaults to `true`. */\n    snap?: boolean;\n    /** Snap strength. Defaults to `mandatory`; use `proximity` for looser, free-er scrolling. */\n    snapType?: CarouselSnapType;\n    /** Hard snap stop per card. Defaults to `normal`; `always` is more magnetic — each swipe lands on the neighbor. */\n    snapStop?: CarouselSnapStop;\n    /** Snap alignment for each slide. Defaults to `start`. */\n    snapAlign?: CarouselSnapAlign;\n    /** Slide width. `peek` leaves room for the configured next-card peek. Defaults to `full`. */\n    slideWidth?: CarouselSlideWidth;\n    /** Visible next-card width when `slideWidth='peek'`, in `--cds-space-*` steps. */\n    peek?: CdsSpace;\n    /** Cancels one page gutter so the strip bleeds to the screen edges while items stay aligned to the gutter. */\n    fullBleed?: boolean;\n    /** Leading/trailing inset on the scroll strip, in `--cds-space-*` steps (snap-aware edge bleed). */\n    inset?: CdsSpace;\n    /** Shows pagination dots below the strip. */\n    dots?: boolean;\n    /** Shows previous/next controls over the strip. */\n    controls?: boolean;\n    /** Automatically advances slides, pausing while hovered, interacting or focused within. Defaults to `false`. */\n    autoplay?: boolean;\n    /** Autoplay interval in milliseconds. Defaults to `3000`. */\n    autoplayInterval?: number;\n    /** Wraps previous/next/autoplay around both ends. */\n    loop?: boolean;\n    /** Controlled selected slide index. */\n    selectedIndex?: number;\n    /** Initial selected slide index for uncontrolled usage. */\n    defaultSelectedIndex?: number;\n    /** Fires on every selection change — swipe, control, dot, or autoplay — controlled or not. */\n    onSelectedIndexChange?: (index: number) => void;\n    /** Haptic feedback for user-driven slide changes. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    /** Accessible label for the carousel region. */\n    ariaLabel?: string;\n    className?: string;\n    style?: React.CSSProperties;\n    /**\n     * Root selector. Children derive from it: `-strip`, `-previous`/`-next`, `-item-${index}`, and\n     * `-dot-${index}`.\n     */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/layout/Carousel/carouselUtils.ts",
        "line": 4,
        "name": "CarouselSlideWidth",
        "code": "export type CarouselSlideWidth = 'full' | 'peek' | React.CSSProperties['flexBasis'];"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/CdsSpace.ts",
        "line": 8,
        "name": "PUI_SPACES",
        "code": "PUI_SPACES = [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 120, 240] as const"
      },
      {
        "path": "packages/design-system/src/tokens/CdsSpace.ts",
        "line": 13,
        "name": "CdsSpace",
        "code": "export type CdsSpace = (typeof PUI_SPACES)[number];"
      },
      {
        "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."
  },
  "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"
    }
  },
  "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."
    }
  ],
  "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."
  }
}