@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/sheet.md

@@ -0,0 +1,100 @@
+# Sheet
+
+**Category:** overlay  
+**Description:** Slide-in panel from any edge, using popover=manual and @starting-style animations
+
+## When to use
+
+- Showing secondary content or a form in a panel that slides in from a screen edge
+- Navigation, filters, or detail views that benefit from full-height side space without leaving the page
+- Mobile-friendly drawers where a centered modal would feel cramped
+
+## When NOT to use
+
+- A short confirmation or focused decision — use Modal or AlertDialog
+- Small contextual content anchored to a trigger — use Popover
+
+## Anti-patterns
+
+### A full edge-to-edge panel is overkill for a yes/no decision; AlertDialog is the right scale and semantics
+
+**Bad:** `<Sheet title="Delete item?">Are you sure?</Sheet>`  
+**Good:** `<AlertDialog title="Delete item?" />`  
+**Why:** A full edge-to-edge panel is overkill for a yes/no decision; AlertDialog is the right scale and semantics
+
+## Related components
+
+- **Modal** (alternative): Use for centered, focused dialogs rather than edge panels
+- **Popover** (alternative): Use for small content anchored to a trigger element
+
+## Accessibility rationale
+
+Uses popover="manual" with role="dialog" and aria-modal so it is announced as a modal surface; when a title is provided it labels the dialog via aria-labelledby (so rich title nodes stay accessible), and Escape/Tab handling comes from the popover platform behavior.
+
+## Props
+
+| Name      | Type                                    | Required | Default | Description                                 |
+| --------- | --------------------------------------- | -------- | ------- | ------------------------------------------- |
+| `open`    | `boolean`                               | Yes      | —       | Whether the component is open (controlled). |
+| `onClose` | `() => void`                            | Yes      | —       | Called when the component is closed.        |
+| `title`   | `React.ReactNode`                       | No       | —       | Title text for the component.               |
+| `side`    | `'start' \| 'end' \| 'top' \| 'bottom'` | No       | end     | Edge the component is anchored to.          |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-lg`
+- `--cascivo-shadow-xl`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Basic
+
+```jsx
+<Sheet open={isOpen} onClose={() => setIsOpen(false)} title="Filters">
+  <FilterForm />
+</Sheet>
+```
+
+### Bottom sheet
+
+```jsx
+<Sheet open={isOpen} onClose={close} side="bottom" title="Share">
+  <ShareOptions />
+</Sheet>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                |
+| ------------ | -------- | ----------------------------------------------------------------------------------- |
+| side         | strict   | Limited to start \| end \| top \| bottom — drives the slide direction and animation |
+| body content | flexible | Any children; consumer owns the panel contents                                      |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Sheet component (overlay). Slide-in panel from any edge, using popover=manual and @starting-style animations
+
+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).
+
+Sheet is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-lg, --cascivo-shadow-xl, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "dialog", WCAG 2.2-AA, keyboard: Escape/Tab/Shift+Tab. Keep it AA.
+
+Do not change (strict): side — Limited to start | end | top | bottom — drives the slide direction and animation
+Flexible: body content.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/shell-header.md

@@ -0,0 +1,105 @@
+# ShellHeader
+
+**Category:** navigation  
+**Description:** Console application header: brand with prefix, dropdown nav menus, global icon actions, hamburger, skip-to-content
+
+## When to use
+
+- Building console/admin app chrome with brand, dropdown nav, and global icon actions
+- Providing a hamburger that toggles a SideNav and a skip-to-content link
+- Hosting global controls (notifications, switcher, user menu) in one top bar
+
+## When NOT to use
+
+- A simple marketing or app top bar — use Header
+- In-page section headings — use Heading
+
+## Anti-patterns
+
+### ShellHeader carries console machinery (dropdowns, icon actions, hamburger) that is overkill for simple sites
+
+**Bad:** `Reaching for ShellHeader on a basic landing page`  
+**Good:** `<Header> for simple top bars`  
+**Why:** ShellHeader carries console machinery (dropdowns, icon actions, hamburger) that is overkill for simple sites
+
+## Related components
+
+- **SideNav** (pairs-with): The hamburger toggles a SideNav in the app shell
+- **HeaderPanel** (pairs-with): Icon actions open HeaderPanels (notifications, switcher)
+- **Header** (alternative): Header is the simpler top bar for non-console apps
+
+## Accessibility rationale
+
+role="banner" landmarks the header; nav dropdowns expose aria-expanded, icon actions use aria-pressed, the hamburger reports aria-expanded, and a skip-to-content link lets keyboard users bypass the chrome
+
+## Props
+
+| Name                | Type                            | Required | Default         | Description                                                                              |
+| ------------------- | ------------------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------- |
+| `brand`             | `ShellHeaderBrand \| ReactNode` | No       | —               | Brand: { prefix?, name, href? } or free-form node                                        |
+| `nav`               | `ShellHeaderNavItem[]`          | No       | —               | Top nav: links ({ label, href, active?, onClick? }) or dropdown menus ({ label, items }) |
+| `actions`           | `ShellHeaderAction[]`           | No       | —               | Right-aligned global icon actions with aria-pressed                                      |
+| `end`               | `ReactNode`                     | No       | —               | Free-form trailing slot (user menu, theme switcher)                                      |
+| `onMenuClick`       | `() => void`                    | No       | —               | Renders the hamburger button; call shell.toggleSideNav                                   |
+| `menuExpanded`      | `boolean`                       | No       | —               | aria-expanded for the hamburger button                                                   |
+| `skipToContentHref` | `string \| false`               | No       | '#cascade-main' | Skip-link target; false disables the link                                                |
+| `labels`            | `ShellHeaderLabels`             | No       | —               | i18n overrides for built-in strings                                                      |
+
+## Tokens
+
+- `--cascivo-shell-header-block-size`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-accent`
+- `--cascivo-radius-control`
+
+## Examples
+
+### Console header
+
+Brand with prefix, dropdown nav, global icon action
+
+```jsx
+<ShellHeader
+  brand={{ prefix: 'cascivo', name: 'Console', href: '/' }}
+  nav={[
+    { label: 'Dashboard', href: '/dash', active: true },
+    { label: 'Manage', items: [{ label: 'Users', href: '/users' }] },
+  ]}
+  actions={[{ id: 'notifications', label: 'Notifications', icon: <Bell /> }]}
+/>
+```
+
+## Boundaries
+
+| Area                      | Level    | Note                                                                   |
+| ------------------------- | -------- | ---------------------------------------------------------------------- |
+| nav / actions / end slots | flexible | Brand, nav, actions, and end are composable and optional               |
+| token names               | strict   | Surfaces, sizing, and accent must resolve to --cascivo-\* shell tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ShellHeader component (navigation). Console application header: brand with prefix, dropdown nav menus, global icon actions, hamburger, skip-to-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).
+
+ShellHeader is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-shell-header-block-size, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-accent, --cascivo-radius-control
+
+Accessibility: role "banner", WCAG 2.2-AA, keyboard: Tab/Enter/Space/ArrowDown/ArrowUp/Escape. Keep it AA.
+
+Do not change (strict): token names — Surfaces, sizing, and accent must resolve to --cascivo-* shell tokens
+Flexible: nav / actions / end slots.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/side-nav.md

@@ -0,0 +1,134 @@
+# SideNav
+
+**Category:** navigation  
+**Description:** Collapsible sidebar navigation with optional icons and one level of grouping
+
+## When to use
+
+- Persistent primary navigation along the side of an app shell
+- Grouping nav items one level deep with collapsible groups
+- Saving space with a collapsible icon rail (collapsed / expandOnHover)
+
+## When NOT to use
+
+- Top-level horizontal navigation — use Header or ShellHeader nav
+- A transient contextual menu — use Dropdown
+
+## Anti-patterns
+
+### Deep nesting in a sidebar is hard to scan and the component supports only one level by design
+
+**Bad:** `Nesting nav groups more than one level deep`  
+**Good:** `Flatten to a single level of grouping, or split into sections`  
+**Why:** Deep nesting in a sidebar is hard to scan and the component supports only one level by design
+
+## Related components
+
+- **ShellHeader** (pairs-with): The header hamburger toggles SideNav collapse
+
+## Accessibility rationale
+
+role="navigation" with an aria-label names the region; the collapse toggle has an explicit expand/collapse label, groups expose aria-expanded, and the collapsed rail provides tooltips/flyouts so icon-only items remain identifiable
+
+## Props
+
+| Name                | Type                           | Required | Default             | Description                                                                                                                                                                                                                                                                                               |
+| ------------------- | ------------------------------ | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`             | `SideNavItem[]`                | Yes      | —                   | { label, href?, icon?, active?, items?, onClick?, disabled?, tone?, trailing?, render? } — an onClick-only item renders a focusable <button>; nested items render expandable menus (links, action sub-items with onSelect/selected, separators, labels); render() is an alignment-preserving escape hatch |
+| `collapsed`         | `boolean`                      | No       | —                   | Controlled collapsed state (rail mode)                                                                                                                                                                                                                                                                    |
+| `defaultCollapsed`  | `boolean`                      | No       | false               | Whether the rail is collapsed on first render (uncontrolled).                                                                                                                                                                                                                                             |
+| `onCollapsedChange` | `(collapsed: boolean) => void` | No       | —                   | Called with the new collapsed state when it changes.                                                                                                                                                                                                                                                      |
+| `ariaLabel`         | `string`                       | No       | Side navigation     | Accessible label for the component.                                                                                                                                                                                                                                                                       |
+| `collapseLabel`     | `string`                       | No       | Collapse navigation | Accessible label for the collapse control.                                                                                                                                                                                                                                                                |
+| `expandLabel`       | `string`                       | No       | Expand navigation   | Accessible label for the expand control.                                                                                                                                                                                                                                                                  |
+| `expandOnHover`     | `boolean`                      | No       | false               | Widens the rail as an overlay on hover/focus-within; suppresses tooltips/flyouts                                                                                                                                                                                                                          |
+| `header`            | `ReactNode`                    | No       | —                   | Content rendered above the items, inside the item padding context (e.g. app-context pickers)                                                                                                                                                                                                              |
+| `footer`            | `ReactNode`                    | No       | —                   | Content rendered above the collapse toggle (e.g. version string, user info)                                                                                                                                                                                                                               |
+| `className`         | `string`                       | No       | —                   | Additional CSS class names merged onto the root element.                                                                                                                                                                                                                                                  |
+
+## Tokens
+
+- `--cascivo-sidenav-inline-size`
+- `--cascivo-sidenav-rail-inline-size`
+- `--cascivo-sidenav-bg`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-subtle`
+- `--cascivo-color-destructive`
+- `--cascivo-color-warning`
+- `--cascivo-color-success`
+- `--cascivo-focus-ring`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-motion-emphasis`
+
+## Examples
+
+### Basic
+
+```jsx
+<SideNav
+  items={[
+    { label: 'Home', href: '/', active: true },
+    { label: 'Reports', href: '/reports' },
+  ]}
+/>
+```
+
+### With a group
+
+```jsx
+<SideNav items={[{ label: 'Settings', items: [{ label: 'Profile', href: '/profile' }] }]} />
+```
+
+### Icon rail
+
+Collapsed rail: icons-only with tooltips, grapheme fallback for icon-less items, flyout menus for groups
+
+```jsx
+<SideNav collapsed items={[{ label: 'Home', href: '/', icon: <Home size={16} /> }]} />
+```
+
+### Expand on hover
+
+Rail widens as CSS overlay on hover without reflowing adjacent content
+
+```jsx
+<SideNav collapsed expandOnHover items={items} />
+```
+
+## Boundaries
+
+| Area                      | Level    | Note                                                             |
+| ------------------------- | -------- | ---------------------------------------------------------------- |
+| collapsed / expandOnHover | flexible | Rail behavior is configurable for density needs                  |
+| token names               | strict   | Sizing, surfaces, and motion 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 SideNav component (navigation). Collapsible sidebar navigation with optional icons and one level of grouping
+
+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).
+
+SideNav is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-sidenav-inline-size, --cascivo-sidenav-rail-inline-size, --cascivo-sidenav-bg, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-bg-subtle, --cascivo-color-accent, --cascivo-color-accent-subtle, --cascivo-color-destructive, --cascivo-color-warning, --cascivo-color-success, --cascivo-focus-ring, --cascivo-motion-enter, --cascivo-motion-exit, --cascivo-motion-emphasis
+
+Accessibility: role "navigation", WCAG 2.2-AA, keyboard: Tab/Enter/Space/ArrowDown/ArrowUp/Escape. Keep it AA.
+
+Do not change (strict): token names — Sizing, surfaces, and motion must resolve to --cascivo-* tokens
+Flexible: collapsed / expandOnHover.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/skeleton.md

@@ -0,0 +1,101 @@
+# Skeleton
+
+**Category:** display  
+**Description:** Animated loading placeholder that mirrors the shape of pending content
+
+## When to use
+
+- Indicating loading by mirroring the shape of the content that will appear
+- Reducing layout shift while data for a known structure is fetching
+- Loading larger content regions where shape preview reassures the user
+
+## When NOT to use
+
+- Indeterminate work with no known content shape — use Spinner
+- A view that is empty rather than loading — use EmptyState
+
+## Anti-patterns
+
+### A persistent skeleton signals perpetual loading and traps assistive tech in a pending state
+
+**Bad:** `Leaving Skeleton mounted after data has loaded`  
+**Good:** `Swap Skeleton for the real content once data resolves`  
+**Why:** A persistent skeleton signals perpetual loading and traps assistive tech in a pending state
+
+## Related components
+
+- **Spinner** (alternative): Spinner suits indeterminate work with no content shape to preview
+- **EmptyState** (alternative): Use EmptyState when the result is empty, not loading
+
+## Accessibility rationale
+
+Presentational by role — the placeholder shapes carry no meaning; the surrounding region should expose busy/loading state so assistive tech is not left guessing
+
+## Props
+
+| Name      | Type                           | Required | Default | Description                                                       |
+| --------- | ------------------------------ | -------- | ------- | ----------------------------------------------------------------- |
+| `variant` | `'text' \| 'circle' \| 'rect'` | No       | text    | Selects the visual style variant.                                 |
+| `width`   | `string`                       | No       | —       | CSS length applied as an inline custom property                   |
+| `height`  | `string`                       | No       | —       | CSS length applied as an inline custom property                   |
+| `lines`   | `number`                       | No       | 1       | Number of bars for the text variant; the last bar renders shorter |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-sm`
+- `--cascivo-radius-full`
+- `--cascivo-radius-component`
+
+## Examples
+
+### Text
+
+```jsx
+<Skeleton lines={3} />
+```
+
+### Avatar
+
+```jsx
+<Skeleton variant="circle" width="3rem" height="3rem" />
+```
+
+### Image
+
+```jsx
+<Skeleton variant="rect" height="12rem" />
+```
+
+## Boundaries
+
+| Area                   | Level    | Note                                                           |
+| ---------------------- | -------- | -------------------------------------------------------------- |
+| variant and dimensions | flexible | Shape, width, height, and line count match the pending content |
+| token names            | strict   | Background and radius 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 Skeleton component (display). Animated loading placeholder that mirrors the shape of pending 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).
+
+Skeleton is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-radius-sm, --cascivo-radius-full, --cascivo-radius-component
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Background and radius must resolve to --cascivo-* tokens
+Flexible: variant and dimensions.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/skip-nav.md

@@ -0,0 +1,103 @@
+# SkipNav
+
+**Category:** navigation  
+**Description:** Skip link that jumps keyboard users past the navigation to the main content
+
+## When to use
+
+- Letting keyboard users jump past repeated navigation to the main content
+- Meeting WCAG bypass-blocks by providing a skip link as the first focusable element
+- Targeting a custom main-content anchor (targetId / matching SkipNavTarget id)
+
+## When NOT to use
+
+- General in-page navigation — use anchor links or a table of contents
+- Visible persistent navigation — this link is hidden until focused
+
+## Anti-patterns
+
+### A skip link only works if the user reaches it before tabbing through the nav it bypasses
+
+**Bad:** `Placing SkipNavLink after the navigation in the DOM`  
+**Good:** `Make SkipNavLink the first focusable element on the page`  
+**Why:** A skip link only works if the user reaches it before tabbing through the nav it bypasses
+
+## Related components
+
+- **ShellHeader** (alternative): ShellHeader has a built-in skip-to-content link for console shells
+
+## Accessibility rationale
+
+Renders an anchor that is visually hidden until focused, then becomes visible so sighted keyboard users see where focus is; activating it moves focus to the matching target past the navigation
+
+## Props
+
+| Name       | Type                 | Required | Default             | Description                                                 |
+| ---------- | -------------------- | -------- | ------------------- | ----------------------------------------------------------- |
+| `targetId` | `string`             | No       | cascade-skip-target | SkipNavLink: id of the SkipNavTarget to jump to             |
+| `labels`   | `{ label?: string }` | No       | —                   | SkipNavLink: overrides the built-in i18n label per instance |
+| `id`       | `string`             | No       | cascade-skip-target | SkipNavTarget: anchor id — must match the link targetId     |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-text`
+- `--cascivo-radius-control`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Default pair
+
+SkipNavLink must be the first focusable element on the page
+
+```jsx
+<>
+  <SkipNavLink />
+  <nav>…</nav>
+  <SkipNavTarget />
+  <main>…</main>
+</>
+```
+
+### Custom target
+
+```jsx
+<>
+  <SkipNavLink targetId="main-content" />
+  <SkipNavTarget id="main-content" />
+</>
+```
+
+## Boundaries
+
+| Area                      | Level    | Note                                                        |
+| ------------------------- | -------- | ----------------------------------------------------------- |
+| target id                 | flexible | targetId/id may be customized as long as they match         |
+| first-focusable placement | strict   | SkipNavLink must be the first focusable element to function |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo SkipNav component (navigation). Skip link that jumps keyboard users past the navigation to the main 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).
+
+SkipNav is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-text, --cascivo-radius-control, --cascivo-focus-ring
+
+Accessibility: role "link", WCAG 2.2-AA, keyboard: Tab/Enter. Keep it AA.
+
+Do not change (strict): first-focusable placement — SkipNavLink must be the first focusable element to function
+Flexible: target id.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/slider.md

@@ -0,0 +1,98 @@
+# Slider
+
+**Category:** inputs  
+**Description:** Range input for selecting a value within bounds
+
+## When to use
+
+- Selecting a value within a continuous or stepped numeric range where approximate adjustment is fine
+- Settings like volume, brightness, or opacity where dragging gives instant feedback
+- When the bounds (min/max) matter more than entering an exact figure
+
+## When NOT to use
+
+- A precise numeric value must be typed — use NumberInput
+- Picking a discrete rating on a small scale where stars/icons read better — use RatingGroup
+
+## Anti-patterns
+
+### A huge range makes a single value impossible to hit by dragging; type the exact number instead
+
+**Bad:** `<Slider label="Price" min={0} max={1000000} />`  
+**Good:** `<NumberInput label="Price" />`  
+**Why:** A huge range makes a single value impossible to hit by dragging; type the exact number instead
+
+## Related components
+
+- **NumberInput** (alternative): Use when an exact, typed numeric value is required
+- **RatingGroup** (alternative): Use for small discrete rating scales rather than a continuous range
+
+## Accessibility rationale
+
+Renders a native <input type="range"> so the slider role, value announcements, and full arrow/Home/End keyboard support come from the platform without custom ARIA.
+
+## Props
+
+| Name           | Type      | Required | Default | Description                                                        |
+| -------------- | --------- | -------- | ------- | ------------------------------------------------------------------ |
+| `label`        | `string`  | No       | —       | Text label for the control.                                        |
+| `min`          | `number`  | No       | 0       | Minimum allowed value.                                             |
+| `max`          | `number`  | No       | 100     | Maximum allowed value.                                             |
+| `step`         | `number`  | No       | 1       | Increment between allowed values.                                  |
+| `value`        | `number`  | No       | —       | The controlled value.                                              |
+| `defaultValue` | `number`  | No       | —       | The initial value when uncontrolled.                               |
+| `disabled`     | `boolean` | No       | false   | When true, disables the control and removes it from the tab order. |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-surface`
+- `--cascivo-radius-full`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Slider label="Volume" defaultValue={50} />
+```
+
+### Stepped
+
+```jsx
+<Slider label="Rating" min={0} max={5} step={1} />
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                   |
+| ------------ | -------- | -------------------------------------------------------------------------------------- |
+| token names  | strict   | Track and thumb colors must resolve to --cascivo-color-\* / radius / focus-ring tokens |
+| min/max/step | flexible | Consumer-defined bounds and increment                                                  |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Slider component (inputs). Range input for selecting a value within bounds
+
+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).
+
+Slider is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-border-strong, --cascivo-color-surface, --cascivo-radius-full, --cascivo-focus-ring
+
+Accessibility: role "slider", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowUp/ArrowDown/Home/End. Keep it AA.
+
+Do not change (strict): token names — Track and thumb colors must resolve to --cascivo-color-* / radius / focus-ring tokens
+Flexible: min/max/step.
+
+Do not invent props, tokens, or global viewport media queries.
+```