@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/icon-button.md

@@ -0,0 +1,115 @@
+# IconButton
+
+**Category:** inputs  
+**Description:** Square, icon-only button with a required accessible label
+
+## When to use
+
+- A compact, recognizable action where an icon alone communicates intent (close, edit, more)
+- Dense toolbars or table rows where a text label would not fit
+
+## When NOT to use
+
+- The action is not universally recognizable by its icon — use a Button with a text label
+- Navigating between pages — use an anchor (optionally via asChild)
+
+## Anti-patterns
+
+### An icon-only control has no visible text, so the label prop is the only accessible name screen readers can announce
+
+**Bad:** `<IconButton label=""><TrashIcon /></IconButton>`  
+**Good:** `<IconButton label="Delete item"><TrashIcon /></IconButton>`  
+**Why:** An icon-only control has no visible text, so the label prop is the only accessible name screen readers can announce
+
+## Related components
+
+- **Button** (alternative): Use a Button when the action needs a visible text label
+- **ButtonGroup** (contained-by): Icon buttons are commonly joined into a toolbar via ButtonGroup
+
+## Accessibility rationale
+
+Renders a native <button> with a mandatory aria-label so the icon-only control always exposes an accessible name; focus, role, and Enter/Space activation come from the platform
+
+## Props
+
+| Name       | Type                                         | Required | Default | Description                                                                                       |
+| ---------- | -------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `label`    | `string`                                     | Yes      | —       | Text label for the control.                                                                       |
+| `icon`     | `React.ReactNode`                            | No       | —       | Icon element rendered in the component.                                                           |
+| `variant`  | `'ghost' \| 'outline' \| 'filled'`           | No       | ghost   | Selects the visual style variant.                                                                 |
+| `size`     | `'sm' \| 'md' \| 'lg'`                       | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').                                             |
+| `asChild`  | `boolean`                                    | No       | false   | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
+| `disabled` | `boolean`                                    | No       | false   | When true, disables the control and removes it from the tab order.                                |
+| `onClick`  | `React.MouseEventHandler<HTMLButtonElement>` | No       | —       | Called when the element is clicked.                                                               |
+
+## Tokens
+
+- `--cascivo-control-height-sm`
+- `--cascivo-control-height-md`
+- `--cascivo-control-height-lg`
+- `--cascivo-button-radius`
+- `--cascivo-radius-control`
+- `--cascivo-color-primary`
+- `--cascivo-color-primary-fg`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-surface`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Ghost
+
+```jsx
+<IconButton label="Settings">
+  <GearIcon />
+</IconButton>
+```
+
+### Filled
+
+```jsx
+<IconButton label="Add" variant="filled" icon={<PlusIcon />} />
+```
+
+### As link
+
+```jsx
+<IconButton label="Home" asChild>
+  <a href="/">
+    <HomeIcon />
+  </a>
+</IconButton>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                                  |
+| ----------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| token names | strict   | Sizing must resolve to --cascivo-control-height-\* so it stays square and aligned with other controls |
+| icon choice | flexible | Any single icon node; consumer owns the icon set                                                      |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo IconButton component (inputs). Square, icon-only button with a required accessible label
+
+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).
+
+IconButton is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-control-height-sm, --cascivo-control-height-md, --cascivo-control-height-lg, --cascivo-button-radius, --cascivo-radius-control, --cascivo-color-primary, --cascivo-color-primary-fg, --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-color-surface, --cascivo-focus-ring
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): token names — Sizing must resolve to --cascivo-control-height-* so it stays square and aligned with other controls
+Flexible: icon choice.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/image.md

@@ -0,0 +1,115 @@
+# Image
+
+**Category:** display  
+**Description:** Image with load state, blur-up placeholder, graceful fallback, and optional zoom
+
+## When to use
+
+- Displaying a content image that should show a placeholder while loading and degrade gracefully on error
+- Photos, thumbnails, or media that benefit from a blur-up placeholder or hover zoom
+- Any image where a broken src should fall back rather than show a broken-image icon
+
+## When NOT to use
+
+- Identity thumbnails for a person or entity — use Avatar
+- Purely decorative shapes or a fixed-ratio layout box with no load behavior — use AspectRatio
+
+## Anti-patterns
+
+### Without alt the image is invisible to assistive tech; pass an empty alt only for decorative images
+
+**Bad:** `<Image src="/photo.jpg" /> with no alt`  
+**Good:** `<Image src="/photo.jpg" alt="Sunset over the bay" />`  
+**Why:** Without alt the image is invisible to assistive tech; pass an empty alt only for decorative images
+
+## Related components
+
+- **Avatar** (alternative): Use Avatar for identity thumbnails with an initials fallback
+- **AspectRatio** (alternative): Use AspectRatio for a ratio box that does not own image load behavior
+
+## Accessibility rationale
+
+role="img" with alt names the image; on error it shows a fallback image or neutral box so layout survives; the blur-up and zoom transitions are disabled under prefers-reduced-motion
+
+## Props
+
+| Name            | Type                                       | Required | Default | Description                                                            |
+| --------------- | ------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------- |
+| `src`           | `string`                                   | No       | —       | Image source URL.                                                      |
+| `alt`           | `string`                                   | No       | —       | Alternative text describing the image.                                 |
+| `fallbackSrc`   | `string`                                   | No       | —       | Image shown if src fails to load                                       |
+| `width`         | `string \| number`                         | No       | —       | Width of the component.                                                |
+| `height`        | `string \| number`                         | No       | —       | Height of the component.                                               |
+| `radius`        | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | No       | md      | Corner radius of the image ('none' \| 'sm' \| 'md' \| 'lg' \| 'full'). |
+| `zoom`          | `boolean`                                  | No       | false   | When true, zooms the image on hover.                                   |
+| `removeWrapper` | `boolean`                                  | No       | false   | Render a bare <img> with no wrapper, placeholder, or zoom              |
+| `isBlurred`     | `boolean`                                  | No       | false   | When true, renders a blurred backdrop behind the image.                |
+
+## Tokens
+
+- `--cascivo-radius-none`
+- `--cascivo-radius-sm`
+- `--cascivo-radius-md`
+- `--cascivo-radius-lg`
+- `--cascivo-radius-full`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-space-12`
+
+## Examples
+
+### Basic
+
+```jsx
+<Image src="/photo.jpg" alt="A photo" width={320} height={240} />
+```
+
+### With fallback
+
+```jsx
+<Image src="/broken.jpg" fallbackSrc="/placeholder.jpg" alt="A photo" />
+```
+
+### Blurred placeholder
+
+```jsx
+<Image src="/photo.jpg" alt="A photo" isBlurred />
+```
+
+### Hover zoom
+
+```jsx
+<Image src="/photo.jpg" alt="A photo" zoom />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                              |
+| ----------- | -------- | ----------------------------------------------------------------- |
+| radius      | flexible | Pick the corner radius that matches the surrounding surface       |
+| token names | strict   | Radius and placeholder colors 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 Image component (display). Image with load state, blur-up placeholder, graceful fallback, and optional zoom
+
+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).
+
+Image is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-radius-none, --cascivo-radius-sm, --cascivo-radius-md, --cascivo-radius-lg, --cascivo-radius-full, --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-space-12
+
+Accessibility: role "img", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Radius and placeholder colors must resolve to --cascivo-* tokens
+Flexible: radius.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/indicator.md

@@ -0,0 +1,95 @@
+# Indicator
+
+**Category:** layout  
+**Description:** Positions an overlay element (badge, dot, count) at a corner of its child
+
+## When to use
+
+- Notification counts on icon buttons
+- Status dots on avatars
+
+## When NOT to use
+
+- Inline badges within text — use Badge directly
+- Status messages below a field — use a form hint or Alert
+
+## Related components
+
+- **Badge** (contained-by): Badge is the most common overlay content placed inside Indicator
+- **Avatar** (pairs-with): Indicator is frequently used to attach a status dot to an Avatar
+
+## Accessibility rationale
+
+The overlay is marked aria-hidden because it is a visual affordance — the underlying control (button, avatar) carries its own accessible label. Screen-reader users should receive the count or status through the control's accessible name or a live region, not from the overlay div.
+
+## Props
+
+| Name        | Type                                                         | Required | Default | Description                                              |
+| ----------- | ------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------- |
+| `children`  | `React.ReactNode`                                            | Yes      | —       | Content rendered inside the component.                   |
+| `overlay`   | `React.ReactNode`                                            | Yes      | —       | The element to display at the corner (badge, dot, count) |
+| `placement` | `'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | No       | top-end | Placement relative to the trigger.                       |
+| `className` | `string`                                                     | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Examples
+
+### Notification count
+
+Notification count badge on an icon button
+
+```jsx
+<Indicator overlay={<Badge>3</Badge>}>
+  <Button variant="ghost">
+    <Icon name="bell" />
+  </Button>
+</Indicator>
+```
+
+### Online status
+
+Online status dot on an avatar
+
+```jsx
+<Indicator overlay={<span className="status-dot" />} placement="bottom-end">
+  <Avatar src="/user.jpg" />
+</Indicator>
+```
+
+### Bottom-start placement
+
+Indicator positioned at the bottom-start corner
+
+```jsx
+<Indicator overlay={<Badge variant="destructive">!</Badge>} placement="bottom-start">
+  <Card>Content</Card>
+</Indicator>
+```
+
+## Boundaries
+
+| Area      | Level    | Note                                                                                          |
+| --------- | -------- | --------------------------------------------------------------------------------------------- |
+| placement | flexible | All four corners are supported; top-end is the most common convention for notification counts |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Indicator component (layout). Positions an overlay element (badge, dot, count) at a corner of its child
+
+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).
+
+Indicator is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+Flexible: placement.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/inline-loading.md

@@ -0,0 +1,101 @@
+# InlineLoading
+
+**Category:** feedback  
+**Description:** Compact inline status indicator that pairs a label with a loading, success, or error state
+
+## When to use
+
+- Showing the progress of a single inline action — a Save button that becomes "Saving… / Saved / Failed"
+- Communicating async status next to a control without occupying its own block or modal
+- Reflecting a terminal success or error state that should be announced to assistive tech
+
+## When NOT to use
+
+- Page- or section-level loading where layout space is reserved — use Skeleton or Spinner
+- Persistent, multi-line messages with recovery actions — use Alert or Notification
+- Determinate progress with a known percentage — use a progress bar
+
+## Anti-patterns
+
+### A single status keeps the icon, color, and announced label in sync and prevents mismatched states
+
+**Bad:** `<Spinner /> with separate manually-managed success and error markup`  
+**Good:** `<InlineLoading status={status} /> driving icon and color from one status prop`  
+**Why:** A single status keeps the icon, color, and announced label in sync and prevents mismatched states
+
+## Related components
+
+- **Spinner** (contains): InlineLoading renders a Spinner for its active state and adds finished/error icons plus a label
+- **Alert** (alternative): Use Alert for persistent messages that need a title, body, and actions rather than a terse status
+
+## Accessibility rationale
+
+role="status" with aria-live="polite" announces the label when the status changes; the icon is decorative (aria-hidden) so meaning is carried by the text and color is never the sole signal
+
+## Props
+
+| Name     | Type                                                     | Required | Default | Description                                                |
+| -------- | -------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------- |
+| `status` | `'inactive' \| 'active' \| 'finished' \| 'error'`        | Yes      | —       | Status state.                                              |
+| `label`  | `ReactNode`                                              | No       | —       | Text label for the control.                                |
+| `labels` | `{ active?: string; finished?: string; error?: string }` | No       | —       | Overrides for the component’s user-visible strings (i18n). |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-success`
+- `--cascivo-color-destructive`
+- `--cascivo-motion-enter`
+
+## Examples
+
+### Active
+
+```jsx
+<InlineLoading status="active" />
+```
+
+### Finished
+
+```jsx
+<InlineLoading status="finished" label="Saved" />
+```
+
+### Error
+
+```jsx
+<InlineLoading status="error" label="Save failed" />
+```
+
+## Boundaries
+
+| Area             | Level    | Note                                                                                             |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| label            | flexible | Defaults come from the i18n catalog per status; override with label or the per-status labels map |
+| status semantics | strict   | active must show a spinner, finished a success icon, error an error icon — do not repurpose      |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo InlineLoading component (feedback). Compact inline status indicator that pairs a label with a loading, success, or 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).
+
+InlineLoading is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-success, --cascivo-color-destructive, --cascivo-motion-enter
+
+Accessibility: role "status", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): status semantics — active must show a spinner, finished a success icon, error an error icon — do not repurpose
+Flexible: label.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/input-group.md

@@ -0,0 +1,122 @@
+# InputGroup
+
+**Category:** inputs  
+**Description:** Prefix/suffix addon wrapper for Input; InputGroupAddon renders inline icons/units inside the field border; ButtonGroup collapses adjacent button borders
+
+## When to use
+
+- Attaching a prefix/suffix addon (protocol, currency, unit) to an Input so it reads as one field
+- Placing a leading or trailing inline icon/unit inside the field border via InputGroupAddon
+- Grouping adjacent buttons with collapsed shared borders via ButtonGroup
+
+## When NOT to use
+
+- A standalone field with no adornment — use Input directly
+- Conveying meaning that the user must read via an addon — decorative addons are aria-hidden
+
+## Anti-patterns
+
+### InputGroupAddon is aria-hidden and decorative, so screen readers never announce it
+
+**Bad:** `<InputGroupAddon>Required</InputGroupAddon> to convey field status`  
+**Good:** `Use the Input error/hint props for meaningful text`  
+**Why:** InputGroupAddon is aria-hidden and decorative, so screen readers never announce it
+
+## Related components
+
+- **Input** (contains): InputGroup composes around an Input to add prefix/suffix addons
+- **Button** (contains): ButtonGroup arranges adjacent Buttons with merged borders
+
+## Accessibility rationale
+
+Inline addons are marked aria-hidden because they are purely decorative units/icons, so the wrapped Input keeps its own accessible name; ButtonGroup uses role="group" to convey that its buttons form a related set.
+
+## Props
+
+| Name       | Type        | Required | Default | Description                                            |
+| ---------- | ----------- | -------- | ------- | ------------------------------------------------------ |
+| `prefix`   | `ReactNode` | No       | —       | Content rendered before the input (leading adornment). |
+| `suffix`   | `ReactNode` | No       | —       | Content rendered after the input (trailing adornment). |
+| `children` | `ReactNode` | Yes      | —       | Content rendered inside the component.                 |
+
+## Tokens
+
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-text-subtle`
+- `--cascivo-radius-input`
+
+## Examples
+
+### With prefix
+
+```jsx
+<InputGroup prefix="https://">
+  <Input placeholder="example.com" />
+</InputGroup>
+```
+
+### With leading icon addon
+
+```jsx
+<InputGroup>
+  <InputGroupAddon>
+    <svg viewBox="0 0 16 16" width="16" height="16">
+      <circle cx="6" cy="6" r="4" fill="none" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M10 10l3 3" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  </InputGroupAddon>
+  <Input placeholder="Search…" aria-label="Search" />
+</InputGroup>
+```
+
+### With trailing unit addon
+
+```jsx
+<InputGroup>
+  <Input placeholder="0.00" aria-label="Weight" />
+  <InputGroupAddon align="inline-end">kg</InputGroupAddon>
+</InputGroup>
+```
+
+### ButtonGroup
+
+```jsx
+<ButtonGroup>
+  <Button>Left</Button>
+  <Button>Right</Button>
+</ButtonGroup>
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                                                      |
+| --------------- | -------- | ----------------------------------------------------------------------------------------- |
+| token names     | strict   | Addon background, border, text, and radius must resolve to the listed --cascivo-\* tokens |
+| addon alignment | flexible | InputGroupAddon align is inline-start (leading) or inline-end (trailing)                  |
+| addon content   | flexible | prefix/suffix and addon children accept arbitrary ReactNode                               |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo InputGroup component (inputs). Prefix/suffix addon wrapper for Input; InputGroupAddon renders inline icons/units inside the field border; ButtonGroup collapses adjacent button borders
+
+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).
+
+InputGroup is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-color-text-subtle, --cascivo-radius-input
+
+Accessibility: role "generic", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Addon background, border, text, and radius must resolve to the listed --cascivo-* tokens
+Flexible: addon alignment, addon content.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/input.md

@@ -0,0 +1,101 @@
+# Input
+
+**Category:** inputs  
+**Description:** Text input field with optional label, hint, and error state
+
+## When to use
+
+- Collecting a single line of free-form text from the user
+- Pairing a labelled field with optional hint and validation error messaging
+- As a field control inside a Form, wired via form.field()
+
+## When NOT to use
+
+- Multi-line text — use Textarea
+- Choosing from a fixed list of options — use Select, Combobox, or MultiSelect
+- Editing one read-only value in place — use Editable
+
+## Anti-patterns
+
+### Placeholder text disappears on input and is not a substitute for a persistent, programmatically associated label
+
+**Bad:** `<Input placeholder="Email" /> with no label`  
+**Good:** `<Input label="Email" placeholder="you@example.com" />`  
+**Why:** Placeholder text disappears on input and is not a substitute for a persistent, programmatically associated label
+
+## Related components
+
+- **Form** (contained-by): Input is the primary field control wired into a Form store
+- **InputGroup** (pairs-with): Wrap Input in InputGroup to add prefix/suffix addons
+- **Textarea** (alternative): Use Textarea for multi-line input
+
+## Accessibility rationale
+
+The label is associated to the input via htmlFor/id, error text is linked through aria-describedby and announced with role="alert", and aria-invalid is set when an error is present so assistive tech reports the field as erroneous; visual focus state is driven by CSS, not tracked imperatively.
+
+## 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.                     |
+| `size`        | `'sm' \| 'md' \| 'lg'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `placeholder` | `string`               | No       | —       | Placeholder text shown when the field is empty.                    |
+| `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
+<Input label="Email" placeholder="you@example.com" />
+```
+
+### With error
+
+```jsx
+<Input label="Email" error="Invalid email address" />
+```
+
+## Boundaries
+
+| Area                      | Level    | Note                                                                                                        |
+| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| token names               | strict   | Surface, border, accent, destructive, radius, and focus-ring must resolve to the listed --cascivo-\* tokens |
+| label / hint / error copy | flexible | Free, within content tone guidance                                                                          |
+| size                      | flexible | sm \| md \| lg, defaulting to md                                                                            |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Input component (inputs). Text input field 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).
+
+Input 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 — Surface, border, accent, destructive, radius, and focus-ring must resolve to the listed --cascivo-* tokens
+Flexible: label / hint / error copy, size.
+
+Do not invent props, tokens, or global viewport media queries.
+```