@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/spinner.md

@@ -0,0 +1,89 @@
+# Spinner
+
+**Category:** feedback  
+**Description:** Indeterminate loading indicator
+
+## When to use
+
+- Indicating indeterminate work where duration and progress are unknown
+- Loading a small region or inline control where a shape preview is unnecessary
+- Showing busy state in buttons or compact UI
+
+## When NOT to use
+
+- Progress with a known percentage — use ProgressBar or ProgressCircle
+- Loading content with a known structure — use Skeleton
+
+## Anti-patterns
+
+### Skeletons preview structure and feel faster; spinners are best for short, shapeless waits
+
+**Bad:** `A full-page spinner for content whose layout is known`  
+**Good:** `<Skeleton> mirroring the content shape to reduce perceived wait and layout shift`  
+**Why:** Skeletons preview structure and feel faster; spinners are best for short, shapeless waits
+
+## Related components
+
+- **Skeleton** (alternative): Skeleton suits content with a known shape
+- **ProgressBar** (alternative): ProgressBar suits determinate progress
+
+## Accessibility rationale
+
+role="status" with an accessible label (default "Loading", i18n-driven) so assistive tech announces the busy state rather than leaving the spin silent
+
+## Props
+
+| Name    | Type                   | Required | Default | Description                                           |
+| ------- | ---------------------- | -------- | ------- | ----------------------------------------------------- |
+| `size`  | `'sm' \| 'md' \| 'lg'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+| `label` | `string`               | No       | Loading | Accessible label announced by screen readers          |
+
+## Tokens
+
+- `--cascivo-radius-full`
+
+## Examples
+
+### Default
+
+```jsx
+<Spinner />
+```
+
+### Large
+
+```jsx
+<Spinner size="lg" />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                         |
+| ----------- | -------- | -------------------------------------------- |
+| size        | flexible | sm/md/lg to fit inline vs standalone use     |
+| token names | strict   | Radius must resolve to --cascivo-radius-full |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Spinner component (feedback). Indeterminate loading indicator
+
+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).
+
+Spinner is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-radius-full
+
+Accessibility: role "status", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Radius must resolve to --cascivo-radius-full
+Flexible: size.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/stack.md

@@ -0,0 +1,96 @@
+# Stack
+
+**Category:** layout  
+**Description:** Overlaps children in a CSS grid stack with a configurable offset to create a card-pile effect
+
+## When to use
+
+- Card pile UI where depth and layering should be visible
+- Overlapping avatar groups
+- Notification stack visualisations
+
+## When NOT to use
+
+- Gap-based vertical/horizontal layout — that is a DIFFERENT component, the flex `layout/stack` (also exported as `Stack`). This `Stack` only overlaps children with an offset.
+- Independent positioned elements — use CSS position directly
+
+## Anti-patterns
+
+### The npm `Stack` overlaps its children by an offset — it does not do gap-based layout. The two components share a name; pick by behaviour, not by the name.
+
+**Bad:** `import { Stack } from '@cascivo/react' to space items vertically`  
+**Good:** `For flex layout use layout/stack (npx cascivo add stack); use this Stack only for a visual card-pile`  
+**Why:** The npm `Stack` overlaps its children by an offset — it does not do gap-based layout. The two components share a name; pick by behaviour, not by the name.
+
+## Related components
+
+- **layout/stack** (alternative): The flex layout primitive for gap-based vertical/horizontal stacking. It shares the `Stack` export name but is copy-paste-only (`npx cascivo add stack`) — not this card-pile component.
+- **Avatar** (pairs-with): Overlapping avatar groups are a primary use case for Stack
+- **Card** (pairs-with): Card pile visualisations are a common Stack pattern
+
+## Accessibility rationale
+
+Stack is a layout-only container (role="none"). Each child must carry its own accessible semantics. Stacked cards that are interactive should each have a focusable element and a descriptive label.
+
+## Props
+
+| Name        | Type              | Required | Default | Description                                              |
+| ----------- | ----------------- | -------- | ------- | -------------------------------------------------------- |
+| `children`  | `React.ReactNode` | Yes      | —       | Content rendered inside the component.                   |
+| `offset`    | `number`          | No       | 4       | Pixel offset applied per layer in both axes              |
+| `className` | `string`          | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Examples
+
+### Card pile
+
+Three cards stacked with a 6px offset to show depth
+
+```jsx
+<Stack offset={6}>
+  <Card>First</Card>
+  <Card>Second</Card>
+  <Card>Third</Card>
+</Stack>
+```
+
+### Tight stack
+
+Overlapping avatar group with minimal offset
+
+```jsx
+<Stack offset={2}>
+  <Avatar src="/a.jpg" />
+  <Avatar src="/b.jpg" />
+  <Avatar src="/c.jpg" />
+</Stack>
+```
+
+## Boundaries
+
+| Area   | Level    | Note                                                                              |
+| ------ | -------- | --------------------------------------------------------------------------------- |
+| offset | flexible | The pixel offset is fully configurable; set to 0 for a pure overlap with no shift |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Stack component (layout). Overlaps children in a CSS grid stack with a configurable offset to create a card-pile effect
+
+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).
+
+Stack is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+Flexible: offset.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/stat.md

@@ -0,0 +1,101 @@
+# Stat
+
+**Category:** display  
+**Description:** Displays a key metric with optional delta, trend direction and help text
+
+## When to use
+
+- Highlighting a single key metric with a clear label
+- Showing change over time with a delta and trend direction
+- Annotating a metric with methodology or time-range help text
+
+## When NOT to use
+
+- Multiple comparable rows of data — use DataTable
+- A non-numeric status label — use Badge or Status
+
+## Anti-patterns
+
+### Stat optimizes for one headline number, not tabular comparison
+
+**Bad:** `A grid of Stats used to fake a data table`  
+**Good:** `DataTable when the values are rows to compare and sort`  
+**Why:** Stat optimizes for one headline number, not tabular comparison
+
+## Related components
+
+- **Card** (contained-by): Stats commonly sit inside a Card tile on dashboards
+
+## Accessibility rationale
+
+Presentational by role; the label-value pairing is real text so the metric and its meaning are read in order, and trend direction is conveyed by text/glyph, not color alone
+
+## Props
+
+| Name       | Type                       | Required | Default | Description                                                  |
+| ---------- | -------------------------- | -------- | ------- | ------------------------------------------------------------ |
+| `label`    | `string`                   | Yes      | —       | What the metric measures                                     |
+| `value`    | `string \| number`         | Yes      | —       | The metric value                                             |
+| `delta`    | `string`                   | No       | —       | Change indicator rendered next to the trend arrow            |
+| `trend`    | `'up' \| 'down' \| 'flat'` | No       | flat    | Direction of the trend indicator ('up' \| 'down' \| 'flat'). |
+| `helpText` | `string`                   | No       | —       | Fine print below the value (methodology, time range)         |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-success`
+- `--cascivo-color-destructive`
+
+## Examples
+
+### Default
+
+```jsx
+<Stat label="Components" value={106} />
+```
+
+### With trend
+
+```jsx
+<Stat label="Bundle size" value="12.4 kB" delta="-1.2 kB" trend="up" />
+```
+
+### With help text
+
+```jsx
+<Stat label="Axe violations" value={0} helpText="WCAG 2.1 AA, 4 app states" />
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                             |
+| --------------- | -------- | ---------------------------------------------------------------- |
+| delta and trend | flexible | Optional — include only when change is meaningful                |
+| token names     | strict   | Trend colors must resolve to --cascivo-color-success/destructive |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Stat component (display). Displays a key metric with optional delta, trend direction and help text
+
+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).
+
+Stat is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-text-muted, --cascivo-color-success, --cascivo-color-destructive
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Trend colors must resolve to --cascivo-color-success/destructive
+Flexible: delta and trend.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/status.md

@@ -0,0 +1,105 @@
+# Status
+
+**Category:** display  
+**Description:** Colored dot with a label communicating the state of a system or entity
+
+## When to use
+
+- Communicating the live state of a system or entity (operational, deploying, down)
+- Pairing a colored dot with a text label for an at-a-glance state
+- Drawing attention to an active/changing state with an optional pulse
+
+## When NOT to use
+
+- A static category or count label — use Badge
+- An identity thumbnail with presence — use Avatar with its status prop
+
+## Anti-patterns
+
+### A bare colored dot conveys nothing to color-blind or screen-reader users; always pair with text
+
+**Bad:** `<Status status="success" /> with no label`  
+**Good:** `<Status status="success">Operational</Status>`  
+**Why:** A bare colored dot conveys nothing to color-blind or screen-reader users; always pair with text
+
+## Related components
+
+- **Badge** (alternative): Badge labels categories; Status reflects live state with a dot
+- **Avatar** (alternative): Avatar embeds presence status on an identity
+
+## Accessibility rationale
+
+Meaning is carried by the text label, never by the dot color alone; the pulse animation is gated behind prefers-reduced-motion: no-preference so it never animates for users who opt out
+
+## Props
+
+| Name     | Type                                                       | Required | Default | Description                                                         |
+| -------- | ---------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------- |
+| `status` | `'success' \| 'warning' \| 'error' \| 'info' \| 'neutral'` | No       | neutral | Status state.                                                       |
+| `pulse`  | `boolean`                                                  | No       | false   | Pulses the dot — gated behind prefers-reduced-motion: no-preference |
+
+## Tokens
+
+- `--cascivo-color-success`
+- `--cascivo-color-warning`
+- `--cascivo-color-error`
+- `--cascivo-color-info`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-text`
+- `--cascivo-radius-full`
+
+## Examples
+
+### Default
+
+```jsx
+<Status>Unknown</Status>
+```
+
+### Success
+
+```jsx
+<Status status="success">Operational</Status>
+```
+
+### Pulsing
+
+The pulse animation respects prefers-reduced-motion
+
+```jsx
+<Status status="info" pulse>
+  Deploying
+</Status>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                    |
+| ----------- | -------- | ----------------------------------------------------------------------- |
+| pulse       | flexible | Enable pulse only for actively-changing states                          |
+| token names | strict   | State colors must resolve to --cascivo-color-success/warning/error/info |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Status component (display). Colored dot with a label communicating the state of a system or entity
+
+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).
+
+Status is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-success, --cascivo-color-warning, --cascivo-color-error, --cascivo-color-info, --cascivo-color-text-muted, --cascivo-color-text, --cascivo-radius-full
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — State colors must resolve to --cascivo-color-success/warning/error/info
+Flexible: pulse.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/steps.md

@@ -0,0 +1,124 @@
+# Steps
+
+**Category:** navigation  
+**Description:** Visual progress indicator for multi-step flows with horizontal and vertical orientations
+
+## When to use
+
+- Checkout flows where the user moves through a fixed sequence of screens
+- Onboarding wizards with a known number of steps
+- Multi-step forms where showing overall progress reduces abandonment
+
+## When NOT to use
+
+- General section navigation — use Tabs instead
+- Simple back/next controls without step labels — use Pagination instead
+- More than 7 steps where the connector lines become unreadable on mobile
+
+## Anti-patterns
+
+### Steps imply a linear sequence and derive complete/pending state from position
+
+**Bad:** `Using Steps as a replacement for Tabs for non-sequential navigation`  
+**Good:** `<Tabs> for switching between independent views`  
+**Why:** Steps imply a linear sequence and derive complete/pending state from position
+
+## Related components
+
+- **Pagination** (alternative): Pagination is for paged data sets, Steps is for guided task sequences
+- **Tabs** (alternative): Tabs are for non-sequential section switching, not ordered task flows
+
+## Accessibility rationale
+
+Rendered as an ordered list (<ol>) with aria-label; the active item carries aria-current="step" to communicate progress to screen readers
+
+## Props
+
+| Name          | Type                         | Required | Default      | Description                                                  |
+| ------------- | ---------------------------- | -------- | ------------ | ------------------------------------------------------------ |
+| `steps`       | `Step[]`                     | Yes      | —            | Array of step objects with label and optional explicit state |
+| `activeStep`  | `number`                     | No       | 0            | Index of the currently active step (0-based)                 |
+| `orientation` | `'horizontal' \| 'vertical'` | No       | 'horizontal' | Layout direction of the steps                                |
+| `className`   | `string`                     | No       | —            | Additional CSS class names merged onto the root element.     |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-content`
+- `--cascivo-color-success`
+- `--cascivo-color-success-content`
+- `--cascivo-color-error`
+- `--cascivo-color-error-content`
+- `--cascivo-color-surface`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-text-muted`
+- `--cascivo-border-default`
+- `--cascivo-radius-full`
+- `--cascivo-ease-out`
+
+## Examples
+
+### Horizontal (default)
+
+Standard checkout or onboarding progress tracker
+
+```jsx
+<Steps
+  steps={[{ label: 'Cart' }, { label: 'Shipping' }, { label: 'Payment' }, { label: 'Confirm' }]}
+  activeStep={1}
+/>
+```
+
+### Vertical
+
+Sidebar-style progress for tall forms
+
+```jsx
+<Steps
+  orientation="vertical"
+  steps={[{ label: 'Account info' }, { label: 'Profile details' }, { label: 'Preferences' }]}
+  activeStep={0}
+/>
+```
+
+### With explicit error state
+
+Override derived state on a specific step
+
+```jsx
+<Steps
+  steps={[{ label: 'Upload' }, { label: 'Validate', state: 'error' }, { label: 'Process' }]}
+  activeStep={1}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                        |
+| ----------- | -------- | --------------------------------------------------------------------------- |
+| step state  | flexible | Each step can override derived pending/active/complete state via step.state |
+| orientation | flexible | Horizontal for top progress bars, vertical for sidebar wizards              |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Steps component (navigation). Visual progress indicator for multi-step flows with horizontal and vertical orientations
+
+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).
+
+Steps is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-accent-content, --cascivo-color-success, --cascivo-color-success-content, --cascivo-color-error, --cascivo-color-error-content, --cascivo-color-surface, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-text-muted, --cascivo-border-default, --cascivo-radius-full, --cascivo-ease-out
+
+Accessibility: role "list", WCAG 2.2-AA. Keep it AA.
+Flexible: step state, orientation.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/structured-list.md

@@ -0,0 +1,107 @@
+# StructuredList
+
+**Category:** display  
+**Description:** Tabular row list for scannable data, optionally single-selectable
+
+## When to use
+
+- Presenting a set of related records in aligned columns the user scans top to bottom
+- Letting the user pick exactly one row from a short, readable list (selectable)
+- Carbon-style structured content where a full data table is heavier than needed
+
+## When NOT to use
+
+- Sorting, filtering, pagination, or multi-select over many rows — use DataTable
+- Free-form vertical content without column alignment — use List
+
+## Anti-patterns
+
+### The selectable variant is a radiogroup; multiple selected rows break the radio semantics
+
+**Bad:** `selectable with multiple rows marked selected`  
+**Good:** `A single selected id (value/defaultValue) — selection is single-choice`  
+**Why:** The selectable variant is a radiogroup; multiple selected rows break the radio semantics
+
+## Related components
+
+- **DataTable** (alternative): DataTable adds sorting, filtering, and pagination; StructuredList stays static and lightweight
+- **List** (alternative): List is single-column vertical content; StructuredList aligns multiple cells per row
+
+## Accessibility rationale
+
+Static lists use table/row/cell roles so columns are announced; selectable lists become a radiogroup of role=radio rows with roving tabindex, so arrow keys move focus and Enter/Space check a row exactly like native radios
+
+## Props
+
+| Name           | Type                                                       | Required | Default | Description                          |
+| -------------- | ---------------------------------------------------------- | -------- | ------- | ------------------------------------ |
+| `items`        | `{ id: string; cells: ReactNode[]; selected?: boolean }[]` | Yes      | —       | The items to render.                 |
+| `headers`      | `ReactNode[]`                                              | No       | —       | The column header cells.             |
+| `selectable`   | `boolean`                                                  | No       | false   | When true, rows can be selected.     |
+| `value`        | `string`                                                   | No       | —       | The controlled value.                |
+| `defaultValue` | `string`                                                   | No       | —       | The initial value when uncontrolled. |
+| `onSelect`     | `(id: string) => void`                                     | No       | —       | Called with the selected value.      |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-primary`
+- `--cascivo-color-surface`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Static
+
+```jsx
+<StructuredList headers={['Name', 'Role']} items={[{ id: 'a', cells: ['Ada', 'Engineer'] }]} />
+```
+
+### Selectable
+
+```jsx
+<StructuredList
+  selectable
+  defaultValue="a"
+  items={[
+    { id: 'a', cells: ['Ada'] },
+    { id: 'b', cells: ['Grace'] },
+  ]}
+  onSelect={(id) => set(id)}
+/>
+```
+
+## Boundaries
+
+| Area       | Level    | Note                                                                                |
+| ---------- | -------- | ----------------------------------------------------------------------------------- |
+| selectable | flexible | Toggle selectable based on whether the list is interactive or purely presentational |
+| roles      | strict   | Static uses table semantics; selectable uses radiogroup — do not mix                |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo StructuredList component (display). Tabular row list for scannable data, optionally single-selectable
+
+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).
+
+StructuredList 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-color-text-subtle, --cascivo-color-primary, --cascivo-color-surface, --cascivo-focus-ring
+
+Accessibility: role "table", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Home/End/Enter/Space. Keep it AA.
+
+Do not change (strict): roles — Static uses table semantics; selectable uses radiogroup — do not mix
+Flexible: selectable.
+
+Do not invent props, tokens, or global viewport media queries.
+```