# Carousel

A horizontal snap carousel backed by native scroll-snap, with optional controls, dots, autoplay, loop, and peek.

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

## 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."
}

## Contract and public API

```json
{
  "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": {},
  "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."
  },
  "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": []
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-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"
    }
  ],
  "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."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

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

- [Single Slide](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--single-slide&viewMode=story) | export: SingleSlide | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

- [With Controls And Dots](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--with-controls-and-dots&viewMode=story) | export: WithControlsAndDots | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

- [Peek](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--peek&viewMode=story) | export: Peek | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

- [Magnetic](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--magnetic&viewMode=story) | export: Magnetic | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

- [Loose](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--loose&viewMode=story) | export: Loose | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

- [Overflow Content](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--overflow-content&viewMode=story) | export: OverflowContent | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

- [Autoplay](/storybook/iframe.html?id=cloaked-design-system-layout-carousel--autoplay&viewMode=story) | export: Autoplay | source: packages/design-system/src/components/layout/Carousel/Carousel.stories.tsx

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