@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/chart/meter.md

@@ -0,0 +1,71 @@
+# Meter
+
+**Category:** chart  
+**Description:** Progress meter in bar or gauge variant with threshold coloring.
+
+## When to use
+
+- Showing a rated or gauged value within a known min/max range
+- Surfacing threshold-based status (e.g. CPU, disk, score) as a bar or gauge
+
+## When NOT to use
+
+- Showing task completion progress — use a ProgressBar
+- Comparing a value against a target with range bands — use Bullet
+
+## Related components
+
+- **Bullet** (alternative): Use when a target marker and qualitative bands are needed
+- **Kpi** (alternative): Use for a headline metric without a bounded range
+
+## Accessibility rationale
+
+Renders with role="meter" exposing min, max, and current value to assistive tech.
+
+## Props
+
+| Name         | Type               | Required | Default | Description                       |
+| ------------ | ------------------ | -------- | ------- | --------------------------------- |
+| `value`      | `number`           | Yes      | —       | Current value                     |
+| `label`      | `string`           | Yes      | —       | Text label for the control.       |
+| `min`        | `number`           | No       | 0       | Minimum allowed value.            |
+| `max`        | `number`           | No       | 100     | Maximum allowed value.            |
+| `variant`    | `'bar' \| 'gauge'` | No       | bar     | Selects the visual style variant. |
+| `thresholds` | `MeterThresholds`  | No       | —       | Color breakpoints                 |
+| `width`      | `number`           | No       | —       | Width of the component.           |
+| `height`     | `number`           | No       | —       | Height of the component.          |
+
+## Tokens
+
+- `--cascivo-chart-1`
+
+## Examples
+
+### Basic meter
+
+```jsx
+import { Meter } from '@cascivo/charts'
+;<Meter value={72} label="CPU usage" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Meter component (chart). Progress meter in bar or gauge variant with threshold coloring.
+
+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).
+
+Meter is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1
+
+Accessibility: role "meter", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/pie-chart.md

@@ -0,0 +1,126 @@
+# PieChart
+
+**Category:** chart  
+**Description:** Pie or donut chart with hover segments and optional legend.
+
+## When to use
+
+- Showing part-of-whole proportions with five or fewer slices
+- A single composition at one point in time
+
+## When NOT to use
+
+- Comparing precise values or many categories — use BarChart
+- Showing change over time — use LineChart or AreaChart
+
+## Related components
+
+- **BarChart** (alternative): Use when comparing more than five categories or precise values
+- **Treemap** (alternative): Use for part-to-whole with many or hierarchical segments
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name            | Type                                                               | Required | Default | Description                                                                                                                               |
+| --------------- | ------------------------------------------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`          | `PieChartDatum[]`                                                  | Yes      | —       | Array of { id, label, value, color? } datums. Optional per-datum `color` (any CSS color) overrides the positional palette for that slice. |
+| `title`         | `string`                                                           | Yes      | —       | Title text for the component.                                                                                                             |
+| `description`   | `string`                                                           | No       | —       | Supporting description text.                                                                                                              |
+| `donut`         | `boolean`                                                          | No       | —       | Render as donut chart                                                                                                                     |
+| `width`         | `number`                                                           | No       | —       | Width of the component.                                                                                                                   |
+| `height`        | `number`                                                           | No       | 300     | Height of the component.                                                                                                                  |
+| `size`          | `number`                                                           | No       | —       | Square shorthand: sets width === height. Explicit width/height win.                                                                       |
+| `thickness`     | `number`                                                           | No       | —       | Ring width in px (donut only); defaults to 0.4 × radius.                                                                                  |
+| `innerRadius`   | `number`                                                           | No       | —       | Inner radius in px (donut only); takes precedence over thickness; clamped to [0, outerRadius).                                            |
+| `centerValue`   | `string`                                                           | No       | —       | Center value text rendered in the donut hole (donut only).                                                                                |
+| `centerLabel`   | `string`                                                           | No       | —       | Center label text rendered below the value (donut only).                                                                                  |
+| `centerSlot`    | `ReactNode`                                                        | No       | —       | Arbitrary content for the donut hole; takes precedence over centerValue/centerLabel.                                                      |
+| `emptyLabel`    | `string`                                                           | No       | —       | Visible placeholder text when data is empty. Defaults to the i18n "No data".                                                              |
+| `tooltipFormat` | `(p: ChartPoint) => string`                                        | No       | —       | Custom tooltip formatter. Defaults to "value (pct%)" in the slice color.                                                                  |
+| `legend`        | `boolean`                                                          | No       | —       | Whether to show the legend.                                                                                                               |
+| `className`     | `string`                                                           | No       | —       | Additional CSS class names merged onto the root element.                                                                                  |
+| `plain`         | `boolean`                                                          | No       | false   | Marks only — no axes, grid lines, or legend. For micro/inline charts.                                                                     |
+| `labels`        | `boolean \| { format?: (v: number) => string; position?: string }` | No       | —       | Print each value as a label on the mark (collision-aware, decorative/aria-hidden).                                                        |
+| `onSelect`      | `(point: ChartPoint) => void`                                      | No       | —       | Fired when a point is clicked or activated (Enter/Space) — for drill-down.                                                                |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Basic pie chart
+
+```jsx
+import { PieChart } from '@cascivo/charts'
+;<PieChart
+  data={[
+    { label: 'A', value: 60 },
+    { label: 'B', value: 40 },
+  ]}
+  title="Market share"
+/>
+```
+
+### Donut with center total and custom thickness
+
+```jsx
+import { PieChart } from '@cascivo/charts'
+;<PieChart
+  donut
+  size={220}
+  thickness={28}
+  centerValue="142"
+  centerLabel="Total tasks"
+  data={[
+    { id: 'done', label: 'Done', value: 92, color: 'var(--cascivo-color-success)' },
+    { id: 'wip', label: 'In progress', value: 34, color: 'var(--cascivo-color-warning)' },
+    { id: 'blocked', label: 'Blocked', value: 16, color: 'var(--cascivo-color-destructive)' },
+  ]}
+  title="Task status"
+/>
+```
+
+### Percentage tooltip + empty state
+
+```jsx
+import { PieChart } from '@cascivo/charts'
+
+// Default tooltip shows "value (pct%)" in the slice color; pass tooltipFormat to override.
+<PieChart data={[{id:'a',label:'A',value:60},{id:'b',label:'B',value:40}]} title="Share" />
+
+// Empty data renders a visible "No data" placeholder (override via emptyLabel).
+<PieChart data={[]} title="Share" emptyLabel="Nothing tracked yet" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo PieChart component (chart). Pie or donut chart with hover segments and optional legend.
+
+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).
+
+PieChart is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/polar.md

@@ -0,0 +1,92 @@
+# Polar
+
+**Category:** chart  
+**Description:** A polar coordinate plot — categories around the circle, value as radius. Bars (a rose), or a polar line/area.
+
+## When to use
+
+- Cyclical/directional categories where the circle is meaningful (wind, hours, months)
+- A rose chart comparing a value across directions
+
+## When NOT to use
+
+- Precise magnitude comparison — use BarChart
+- Multi-metric profiles on shared axes — use Radar
+
+## Related components
+
+- **Radar** (alternative): Use to compare several series across the same axes
+- **RadialBar** (alternative): Use concentric rings for progress-to-goal
+
+## Accessibility rationale
+
+Renders with role="img"; values are in the fallback table.
+
+## Props
+
+| Name          | Type                        | Required | Default | Description                                               |
+| ------------- | --------------------------- | -------- | ------- | --------------------------------------------------------- |
+| `data`        | `PolarDatum[]`              | Yes      | —       | One entry per category: { label, value, color? }.         |
+| `title`       | `string`                    | Yes      | —       | Chart title (also aria-label).                            |
+| `description` | `string`                    | No       | —       | Supporting description text.                              |
+| `mode`        | `'bar' \| 'line' \| 'area'` | No       | bar     | Bars (rose), a polar line, or a filled polar area.        |
+| `width`       | `number`                    | No       | —       | Width of the component.                                   |
+| `height`      | `number`                    | No       | 320     | Height of the component.                                  |
+| `rings`       | `number`                    | No       | 4       | Radial ring count.                                        |
+| `max`         | `number`                    | No       | —       | Domain top (full radius). Defaults to the largest value.  |
+| `tooltip`     | `boolean`                   | No       | —       | Enable hover tooltip.                                     |
+| `className`   | `string`                    | No       | —       | Additional CSS class names merged onto the root element.  |
+| `plain`       | `boolean`                   | No       | false   | Marks only — no rings or labels. For micro/inline charts. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+- `--cascivo-chart-grid`
+
+## Examples
+
+### Wind rose
+
+```jsx
+import { Polar } from '@cascivo/charts'
+;<Polar
+  title="Wind by direction"
+  mode="bar"
+  tooltip
+  data={[
+    { label: 'N', value: 12 },
+    { label: 'E', value: 8 },
+    { label: 'S', value: 5 },
+    { label: 'W', value: 15 },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Polar component (chart). A polar coordinate plot — categories around the circle, value as radius. Bars (a rose), or a polar line/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).
+
+Polar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8, --cascivo-chart-grid
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/radar.md

@@ -0,0 +1,81 @@
+# Radar
+
+**Category:** chart  
+**Description:** Radar / spider chart with polar grid rings, spokes, and multi-series polygon overlays.
+
+## When to use
+
+- Comparing several entities across the same set of quantitative dimensions
+- Showing a multi-attribute profile or balance at a glance
+
+## When NOT to use
+
+- Precise value reading — polar axes distort comparison
+- More than a few series — overlapping polygons become unreadable
+
+## Related components
+
+- **BarChart** (alternative): Use when precise per-dimension comparison matters
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                                | Required | Default | Description                                                           |
+| ------------- | --------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------- |
+| `axes`        | `string[]`                                          | Yes      | —       | Axis labels (one per dimension)                                       |
+| `series`      | `{ id: string; label: string; values: number[] }[]` | Yes      | —       | One value per axis per series                                         |
+| `max`         | `number`                                            | No       | —       | Maximum value (defaults to data max)                                  |
+| `title`       | `string`                                            | Yes      | —       | Title text for the component.                                         |
+| `description` | `string`                                            | No       | —       | Supporting description text.                                          |
+| `width`       | `number`                                            | No       | —       | Width of the component.                                               |
+| `height`      | `number`                                            | No       | 320     | Height of the component.                                              |
+| `className`   | `string`                                            | No       | —       | Additional CSS class names merged onto the root element.              |
+| `plain`       | `boolean`                                           | No       | false   | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Basic radar chart
+
+```jsx
+import { Radar } from '@cascivo/charts'
+
+const axes = ['Speed','Power','Range','Efficiency','Cost']
+const series = [{ id:'a', label:'Model A', values:[80,70,60,90,50] }]
+<Radar axes={axes} series={series} title="Model comparison" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Radar component (chart). Radar / spider chart with polar grid rings, spokes, and multi-series polygon overlays.
+
+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).
+
+Radar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/radial-bar.md

@@ -0,0 +1,96 @@
+# RadialBar
+
+**Category:** chart  
+**Description:** Concentric radial bars (a circular gauge family) — each datum is a ring whose sweep is proportional to its value.
+
+## When to use
+
+- Showing a few progress-to-goal values in a compact circular form
+- A dashboard KPI cluster where each metric is a ring toward its target
+
+## When NOT to use
+
+- Comparing many categories precisely — use BarChart
+- Part-of-whole of a single total — use PieChart
+
+## Related components
+
+- **Meter** (alternative): Use for a single value against thresholds
+- **PieChart** (alternative): Use for part-of-whole proportions of one total
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type               | Required | Default | Description                                                                    |
+| ------------- | ------------------ | -------- | ------- | ------------------------------------------------------------------------------ |
+| `data`        | `RadialBarDatum[]` | Yes      | —       | One ring per datum: { id, label, value, color? }.                              |
+| `title`       | `string`           | Yes      | —       | Chart title (also used as aria-label).                                         |
+| `description` | `string`           | No       | —       | Subtitle below the title.                                                      |
+| `size`        | `number`           | No       | —       | Square shorthand (width === height). Explicit width/height win.                |
+| `width`       | `number`           | No       | —       | Width of the component.                                                        |
+| `height`      | `number`           | No       | 300     | Height of the component.                                                       |
+| `max`         | `number`           | No       | —       | Domain top — the value a full sweep represents. Defaults to the largest datum. |
+| `sweep`       | `number`           | No       | 270     | Sweep angle in degrees (270 = a gauge arc; 360 = a full ring).                 |
+| `centerValue` | `string`           | No       | —       | Text in the hole.                                                              |
+| `centerLabel` | `string`           | No       | —       | Caption below centerValue.                                                     |
+| `centerSlot`  | `ReactNode`        | No       | —       | Arbitrary hole content; wins over centerValue/centerLabel.                     |
+| `tooltip`     | `boolean`          | No       | —       | Enable hover tooltip.                                                          |
+| `legend`      | `boolean`          | No       | —       | Show ring legend.                                                              |
+| `className`   | `string`           | No       | —       | Additional CSS class names merged onto the root element.                       |
+| `plain`       | `boolean`          | No       | false   | Marks only — no legend. For micro/inline charts.                               |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+- `--cascivo-chart-grid`
+
+## Examples
+
+### Goal progress rings
+
+```jsx
+import { RadialBar } from '@cascivo/charts'
+;<RadialBar
+  title="Quarterly goals"
+  max={100}
+  centerValue="72%"
+  centerLabel="On track"
+  data={[
+    { id: 'rev', label: 'Revenue', value: 84 },
+    { id: 'nps', label: 'NPS', value: 61 },
+    { id: 'ret', label: 'Retention', value: 72 },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo RadialBar component (chart). Concentric radial bars (a circular gauge family) — each datum is a ring whose sweep is proportional to its value.
+
+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).
+
+RadialBar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8, --cascivo-chart-grid
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate rings)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/sankey.md

@@ -0,0 +1,89 @@
+# Sankey
+
+**Category:** chart  
+**Description:** Flow diagram — ranked nodes connected by throughput-sized link ribbons.
+
+## When to use
+
+- Showing flow/throughput between stages or categories
+- Visualizing where volume splits and merges
+
+## When NOT to use
+
+- Strict ordered stages with one path — use Funnel
+- Arbitrary node/edge graphs — use @cascivo/flow
+
+## Related components
+
+- **Funnel** (alternative): Use for a single decreasing path
+
+## Accessibility rationale
+
+Renders role="img" with a title and a fallback from/to/value table.
+
+## Props
+
+| Name          | Type           | Required | Default | Description                                                |
+| ------------- | -------------- | -------- | ------- | ---------------------------------------------------------- |
+| `nodes`       | `SankeyNode[]` | Yes      | —       | Nodes: { id, label, color? }.                              |
+| `links`       | `SankeyLink[]` | Yes      | —       | Links: { source, target, value }.                          |
+| `title`       | `string`       | Yes      | —       | Title text for the component.                              |
+| `description` | `string`       | No       | —       | Supporting description text.                               |
+| `width`       | `number`       | No       | —       | Width of the component.                                    |
+| `height`      | `number`       | No       | 320     | Height of the component.                                   |
+| `tooltip`     | `boolean`      | No       | —       | Whether to show tooltips on hover.                         |
+| `className`   | `string`       | No       | —       | Additional CSS class names merged onto the root element.   |
+| `plain`       | `boolean`      | No       | false   | When true, renders a minimal variant without chart chrome. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Sankey flow
+
+```jsx
+import { Sankey } from '@cascivo/charts'
+;<Sankey
+  title="Traffic flow"
+  nodes={[
+    { id: 'a', label: 'Search' },
+    { id: 'b', label: 'Home' },
+    { id: 'c', label: 'Signup' },
+  ]}
+  links={[
+    { source: 'a', target: 'b', value: 30 },
+    { source: 'b', target: 'c', value: 12 },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Sankey component (chart). Flow diagram — ranked nodes connected by throughput-sized link ribbons.
+
+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).
+
+Sankey is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate nodes)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/scatter-chart.md

@@ -0,0 +1,90 @@
+# ScatterChart
+
+**Category:** chart  
+**Description:** Scatter plot with variable point radius, multi-series, and hover tooltip.
+
+## When to use
+
+- Revealing correlation or clustering between two numeric variables
+- Plotting many individual observations across a 2D space
+
+## When NOT to use
+
+- Encoding a third magnitude dimension — use BubbleChart
+- Showing a trend over ordered time — use LineChart
+
+## Related components
+
+- **BubbleChart** (alternative): Use when a third size dimension must be encoded
+- **LineChart** (alternative): Use when points form an ordered trend over time
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                          | Required | Default | Description                                                                                                                               |
+| ------------- | --------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `series`      | `ScatterChartSeries[]`                        | Yes      | —       | The data series to plot.                                                                                                                  |
+| `title`       | `string`                                      | Yes      | —       | Title text for the component.                                                                                                             |
+| `description` | `string`                                      | No       | —       | Supporting description text.                                                                                                              |
+| `r`           | `number \| ((d: ScatterDatum) => number)`     | No       | 4       | Point radius or accessor                                                                                                                  |
+| `width`       | `number`                                      | No       | —       | Width of the component.                                                                                                                   |
+| `height`      | `number`                                      | No       | 300     | Height of the component.                                                                                                                  |
+| `xTicks`      | `number`                                      | No       | 5       | Approximate number of ticks on the x-axis.                                                                                                |
+| `yTicks`      | `number`                                      | No       | 5       | Approximate number of ticks on the y-axis.                                                                                                |
+| `legend`      | `boolean`                                     | No       | —       | Whether to show the legend.                                                                                                               |
+| `tooltip`     | `boolean`                                     | No       | —       | Enable hover/keyboard tooltip                                                                                                             |
+| `className`   | `string`                                      | No       | —       | Additional CSS class names merged onto the root element.                                                                                  |
+| `plain`       | `boolean`                                     | No       | false   | Marks only — no axes, grid lines, or legend. For micro/inline charts.                                                                     |
+| `annotations` | `Annotation[]`                                | No       | —       | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line).                                            |
+| `onSelect`    | `(point: ChartPoint) => void`                 | No       | —       | Fired when a point is clicked or activated (Enter/Space) — for drill-down.                                                                |
+| `glyph`       | `GlyphShape \| ((d, seriesId) => GlyphShape)` | No       | —       | Point glyph shape (circle/square/diamond/triangle/cross/star) — a fixed shape or a function to encode a category by shape.                |
+| `renderer`    | `'svg' \| 'canvas' \| 'auto'`                 | No       | svg     | Renderer — svg (default), canvas (force), or auto (canvas past ~2000 points). Canvas keeps the full a11y fallback table + keyboard layer. |
+| `visualMap`   | `VisualMapOptions`                            | No       | —       | Map each point’s y → CVD-safe colour and/or size via a keyboard-operable legend that filters the visible range.                           |
+| `toolbox`     | `boolean \| ToolboxOptions`                   | No       | —       | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset the visualMap filter).                 |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Basic scatter chart
+
+```jsx
+import { ScatterChart } from '@cascivo/charts'
+
+const series = [{ id: 'a', label: 'Group A', data: [{x:1,y:2},{x:3,y:4}] }]
+<ScatterChart series={series} title="Scatter" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ScatterChart component (chart). Scatter plot with variable point radius, multi-series, and hover tooltip.
+
+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).
+
+ScatterChart is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate points)/Home/End (first/last point)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```