@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/menu.md

@@ -0,0 +1,108 @@
+# Menu
+
+**Category:** overlay  
+**Description:** Dropdown menu with keyboard navigation, built on usePopover
+
+## When to use
+
+- Presenting a list of actions or commands triggered from a button
+- Action lists that need arrow-key navigation and Enter/Space activation
+- Grouping related commands with separators behind a single trigger
+
+## When NOT to use
+
+- Selecting a persistent value from options — use Select or MultiSelect
+- Right-click contextual actions on an element — use ContextMenu
+- A single non-list action — use a Button
+
+## Anti-patterns
+
+### Menu items use role="menuitem" and close on activation — they are not selectable options and do not model a chosen value
+
+**Bad:** `Using Menu items to pick a form value and showing the choice as selected`  
+**Good:** `Use Select for value selection; Menu items are one-shot actions`  
+**Why:** Menu items use role="menuitem" and close on activation — they are not selectable options and do not model a chosen value
+
+## Related components
+
+- **ContextMenu** (alternative): Use ContextMenu for right-click activation on a target element
+- **Select** (alternative): Use Select when the user is choosing a value rather than firing an action
+- **Button** (pairs-with): A button (MenuTrigger) opens the menu
+
+## Accessibility rationale
+
+The trigger exposes aria-haspopup="menu" and aria-expanded, the panel is role="menu" with role="menuitem" children, focus moves to the first enabled item on open, ArrowUp/ArrowDown rove focus between items, disabled items are aria-disabled and removed from the tab order, and separators use role="separator".
+
+## Props
+
+| Name       | Type              | Required | Default | Description                                                         |
+| ---------- | ----------------- | -------- | ------- | ------------------------------------------------------------------- |
+| `children` | `React.ReactNode` | Yes      | —       | The MenuTrigger first, followed by MenuItem/MenuSeparator children. |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-md`
+- `--cascivo-shadow-md`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-color-bg-subtle`
+
+## Examples
+
+### Basic
+
+```jsx
+<Menu>
+  <MenuTrigger>Options</MenuTrigger>
+  <MenuItem onSelect={rename}>Rename</MenuItem>
+  <MenuItem onSelect={duplicate}>Duplicate</MenuItem>
+</Menu>
+```
+
+### With separator and disabled item
+
+```jsx
+<Menu>
+  <MenuTrigger aria-label="More actions">…</MenuTrigger>
+  <MenuItem onSelect={share}>Share</MenuItem>
+  <MenuSeparator />
+  <MenuItem onSelect={remove} disabled>
+    Delete
+  </MenuItem>
+</Menu>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                       |
+| ------------ | -------- | ------------------------------------------------------------------------------------------ |
+| token names  | strict   | Surface, border, radius, shadow, and motion must resolve to the listed --cascivo-\* tokens |
+| item content | flexible | MenuItem accepts arbitrary children; onSelect defines the action                           |
+| composition  | flexible | MenuItem and MenuSeparator can be mixed freely under the trigger                           |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Menu component (overlay). Dropdown menu with keyboard navigation, built on usePopover
+
+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).
+
+Menu is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-md, --cascivo-shadow-md, --cascivo-motion-enter, --cascivo-motion-exit, --cascivo-color-bg-subtle
+
+Accessibility: role "menu", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Enter/Space/Escape. Keep it AA.
+
+Do not change (strict): token names — Surface, border, radius, shadow, and motion must resolve to the listed --cascivo-* tokens
+Flexible: item content, composition.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/menubar.md

@@ -0,0 +1,92 @@
+# Menubar
+
+**Category:** navigation  
+**Description:** Horizontal application menu bar with keyboard-navigable dropdown menus
+
+## When to use
+
+- A persistent application-style command bar (File / Edit / View) where each top-level entry opens a menu of actions
+- Desktop-like apps that expose grouped commands across a horizontal bar
+
+## When NOT to use
+
+- Site or section navigation between pages or destinations — use NavigationMenu
+- A single trigger that opens one menu of actions — use a Menu/Dropdown
+- Switching between peer content panels — use Tabs
+
+## Anti-patterns
+
+### menubar implies commands/actions within the current view, not navigation to other pages
+
+**Bad:** `Using Menubar entries as page links`  
+**Good:** `<NavigationMenu> for navigating between destinations`  
+**Why:** menubar implies commands/actions within the current view, not navigation to other pages
+
+## Related components
+
+- **NavigationMenu** (alternative): NavigationMenu navigates between destinations; Menubar invokes commands
+- **Menu** (contains): Each Menubar entry behaves like a single Menu anchored under its trigger
+
+## Accessibility rationale
+
+Implements the WAI-ARIA menubar pattern: a roving-tabindex row of menuitem triggers (Left/Right/Home/End) where ArrowDown opens the menu and focuses its first item, Up/Down move within the menu, and Escape closes and restores focus to the trigger
+
+## Props
+
+| Name         | Type            | Required | Default | Description                                              |
+| ------------ | --------------- | -------- | ------- | -------------------------------------------------------- |
+| `menus`      | `MenubarMenu[]` | Yes      | —       | The top-level menus to render.                           |
+| `aria-label` | `string`        | Yes      | —       | Accessible label used when no visible label is present.  |
+| `className`  | `string`        | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-border`
+- `--cascivo-focus-ring`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Basic
+
+```jsx
+<Menubar
+  aria-label="Main"
+  menus={[{ id: 'file', label: 'File', items: [{ id: 'new', label: 'New', onSelect: () => {} }] }]}
+/>
+```
+
+## Boundaries
+
+| Area         | Level  | Note                                                                               |
+| ------------ | ------ | ---------------------------------------------------------------------------------- |
+| menu content | strict | Menus are described by data (menus prop) so roles and keyboard wiring stay correct |
+| token names  | strict | Surface, borders, and focus ring must resolve to --cascivo-\* tokens               |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Menubar component (navigation). Horizontal application menu bar with keyboard-navigable dropdown menus
+
+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).
+
+Menubar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-bg-subtle, --cascivo-color-text, --cascivo-color-border, --cascivo-focus-ring, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "menubar", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowDown/ArrowUp/Home/End/Enter/Escape. Keep it AA.
+
+Do not change (strict): menu content — Menus are described by data (menus prop) so roles and keyboard wiring stay correct; token names — Surface, borders, and focus ring must resolve to --cascivo-* tokens
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/modal.md

@@ -0,0 +1,96 @@
+# Modal
+
+**Category:** overlay  
+**Description:** Accessible dialog overlay using native <dialog> element
+
+## When to use
+
+- Presenting focused content or a task that must interrupt the current flow
+- Confirmations and forms that require the user to act before continuing
+- Cases needing a modal backdrop, focus trap, and Escape-to-close from the native <dialog>
+
+## When NOT to use
+
+- Anchored, non-modal content next to a trigger — use Popover
+- A side panel or drawer for secondary content — use Sheet
+- A destructive confirmation with a clear yes/no decision — use AlertDialog
+
+## Anti-patterns
+
+### The open prop drives showModal()/close() on the native dialog, which manages the top layer, backdrop, and focus trap; hiding with CSS breaks all three
+
+**Bad:** `Rendering <Modal> mounted but driving visibility with CSS display`  
+**Good:** `Control visibility with the open prop`  
+**Why:** The open prop drives showModal()/close() on the native dialog, which manages the top layer, backdrop, and focus trap; hiding with CSS breaks all three
+
+## Related components
+
+- **AlertDialog** (alternative): Use AlertDialog for a focused confirm/cancel decision, especially destructive ones
+- **Sheet** (alternative): Use Sheet for an edge-anchored drawer rather than a centered dialog
+- **Popover** (alternative): Use Popover for lightweight, non-modal content anchored to a trigger
+
+## Accessibility rationale
+
+Built on the native <dialog> element so showModal() provides a real focus trap, top-layer rendering, and inert background for free; role="dialog" plus aria-labelledby/aria-describedby tie the title and description to the dialog, and Escape closes via the platform.
+
+## Props
+
+| Name          | Type                   | Required | Default | Description                                           |
+| ------------- | ---------------------- | -------- | ------- | ----------------------------------------------------- |
+| `open`        | `boolean`              | No       | false   | Whether the component is open (controlled).           |
+| `onClose`     | `() => void`           | No       | —       | Called when the component is closed.                  |
+| `title`       | `string`               | No       | —       | Title text for the component.                         |
+| `description` | `string`               | No       | —       | Supporting description text.                          |
+| `size`        | `'sm' \| 'md' \| 'lg'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+| `draggable`   | `boolean`              | No       | false   | Allow dragging the dialog by its header               |
+
+## Tokens
+
+- `--cascivo-color-surface-overlay`
+- `--cascivo-color-border`
+- `--cascivo-radius-modal`
+- `--cascivo-shadow-xl`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic modal
+
+```jsx
+<Modal open={isOpen} onClose={() => setIsOpen(false)} title="Confirm action">
+  <p>Are you sure?</p>
+</Modal>
+```
+
+## Boundaries
+
+| Area                       | Level    | Note                                                                                                   |
+| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| token names                | strict   | Overlay surface, border, radius, shadow, and focus-ring must resolve to the listed --cascivo-\* tokens |
+| size                       | flexible | sm \| md \| lg, defaulting to md                                                                       |
+| title / description / body | flexible | All optional; body accepts arbitrary children                                                          |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Modal component (overlay). Accessible dialog overlay using native <dialog> element
+
+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).
+
+Modal is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface-overlay, --cascivo-color-border, --cascivo-radius-modal, --cascivo-shadow-xl, --cascivo-focus-ring
+
+Accessibility: role "dialog", WCAG 2.2-AA, keyboard: Escape/Tab/Shift+Tab. Keep it AA.
+
+Do not change (strict): token names — Overlay surface, border, radius, shadow, and focus-ring must resolve to the listed --cascivo-* tokens
+Flexible: size, title / description / body.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/multi-select.md

@@ -0,0 +1,104 @@
+# MultiSelect
+
+**Category:** inputs  
+**Description:** Searchable multi-value select with popover listbox
+
+## When to use
+
+- Selecting several values at once from a known list of options
+- Lists long enough that the built-in search/filter helps the user find options
+- Cases needing a compact trigger that summarizes the selected count
+
+## When NOT to use
+
+- Choosing exactly one value — use Select
+- Allowing free-text entries not in a predefined list — use Combobox or TagsInput
+- A handful of always-visible options — use a Checkbox group
+
+## Anti-patterns
+
+### Selection is fully controlled; the listbox reflects value, so dropping the update leaves checkboxes out of sync with state
+
+**Bad:** `<MultiSelect value={value} onValueChange={...} /> without keeping value in sync`  
+**Good:** `Store the selected string[] and update it from onValueChange every toggle`  
+**Why:** Selection is fully controlled; the listbox reflects value, so dropping the update leaves checkboxes out of sync with state
+
+## Related components
+
+- **Select** (alternative): Use Select for single-value selection
+- **Combobox** (alternative): Use Combobox when users may type values not in the list
+- **Checkbox** (alternative): Use a Checkbox group for a small set of always-visible options
+
+## Accessibility rationale
+
+The trigger advertises aria-haspopup="listbox" and aria-expanded, the panel is role="listbox" with aria-multiselectable, each option is role="option" with aria-selected reflecting membership and aria-disabled for unavailable ones; ArrowUp/ArrowDown move the active option, Space/Enter toggle it, and Escape closes the popover.
+
+## Props
+
+| Name            | Type                    | Required | Default | Description                                                        |
+| --------------- | ----------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `options`       | `MultiSelectOption[]`   | Yes      | —       | The selectable options.                                            |
+| `value`         | `string[]`              | Yes      | —       | The controlled value.                                              |
+| `onValueChange` | `(v: string[]) => void` | Yes      | —       | Called with the new value when it changes.                         |
+| `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. |
+| `labels`        | `MultiSelectLabels`     | No       | —       | Overrides for the component’s user-visible strings (i18n).         |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-radius-input`
+- `--cascivo-radius-md`
+- `--cascivo-shadow-md`
+- `--cascivo-focus-ring`
+- `--cascivo-motion-enter`
+
+## Examples
+
+### Basic
+
+```jsx
+<MultiSelect
+  options={[
+    { label: 'One', value: '1' },
+    { label: 'Two', value: '2' },
+  ]}
+  value={[]}
+  onValueChange={() => {}}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                                           |
+| ----------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| token names | strict   | Surface, border, accent, radius, shadow, focus-ring, and motion must resolve to the listed --cascivo-\* tokens |
+| labels      | flexible | placeholder, selected(count), search, and noResults are overridable                                            |
+| options     | flexible | Caller supplies the option list and may mark individual options disabled                                       |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo MultiSelect component (inputs). Searchable multi-value select with popover listbox
+
+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).
+
+MultiSelect is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-accent, --cascivo-radius-input, --cascivo-radius-md, --cascivo-shadow-md, --cascivo-focus-ring, --cascivo-motion-enter
+
+Accessibility: role "listbox", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Space/Enter/Escape. Keep it AA.
+
+Do not change (strict): token names — Surface, border, accent, radius, shadow, focus-ring, and motion must resolve to the listed --cascivo-* tokens
+Flexible: labels, options.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/native-select.md

@@ -0,0 +1,118 @@
+# NativeSelect
+
+**Category:** inputs  
+**Description:** A styled native <select> that keeps platform form/keyboard behavior with a custom chevron and focus ring
+
+## When to use
+
+- A standard single-choice dropdown where native behavior and form integration matter most
+- Mobile-first forms that should use the platform picker UI
+- Pairing with a Field/Label inside a regular HTML form
+
+## When NOT to use
+
+- Multi-select, search/typeahead, or rich option rendering — use the custom Select/Combobox
+- A handful of mutually exclusive options where radios read better
+
+## Anti-patterns
+
+### Native <option> cannot render icons or be searched; use a custom listbox for rich options
+
+**Bad:** `<NativeSelect options={oneHundredOptionsWithIcons} />`  
+**Good:** `<Combobox options={...} />`  
+**Why:** Native <option> cannot render icons or be searched; use a custom listbox for rich options
+
+## Related components
+
+- **Select** (alternative): Custom-rendered listbox for richer options at the cost of native form/keyboard behavior
+- **RadioCard** (alternative): Better for a small fixed set of mutually exclusive choices shown inline
+
+## Accessibility rationale
+
+It is a real <select>, so the browser provides the combobox role, keyboard interaction, and announcement. aria-invalid is set when invalid; the placeholder is a disabled hidden first option so it shows but is not selectable.
+
+## Props
+
+| Name           | Type                                          | Required | Default | Description                                                        |
+| -------------- | --------------------------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `options`      | `NativeSelectOption[]`                        | No       | —       | Options to render. Alternatively pass <option> children.           |
+| `children`     | `React.ReactNode`                             | No       | —       | Raw <option> children (used when options is not provided).         |
+| `size`         | `'sm' \| 'md' \| 'lg'`                        | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `invalid`      | `boolean`                                     | No       | —       | Marks the control as invalid for error styling and a11y.           |
+| `placeholder`  | `string`                                      | No       | —       | Placeholder rendered as a disabled, hidden first option.           |
+| `value`        | `string`                                      | No       | —       | The controlled value.                                              |
+| `defaultValue` | `string`                                      | No       | —       | The initial value when uncontrolled.                               |
+| `onChange`     | `React.ChangeEventHandler<HTMLSelectElement>` | No       | —       | Called when the selected value changes.                            |
+| `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-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-color-text-muted`
+- `--cascivo-radius-field`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<NativeSelect
+  placeholder="Choose a country"
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'de', label: 'Germany' },
+  ]}
+  onChange={(e) => setCountry(e.target.value)}
+/>
+```
+
+### Option children
+
+```jsx
+<NativeSelect size="sm" defaultValue="light" aria-label="Theme">
+  <option value="light">Light</option>
+  <option value="dark">Dark</option>
+</NativeSelect>
+```
+
+### Invalid
+
+```jsx
+<NativeSelect invalid placeholder="Required" options={countries} />
+```
+
+## Boundaries
+
+| Area    | Level    | Note                                                       |
+| ------- | -------- | ---------------------------------------------------------- |
+| options | flexible | Pass an options array or raw <option> children             |
+| value   | flexible | Controlled (value/onChange) or uncontrolled (defaultValue) |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo NativeSelect component (inputs). A styled native <select> that keeps platform form/keyboard behavior with a custom chevron and focus ring
+
+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).
+
+NativeSelect is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-accent, --cascivo-color-destructive, --cascivo-color-text-muted, --cascivo-radius-field, --cascivo-focus-ring
+
+Accessibility: role "combobox", WCAG 2.2-AA, keyboard: ArrowUp/ArrowDown/Enter/Space/Home/End. Keep it AA.
+Flexible: options, value.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/navigation-menu.md

@@ -0,0 +1,95 @@
+# NavigationMenu
+
+**Category:** navigation  
+**Description:** Site navigation bar with links and dropdown flyout panels
+
+## When to use
+
+- Primary site navigation where some destinations are plain links and others reveal a flyout of grouped links
+- A header nav bar that mixes direct links with rich dropdown panels
+
+## When NOT to use
+
+- Application commands and actions grouped under File/Edit/View — use Menubar
+- A single trigger opening a list of actions — use a Menu/Dropdown
+- Switching between peer content panels in place — use Tabs
+
+## Anti-patterns
+
+### navigation landmark implies moving between destinations, not invoking actions
+
+**Bad:** `Putting action commands (Save, Delete) inside NavigationMenu flyouts`  
+**Good:** `<Menubar> or <Menu> for commands; NavigationMenu is for destinations`  
+**Why:** navigation landmark implies moving between destinations, not invoking actions
+
+## Related components
+
+- **Menubar** (alternative): Menubar invokes application commands; NavigationMenu navigates to destinations
+- **Tabs** (alternative): Tabs swap in-page panels; NavigationMenu links to other destinations
+
+## Accessibility rationale
+
+Wrapped in a navigation landmark with a roving-tabindex row of links and disclosure triggers; triggers expose aria-expanded/aria-controls onto a flyout panel, and outside-pointer or Escape dismisses the open panel and restores trigger focus
+
+## Props
+
+| Name          | Type                                   | Required | Default | Description                                              |
+| ------------- | -------------------------------------- | -------- | ------- | -------------------------------------------------------- |
+| `items`       | `NavigationMenuItem[]`                 | Yes      | —       | The items to render.                                     |
+| `aria-label`  | `string`                               | No       | —       | Accessible label used when no visible label is present.  |
+| `orientation` | `'horizontal' \| 'vertical' \| 'both'` | No       | —       | Layout orientation of the component.                     |
+| `className`   | `string`                               | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-border`
+- `--cascivo-focus-ring`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Basic
+
+```jsx
+<NavigationMenu
+  aria-label="Main"
+  items={[
+    { id: 'home', label: 'Home', href: '/' },
+    { id: 'products', label: 'Products', content: <ul>…</ul> },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                          |
+| ------------- | -------- | ----------------------------------------------------------------------------- |
+| orientation   | flexible | horizontal (default) or vertical roving navigation                            |
+| panel content | flexible | content is arbitrary ReactNode; links without content render as plain anchors |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo NavigationMenu component (navigation). Site navigation bar with links and dropdown flyout panels
+
+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).
+
+NavigationMenu is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-bg-subtle, --cascivo-color-text, --cascivo-color-border, --cascivo-focus-ring, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "navigation", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/Home/End/Enter/Escape. Keep it AA.
+Flexible: orientation, panel content.
+
+Do not invent props, tokens, or global viewport media queries.
+```