@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/text.md

@@ -0,0 +1,111 @@
+# Text
+
+**Category:** display  
+**Description:** Body text with size, weight, and muted variants
+
+## When to use
+
+- Rendering body copy, paragraphs, and inline text in app UI
+- Applying size/weight/muted treatment to secondary or emphasized text
+- Inline emphasis inside flow content (as="span")
+
+## When NOT to use
+
+- Section or page titles — use Heading for the document outline
+- Long-form authored/markdown content — use Prose
+
+## Anti-patterns
+
+### Visually-large Text has no heading semantics, so it is missing from the document outline
+
+**Bad:** `<Text size="lg" weight="semibold"> used as a page title`  
+**Good:** `<Heading level={1}>`  
+**Why:** Visually-large Text has no heading semantics, so it is missing from the document outline
+
+## Related components
+
+- **Heading** (alternative): Heading carries outline semantics; Text is plain body copy
+
+## Accessibility rationale
+
+Renders the chosen native element (p/span/div) without imposing roles; muted styling keeps contrast within AA so secondary text stays readable
+
+## Props
+
+| Name     | Type                                 | Required | Default | Description                                           |
+| -------- | ------------------------------------ | -------- | ------- | ----------------------------------------------------- |
+| `as`     | `'p' \| 'span' \| 'div'`             | No       | p       | The HTML element to render as.                        |
+| `size`   | `'sm' \| 'md' \| 'lg'`               | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+| `weight` | `'normal' \| 'medium' \| 'semibold'` | No       | normal  | Font weight ('normal' \| 'medium' \| 'semibold').     |
+| `muted`  | `boolean`                            | No       | false   | When true, renders in a muted/subtle color.           |
+
+## Tokens
+
+- `--cascivo-font-sans`
+- `--cascivo-font-normal`
+- `--cascivo-font-medium`
+- `--cascivo-font-semibold`
+- `--cascivo-leading-normal`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-text-sm`
+- `--cascivo-text-base`
+- `--cascivo-text-lg`
+
+## Examples
+
+### Default
+
+```jsx
+<Text>Body copy reads at the base size.</Text>
+```
+
+### Muted helper
+
+```jsx
+<Text size="sm" muted>
+  Secondary information
+</Text>
+```
+
+### Inline span
+
+Use as="span" inside other flow content
+
+```jsx
+<Text as="span" weight="semibold">
+  emphasis
+</Text>
+```
+
+## Boundaries
+
+| Area               | Level    | Note                                                         |
+| ------------------ | -------- | ------------------------------------------------------------ |
+| as / size / weight | flexible | Choose element and treatment to fit context                  |
+| token names        | strict   | Font, leading, and color 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 Text component (display). Body text with size, weight, and muted variants
+
+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).
+
+Text is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-sans, --cascivo-font-normal, --cascivo-font-medium, --cascivo-font-semibold, --cascivo-leading-normal, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-text-sm, --cascivo-text-base, --cascivo-text-lg
+
+Accessibility: role "paragraph", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Font, leading, and color must resolve to --cascivo-* tokens
+Flexible: as / size / weight.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/textarea.md

@@ -0,0 +1,98 @@
+# Textarea
+
+**Category:** inputs  
+**Description:** Multi-line text input with optional label, hint, and error state
+
+## When to use
+
+- Capturing multi-line free text such as messages, descriptions, or comments
+- Input where line breaks are meaningful and the content may wrap to several rows
+- Form fields that benefit from a visible hint or validation error beneath the control
+
+## When NOT to use
+
+- A single short value like a name or email — use Input
+- A constrained numeric value — use NumberInput
+
+## Anti-patterns
+
+### A one-line value belongs in Input; a textarea invites unwanted line breaks and submits via Enter differently
+
+**Bad:** `<Textarea label="Email" rows={1} />`  
+**Good:** `<Input type="email" label="Email" />`  
+**Why:** A one-line value belongs in Input; a textarea invites unwanted line breaks and submits via Enter differently
+
+## Related components
+
+- **Input** (alternative): Use for single-line values
+- **Form** (contained-by): Typically grouped with other fields inside a form
+
+## Accessibility rationale
+
+Renders a native <textarea> with aria-multiline; hint and error text are associated via aria-describedby and errors use role="alert" with aria-invalid so assistive tech announces validation state.
+
+## Props
+
+| Name       | Type                             | Required | Default  | Description                                                                    |
+| ---------- | -------------------------------- | -------- | -------- | ------------------------------------------------------------------------------ |
+| `label`    | `string`                         | No       | —        | Text label for the control.                                                    |
+| `hint`     | `string`                         | No       | —        | Supplementary hint text shown with the control.                                |
+| `error`    | `string`                         | No       | —        | Error message shown when the value is invalid.                                 |
+| `rows`     | `number`                         | No       | 4        | Number of visible text rows.                                                   |
+| `resize`   | `'none' \| 'vertical' \| 'both'` | No       | vertical | Which directions the textarea can be resized ('none' \| 'vertical' \| 'both'). |
+| `disabled` | `boolean`                        | No       | false    | When true, disables the control and removes it from the tab order.             |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-radius-input`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### With label
+
+```jsx
+<Textarea label="Message" placeholder="Type here…" />
+```
+
+### With error
+
+```jsx
+<Textarea label="Bio" error="Bio is required" />
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                                             |
+| --------------- | -------- | -------------------------------------------------------------------------------- |
+| token names     | strict   | Border/focus/error colors must resolve to --cascivo-color-\* / focus-ring tokens |
+| resize and rows | flexible | Consumer chooses initial rows and whether the field can resize                   |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Textarea component (inputs). Multi-line text input with optional label, hint, and error state
+
+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).
+
+Textarea is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-accent, --cascivo-color-destructive, --cascivo-radius-input, --cascivo-focus-ring
+
+Accessibility: role "textbox", WCAG 2.2-AA, keyboard: Tab/Shift+Tab. Keep it AA.
+
+Do not change (strict): token names — Border/focus/error colors must resolve to --cascivo-color-* / focus-ring tokens
+Flexible: resize and rows.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/tile.md

@@ -0,0 +1,116 @@
+# Tile
+
+**Category:** inputs  
+**Description:** A selectable card with radio (single) or checkbox (multi) semantics, toggled by click or keyboard
+
+## When to use
+
+- A visually rich, clickable choice card in a single- or multi-select group
+- Plan/option pickers where each option needs an icon and supporting content
+- A larger touch target than a plain radio or checkbox
+
+## When NOT to use
+
+- A simple inline boolean — use Checkbox or Toggle
+- A dense list of text-only options — use RadioGroup or a Select
+
+## Anti-patterns
+
+### Single (radio) tiles cannot be unselected by clicking; use multi for toggleable behavior
+
+**Bad:** `<Tile value="on">Enable</Tile> // used as a standalone on/off control`  
+**Good:** `<Tile value="on" selectable="multi">Enable</Tile> // multi allows deselect`  
+**Why:** Single (radio) tiles cannot be unselected by clicking; use multi for toggleable behavior
+
+## Related components
+
+- **RadioCard** (alternative): RadioCard wraps a native input in a group; Tile is a standalone ARIA radio/checkbox
+- **CheckboxCard** (alternative): Use CheckboxCard when native checkbox form semantics are required
+
+## Accessibility rationale
+
+Exposes role="radio" (single) or role="checkbox" (multi) with aria-checked reflecting selection, is focusable, and toggles on Space/Enter. aria-disabled and a -1 tabindex remove disabled tiles from interaction.
+
+## Props
+
+| Name              | Type                      | Required | Default | Description                                                                                       |
+| ----------------- | ------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `value`           | `string`                  | Yes      | —       | Identifies this tile within a group.                                                              |
+| `selected`        | `boolean`                 | No       | —       | Controlled selected state.                                                                        |
+| `defaultSelected` | `boolean`                 | No       | —       | Initial selected state for uncontrolled use.                                                      |
+| `onSelect`        | `(value: string) => void` | No       | —       | Called with this tile's value whenever it is toggled on (or off for multi).                       |
+| `selectable`      | `'single' \| 'multi'`     | No       | single  | Single = radio semantics (toggle on); multi = checkbox semantics (toggle on/off).                 |
+| `disabled`        | `boolean`                 | No       | —       | When true, disables the control and removes it from the tab order.                                |
+| `icon`            | `React.ReactNode`         | No       | —       | Optional leading icon/visual.                                                                     |
+| `asChild`         | `boolean`                 | No       | —       | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
+| `children`        | `React.ReactNode`         | No       | —       | Content rendered inside the component.                                                            |
+| `className`       | `string`                  | No       | —       | Additional CSS class names merged onto the root element.                                          |
+
+## Tokens
+
+- `--cascivo-color-bg`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-accent`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-radius-surface`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Single-select group
+
+```jsx
+<div role="radiogroup" aria-label="Plan">
+  <Tile value="starter" selected={plan === 'starter'} onSelect={setPlan}>
+    Starter
+  </Tile>
+  <Tile value="pro" selected={plan === 'pro'} onSelect={setPlan}>
+    Pro
+  </Tile>
+</div>
+```
+
+### Multi-select with icon
+
+Multi tiles toggle on and off like a checkbox.
+
+```jsx
+<Tile value="notifications" selectable="multi" icon={<BellIcon />} defaultSelected>
+  Email notifications
+</Tile>
+```
+
+## Boundaries
+
+| Area           | Level    | Note                                                             |
+| -------------- | -------- | ---------------------------------------------------------------- |
+| selectable     | strict   | single (radio, select-only) \| multi (checkbox, toggle)          |
+| selected state | flexible | Controlled (selected/onSelect) or uncontrolled (defaultSelected) |
+| element        | flexible | asChild renders onto a custom element via Slot                   |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Tile component (inputs). A selectable card with radio (single) or checkbox (multi) semantics, toggled by click or keyboard
+
+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).
+
+Tile is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-bg, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-accent, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-radius-surface, --cascivo-focus-ring
+
+Accessibility: role "radio", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): selectable — single (radio, select-only) | multi (checkbox, toggle)
+Flexible: selected state, element.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/time-picker.md

@@ -0,0 +1,102 @@
+# TimePicker
+
+**Category:** inputs  
+**Description:** Native time input wrapper with label, hint, error, and size variants
+
+## When to use
+
+- Capturing a time of day (HH:mm) in a form, such as a meeting or reminder time
+- You want the native OS time entry UX with built-in formatting and validation
+- A time field that needs a label, hint, error, or min/max bounds
+
+## When NOT to use
+
+- Picking a calendar date — use DatePicker
+- A free-form or non-time text value — use Input
+
+## Anti-patterns
+
+### A plain Input cannot enforce time format or offer the native time UI; TimePicker gives parsing and locale handling for free
+
+**Bad:** `<Input placeholder="HH:mm" /> // hand-rolled time field`  
+**Good:** `<TimePicker label="Start" />`  
+**Why:** A plain Input cannot enforce time format or offer the native time UI; TimePicker gives parsing and locale handling for free
+
+## Related components
+
+- **DatePicker** (alternative): Use when a calendar date is needed instead of a time
+- **Input** (alternative): Use for non-time free-text values
+
+## Accessibility rationale
+
+Renders a native <input type="time"> so segmented HH/mm entry, format enforcement, and keyboard support come from the platform; error text is linked via aria-describedby with aria-invalid.
+
+## Props
+
+| Name           | Type                      | Required | Default | Description                                                        |
+| -------------- | ------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `value`        | `string`                  | No       | —       | Controlled value (HH:mm)                                           |
+| `defaultValue` | `string`                  | No       | —       | The initial value when uncontrolled.                               |
+| `onChange`     | `(value: string) => void` | No       | —       | Called when the value changes.                                     |
+| `min`          | `string`                  | No       | —       | Minimum allowed value.                                             |
+| `max`          | `string`                  | No       | —       | Maximum allowed value.                                             |
+| `step`         | `number`                  | No       | —       | Increment between allowed values.                                  |
+| `label`        | `string`                  | No       | —       | Text label for the control.                                        |
+| `hint`         | `string`                  | No       | —       | Supplementary hint text shown with the control.                    |
+| `error`        | `string`                  | No       | —       | Error message shown when the value is invalid.                     |
+| `size`         | `'sm' \| 'md' \| 'lg'`    | No       | 'md'    | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `disabled`     | `boolean`                 | No       | —       | When true, disables the control and removes it from the tab order. |
+| `className`    | `string`                  | No       | —       | Additional CSS class names merged onto the root element.           |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-accent`
+- `--cascivo-color-danger`
+- `--cascivo-radius-input`
+- `--cascivo-radius-md`
+
+## Examples
+
+### Basic time picker
+
+```jsx
+<TimePicker label="Meeting time" onChange={(v) => console.log(v)} />
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                            |
+| ------------ | -------- | --------------------------------------------------------------- |
+| value format | strict   | Value is a 24-hour HH:mm string driven by the native time input |
+| min/max/step | flexible | Consumer-defined bounds and step granularity                    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo TimePicker component (inputs). Native time input wrapper with label, hint, error, and size variants
+
+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).
+
+TimePicker is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-accent, --cascivo-color-danger, --cascivo-radius-input, --cascivo-radius-md
+
+Accessibility: role "textbox", WCAG 2.2-AA, keyboard: Tab. Keep it AA.
+
+Do not change (strict): value format — Value is a 24-hour HH:mm string driven by the native time input
+Flexible: min/max/step.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/timeline.md

@@ -0,0 +1,93 @@
+# Timeline
+
+**Category:** display  
+**Description:** Ordered sequence of events with status markers and a connector line
+
+## When to use
+
+- Showing an ordered sequence of events over time (activity feeds, order tracking)
+- Communicating progress through discrete stages with complete/current/upcoming status
+- Presenting a chronological history where order is meaningful
+
+## When NOT to use
+
+- Interactive multi-step navigation the user controls — use Tabs or a Stepper
+- Unordered lists where sequence carries no meaning — use List
+
+## Anti-patterns
+
+### Multiple current markers make the active position ambiguous for assistive tech
+
+**Bad:** `Marking several items as status="current" at once`  
+**Good:** `Exactly one current item so aria-current="step" points to a single position`  
+**Why:** Multiple current markers make the active position ambiguous for assistive tech
+
+## Related components
+
+- **List** (alternative): List is for unordered prose; Timeline conveys ordered, time-stamped events
+
+## Accessibility rationale
+
+Rendered as an ordered list (ol/li) to convey sequence; the active item carries aria-current="step" and decorative markers are aria-hidden so screen readers read only the text
+
+## Props
+
+| Name          | Type                                                                                                                                           | Required | Default  | Description                          |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ------------------------------------ |
+| `items`       | `{ id: string; title: ReactNode; description?: ReactNode; time?: string; icon?: ReactNode; status?: "complete" \| "current" \| "upcoming" }[]` | Yes      | —        | The items to render.                 |
+| `orientation` | `'vertical' \| 'horizontal'`                                                                                                                   | No       | vertical | Layout orientation of the component. |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-surface`
+- `--cascivo-color-success`
+- `--cascivo-color-primary`
+- `--cascivo-radius-full`
+
+## Examples
+
+### Vertical timeline with statuses
+
+```jsx
+<Timeline
+  items={[
+    { id: '1', title: 'Order placed', time: '09:00', status: 'complete' },
+    { id: '2', title: 'Shipped', time: '12:30', status: 'current' },
+    { id: '3', title: 'Delivered', status: 'upcoming' },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area             | Level    | Note                                                                   |
+| ---------------- | -------- | ---------------------------------------------------------------------- |
+| orientation      | flexible | vertical for feeds, horizontal for compact progress strips             |
+| status semantics | strict   | Use a single current item; status drives marker colour via data-status |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Timeline component (display). Ordered sequence of events with status markers and a connector line
+
+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).
+
+Timeline is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-surface, --cascivo-color-success, --cascivo-color-primary, --cascivo-radius-full
+
+Accessibility: role "list", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): status semantics — Use a single current item; status drives marker colour via data-status
+Flexible: orientation.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/toast.md

@@ -0,0 +1,91 @@
+# Toast
+
+**Category:** overlay  
+**Description:** Transient notification surfaced via the useToast hook
+
+## When to use
+
+- Confirming that a background or just-completed action succeeded or failed (e.g. "Saved")
+- Brief, transient feedback that should auto-dismiss without interrupting the task
+- Non-blocking notifications that can stack and disappear on their own
+
+## When NOT to use
+
+- A persistent, inline message tied to a specific region of the page — use Alert
+- Feedback that requires the user to acknowledge or decide before continuing — use Modal or AlertDialog
+
+## Anti-patterns
+
+### Toasts auto-dismiss and are easy to miss; a destructive decision needs a blocking dialog the user must confirm
+
+**Bad:** `toast({ title: "Delete this account?", duration: 0 })`  
+**Good:** `<AlertDialog title="Delete this account?" />`  
+**Why:** Toasts auto-dismiss and are easy to miss; a destructive decision needs a blocking dialog the user must confirm
+
+## Related components
+
+- **Alert** (alternative): Use for persistent inline status that stays until resolved
+- **Modal** (alternative): Use when the user must acknowledge before proceeding
+
+## Accessibility rationale
+
+Toasts render into a labelled region; non-critical ones use role="status" with aria-live="polite", while destructive variants escalate to role="alert" with aria-live="assertive" so urgency is conveyed without stealing focus.
+
+## Props
+
+| Name          | Type                                                   | Required | Default | Description                                                |
+| ------------- | ------------------------------------------------------ | -------- | ------- | ---------------------------------------------------------- |
+| `title`       | `string`                                               | Yes      | —       | Title text for the component.                              |
+| `description` | `string`                                               | No       | —       | Supporting description text.                               |
+| `variant`     | `'default' \| 'success' \| 'warning' \| 'destructive'` | No       | default | Selects the visual style variant.                          |
+| `duration`    | `number`                                               | No       | 5000    | How long (ms) the toast stays visible before auto-dismiss. |
+
+## Tokens
+
+- `--cascivo-color-surface-overlay`
+- `--cascivo-color-success`
+- `--cascivo-color-warning`
+- `--cascivo-color-destructive`
+- `--cascivo-radius-md`
+- `--cascivo-z-toast`
+
+## Examples
+
+### Trigger
+
+```jsx
+const { toast } = useToast()
+toast({ title: 'Saved', variant: 'success' })
+```
+
+## Boundaries
+
+| Area     | Level    | Note                                                                                           |
+| -------- | -------- | ---------------------------------------------------------------------------------------------- |
+| variant  | strict   | Limited to default \| success \| warning \| destructive — drives color and live-region urgency |
+| duration | flexible | Consumer can tune auto-dismiss timing (default 5000ms)                                         |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Toast component (overlay). Transient notification surfaced via the useToast hook
+
+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).
+
+Toast is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface-overlay, --cascivo-color-success, --cascivo-color-warning, --cascivo-color-destructive, --cascivo-radius-md, --cascivo-z-toast
+
+Accessibility: role "status", WCAG 2.2-AA, keyboard: Tab. Keep it AA.
+
+Do not change (strict): variant — Limited to default | success | warning | destructive — drives color and live-region urgency
+Flexible: duration.
+
+Do not invent props, tokens, or global viewport media queries.
+```