@cascivo/mcp 0.1.8 → 0.3.3

package/dist/context/button-group.md

@@ -0,0 +1,100 @@
+# ButtonGroup
+
+**Category:** inputs  
+**Description:** Visually joins a set of related buttons into a single segmented control
+
+## When to use
+
+- Presenting several related, independent actions that read as one control (e.g. an editor toolbar)
+- Visually grouping buttons that share context without implying mutual exclusivity
+
+## When NOT to use
+
+- The buttons represent a single selected value among options — use ToggleGroup
+- The actions are unrelated and should read as separate buttons — lay them out with spacing instead
+
+## Anti-patterns
+
+### A group with no accessible name is announced as an unlabeled region; supply aria-label or aria-labelledby
+
+**Bad:** `<ButtonGroup><Button>Bold</Button><Button>Italic</Button></ButtonGroup>`  
+**Good:** `<ButtonGroup aria-label="Formatting"><Button>Bold</Button><Button>Italic</Button></ButtonGroup>`  
+**Why:** A group with no accessible name is announced as an unlabeled region; supply aria-label or aria-labelledby
+
+## Related components
+
+- **ToggleGroup** (alternative): Use when the buttons select a value rather than fire independent actions
+- **Button** (contains): A button group is a layout container for buttons
+
+## Accessibility rationale
+
+Exposes role="group" so assistive tech treats the buttons as one labeled set; optional roving focus lets arrow keys traverse the buttons as a single tab stop, matching toolbar expectations
+
+## Props
+
+| Name              | Type                         | Required | Default    | Description                                                               |
+| ----------------- | ---------------------------- | -------- | ---------- | ------------------------------------------------------------------------- |
+| `orientation`     | `'horizontal' \| 'vertical'` | No       | horizontal | Layout orientation of the component.                                      |
+| `size`            | `'sm' \| 'md' \| 'lg'`       | No       | md         | Visual size of the component (e.g. 'sm', 'md', 'lg').                     |
+| `roving`          | `boolean`                    | No       | false      | When true, uses roving tabindex so arrow keys move focus between buttons. |
+| `loop`            | `boolean`                    | No       | false      | When true, navigation wraps around from end to start.                     |
+| `aria-label`      | `string`                     | No       | —          | Accessible label used when no visible label is present.                   |
+| `aria-labelledby` | `string`                     | No       | —          | Id of the element that labels this component.                             |
+
+## Tokens
+
+- `--cascivo-button-radius`
+- `--cascivo-radius-control`
+
+## Examples
+
+### Joined actions
+
+```jsx
+<ButtonGroup aria-label="Text alignment">
+  <Button>Left</Button>
+  <Button>Center</Button>
+  <Button>Right</Button>
+</ButtonGroup>
+```
+
+### Vertical with roving focus
+
+```jsx
+<ButtonGroup orientation="vertical" roving aria-label="View">
+  <Button>List</Button>
+  <Button>Grid</Button>
+</ButtonGroup>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                                               |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| token names | strict   | Outer corner radius must resolve to --cascivo-button-radius / --cascivo-radius-control to match standalone buttons |
+| children    | flexible | Any focusable controls (Button, IconButton, links) may be grouped                                                  |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ButtonGroup component (inputs). Visually joins a set of related buttons into a single segmented control
+
+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).
+
+ButtonGroup is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-button-radius, --cascivo-radius-control
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: ArrowRight/ArrowLeft/ArrowUp/ArrowDown/Home/End. Keep it AA.
+
+Do not change (strict): token names — Outer corner radius must resolve to --cascivo-button-radius / --cascivo-radius-control to match standalone buttons
+Flexible: children.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/button.md

@@ -0,0 +1,117 @@
+# Button
+
+**Category:** inputs  
+**Description:** Triggers an action or event
+
+## When to use
+
+- Triggering an action or navigation the user initiates by click/press
+- Submitting a form or confirming a decision
+
+## When NOT to use
+
+- Navigation between pages where a real link is semantically correct — use an anchor
+- Toggling a binary setting — use Toggle; persistent selection — use Checkbox/Radio
+
+## Anti-patterns
+
+### Buttons are for actions, links for navigation — assistive tech and the browser treat them differently
+
+**Bad:** `<Button onClick={() => navigate("/x")}>Home</Button>`  
+**Good:** `<a href="/x">Home</a>`  
+**Why:** Buttons are for actions, links for navigation — assistive tech and the browser treat them differently
+
+## Related components
+
+- **Toggle** (alternative): Use for binary on/off state, not one-shot actions
+- **Dropdown** (pairs-with): A button often triggers a menu
+
+## Accessibility rationale
+
+Renders a native <button> so Enter/Space activation, focus, and role come from the platform; loading state uses aria-busy rather than removing the element so focus is preserved
+
+## Props
+
+| Name       | Type                                                   | Required | Default | Description                                                                                       |
+| ---------- | ------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `variant`  | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | No       | primary | Selects the visual style variant.                                                                 |
+| `size`     | `'sm' \| 'md' \| 'lg'`                                 | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').                                             |
+| `loading`  | `boolean`                                              | No       | false   | When true, shows a loading state.                                                                 |
+| `disabled` | `boolean`                                              | No       | false   | When true, disables the control and removes it from the tab order.                                |
+| `asChild`  | `boolean`                                              | No       | false   | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
+| `onClick`  | `React.MouseEventHandler<HTMLButtonElement>`           | No       | —       | Called when the element is clicked.                                                               |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-hover`
+- `--cascivo-color-accent-active`
+- `--cascivo-color-text-on-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-radius-button`
+- `--cascivo-focus-ring`
+- `--cascivo-disabled-opacity`
+- `--cascivo-text-ui`
+- `--cascivo-text-body`
+
+## Examples
+
+### Primary
+
+```jsx
+<Button>Click me</Button>
+```
+
+### Loading
+
+```jsx
+<Button loading>Saving…</Button>
+```
+
+### Destructive
+
+```jsx
+<Button variant="destructive">Delete</Button>
+```
+
+### As link
+
+Render button styling on a real anchor (keeps middle-click / open-in-new-tab).
+
+```jsx
+<Button asChild>
+  <a href="/pricing">View pricing</a>
+</Button>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                               |
+| ----------- | -------- | ------------------------------------------------------------------ |
+| token names | strict   | Visual props must resolve to --cascivo-button-\* / semantic tokens |
+| label copy  | flexible | Free, within tone guidance                                         |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Button component (inputs). Triggers an action or event
+
+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).
+
+Button is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-accent-hover, --cascivo-color-accent-active, --cascivo-color-text-on-accent, --cascivo-color-destructive, --cascivo-radius-button, --cascivo-focus-ring, --cascivo-disabled-opacity, --cascivo-text-ui, --cascivo-text-body
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): token names — Visual props must resolve to --cascivo-button-* / semantic tokens
+Flexible: label copy.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/calendar.md

@@ -0,0 +1,118 @@
+# Calendar
+
+**Category:** inputs  
+**Description:** An accessible standalone month-grid date picker.
+
+## When to use
+
+- Showing an always-visible month grid for picking a single date (inline, not a popover)
+- As the building block inside a date-picker or date-range-picker popover
+
+## When NOT to use
+
+- A compact form field where an inline grid wastes space — use DatePicker (trigger + popover)
+- Selecting a contiguous date range — use DateRangePicker, which composes two calendars
+
+## Anti-patterns
+
+### Local-time construction can land a midnight date on the previous day in negative-offset zones, breaking selection and range math
+
+**Bad:** `Comparing dates with local-time getters (getHours/getDate) after constructing them with new Date(y, m, d)`  
+**Good:** `All arithmetic and comparisons use UTC getters/Date.UTC so DST and timezone offsets never shift a day`  
+**Why:** Local-time construction can land a midnight date on the previous day in negative-offset zones, breaking selection and range math
+
+## Related components
+
+- **DatePicker** (alternative): Use the popover-based picker when an inline grid is too heavy for the layout
+- **DateRangePicker** (contained-by): The range picker renders two Calendar instances side-by-side
+
+## Accessibility rationale
+
+Renders an APG-compliant role="grid" table with role="row"/role="gridcell"; a roving tabindex keeps exactly one day focusable (the focused date) so arrow keys move focus per APG, Home/End jump to the week edges, PageUp/PageDown change month (with Shift for year), today exposes aria-current="date", selection sets data-selected with aria-selected on the cell, and out-of-range or predicate-disabled days get aria-disabled and are skipped by selection
+
+## Props
+
+| Name            | Type                                              | Required | Default | Description                                              |
+| --------------- | ------------------------------------------------- | -------- | ------- | -------------------------------------------------------- |
+| `value`         | `Date \| null`                                    | No       | —       | Controlled selected date                                 |
+| `defaultValue`  | `Date`                                            | No       | —       | Uncontrolled initial selected date                       |
+| `onValueChange` | `(date: Date) => void`                            | No       | —       | Called when a day is selected                            |
+| `min`           | `Date`                                            | No       | —       | Earliest selectable date                                 |
+| `max`           | `Date`                                            | No       | —       | Latest selectable date                                   |
+| `disabled`      | `(date: Date) => boolean`                         | No       | —       | Predicate to disable individual days                     |
+| `locale`        | `string`                                          | No       | —       | BCP-47 locale; defaults to the current i18n locale       |
+| `size`          | `'sm' \| 'md' \| 'lg'`                            | No       | —       | Grid cell size                                           |
+| `labels`        | `CalendarLabels`                                  | No       | —       | i18n label overrides for the nav buttons                 |
+| `month`         | `number`                                          | No       | —       | Controlled view month (0-11)                             |
+| `year`          | `number`                                          | No       | —       | Controlled view year                                     |
+| `onViewChange`  | `(view: { month: number; year: number }) => void` | No       | —       | Called when the visible month changes                    |
+| `hideNav`       | `boolean`                                         | No       | —       | Hides the prev/next nav so a parent can drive navigation |
+
+## Tokens
+
+- `--cascivo-calendar-bg`
+- `--cascivo-calendar-radius`
+- `--cascivo-calendar-cell-size`
+- `--cascivo-calendar-day-selected-bg`
+- `--cascivo-calendar-day-selected-fg`
+- `--cascivo-calendar-day-today-color`
+- `--cascivo-calendar-range-bg`
+
+## Examples
+
+### Basic
+
+Uncontrolled calendar
+
+```jsx
+<Calendar defaultValue={new Date(Date.UTC(2024, 5, 15))} />
+```
+
+### Constrained
+
+Limits the selectable range
+
+```jsx
+<Calendar min={new Date(Date.UTC(2024, 5, 1))} max={new Date(Date.UTC(2024, 5, 30))} />
+```
+
+### Disabled weekends
+
+Predicate disables individual days
+
+```jsx
+<Calendar disabled={(d) => [0, 6].includes(d.getUTCDay())} />
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                                      |
+| ------------ | -------- | --------------------------------------------------------------------------------------------------------- |
+| date type    | strict   | All date props are native Date objects compared in UTC                                                    |
+| locale       | flexible | Weekday labels, month label, and first-day-of-week derive from the locale via Intl (with Monday fallback) |
+| view control | flexible | month/year/onViewChange/hideNav let a parent drive navigation (used by DateRangePicker)                   |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Calendar component (inputs). An accessible standalone month-grid date picker.
+
+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).
+
+Calendar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-calendar-bg, --cascivo-calendar-radius, --cascivo-calendar-cell-size, --cascivo-calendar-day-selected-bg, --cascivo-calendar-day-selected-fg, --cascivo-calendar-day-today-color, --cascivo-calendar-range-bg
+
+Accessibility: role "grid", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowUp/ArrowDown/Home/End/PageUp/PageDown/Enter/Space. Keep it AA.
+
+Do not change (strict): date type — All date props are native Date objects compared in UTC
+Flexible: locale, view control.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/card.md

@@ -0,0 +1,90 @@
+# Card
+
+**Category:** display  
+**Description:** Container for grouping related content
+
+## When to use
+
+- Grouping related content into a visually distinct surface with border/shadow
+- Creating scannable units in a grid or list (dashboard tiles, item summaries)
+- Giving a content cluster elevation to separate it from the page background
+
+## When NOT to use
+
+- Pure semantic/structural grouping with no surface — use a <section>
+- Wrapping every element in a card — nesting surfaces flattens visual hierarchy
+
+## Anti-patterns
+
+### Stacked surfaces and shadows compete for attention and muddy the hierarchy
+
+**Bad:** `Nesting Cards several levels deep for layout`  
+**Good:** `A single Card with internal spacing, or a plain <section>`  
+**Why:** Stacked surfaces and shadows compete for attention and muddy the hierarchy
+
+## Related components
+
+- **Separator** (pairs-with): Use a Separator to divide regions inside a card
+
+## Accessibility rationale
+
+role="region" is appropriate only when the card is a meaningful landmark; otherwise treat it as presentational — the visual surface adds no semantics on its own
+
+## Props
+
+| Name      | Type                                    | Required | Default | Description                       |
+| --------- | --------------------------------------- | -------- | ------- | --------------------------------- |
+| `variant` | `'default' \| 'outlined' \| 'elevated'` | No       | default | Selects the visual style variant. |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'`        | No       | md      | Inner padding of the component.   |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-card`
+- `--cascivo-shadow-md`
+
+## Examples
+
+### Basic card
+
+```jsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content here</CardContent>
+</Card>
+```
+
+## Boundaries
+
+| Area                | Level    | Note                                                                    |
+| ------------------- | -------- | ----------------------------------------------------------------------- |
+| variant and padding | flexible | Choose elevation and density to fit the surrounding layout              |
+| token names         | strict   | Surface, border, radius, and shadow must resolve to --cascivo-\* tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Card component (display). Container for grouping related 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).
+
+Card is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-card, --cascivo-shadow-md
+
+Accessibility: role "region", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Surface, border, radius, and shadow must resolve to --cascivo-* tokens
+Flexible: variant and padding.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/carousel.md

@@ -0,0 +1,101 @@
+# Carousel
+
+**Category:** display  
+**Description:** Scroll-snap slide deck with previous/next controls and dot indicators
+
+## When to use
+
+- Presenting a sequence of media or cards the user pages through one at a time
+- Image galleries, onboarding decks, or featured-content rotators
+- When horizontal swiping/scrolling is a natural interaction on touch devices
+
+## When NOT to use
+
+- Content users must compare side-by-side — show a grid instead
+- Critical information that must always be visible — carousels hide most of their content
+
+## Anti-patterns
+
+### Auto-rotation and hidden slides reduce discoverability and accessibility of important content
+
+**Bad:** `Auto-rotating carousel for primary navigation or key calls-to-action`  
+**Good:** `A static list or grid where every item is visible`  
+**Why:** Auto-rotation and hidden slides reduce discoverability and accessibility of important content
+
+## Related components
+
+- **Tabs** (alternative): Use tabs when sections are distinct and should be directly addressable
+
+## Accessibility rationale
+
+The container is a labelled region with aria-roledescription="carousel"; each slide is a labelled group ("n of total"); prev/next are real buttons and the dot indicators use roving tabindex with arrow-key navigation. Scrolling honours prefers-reduced-motion.
+
+## Props
+
+| Name            | Type                      | Required | Default | Description                                           |
+| --------------- | ------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `children`      | `ReactNode`               | No       | —       | Slides as children                                    |
+| `slides`        | `ReactNode[]`             | No       | —       | Slides as an array                                    |
+| `index`         | `number`                  | No       | —       | Controlled active index                               |
+| `defaultIndex`  | `number`                  | No       | 0       | The initial slide index when uncontrolled.            |
+| `onIndexChange` | `(index: number) => void` | No       | —       | Called with the new slide index when it changes.      |
+| `loop`          | `boolean`                 | No       | false   | When true, navigation wraps around from end to start. |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-radius-md`
+- `--cascivo-radius-full`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Carousel>
+  <img src="/1.jpg" alt="" />
+  <img src="/2.jpg" alt="" />
+</Carousel>
+```
+
+### Looping with array
+
+```jsx
+<Carousel loop slides={[<Slide1 />, <Slide2 />, <Slide3 />]} />
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                             |
+| ------------- | -------- | -------------------------------------------------------------------------------- |
+| transition    | strict   | Paging uses native CSS scroll-snap, not transform math — no custom easing config |
+| slide content | flexible | Any ReactNode may be a slide; pass via children or the slides array              |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Carousel component (display). Scroll-snap slide deck with previous/next controls and dot indicators
+
+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).
+
+Carousel is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-radius-md, --cascivo-radius-full, --cascivo-focus-ring
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/Home/End. Keep it AA.
+
+Do not change (strict): transition — Paging uses native CSS scroll-snap, not transform math — no custom easing config
+Flexible: slide content.
+
+Do not invent props, tokens, or global viewport media queries.
+```

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

@@ -0,0 +1,99 @@
+# AreaChart
+
+**Category:** chart  
+**Description:** Area chart with optional stacking, multi-series support, and hover tooltip.
+
+## When to use
+
+- Showing cumulative volume or magnitude of a trend over continuous time
+- Emphasising the total of stacked multi-series values across a range
+
+## When NOT to use
+
+- Reading precise individual values — use LineChart
+- Comparing discrete categories — use BarChart
+
+## Related components
+
+- **LineChart** (alternative): Use when precise values matter more than filled volume
+- **BarChart** (alternative): Use for discrete categorical comparison
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                                                                                                    | Required | Default  | Description                                                                                                                 |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `series`      | `AreaChartSeries<Datum>[]`                                                                                              | Yes      | —        | Array of data series                                                                                                        |
+| `x`           | `(d: Datum) => number`                                                                                                  | Yes      | —        | X-value accessor                                                                                                            |
+| `y`           | `(d: Datum) => number`                                                                                                  | Yes      | —        | Y-value accessor                                                                                                            |
+| `title`       | `string`                                                                                                                | Yes      | —        | Title text for the component.                                                                                               |
+| `description` | `string`                                                                                                                | No       | —        | Supporting description text.                                                                                                |
+| `stacked`     | `boolean`                                                                                                               | No       | —        | Stack series areas                                                                                                          |
+| `curve`       | `'linear' \| 'monotone' \| 'step' \| 'stepBefore' \| 'stepAfter' \| 'natural' \| 'basis' \| 'cardinal' \| 'catmullRom'` | No       | monotone | Line/area interpolation curve.                                                                                              |
+| `fill`        | `'solid' \| 'gradient' \| 'pattern'`                                                                                    | No       | solid    | Area fill style — solid, a top→bottom gradient, or a pattern.                                                               |
+| `patternKind` | `'dots' \| 'lines' \| 'cross'`                                                                                          | No       | —        | Pattern motif when fill="pattern".                                                                                          |
+| `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).                              |
+| `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.                                                  |
+| `brush`       | `boolean`                                                                                                               | No       | false    | Show a keyboard-operable Brush below the plot to subset the series to a window.                                             |
+| `dataZoom`    | `boolean`                                                                                                               | No       | false    | Show a DataZoom slider below the plot — a Brush whose body also pans the window.                                            |
+| `zoom`        | `boolean`                                                                                                               | No       | false    | Enable in-plot wheel/drag/keyboard zoom-pan (+/-/0) over the series index window, with a reset control and re-ticked axes.  |
+| `syncId`      | `string`                                                                                                                | No       | —        | Connect this chart to others sharing the same id — they mirror the zoom window and hovered x.                               |
+| `tooltipMode` | `'item' \| 'axis'`                                                                                                      | No       | item     | Tooltip trigger — item (nearest point) or axis (a crosshair + a shared tooltip listing every series at the hovered x).      |
+| `decimate`    | `boolean \| { method?: 'lttb' \| 'minmax'; threshold?: number }`                                                        | No       | —        | Downsample dense non-stacked series before drawing (LTTB or min-max). Visual only — the fallback table keeps the full data. |
+| `toolbox`     | `boolean \| ToolboxOptions`                                                                                             | No       | —        | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset zoom).                   |
+
+## 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 area chart
+
+```jsx
+import { AreaChart } from '@cascivo/charts'
+
+const series = [{ id: 'a', label: 'Revenue', data: [{x:1,y:10},{x:2,y:20}] }]
+<AreaChart series={series} x={d => d.x} y={d => d.y} title="Revenue" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AreaChart component (chart). Area chart with optional stacking, multi-series support, 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).
+
+AreaChart 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.
+```