@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/breadcrumb.md

@@ -0,0 +1,106 @@
+# Breadcrumb
+
+**Category:** navigation  
+**Description:** Shows the current page location within a navigation hierarchy
+
+## When to use
+
+- Showing the user where the current page sits in a navigation hierarchy
+- Providing one-click navigation back to ancestor pages
+- Collapsing deep trails to keep the trail compact (maxVisible)
+
+## When NOT to use
+
+- Paging through data records — use Pagination
+- Switching between sibling views — use Tabs
+
+## Anti-patterns
+
+### Breadcrumb models hierarchy depth, not sequential position in a list
+
+**Bad:** `Using Breadcrumb to step through pages 1, 2, 3 of a dataset`  
+**Good:** `<Pagination> for paged data`  
+**Why:** Breadcrumb models hierarchy depth, not sequential position in a list
+
+## Related components
+
+- **Pagination** (alternative): Pagination moves through data pages; Breadcrumb moves up a hierarchy
+
+## Accessibility rationale
+
+Wrapped in <nav> with an aria-label and the current page marked aria-current="page"; ancestor entries are real links so keyboard users can jump up the hierarchy
+
+## Props
+
+| Name         | Type                                 | Required | Default    | Description                                                                                   |
+| ------------ | ------------------------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------- |
+| `items`      | `{ label: string; href?: string }[]` | Yes      | —          | The items to render.                                                                          |
+| `maxVisible` | `number`                             | No       | —          | When items exceed this count, collapse to the first item, an ellipsis, and the trailing items |
+| `className`  | `string`                             | No       | —          | Additional CSS class names merged onto the root element.                                      |
+| `ariaLabel`  | `string`                             | No       | Breadcrumb | Accessible label for the component.                                                           |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-text-subtle`
+- `--cascivo-radius-sm`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Breadcrumb
+  items={[{ label: 'Home', href: '/' }, { label: 'Docs', href: '/docs' }, { label: 'Breadcrumb' }]}
+/>
+```
+
+### Collapsed
+
+Long trails collapse to the first item, an ellipsis, and the trailing items.
+
+```jsx
+<Breadcrumb
+  maxVisible={3}
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Docs', href: '/docs' },
+    { label: 'Components', href: '/docs/components' },
+    { label: 'Breadcrumb' },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                           |
+| ----------- | -------- | -------------------------------------------------------------- |
+| maxVisible  | flexible | Collapse long trails to fit available width                    |
+| token names | strict   | Text colors and focus ring must resolve to --cascivo-\* tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Breadcrumb component (navigation). Shows the current page location within a navigation hierarchy
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Breadcrumb is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-text-subtle, --cascivo-radius-sm, --cascivo-focus-ring
+
+Accessibility: role "navigation", WCAG 2.2-AA, keyboard: Tab/Enter. Keep it AA.
+
+Do not change (strict): token names — Text colors and focus ring must resolve to --cascivo-* tokens
+Flexible: maxVisible.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/button-group.md

@@ -0,0 +1,100 @@
+# ButtonGroup
+
+**Category:** inputs  
+**Description:** Visually joins a set of related buttons into a single segmented control
+
+## When to use
+
+- Presenting several related, independent actions that read as one control (e.g. an editor toolbar)
+- Visually grouping buttons that share context without implying mutual exclusivity
+
+## When NOT to use
+
+- The buttons represent a single selected value among options — use ToggleGroup
+- The actions are unrelated and should read as separate buttons — lay them out with spacing instead
+
+## Anti-patterns
+
+### A group with no accessible name is announced as an unlabeled region; supply aria-label or aria-labelledby
+
+**Bad:** `<ButtonGroup><Button>Bold</Button><Button>Italic</Button></ButtonGroup>`  
+**Good:** `<ButtonGroup aria-label="Formatting"><Button>Bold</Button><Button>Italic</Button></ButtonGroup>`  
+**Why:** A group with no accessible name is announced as an unlabeled region; supply aria-label or aria-labelledby
+
+## Related components
+
+- **ToggleGroup** (alternative): Use when the buttons select a value rather than fire independent actions
+- **Button** (contains): A button group is a layout container for buttons
+
+## Accessibility rationale
+
+Exposes role="group" so assistive tech treats the buttons as one labeled set; optional roving focus lets arrow keys traverse the buttons as a single tab stop, matching toolbar expectations
+
+## Props
+
+| Name              | Type                         | Required | Default    | Description                                                               |
+| ----------------- | ---------------------------- | -------- | ---------- | ------------------------------------------------------------------------- |
+| `orientation`     | `'horizontal' \| 'vertical'` | No       | horizontal | Layout orientation of the component.                                      |
+| `size`            | `'sm' \| 'md' \| 'lg'`       | No       | md         | Visual size of the component (e.g. 'sm', 'md', 'lg').                     |
+| `roving`          | `boolean`                    | No       | false      | When true, uses roving tabindex so arrow keys move focus between buttons. |
+| `loop`            | `boolean`                    | No       | false      | When true, navigation wraps around from end to start.                     |
+| `aria-label`      | `string`                     | No       | —          | Accessible label used when no visible label is present.                   |
+| `aria-labelledby` | `string`                     | No       | —          | Id of the element that labels this component.                             |
+
+## Tokens
+
+- `--cascivo-button-radius`
+- `--cascivo-radius-control`
+
+## Examples
+
+### Joined actions
+
+```jsx
+<ButtonGroup aria-label="Text alignment">
+  <Button>Left</Button>
+  <Button>Center</Button>
+  <Button>Right</Button>
+</ButtonGroup>
+```
+
+### Vertical with roving focus
+
+```jsx
+<ButtonGroup orientation="vertical" roving aria-label="View">
+  <Button>List</Button>
+  <Button>Grid</Button>
+</ButtonGroup>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                                               |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| token names | strict   | Outer corner radius must resolve to --cascivo-button-radius / --cascivo-radius-control to match standalone buttons |
+| children    | flexible | Any focusable controls (Button, IconButton, links) may be grouped                                                  |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ButtonGroup component (inputs). Visually joins a set of related buttons into a single segmented control
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+ButtonGroup is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-button-radius, --cascivo-radius-control
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: ArrowRight/ArrowLeft/ArrowUp/ArrowDown/Home/End. Keep it AA.
+
+Do not change (strict): token names — Outer corner radius must resolve to --cascivo-button-radius / --cascivo-radius-control to match standalone buttons
+Flexible: children.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/button.md

@@ -0,0 +1,117 @@
+# Button
+
+**Category:** inputs  
+**Description:** Triggers an action or event
+
+## When to use
+
+- Triggering an action or navigation the user initiates by click/press
+- Submitting a form or confirming a decision
+
+## When NOT to use
+
+- Navigation between pages where a real link is semantically correct — use an anchor
+- Toggling a binary setting — use Toggle; persistent selection — use Checkbox/Radio
+
+## Anti-patterns
+
+### Buttons are for actions, links for navigation — assistive tech and the browser treat them differently
+
+**Bad:** `<Button onClick={() => navigate("/x")}>Home</Button>`  
+**Good:** `<a href="/x">Home</a>`  
+**Why:** Buttons are for actions, links for navigation — assistive tech and the browser treat them differently
+
+## Related components
+
+- **Toggle** (alternative): Use for binary on/off state, not one-shot actions
+- **Dropdown** (pairs-with): A button often triggers a menu
+
+## Accessibility rationale
+
+Renders a native <button> so Enter/Space activation, focus, and role come from the platform; loading state uses aria-busy rather than removing the element so focus is preserved
+
+## Props
+
+| Name       | Type                                                   | Required | Default | Description                                                                                       |
+| ---------- | ------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `variant`  | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | No       | primary | Selects the visual style variant.                                                                 |
+| `size`     | `'sm' \| 'md' \| 'lg'`                                 | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').                                             |
+| `loading`  | `boolean`                                              | No       | false   | When true, shows a loading state.                                                                 |
+| `disabled` | `boolean`                                              | No       | false   | When true, disables the control and removes it from the tab order.                                |
+| `asChild`  | `boolean`                                              | No       | false   | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
+| `onClick`  | `React.MouseEventHandler<HTMLButtonElement>`           | No       | —       | Called when the element is clicked.                                                               |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-hover`
+- `--cascivo-color-accent-active`
+- `--cascivo-color-text-on-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-radius-button`
+- `--cascivo-focus-ring`
+- `--cascivo-disabled-opacity`
+- `--cascivo-text-ui`
+- `--cascivo-text-body`
+
+## Examples
+
+### Primary
+
+```jsx
+<Button>Click me</Button>
+```
+
+### Loading
+
+```jsx
+<Button loading>Saving…</Button>
+```
+
+### Destructive
+
+```jsx
+<Button variant="destructive">Delete</Button>
+```
+
+### As link
+
+Render button styling on a real anchor (keeps middle-click / open-in-new-tab).
+
+```jsx
+<Button asChild>
+  <a href="/pricing">View pricing</a>
+</Button>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                               |
+| ----------- | -------- | ------------------------------------------------------------------ |
+| token names | strict   | Visual props must resolve to --cascivo-button-\* / semantic tokens |
+| label copy  | flexible | Free, within tone guidance                                         |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Button component (inputs). Triggers an action or event
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Button is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-accent-hover, --cascivo-color-accent-active, --cascivo-color-text-on-accent, --cascivo-color-destructive, --cascivo-radius-button, --cascivo-focus-ring, --cascivo-disabled-opacity, --cascivo-text-ui, --cascivo-text-body
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): token names — Visual props must resolve to --cascivo-button-* / semantic tokens
+Flexible: label copy.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/calendar.md

@@ -0,0 +1,118 @@
+# Calendar
+
+**Category:** inputs  
+**Description:** An accessible standalone month-grid date picker.
+
+## When to use
+
+- Showing an always-visible month grid for picking a single date (inline, not a popover)
+- As the building block inside a date-picker or date-range-picker popover
+
+## When NOT to use
+
+- A compact form field where an inline grid wastes space — use DatePicker (trigger + popover)
+- Selecting a contiguous date range — use DateRangePicker, which composes two calendars
+
+## Anti-patterns
+
+### Local-time construction can land a midnight date on the previous day in negative-offset zones, breaking selection and range math
+
+**Bad:** `Comparing dates with local-time getters (getHours/getDate) after constructing them with new Date(y, m, d)`  
+**Good:** `All arithmetic and comparisons use UTC getters/Date.UTC so DST and timezone offsets never shift a day`  
+**Why:** Local-time construction can land a midnight date on the previous day in negative-offset zones, breaking selection and range math
+
+## Related components
+
+- **DatePicker** (alternative): Use the popover-based picker when an inline grid is too heavy for the layout
+- **DateRangePicker** (contained-by): The range picker renders two Calendar instances side-by-side
+
+## Accessibility rationale
+
+Renders an APG-compliant role="grid" table with role="row"/role="gridcell"; a roving tabindex keeps exactly one day focusable (the focused date) so arrow keys move focus per APG, Home/End jump to the week edges, PageUp/PageDown change month (with Shift for year), today exposes aria-current="date", selection sets data-selected with aria-selected on the cell, and out-of-range or predicate-disabled days get aria-disabled and are skipped by selection
+
+## Props
+
+| Name            | Type                                              | Required | Default | Description                                              |
+| --------------- | ------------------------------------------------- | -------- | ------- | -------------------------------------------------------- |
+| `value`         | `Date \| null`                                    | No       | —       | Controlled selected date                                 |
+| `defaultValue`  | `Date`                                            | No       | —       | Uncontrolled initial selected date                       |
+| `onValueChange` | `(date: Date) => void`                            | No       | —       | Called when a day is selected                            |
+| `min`           | `Date`                                            | No       | —       | Earliest selectable date                                 |
+| `max`           | `Date`                                            | No       | —       | Latest selectable date                                   |
+| `disabled`      | `(date: Date) => boolean`                         | No       | —       | Predicate to disable individual days                     |
+| `locale`        | `string`                                          | No       | —       | BCP-47 locale; defaults to the current i18n locale       |
+| `size`          | `'sm' \| 'md' \| 'lg'`                            | No       | —       | Grid cell size                                           |
+| `labels`        | `CalendarLabels`                                  | No       | —       | i18n label overrides for the nav buttons                 |
+| `month`         | `number`                                          | No       | —       | Controlled view month (0-11)                             |
+| `year`          | `number`                                          | No       | —       | Controlled view year                                     |
+| `onViewChange`  | `(view: { month: number; year: number }) => void` | No       | —       | Called when the visible month changes                    |
+| `hideNav`       | `boolean`                                         | No       | —       | Hides the prev/next nav so a parent can drive navigation |
+
+## Tokens
+
+- `--cascivo-calendar-bg`
+- `--cascivo-calendar-radius`
+- `--cascivo-calendar-cell-size`
+- `--cascivo-calendar-day-selected-bg`
+- `--cascivo-calendar-day-selected-fg`
+- `--cascivo-calendar-day-today-color`
+- `--cascivo-calendar-range-bg`
+
+## Examples
+
+### Basic
+
+Uncontrolled calendar
+
+```jsx
+<Calendar defaultValue={new Date(Date.UTC(2024, 5, 15))} />
+```
+
+### Constrained
+
+Limits the selectable range
+
+```jsx
+<Calendar min={new Date(Date.UTC(2024, 5, 1))} max={new Date(Date.UTC(2024, 5, 30))} />
+```
+
+### Disabled weekends
+
+Predicate disables individual days
+
+```jsx
+<Calendar disabled={(d) => [0, 6].includes(d.getUTCDay())} />
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                                      |
+| ------------ | -------- | --------------------------------------------------------------------------------------------------------- |
+| date type    | strict   | All date props are native Date objects compared in UTC                                                    |
+| locale       | flexible | Weekday labels, month label, and first-day-of-week derive from the locale via Intl (with Monday fallback) |
+| view control | flexible | month/year/onViewChange/hideNav let a parent drive navigation (used by DateRangePicker)                   |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Calendar component (inputs). An accessible standalone month-grid date picker.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Calendar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-calendar-bg, --cascivo-calendar-radius, --cascivo-calendar-cell-size, --cascivo-calendar-day-selected-bg, --cascivo-calendar-day-selected-fg, --cascivo-calendar-day-today-color, --cascivo-calendar-range-bg
+
+Accessibility: role "grid", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowUp/ArrowDown/Home/End/PageUp/PageDown/Enter/Space. Keep it AA.
+
+Do not change (strict): date type — All date props are native Date objects compared in UTC
+Flexible: locale, view control.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/card.md

@@ -0,0 +1,90 @@
+# Card
+
+**Category:** display  
+**Description:** Container for grouping related content
+
+## When to use
+
+- Grouping related content into a visually distinct surface with border/shadow
+- Creating scannable units in a grid or list (dashboard tiles, item summaries)
+- Giving a content cluster elevation to separate it from the page background
+
+## When NOT to use
+
+- Pure semantic/structural grouping with no surface — use a <section>
+- Wrapping every element in a card — nesting surfaces flattens visual hierarchy
+
+## Anti-patterns
+
+### Stacked surfaces and shadows compete for attention and muddy the hierarchy
+
+**Bad:** `Nesting Cards several levels deep for layout`  
+**Good:** `A single Card with internal spacing, or a plain <section>`  
+**Why:** Stacked surfaces and shadows compete for attention and muddy the hierarchy
+
+## Related components
+
+- **Separator** (pairs-with): Use a Separator to divide regions inside a card
+
+## Accessibility rationale
+
+role="region" is appropriate only when the card is a meaningful landmark; otherwise treat it as presentational — the visual surface adds no semantics on its own
+
+## Props
+
+| Name      | Type                                    | Required | Default | Description                       |
+| --------- | --------------------------------------- | -------- | ------- | --------------------------------- |
+| `variant` | `'default' \| 'outlined' \| 'elevated'` | No       | default | Selects the visual style variant. |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'`        | No       | md      | Inner padding of the component.   |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-card`
+- `--cascivo-shadow-md`
+
+## Examples
+
+### Basic card
+
+```jsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content here</CardContent>
+</Card>
+```
+
+## Boundaries
+
+| Area                | Level    | Note                                                                    |
+| ------------------- | -------- | ----------------------------------------------------------------------- |
+| variant and padding | flexible | Choose elevation and density to fit the surrounding layout              |
+| token names         | strict   | Surface, border, radius, and shadow must resolve to --cascivo-\* tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Card component (display). Container for grouping related content
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Card is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-card, --cascivo-shadow-md
+
+Accessibility: role "region", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Surface, border, radius, and shadow must resolve to --cascivo-* tokens
+Flexible: variant and padding.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/carousel.md

@@ -0,0 +1,101 @@
+# Carousel
+
+**Category:** display  
+**Description:** Scroll-snap slide deck with previous/next controls and dot indicators
+
+## When to use
+
+- Presenting a sequence of media or cards the user pages through one at a time
+- Image galleries, onboarding decks, or featured-content rotators
+- When horizontal swiping/scrolling is a natural interaction on touch devices
+
+## When NOT to use
+
+- Content users must compare side-by-side — show a grid instead
+- Critical information that must always be visible — carousels hide most of their content
+
+## Anti-patterns
+
+### Auto-rotation and hidden slides reduce discoverability and accessibility of important content
+
+**Bad:** `Auto-rotating carousel for primary navigation or key calls-to-action`  
+**Good:** `A static list or grid where every item is visible`  
+**Why:** Auto-rotation and hidden slides reduce discoverability and accessibility of important content
+
+## Related components
+
+- **Tabs** (alternative): Use tabs when sections are distinct and should be directly addressable
+
+## Accessibility rationale
+
+The container is a labelled region with aria-roledescription="carousel"; each slide is a labelled group ("n of total"); prev/next are real buttons and the dot indicators use roving tabindex with arrow-key navigation. Scrolling honours prefers-reduced-motion.
+
+## Props
+
+| Name            | Type                      | Required | Default | Description                                           |
+| --------------- | ------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `children`      | `ReactNode`               | No       | —       | Slides as children                                    |
+| `slides`        | `ReactNode[]`             | No       | —       | Slides as an array                                    |
+| `index`         | `number`                  | No       | —       | Controlled active index                               |
+| `defaultIndex`  | `number`                  | No       | 0       | The initial slide index when uncontrolled.            |
+| `onIndexChange` | `(index: number) => void` | No       | —       | Called with the new slide index when it changes.      |
+| `loop`          | `boolean`                 | No       | false   | When true, navigation wraps around from end to start. |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-radius-md`
+- `--cascivo-radius-full`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Carousel>
+  <img src="/1.jpg" alt="" />
+  <img src="/2.jpg" alt="" />
+</Carousel>
+```
+
+### Looping with array
+
+```jsx
+<Carousel loop slides={[<Slide1 />, <Slide2 />, <Slide3 />]} />
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                             |
+| ------------- | -------- | -------------------------------------------------------------------------------- |
+| transition    | strict   | Paging uses native CSS scroll-snap, not transform math — no custom easing config |
+| slide content | flexible | Any ReactNode may be a slide; pass via children or the slides array              |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Carousel component (display). Scroll-snap slide deck with previous/next controls and dot indicators
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Carousel is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-radius-md, --cascivo-radius-full, --cascivo-focus-ring
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/Home/End. Keep it AA.
+
+Do not change (strict): transition — Paging uses native CSS scroll-snap, not transform math — no custom easing config
+Flexible: slide content.
+
+Do not invent props, tokens, or global viewport media queries.
+```