@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/section/hero.md

@@ -0,0 +1,101 @@
+# Hero
+
+**Category:** layout  
+**Description:** Page hero section — centered or split layout with eyebrow, title, description, actions and media slots. Replace demo content before shipping.
+
+## When to use
+
+- The primary page intro with eyebrow, title, description, actions, and media
+- Landing-page tops in centered or split layout
+
+## When NOT to use
+
+- An application page top — use PageHeader
+- A mid-page conversion prompt — use Cta
+
+## Related components
+
+- **PageHeader** (alternative): Use for app pages rather than marketing landings
+- **Cta** (pairs-with): Reinforce the hero with a CTA band later on the page
+
+## Accessibility rationale
+
+Renders a section with the page-level heading as its primary landmark.
+
+## Props
+
+| Name           | Type                    | Required | Default    | Description                                                     |
+| -------------- | ----------------------- | -------- | ---------- | --------------------------------------------------------------- |
+| `variant`      | `"centered" \| "split"` | No       | "centered" | Layout variant: centered (single column) or split (two columns) |
+| `title`        | `ReactNode`             | Yes      | —          | Primary heading content                                         |
+| `eyebrow`      | `ReactNode`             | No       | —          | Small monospace label above the title                           |
+| `description`  | `ReactNode`             | No       | —          | Supporting paragraph below the title                            |
+| `actions`      | `ReactNode`             | No       | —          | Buttons or links rendered in a row below the description        |
+| `media`        | `ReactNode`             | No       | —          | Right-hand slot in the split variant (image, demo, code block)  |
+| `headingLevel` | `1 \| 2 \| 3`           | No       | 1          | HTML heading level for document outline control                 |
+
+## Tokens
+
+- `--cascivo-text-4xl`
+- `--cascivo-text-lg`
+- `--cascivo-text-sm`
+- `--cascivo-font-mono`
+- `--cascivo-font-bold`
+- `--cascivo-text-secondary`
+- `--cascivo-space-*`
+
+## Examples
+
+### Centered hero
+
+Single-column hero with eyebrow, headline, description, and CTA buttons
+
+```jsx
+<Hero
+  eyebrow="v8 — Assembly Included"
+  title="Ship the dashboard your ops team deserves"
+  description="Cascade gives you charts, layouts and sections — fully composed, copy-paste ready."
+  actions={
+    <>
+      <Button>Get started</Button>
+      <Button variant="ghost">View docs</Button>
+    </>
+  }
+/>
+```
+
+### Split hero
+
+Two-column layout with copy on the left and media on the right
+
+```jsx
+<Hero
+  variant="split"
+  title="Signal-driven, CSS-native"
+  description="Fine-grained reactivity with zero re-renders. Beautiful by default."
+  actions={<Button>Start building</Button>}
+  media={<img src="/preview.png" alt="Dashboard preview" />}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Hero component (layout). Page hero section — centered or split layout with eyebrow, title, description, actions and media slots. Replace demo content before shipping.
+
+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).
+
+Hero is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-text-4xl, --cascivo-text-lg, --cascivo-text-sm, --cascivo-font-mono, --cascivo-font-bold, --cascivo-text-secondary, --cascivo-space-*
+
+Accessibility: role "region", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/section/media-masonry.md

@@ -0,0 +1,77 @@
+# MediaMasonry
+
+**Category:** layout  
+**Description:** Masonry gallery section — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders tiles top-to-bottom per column). Tiles style themselves; section provides only the layout shell.
+
+## When to use
+
+- A full-width media gallery section with masonry packing
+- Showcasing images or media tiles of varying heights
+
+## When NOT to use
+
+- A bare masonry primitive without section framing — use Masonry
+- Uniform-height cards in rows — use AutoGrid
+
+## Related components
+
+- **Masonry** (contains): Uses the masonry primitive for tile packing
+
+## Accessibility rationale
+
+Renders a section shell; tiles supply their own accessible content.
+
+## Props
+
+| Name           | Type                          | Required | Default | Description                                                               |
+| -------------- | ----------------------------- | -------- | ------- | ------------------------------------------------------------------------- |
+| `children`     | `ReactNode`                   | Yes      | —       | Tile elements (images, cards, quotes) — consumer-provided and self-styled |
+| `title`        | `ReactNode`                   | No       | —       | Section heading above the gallery                                         |
+| `description`  | `ReactNode`                   | No       | —       | Subheading below the section title                                        |
+| `headingLevel` | `1 \| 2 \| 3`                 | No       | 2       | HTML heading level for the section title                                  |
+| `cols`         | `number`                      | No       | 3       | Number of masonry columns                                                 |
+| `gap`          | `1\|2\|3\|4\|5\|6\|8\|10\|12` | No       | 4       | Gap between tiles (spacing token step)                                    |
+
+## Tokens
+
+- `--cascivo-text-2xl`
+- `--cascivo-text-base`
+- `--cascivo-font-bold`
+- `--cascivo-text-secondary`
+- `--cascivo-space-*`
+
+## Examples
+
+### Media gallery
+
+Masonry gallery with three image tiles; falls back to CSS columns in unsupported browsers
+
+```jsx
+<MediaMasonry title="Customer stories" cols={3} gap={4}>
+  <img src="/photo-1.jpg" alt="Team at desk" />
+  <img src="/photo-2.jpg" alt="Product screenshot" />
+  <img src="/photo-3.jpg" alt="Dashboard view" />
+</MediaMasonry>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo MediaMasonry component (layout). Masonry gallery section — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders tiles top-to-bottom per column). Tiles style themselves; section provides only the layout shell.
+
+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).
+
+MediaMasonry is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-text-2xl, --cascivo-text-base, --cascivo-font-bold, --cascivo-text-secondary, --cascivo-space-*
+
+Accessibility: role "region", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/section/page-footer.md

@@ -0,0 +1,101 @@
+# PageFooter
+
+**Category:** layout  
+**Description:** Site footer — AutoGrid of link groups with a brand/meta bottom row. Renders a <footer> element with a <nav aria-label="Footer"> wrapping the link columns.
+
+## When to use
+
+- A site footer with grouped link columns and a brand/meta bottom row
+- Closing marketing or app pages with secondary navigation
+
+## When NOT to use
+
+- Primary top navigation — use AppShell or a header
+- A conversion prompt — use Cta
+
+## Related components
+
+- **AutoGrid** (contains): Uses an auto-fit grid to lay out link groups
+
+## Accessibility rationale
+
+Renders a footer element wrapping a labeled Footer navigation region.
+
+## Props
+
+| Name     | Type            | Required | Default | Description                                                              |
+| -------- | --------------- | -------- | ------- | ------------------------------------------------------------------------ |
+| `groups` | `FooterGroup[]` | Yes      | —       | Array of link groups, each with a title and array of {label, href} links |
+| `brand`  | `ReactNode`     | No       | —       | Brand name or logo shown in the bottom row                               |
+| `meta`   | `ReactNode`     | No       | —       | Meta line in the bottom row (license, copyright, etc.)                   |
+
+## Tokens
+
+- `--cascivo-text-sm`
+- `--cascivo-font-mono`
+- `--cascivo-font-semibold`
+- `--cascivo-text-primary`
+- `--cascivo-text-secondary`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-space-*`
+
+## Examples
+
+### Site footer
+
+Three-column footer with brand and license meta
+
+```jsx
+<PageFooter
+  brand="Cascade"
+  meta="MIT licensed. Built with care."
+  groups={[
+    {
+      title: 'Product',
+      links: [
+        { label: 'Components', href: '/components' },
+        { label: 'Charts', href: '/charts' },
+        { label: 'Layouts', href: '/layouts' },
+      ],
+    },
+    {
+      title: 'Developers',
+      links: [
+        { label: 'Docs', href: '/docs' },
+        { label: 'GitHub', href: 'https://github.com/cascivo/cascivo' },
+        { label: 'Changelog', href: '/changelog' },
+      ],
+    },
+    {
+      title: 'Resources',
+      links: [
+        { label: 'Figma kit', href: '/figma' },
+        { label: 'Storybook', href: '/storybook' },
+      ],
+    },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo PageFooter component (layout). Site footer — AutoGrid of link groups with a brand/meta bottom row. Renders a <footer> element with a <nav aria-label="Footer"> wrapping the link columns.
+
+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).
+
+PageFooter is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-text-sm, --cascivo-font-mono, --cascivo-font-semibold, --cascivo-text-primary, --cascivo-text-secondary, --cascivo-color-border, --cascivo-color-accent, --cascivo-space-*
+
+Accessibility: role "contentinfo", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/section/stats-band.md

@@ -0,0 +1,81 @@
+# StatsBand
+
+**Category:** layout  
+**Description:** KPI strip — horizontal band of stats with optional delta and inline sparkline trend. Wraps via AutoGrid on narrow containers. No visible heading; provide aria-label for accessibility.
+
+## When to use
+
+- A horizontal KPI strip with optional deltas and inline sparkline trends
+- A marketing or dashboard band summarising headline numbers
+
+## When NOT to use
+
+- A grid of full stat cards — use StatsCards
+- A single metric — use a Kpi card
+
+## Related components
+
+- **StatsCards** (alternative): Use the card grid block for richer per-stat framing
+- **Sparkline** (contains): Embeds inline sparkline trends per stat
+
+## Accessibility rationale
+
+Has no visible heading; consumers must supply an aria-label for the band.
+
+## Props
+
+| Name         | Type         | Required | Default       | Description                                                                                            |
+| ------------ | ------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------ |
+| `stats`      | `StatItem[]` | Yes      | —             | Array of stat items: label, value, optional delta (e.g. "+3.2%"), optional trend numbers for sparkline |
+| `aria-label` | `string`     | No       | "Key metrics" | Accessible label for the stats region                                                                  |
+
+## Tokens
+
+- `--cascivo-text-2xl`
+- `--cascivo-text-sm`
+- `--cascivo-font-bold`
+- `--cascivo-font-mono`
+- `--cascivo-text-secondary`
+- `--cascivo-color-border`
+- `--cascivo-surface-subtle`
+- `--cascivo-space-*`
+
+## Examples
+
+### KPI band with trends
+
+Four KPI cells — three with sparkline trends and signed deltas
+
+```jsx
+<StatsBand
+  aria-label="Performance metrics"
+  stats={[
+    { label: 'p99 latency', value: '184 ms', delta: '-12 ms', trend: [210, 205, 198, 192, 184] },
+    { label: 'Error rate', value: '0.12%', delta: '-0.03%', trend: [0.18, 0.16, 0.15, 0.14, 0.12] },
+    { label: 'Uptime', value: '99.98%', trend: [99.95, 99.97, 99.98, 99.99, 99.98] },
+    { label: 'Deploys today', value: '7' },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo StatsBand component (layout). KPI strip — horizontal band of stats with optional delta and inline sparkline trend. Wraps via AutoGrid on narrow containers. No visible heading; provide aria-label for accessibility.
+
+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).
+
+StatsBand is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-text-2xl, --cascivo-text-sm, --cascivo-font-bold, --cascivo-font-mono, --cascivo-text-secondary, --cascivo-color-border, --cascivo-surface-subtle, --cascivo-space-*
+
+Accessibility: role "region", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/segmented-control.md

@@ -0,0 +1,101 @@
+# SegmentedControl
+
+**Category:** inputs  
+**Description:** Mutually exclusive toggle group
+
+## When to use
+
+- A compact inline single choice among a few mutually exclusive options (2–5) such as view modes or time ranges
+- Switching between alternatives where all options should stay visible in a tight horizontal space
+
+## When NOT to use
+
+- Switching between full panels of page content — use Tabs
+- A single binary on/off state — use Toggle
+- More options than comfortably fit inline, or options needing descriptions — use Select or RadioCard
+
+## Anti-patterns
+
+### A pair of buttons does not convey exclusive selection; SegmentedControl uses radio semantics with aria-checked and arrow-key navigation so the single-choice state is announced
+
+**Bad:** `Two <Button> elements toggling which is "active" via app state`  
+**Good:** `<SegmentedControl options={[{label:"Day",value:"day"},{label:"Week",value:"week"}]} value={range} onValueChange={setRange} />`  
+**Why:** A pair of buttons does not convey exclusive selection; SegmentedControl uses radio semantics with aria-checked and arrow-key navigation so the single-choice state is announced
+
+## Related components
+
+- **Toggle** (alternative): Use for a single binary on/off state, not a multi-option choice
+- **Radio** (alternative): Use for a vertical or longer single-choice list with plain labels
+- **Select** (alternative): Use when there are too many options to show inline
+
+## Accessibility rationale
+
+Wraps role="radio" buttons in a role="group" with aria-checked marking the selected segment, and ArrowLeft/ArrowRight move selection across enabled segments (skipping disabled ones) so keyboard users get standard single-choice navigation.
+
+## Props
+
+| Name            | Type                       | Required | Default | Description                                                        |
+| --------------- | -------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `options`       | `SegmentedControlOption[]` | Yes      | —       | The selectable options.                                            |
+| `value`         | `string`                   | Yes      | —       | The controlled value.                                              |
+| `onValueChange` | `(v: string) => void`      | Yes      | —       | Called with the new value when it changes.                         |
+| `size`          | `'sm' \| 'md' \| 'lg'`     | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `disabled`      | `boolean`                  | No       | false   | When true, disables the control and removes it from the tab order. |
+
+## Tokens
+
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-surface`
+- `--cascivo-color-text`
+- `--cascivo-radius-md`
+- `--cascivo-radius-sm`
+- `--cascivo-shadow-sm`
+
+## Examples
+
+### Basic
+
+```jsx
+<SegmentedControl
+  options={[
+    { label: 'Day', value: 'day' },
+    { label: 'Week', value: 'week' },
+    { label: 'Month', value: 'month' },
+  ]}
+  value="day"
+  onValueChange={() => {}}
+/>
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                    |
+| ------------- | -------- | ----------------------------------------------------------------------- |
+| token names   | strict   | Segment styling must resolve to the listed --cascivo-\* tokens          |
+| option labels | flexible | option label and value are free, and individual options may be disabled |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo SegmentedControl component (inputs). Mutually exclusive toggle group
+
+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).
+
+SegmentedControl is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-color-surface, --cascivo-color-text, --cascivo-radius-md, --cascivo-radius-sm, --cascivo-shadow-sm
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight. Keep it AA.
+
+Do not change (strict): token names — Segment styling must resolve to the listed --cascivo-* tokens
+Flexible: option labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/select.md

@@ -0,0 +1,101 @@
+# Select
+
+**Category:** inputs  
+**Description:** Native select menu styled to match the design system
+
+## When to use
+
+- Choosing exactly one value from a known, finite list inside a form
+- A compact single-value picker where the native OS dropdown UX is acceptable
+- You want zero-JS reliability and built-in mobile/keyboard handling from a real <select>
+
+## When NOT to use
+
+- Users need to filter/search a long list — use Combobox
+- Multiple values must be selectable — use MultiSelect
+- Triggering actions or commands rather than picking a form value — use Dropdown or Menu
+
+## Anti-patterns
+
+### A long unfiltered native list is hard to scan; Combobox adds type-ahead filtering
+
+**Bad:** `<Select options={fiftyCountries} placeholder="Search country" />`  
+**Good:** `<Combobox options={fiftyCountries} />`  
+**Why:** A long unfiltered native list is hard to scan; Combobox adds type-ahead filtering
+
+## Related components
+
+- **Combobox** (alternative): Use when the list is long and needs filtering/search
+- **MultiSelect** (alternative): Use when more than one value can be chosen
+- **Dropdown** (alternative): Use for action menus, not single-value form selection
+
+## Accessibility rationale
+
+Renders a native <select> so options, type-ahead, and arrow-key navigation come from the platform; error text is linked via aria-describedby and role="alert" with aria-invalid on the control.
+
+## 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.                     |
+| `placeholder` | `string`                                                 | No       | —       | Placeholder text shown when the field is empty.                    |
+| `options`     | `{ value: string; label: string; disabled?: boolean }[]` | Yes      | —       | The selectable options.                                            |
+| `size`        | `'sm' \| 'md' \| 'lg'`                                   | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `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-text-muted`
+- `--cascivo-radius-input`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Select label="Role" options={[{ value: 'admin', label: 'Admin' }]} />
+```
+
+### With placeholder
+
+```jsx
+<Select label="Country" placeholder="Choose…" options={countries} />
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                         |
+| ------------- | -------- | ---------------------------------------------------------------------------- |
+| token names   | strict   | Visual props must resolve to --cascivo-color-\* / radius / focus-ring tokens |
+| option labels | flexible | Free, supplied by the consumer via the options array                         |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Select component (inputs). Native select menu styled to match the design system
+
+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).
+
+Select 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-text-muted, --cascivo-radius-input, --cascivo-focus-ring
+
+Accessibility: role "listbox", WCAG 2.2-AA, keyboard: ArrowUp/ArrowDown/Space. Keep it AA.
+
+Do not change (strict): token names — Visual props must resolve to --cascivo-color-* / radius / focus-ring tokens
+Flexible: option labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/separator.md

@@ -0,0 +1,88 @@
+# Separator
+
+**Category:** display  
+**Description:** Visual or semantic divider between content
+
+## When to use
+
+- Dividing groups of content within a section or menu
+- Adding a vertical rule between inline items (orientation="vertical")
+- Marking a meaningful thematic break (decorative=false)
+
+## When NOT to use
+
+- Adding spacing only — use margin/padding, not a separator
+- Bordering a container — use the container border, not a separator
+
+## Anti-patterns
+
+### Separators imply a content division; using them for spacing misleads assistive tech
+
+**Bad:** `Multiple separators stacked to create whitespace`  
+**Good:** `Use spacing tokens for gaps; one separator for a real break`  
+**Why:** Separators imply a content division; using them for spacing misleads assistive tech
+
+## Related components
+
+- **Card** (contained-by): Often used to divide regions inside a Card
+
+## Accessibility rationale
+
+role="separator" when meaningful so screen readers announce the division; setting decorative hides it from the accessibility tree when it is purely visual
+
+## Props
+
+| Name          | Type                         | Required | Default    | Description                                                              |
+| ------------- | ---------------------------- | -------- | ---------- | ------------------------------------------------------------------------ |
+| `orientation` | `'horizontal' \| 'vertical'` | No       | horizontal | Layout orientation of the component.                                     |
+| `decorative`  | `boolean`                    | No       | false      | When true, the separator is purely visual and hidden from assistive tech |
+
+## Tokens
+
+- `--cascivo-color-border`
+
+## Examples
+
+### Horizontal
+
+```jsx
+<Separator />
+```
+
+### Vertical
+
+```jsx
+<Separator orientation="vertical" />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                             |
+| ----------- | -------- | ---------------------------------------------------------------- |
+| decorative  | flexible | Mark decorative when the break carries no meaning beyond visuals |
+| token names | strict   | Color must resolve to --cascivo-color-border                     |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Separator component (display). Visual or semantic divider between content
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Separator is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border
+
+Accessibility: role "separator", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Color must resolve to --cascivo-color-border
+Flexible: decorative.
+
+Do not invent props, tokens, or global viewport media queries.
+```