@cascivo/mcp 0.2.0 → 0.3.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 urbanisierung
+Copyright (c) cascivo contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -31,26 +31,56 @@ Add it to your MCP client configuration:
 }
 ```
 
-The server speaks the MCP stdio transport. By default it reads the `registry.json` bundled with the package; override with the `CASCIVO_REGISTRY_PATH` environment variable to point at a local registry.
+The server speaks the MCP stdio transport. It is **self-contained**: the registry, token catalog, variant matrix, component context, and marketplace catalog are all bundled with the package, so discovery, token, and validation tools work offline — hosted data is only fetched as a fallback. Override the registry with the `CASCIVO_REGISTRY_PATH` environment variable; add extra registries via `CASCADE_REGISTRIES`.
 
 ## Tools
 
-| Tool                 | Input                                 | Returns                                                                                                                                 |
-| -------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `list_components`    | `{ category? }`                       | All component manifests, optionally filtered by category                                                                                |
-| `get_component`      | `{ name }`                            | The full manifest for one component                                                                                                     |
-| `search_components`  | `{ query }`                           | Components matching name, tags, or description                                                                                          |
-| `add_to_project`     | `{ name, outputDir? }`                | Runs `cascivo add <name>` as a child process                                                                                            |
-| `create_app`         | `{ name, theme?, sections?, cwd? }`   | Scaffolds a full Vite + React app (shell + side nav + theme) via `cascivo create`                                                       |
-| `create_theme`       | `{ primary, neutral, accent, name? }` | A custom theme as CSS (semantic token layer)                                                                                            |
-| `scaffold_page`      | `{ description, components? }`        | A JSX page layout string                                                                                                                |
-| `scaffold_view`      | `{ description, components? }`        | A validated starter `ViewConfig` + the bound-vocabulary `grammar` for its components                                                    |
-| `validate_view`      | `{ config }`                          | Validation errors (component, prop type/enum, refs) with exact paths                                                                    |
-| `get_view_grammar`   | `{ components? }`                     | Bound-vocabulary grammar + generation prompt for valid `ViewConfig` JSON                                                                |
-| `get_variant_matrix` | `{ role?, theme? }`                   | Deterministic intent→token map (role + state slot) + every token resolved per theme                                                     |
-| `validate_component` | `{ tsx?, css?, name? }`               | Static structural-invariant check of generated source (banned hooks, off-scale breakpoints, missing CSS fallbacks, hallucinated tokens) |
-
-`category` is one of `inputs`, `display`, `overlay`, `navigation`, `feedback`.
+### Discovery
+
+| Tool                | Input                  | Returns                                                                                            |
+| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `list_registries`   | `{}`                   | Available registries: the cascivo directory plus any configured via `CASCADE_REGISTRIES`           |
+| `list_components`   | `{ category?, type? }` | All component manifests, filterable by category and entry type (`component`, `layout`, `block`, …) |
+| `get_component`     | `{ name, registry? }`  | The full manifest (props, states, tokens, a11y, examples) — optionally from an external registry   |
+| `search_components` | `{ query, registry? }` | Fuzzy search by name, tags, or description                                                         |
+| `get_context`       | `{ name }`             | Intent, whenToUse/whenNotToUse, and authoring guidance for one component                           |
+| `select_component`  | `{ need }`             | Heuristic ranking of components for a natural-language need, with scores and reasons               |
+
+`category` is one of `inputs`, `display`, `overlay`, `navigation`, `feedback`, `chart`.
+
+### Tokens & theming
+
+| Tool                 | Input                                 | Returns                                                                                      |
+| -------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `get_tokens`         | `{ group?, layer?, includeAliases? }` | The closed token catalog — canonical names only by default, so agents never hard-code values |
+| `get_variant_matrix` | `{ role?, theme? }`                   | Deterministic intent→token map (colour role + state slot) + every token resolved per theme   |
+| `create_theme`       | `{ primary, neutral, accent, name? }` | A custom theme as CSS (semantic token layer) generated from three colors                     |
+
+### Scaffold & validate
+
+| Tool                 | Input                              | Returns                                                                                                                                 |
+| -------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `scaffold_view`      | `{ description, components? }`     | A validated starter `ViewConfig` + the bound-vocabulary `grammar` for its components                                                    |
+| `validate_view`      | `{ config }`                       | Validation errors (component, prop type/enum, refs) with exact paths                                                                    |
+| `get_view_grammar`   | `{ components? }`                  | Bound-vocabulary grammar + generation prompt for valid `ViewConfig` JSON                                                                |
+| `validate_component` | `{ tsx?, css?, name? }`            | Static structural-invariant check of generated source (banned hooks, off-scale breakpoints, missing CSS fallbacks, hallucinated tokens) |
+| `scaffold_flow`      | `{ description, steps?, layout? }` | Starter nodes/edges + ready-to-paste `<Flow />` JSX (from `@cascivo/flow`) for a diagram                                                |
+| `scaffold_page`      | `{ description, components? }`     | **Deprecated** — use `scaffold_view`; still returns a JSX scaffold plus the `scaffold_view` output                                      |
+
+### Templates
+
+| Tool             | Input                                            | Returns                                                                          |
+| ---------------- | ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `list_templates` | `{ category?, tag?, framework?, verifiedOnly? }` | Marketplace templates (whole-page compositions) from the catalog                 |
+| `get_template`   | `{ name }`                                       | One template: its components, install command, demo link, and screenshots        |
+| `add_template`   | `{ name, cwd? }`                                 | Installs a template (components + page/fixture files) by running the cascivo CLI |
+
+### Project
+
+| Tool             | Input                               | Returns                                                                           |
+| ---------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| `add_to_project` | `{ name, outputDir? }`              | Runs `cascivo add <name>` as a child process                                      |
+| `create_app`     | `{ name, theme?, sections?, cwd? }` | Scaffolds a full Vite + React app (shell + side nav + theme) via `cascivo create` |
 
 ### Bound-vocabulary generation (anti-hallucination)
 
@@ -59,11 +89,11 @@ prompt** plus a compact **allowed-vocabulary grammar** (each component → its
 props → enum/size/variant values) for emitting valid `ViewConfig` JSON rendered
 by `@cascivo/render` `<CascadeView />`. This is [OpenUI](https://openui.com)'s
 "generate the system prompt from the component library" mechanism (see
-[`docs/ROADMAP-V40.md`](../../docs/ROADMAP-V40.md)): because the grammar is
-**derived**, not authored, an LLM is structurally prevented from inventing
-components, props, or enum values, and the grammar can never drift from the
-components. Pair it with `validate_view` (which now also checks prop types/enums)
-as the enforcement backstop.
+[`ROADMAP-V40.md`](https://github.com/cascivo/cascivo/blob/main/docs/internal/ROADMAP-V40.md)):
+because the grammar is **derived**, not authored, an LLM is structurally
+prevented from inventing components, props, or enum values, and the grammar can
+never drift from the components. Pair it with `validate_view` (which also checks
+prop types/enums) as the enforcement backstop.
 
 ```ts
 import { buildGenerationPrompt, loadRegistry } from '@cascivo/mcp'
@@ -82,7 +112,7 @@ const server = createServer({ registryPath: './registry.json' })
 await server.connect(new StdioServerTransport())
 ```
 
-The pure helpers (`listComponents`, `getComponent`, `searchComponents`, `generateThemeCss`, `scaffoldPage`) are exported too, so the registry can be queried without spinning up the protocol.
+The pure helpers (`listComponents`, `getComponent`, `searchComponents`, `generateThemeCss`, `scaffoldPage`, `buildGrammar`, `buildGenerationPrompt`, `loadRegistry`) are exported too, so the registry can be queried without spinning up the protocol.
 
 ## Install
 

package/dist/context/accordion.md

@@ -0,0 +1,93 @@
+# Accordion
+
+**Category:** navigation  
+**Description:** Vertically stacked, collapsible content sections
+
+## When to use
+
+- Progressively disclosing sections of related content the user reads top to bottom
+- Reducing vertical scroll when most sections stay collapsed (FAQs, settings groups)
+- Allowing multiple sections open at once (type="multiple")
+
+## When NOT to use
+
+- Switching between mutually exclusive, equally important views — use Tabs
+- A single show/hide region — a plain disclosure is enough
+
+## Anti-patterns
+
+### A single permanently-open section adds chrome and indirection for no gain
+
+**Bad:** `<Accordion> with one item that is always open`  
+**Good:** `Render the content directly, or use a collapsible disclosure`  
+**Why:** A single permanently-open section adds chrome and indirection for no gain
+
+## Related components
+
+- **Tabs** (alternative): Tabs switch between peer views; Accordion stacks sequential sections vertically
+
+## Accessibility rationale
+
+Each trigger is a native <button> exposing aria-expanded and controlling its panel via aria-controls, so screen readers announce open/closed state and Enter/Space toggle from the platform
+
+## Props
+
+| Name            | Type                                  | Required | Default | Description                                                                    |
+| --------------- | ------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------ |
+| `type`          | `'single' \| 'multiple'`              | No       | single  | Whether one or multiple sections can be open at once ('single' \| 'multiple'). |
+| `defaultValue`  | `string \| string[]`                  | No       | —       | The initial value when uncontrolled.                                           |
+| `value`         | `string \| string[]`                  | No       | —       | The controlled value.                                                          |
+| `onValueChange` | `(value: string \| string[]) => void` | No       | —       | Called with the new value when it changes.                                     |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-radius-md`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Single
+
+```jsx
+<Accordion type="single" defaultValue="a">
+  <AccordionItem value="a">
+    <AccordionTrigger>Section</AccordionTrigger>
+    <AccordionContent>…</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Boundaries
+
+| Area               | Level    | Note                                                                      |
+| ------------------ | -------- | ------------------------------------------------------------------------- |
+| single vs multiple | flexible | type prop is free to choose based on whether sections are exclusive       |
+| token names        | strict   | Borders, surfaces, and radii must resolve to --cascivo-\* semantic tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Accordion component (navigation). Vertically stacked, collapsible content sections
+
+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).
+
+Accordion is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-color-text, --cascivo-radius-md, --cascivo-focus-ring
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): token names — Borders, surfaces, and radii must resolve to --cascivo-* semantic tokens
+Flexible: single vs multiple.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/action-sheet.md

@@ -0,0 +1,117 @@
+# ActionSheet
+
+**Category:** overlay  
+**Description:** Bottom-rising sheet of discrete actions (iOS action-sheet pattern) with a Cancel button
+
+## When to use
+
+- A short list of discrete actions on a touch surface, rising from the bottom
+- Confirming or choosing among a few operations (e.g. Share, Edit, Delete) on mobile
+- A mobile-first alternative to an anchored dropdown menu when there is no trigger anchor
+
+## When NOT to use
+
+- A single yes/no confirmation — use AlertDialog
+- A form or scrollable content — use BottomSheet or Sheet
+- A menu anchored to a trigger on desktop — use Menu or Dropdown
+
+## Anti-patterns
+
+### A one-action sheet is a confirmation; AlertDialog states the decision clearly
+
+**Bad:** `<ActionSheet actions={[{ label: "OK", onSelect }]} />`  
+**Good:** `<AlertDialog title="Delete item?" />`  
+**Why:** A one-action sheet is a confirmation; AlertDialog states the decision clearly
+
+## Related components
+
+- **BottomSheet** (alternative): Use BottomSheet for rich/resizable content; ActionSheet is a fixed list of actions
+- **Menu** (alternative): Use Menu for a trigger-anchored dropdown on pointer-first surfaces
+
+## Accessibility rationale
+
+Renders role="menu" with role="menuitem" buttons under vertical roving focus (Arrow keys, Home/End, wrapping). The title labels the menu via aria-labelledby (or a built-in label otherwise) and the description via aria-describedby. FocusScope traps and restores focus; DismissableLayer handles Escape and outside-pointer dismissal; a separate Cancel button provides an explicit non-destructive exit.
+
+## Props
+
+| Name           | Type                                  | Required | Default | Description                                                                   |
+| -------------- | ------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
+| `open`         | `boolean`                             | No       | —       | Whether the component is open (controlled).                                   |
+| `defaultOpen`  | `boolean`                             | No       | —       | Whether the component is open on first render (uncontrolled).                 |
+| `onOpenChange` | `(open: boolean) => void`             | No       | —       | Called with the next open state when it changes.                              |
+| `actions`      | `ActionSheetAction[]`                 | Yes      | —       | Choices, each with a label, onSelect, and optional destructive/disabled flags |
+| `title`        | `React.ReactNode`                     | No       | —       | Title text for the component.                                                 |
+| `description`  | `React.ReactNode`                     | No       | —       | Supporting description text.                                                  |
+| `showCancel`   | `boolean`                             | No       | true    | When true, shows a cancel button below the actions.                           |
+| `labels`       | `{ cancel?: string; label?: string }` | No       | —       | Overrides for the component’s user-visible strings (i18n).                    |
+| `className`    | `string`                              | No       | —       | Additional CSS class names merged onto the root element.                      |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-text-muted`
+- `--cascivo-radius-overlay`
+- `--cascivo-shadow-overlay`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-z-overlay`
+
+## Examples
+
+### Basic
+
+```jsx
+<ActionSheet
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  title="Share photo"
+  actions={[
+    { label: 'Copy link', onSelect: copyLink },
+    { label: 'Delete', onSelect: remove, destructive: true },
+  ]}
+/>
+```
+
+### Without cancel button
+
+Escape and outside press still dismiss the sheet.
+
+```jsx
+<ActionSheet defaultOpen showCancel={false} actions={[{ label: 'Archive', onSelect: archive }]} />
+```
+
+## Boundaries
+
+| Area       | Level    | Note                                                                               |
+| ---------- | -------- | ---------------------------------------------------------------------------------- |
+| actions    | flexible | Any number of actions; each may be destructive or disabled                         |
+| open state | flexible | Controlled (open/onOpenChange) or uncontrolled (defaultOpen)                       |
+| cancel     | flexible | showCancel toggles the separate Cancel button (Escape/outside press still dismiss) |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ActionSheet component (overlay). Bottom-rising sheet of discrete actions (iOS action-sheet pattern) with a Cancel button
+
+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).
+
+ActionSheet 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-color-text, --cascivo-color-text-subtle, --cascivo-color-text-muted, --cascivo-radius-overlay, --cascivo-shadow-overlay, --cascivo-motion-enter, --cascivo-motion-exit, --cascivo-z-overlay
+
+Accessibility: role "menu", WCAG 2.2-AA, keyboard: ArrowUp/ArrowDown/Home/End/Enter/Space/Escape. Keep it AA.
+Flexible: actions, open state, cancel.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/alert-dialog.md

@@ -0,0 +1,122 @@
+# AlertDialog
+
+**Category:** overlay  
+**Description:** Confirmation dialog requiring explicit user action; no light-dismiss
+
+## When to use
+
+- Confirming a destructive or irreversible action (delete, overwrite, sign out) before it happens
+- Interrupting a flow to force an explicit decision the user must acknowledge
+
+## When NOT to use
+
+- Showing non-critical information or forms — use Modal, which supports light-dismiss and arbitrary content
+- Confirming a low-stakes action where an undoable Toast is friendlier and less interruptive
+
+## Anti-patterns
+
+### AlertDialog only renders a title, description, and two action buttons, and is role="alertdialog" with no light-dismiss — it is built to demand a yes/no answer, not host content
+
+**Bad:** `Using AlertDialog for a multi-field form or rich content`  
+**Good:** `Use Modal for content; reserve AlertDialog for a title + description + confirm/cancel decision`  
+**Why:** AlertDialog only renders a title, description, and two action buttons, and is role="alertdialog" with no light-dismiss — it is built to demand a yes/no answer, not host content
+
+### It uses popover="manual" so it cannot be light-dismissed by design — closing must go through onConfirm/onCancel so the decision is always explicit
+
+**Bad:** `Adding a backdrop/Escape close to dismiss the dialog without choosing`  
+**Good:** `undefined`  
+**Why:** It uses popover="manual" so it cannot be light-dismissed by design — closing must go through onConfirm/onCancel so the decision is always explicit
+
+## Related components
+
+- **Modal** (alternative): Use for general dialogs with content and light-dismiss; AlertDialog is the must-acknowledge confirm
+- **Toast** (alternative): Prefer an undoable Toast for reversible low-stakes actions instead of a blocking confirm
+- **Button** (pairs-with): A Button typically triggers the action that opens the AlertDialog
+
+## Accessibility rationale
+
+Uses role="alertdialog" with aria-modal and labelled/described-by wiring so assistive tech announces it as an interruptive decision; focus moves to the cancel button on open so the safe default is selected, and popover="manual" prevents accidental dismissal that would skip the decision
+
+## Props
+
+| Name          | Type                         | Required | Default | Description                                                |
+| ------------- | ---------------------------- | -------- | ------- | ---------------------------------------------------------- |
+| `open`        | `boolean`                    | Yes      | —       | Whether the component is open (controlled).                |
+| `title`       | `string`                     | Yes      | —       | Title text for the component.                              |
+| `description` | `string`                     | Yes      | —       | Supporting description text.                               |
+| `onConfirm`   | `() => void`                 | Yes      | —       | Called when the confirm button is activated.               |
+| `onCancel`    | `() => void`                 | Yes      | —       | Called when the cancel button is activated.                |
+| `labels`      | `AlertDialogLabels`          | No       | —       | Overrides for the component’s user-visible strings (i18n). |
+| `variant`     | `'destructive' \| 'default'` | No       | default | Selects the visual style variant.                          |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-lg`
+- `--cascivo-shadow-xl`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+
+## Examples
+
+### Destructive confirm
+
+```jsx
+<AlertDialog
+  open={isOpen}
+  variant="destructive"
+  title="Delete project?"
+  description="This permanently removes the project and cannot be undone."
+  onConfirm={remove}
+  onCancel={() => setIsOpen(false)}
+/>
+```
+
+### Custom action labels
+
+```jsx
+<AlertDialog
+  open={isOpen}
+  title="Sign out?"
+  description="Unsaved changes will be lost."
+  labels={{ confirm: 'Sign out', cancel: 'Stay' }}
+  onConfirm={signOut}
+  onCancel={() => setIsOpen(false)}
+/>
+```
+
+## Boundaries
+
+| Area             | Level    | Note                                                                                                                |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| dismiss behavior | strict   | No light-dismiss — closing must go through onConfirm/onCancel                                                       |
+| action labels    | flexible | confirm/cancel copy overridable via labels; defaults come from the i18n catalog                                     |
+| token names      | strict   | Visual styling resolves to semantic --cascivo-color-\* tokens; destructive variant uses --cascivo-color-destructive |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AlertDialog component (overlay). Confirmation dialog requiring explicit user action; no light-dismiss
+
+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).
+
+AlertDialog 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, --cascivo-color-accent, --cascivo-color-destructive
+
+Accessibility: role "alertdialog", WCAG 2.2-AA, keyboard: Tab/Shift+Tab/Enter/Space. Keep it AA.
+
+Do not change (strict): dismiss behavior — No light-dismiss — closing must go through onConfirm/onCancel; token names — Visual styling resolves to semantic --cascivo-color-* tokens; destructive variant uses --cascivo-color-destructive
+Flexible: action labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/alert.md

@@ -0,0 +1,110 @@
+# Alert
+
+**Category:** display  
+**Description:** Highlights a short, important message inline
+
+## When to use
+
+- Surfacing a persistent, contextual message inline within a view (warning, error, info, success)
+- Communicating status that should stay visible until read or resolved
+- Offering an inline recovery action tied to the message (action prop)
+
+## When NOT to use
+
+- Transient confirmation that should auto-dismiss — use Toast
+- Blocking the user for a decision — use Modal or AlertDialog
+
+## Anti-patterns
+
+### Alerts persist by design; auto-hiding important inline context risks the user missing it
+
+**Bad:** `Auto-dismissing an Alert on a timer to mimic a notification`  
+**Good:** `<Toast> for ephemeral feedback`  
+**Why:** Alerts persist by design; auto-hiding important inline context risks the user missing it
+
+## Related components
+
+- **Toast** (alternative): Toast auto-dismisses and floats; Alert persists inline in the layout
+- **AlertDialog** (alternative): Use AlertDialog when the message must block and demand a choice
+
+## Accessibility rationale
+
+role="alert" makes assistive tech announce the message when it appears; the dismiss control is a real button so it is reachable and labeled, and color is paired with an icon/title so meaning is not conveyed by hue alone
+
+## Props
+
+| Name          | Type                                                             | Required | Default | Description                                          |
+| ------------- | ---------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------- |
+| `variant`     | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | No       | default | Selects the visual style variant.                    |
+| `title`       | `string`                                                         | No       | —       | Title text for the component.                        |
+| `icon`        | `ReactNode`                                                      | No       | —       | Icon element rendered in the component.              |
+| `dismissible` | `boolean`                                                        | No       | false   | When true, shows a control to dismiss the component. |
+| `onDismiss`   | `() => void`                                                     | No       | —       | Called when the component is dismissed.              |
+| `action`      | `{ label: string; onClick: () => void }`                         | No       | —       | Primary action shown in the component.               |
+
+## Tokens
+
+- `--cascivo-color-info`
+- `--cascivo-color-success`
+- `--cascivo-color-warning`
+- `--cascivo-color-destructive`
+- `--cascivo-color-border`
+- `--cascivo-radius-md`
+
+## Examples
+
+### Info
+
+```jsx
+<Alert variant="info" title="Heads up">
+  Your trial ends soon.
+</Alert>
+```
+
+### Dismissible
+
+```jsx
+<Alert variant="success" dismissible title="Saved">
+  Changes saved.
+</Alert>
+```
+
+### Actionable
+
+```jsx
+<Alert variant="warning" title="Update available" action={{ label: 'Update now', onClick: update }}>
+  A new version is ready.
+</Alert>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                             |
+| ----------- | -------- | -------------------------------------------------------------------------------- |
+| variant     | flexible | Choose the severity variant that matches the message; default is neutral         |
+| token names | strict   | Severity colors must resolve to --cascivo-color-info/success/warning/destructive |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Alert component (display). Highlights a short, important message inline
+
+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).
+
+Alert is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-info, --cascivo-color-success, --cascivo-color-warning, --cascivo-color-destructive, --cascivo-color-border, --cascivo-radius-md
+
+Accessibility: role "alert", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Severity colors must resolve to --cascivo-color-info/success/warning/destructive
+Flexible: variant.
+
+Do not invent props, tokens, or global viewport media queries.
+```