@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/layout/center.md

@@ -0,0 +1,67 @@
+# Center
+
+**Category:** layout  
+**Description:** Horizontally centered container with a configurable max-width.
+
+## When to use
+
+- Horizontally centering content within a configurable max-width
+- Constraining page or section content to a readable measure
+
+## When NOT to use
+
+- Stacking children with consistent gaps — use Stack
+- Multi-column or grid arrangements — use Columns or Grid
+
+## Related components
+
+- **Section** (contained-by): Sections use a centered inner width built on the same idea
+- **Stack** (pairs-with): Stack the centered content vertically inside it
+
+## Accessibility rationale
+
+Pure layout wrapper with no semantic role; does not affect the accessibility tree.
+
+## Props
+
+| Name       | Type     | Required | Default | Description         |
+| ---------- | -------- | -------- | ------- | ------------------- |
+| `maxWidth` | `string` | No       | —       | CSS max-width value |
+
+## Tokens
+
+- `--cascivo-space-4`
+
+## Examples
+
+### Centered content
+
+Centered container with custom max-width
+
+```jsx
+<Center maxWidth="60rem">
+  <p>Content</p>
+</Center>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Center component (layout). Horizontally centered container with a configurable max-width.
+
+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).
+
+Center is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-4
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/columns.md

@@ -0,0 +1,70 @@
+# Columns
+
+**Category:** layout  
+**Description:** Equal-width multi-column layout that collapses to single column on narrow viewports.
+
+## When to use
+
+- Equal-width multi-column content that collapses to one column when narrow
+- Side-by-side text or content blocks at a fixed column count
+
+## When NOT to use
+
+- Card grids that auto-fit to width — use AutoGrid
+- Single-direction stacking — use Stack
+
+## Related components
+
+- **Grid** (alternative): Use for general two-dimensional grid placement
+- **AutoGrid** (alternative): Use when column count should adapt to available width
+
+## Accessibility rationale
+
+Pure layout primitive with no semantic role; does not affect the accessibility tree.
+
+## Props
+
+| Name    | Type                          | Required | Default | Description             |
+| ------- | ----------------------------- | -------- | ------- | ----------------------- |
+| `count` | `2\|3\|4`                     | No       | —       | Number of equal columns |
+| `gap`   | `1\|2\|3\|4\|5\|6\|8\|10\|12` | No       | —       | Spacing token step      |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Three columns
+
+Three equal columns
+
+```jsx
+<Columns count={3}>
+  <div>A</div>
+  <div>B</div>
+  <div>C</div>
+</Columns>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Columns component (layout). Equal-width multi-column layout that collapses to single column on narrow viewports.
+
+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).
+
+Columns is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-*
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/dashboard-layout.md

@@ -0,0 +1,68 @@
+# DashboardLayout
+
+**Category:** layout  
+**Description:** Dashboard page layout with stats strip, main content area, and optional aside.
+
+## When to use
+
+- A dashboard page with a stats strip, main content area, and optional aside
+- Composing KPI tiles and charts into a standard analytics layout
+
+## When NOT to use
+
+- A bare app frame without dashboard structure — use AppShell
+- A simple form or content page — use Section or SettingsLayout
+
+## Related components
+
+- **AppShell** (alternative): Use the bare shell when you do not need dashboard structure
+- **StatsCards** (contains): KPI cards commonly fill the stats strip
+
+## Accessibility rationale
+
+Provides landmark regions for main content and complementary aside.
+
+## Props
+
+| Name    | Type        | Required | Default | Description                   |
+| ------- | ----------- | -------- | ------- | ----------------------------- |
+| `stats` | `ReactNode` | No       | —       | Stats/KPI row (auto-fit grid) |
+| `main`  | `ReactNode` | Yes      | —       | Main content area             |
+| `aside` | `ReactNode` | No       | —       | Optional aside panel (20rem)  |
+
+## Tokens
+
+- `--cascivo-space-4`
+- `--cascivo-space-6`
+
+## Examples
+
+### With stats
+
+Stats + main layout
+
+```jsx
+<DashboardLayout stats={<div>KPIs</div>} main={<div>Content</div>} />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo DashboardLayout component (layout). Dashboard page layout with stats strip, main content area, and optional aside.
+
+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).
+
+DashboardLayout is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-4, --cascivo-space-6
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/grid.md

@@ -0,0 +1,70 @@
+# Grid
+
+**Category:** layout  
+**Description:** CSS grid layout primitive with responsive column collapsing.
+
+## When to use
+
+- Two-dimensional layouts with an explicit column count
+- Arranging cards or tiles that should align in rows and columns
+
+## When NOT to use
+
+- Single-direction stacking — use Stack
+- Columns that auto-fit to available width — use AutoGrid
+
+## Related components
+
+- **AutoGrid** (alternative): Use when columns should auto-fill without fixed counts
+- **Columns** (alternative): Use for equal-width text columns that collapse on narrow viewports
+
+## Accessibility rationale
+
+Pure layout primitive with no semantic role; does not affect the accessibility tree.
+
+## Props
+
+| Name   | Type                          | Required | Default | Description                 |
+| ------ | ----------------------------- | -------- | ------- | --------------------------- |
+| `cols` | `number`                      | No       | —       | Number of grid columns      |
+| `gap`  | `1\|2\|3\|4\|5\|6\|8\|10\|12` | No       | —       | Spacing token step          |
+| `span` | `number`                      | No       | —       | GridItem: column span count |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Basic grid
+
+3-column grid with spanning item
+
+```jsx
+<Grid cols={3} gap={4}>
+  <GridItem span={1}>A</GridItem>
+  <GridItem span={2}>B</GridItem>
+</Grid>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Grid component (layout). CSS grid layout primitive with responsive column collapsing.
+
+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).
+
+Grid is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-*
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/masonry.md

@@ -0,0 +1,70 @@
+# Masonry
+
+**Category:** layout  
+**Description:** Masonry layout — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders items top-to-bottom per column).
+
+## When to use
+
+- Galleries of variable-height items packed into balanced columns
+- Pinterest-style image or card walls
+
+## When NOT to use
+
+- Items that must align in rows — use Grid
+- Uniform-height cards — use AutoGrid
+
+## Related components
+
+- **AutoGrid** (alternative): Use when items are uniform height and should align in rows
+- **MediaMasonry** (alternative): Use the section-level masonry for full-width media galleries
+
+## Accessibility rationale
+
+Pure layout primitive with no semantic role; does not affect the accessibility tree.
+
+## Props
+
+| Name   | Type                          | Required | Default | Description        |
+| ------ | ----------------------------- | -------- | ------- | ------------------ |
+| `cols` | `number`                      | No       | 3       | Number of columns  |
+| `gap`  | `1\|2\|3\|4\|5\|6\|8\|10\|12` | No       | 4       | Spacing token step |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Masonry gallery
+
+Variable-height cards laid out in a masonry pattern; falls back to CSS columns
+
+```jsx
+<Masonry cols={3} gap={4}>
+  {items.map((item) => (
+    <Card key={item.id}>{item.content}</Card>
+  ))}
+</Masonry>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Masonry component (layout). Masonry layout — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders items top-to-bottom per column).
+
+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).
+
+Masonry is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-*
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/page-header.md

@@ -0,0 +1,75 @@
+# PageHeader
+
+**Category:** layout  
+**Description:** Page-level header with title, description, breadcrumb, and actions slots.
+
+## When to use
+
+- A page-level header with title, description, breadcrumb, and action slots
+- Establishing consistent page tops across an application
+
+## When NOT to use
+
+- A marketing hero with large media — use Hero
+- A full app top bar with navigation — use AppShell
+
+## Related components
+
+- **Hero** (alternative): Use the marketing hero for landing-page tops
+- **Section** (pairs-with): Place sections below the header to build out the page
+
+## Accessibility rationale
+
+Renders a header region with a top-level heading for screen reader page structure.
+
+## Props
+
+| Name          | Type        | Required | Default | Description            |
+| ------------- | ----------- | -------- | ------- | ---------------------- |
+| `title`       | `string`    | Yes      | —       | Page title             |
+| `description` | `string`    | No       | —       | Supporting description |
+| `breadcrumb`  | `ReactNode` | No       | —       | Breadcrumb slot        |
+| `actions`     | `ReactNode` | No       | —       | Action buttons slot    |
+| `className`   | `string`    | No       | —       | Additional CSS class   |
+
+## Tokens
+
+- `--cascivo-space-2`
+- `--cascivo-space-4`
+- `--cascivo-font-size-2xl`
+- `--cascivo-font-weight-bold`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-font-size-sm`
+
+## Examples
+
+### Basic
+
+Title with description
+
+```jsx
+<PageHeader title="Dashboard" description="Welcome back" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo PageHeader component (layout). Page-level header with title, description, breadcrumb, and actions slots.
+
+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).
+
+PageHeader is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-2, --cascivo-space-4, --cascivo-font-size-2xl, --cascivo-font-weight-bold, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-font-size-sm
+
+Accessibility: role "banner", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/section.md

@@ -0,0 +1,69 @@
+# Section
+
+**Category:** layout  
+**Description:** Page-section shell with block padding, centered inner width, and stack gap.
+
+## When to use
+
+- Wrapping a page region with block padding and a centered inner width
+- The default container for stacking content within a page
+
+## When NOT to use
+
+- Just centering a single element — use Center
+- A marketing band with built-in CTA content — use Cta or Hero
+
+## Related components
+
+- **Center** (contains): Uses centered inner width internally
+- **PageHeader** (pairs-with): Pair sections below a page header
+
+## Accessibility rationale
+
+Renders a section element to group related content for screen readers.
+
+## Props
+
+| Name    | Type                            | Required | Default   | Description                                           |
+| ------- | ------------------------------- | -------- | --------- | ----------------------------------------------------- |
+| `width` | `"content" \| "wide" \| "full"` | No       | "content" | Max inline size: content=72rem, wide=90rem, full=none |
+| `gap`   | `1\|2\|3\|4\|5\|6\|8\|10\|12`   | No       | 8         | Stack gap between children (spacing token step)       |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Content section
+
+Centered 72rem content column with 2rem block padding
+
+```jsx
+<Section width="content" gap={8}>
+  <h2>Heading</h2>
+  <p>Body copy.</p>
+</Section>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Section component (layout). Page-section shell with block padding, centered inner width, and stack gap.
+
+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).
+
+Section is strictly bound to these tokens — use only these, do not invent token names:
+  --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/layout/settings-layout.md

@@ -0,0 +1,68 @@
+# SettingsLayout
+
+**Category:** layout  
+**Description:** Two-column settings page layout with a fixed-width menu and fluid content area.
+
+## When to use
+
+- A two-column settings page with a fixed-width menu and fluid content
+- Account, preferences, or admin pages with sectioned navigation
+
+## When NOT to use
+
+- A general resizable two-pane layout — use SplitView
+- A full app frame — use AppShell or SidebarApp
+
+## Related components
+
+- **SettingsFormPage** (contained-by): The settings form block composes this layout
+- **SplitView** (alternative): Use when the two panes should be user-resizable
+
+## Accessibility rationale
+
+Provides a navigation region for the menu and a main region for content.
+
+## Props
+
+| Name       | Type        | Required | Default | Description           |
+| ---------- | ----------- | -------- | ------- | --------------------- |
+| `menu`     | `ReactNode` | Yes      | —       | Side navigation menu  |
+| `children` | `ReactNode` | Yes      | —       | Settings content area |
+
+## Tokens
+
+- `--cascivo-space-8`
+
+## Examples
+
+### Basic
+
+Menu + content layout
+
+```jsx
+<SettingsLayout menu={<nav>Menu</nav>}>
+  <div>Settings</div>
+</SettingsLayout>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo SettingsLayout component (layout). Two-column settings page layout with a fixed-width menu and fluid content area.
+
+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).
+
+SettingsLayout is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-8
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/spacer.md

@@ -0,0 +1,64 @@
+# Spacer
+
+**Category:** layout  
+**Description:** Fixed-height spacing block using design token steps.
+
+## When to use
+
+- Inserting a fixed vertical gap between blocks using spacing token steps
+- Adding deliberate breathing room where margins are awkward
+
+## When NOT to use
+
+- Spacing a series of siblings — use Stack with a gap instead
+- Arbitrary one-off spacing — prefer token-based gap props
+
+## Related components
+
+- **Stack** (alternative): Use gap on Stack to space multiple siblings consistently
+
+## Accessibility rationale
+
+Empty presentational spacer with no semantic role; ignored by assistive tech.
+
+## Props
+
+| Name   | Type                          | Required | Default | Description        |
+| ------ | ----------------------------- | -------- | ------- | ------------------ |
+| `size` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | No       | —       | Spacing token step |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Spacer
+
+Adds vertical space between elements
+
+```jsx
+<Spacer size={8} />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Spacer component (layout). Fixed-height spacing block using design token steps.
+
+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).
+
+Spacer is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-*
+
+Accessibility: role "none", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```