@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/app-shell.md

@@ -0,0 +1,98 @@
+# AppShell
+
+**Category:** layout  
+**Description:** Sticky-header + full-height side-nav + single-scroll-container layout with an animated, accessible nav toggle.
+
+## When to use
+
+- Building an application screen with a persistent header and side navigation
+- You want the header burger to toggle the side nav with an animated, accessible show/hide out of the box
+- You need one scroll container (the main area) with a fixed header and full-height nav
+
+## When NOT to use
+
+- Marketing/document pages where the whole page should scroll — use a plain Header instead
+- A single, always-visible sidebar with no toggle — compose SideNav directly
+- You need a persisted collapsible sidebar, a top progress bar, or a right aside — that is the richer copy-paste `layout/app-shell` (different props: `sideNav`/`aside`/`persistKey`/`state`), not this drop-in.
+
+## Anti-patterns
+
+### fr units have no definite size to resolve against on a shrink-to-fit flex item, so the track never animates
+
+**Bad:** `Animating the nav collapse with grid-template-columns: 1fr → 0fr on an auto-width sidebar`  
+**Good:** `AppShell animates an explicit inline-size (desktop) / transform (mobile drawer)`  
+**Why:** fr units have no definite size to resolve against on a shrink-to-fit flex item, so the track never animates
+
+## Related components
+
+- **layout/app-shell** (alternative): A richer, copy-paste-only app shell with a persisted collapsible sidebar, a signal-driven top progress bar, an error strip, and a right aside. Same `AppShell` name, different prop surface (`sideNav`/`aside`/`persistKey`/`state`). Choose this npm drop-in for a simple header + toggleable nav; choose layout/app-shell when you need persistence/progress/aside.
+- **ShellHeader** (pairs-with): Provides the top bar and burger AppShell binds to the nav
+- **SideNav** (pairs-with): The side navigation AppShell lays out full-height
+
+## Accessibility rationale
+
+The hidden nav uses transform/inline-size + inert (never display:none alone), so it stays in the a11y tree and is keyboard-reachable when open while leaving the tab order when closed; Escape and a scrim close the mobile drawer and focus returns to the toggle.
+
+## Props
+
+| Name           | Type                      | Required | Default | Description                                                                                                      |
+| -------------- | ------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| `header`       | `ReactNode`               | Yes      | —       | Top bar (typically a ShellHeader). If a React element, its onMenuClick/menuExpanded are bound to the nav toggle. |
+| `nav`          | `ReactNode`               | No       | —       | Side navigation (typically a SideNav). Fills full height and scrolls internally.                                 |
+| `children`     | `ReactNode`               | Yes      | —       | Main content, rendered inside the single scroll container.                                                       |
+| `footer`       | `ReactNode`               | No       | —       | Optional footer pinned below the content area.                                                                   |
+| `open`         | `boolean`                 | No       | —       | Controlled nav open/visible state. Omit for uncontrolled.                                                        |
+| `defaultOpen`  | `boolean`                 | No       | —       | Initial open state when uncontrolled. Defaults open on desktop, closed on small screens.                         |
+| `onOpenChange` | `(open: boolean) => void` | No       | —       | Fired when the nav requests open/close (burger, Escape, scrim).                                                  |
+
+## Tokens
+
+- `--cascivo-shell-aside-inline-size`
+- `--cascivo-shell-panel-inline-size`
+- `--cascivo-motion-emphasis`
+- `--cascivo-z-raised`
+- `--cascivo-z-overlay`
+- `--cascivo-color-foreground`
+- `--cascivo-color-background`
+
+## Examples
+
+### Header + SideNav + content
+
+The burger in ShellHeader toggles the SideNav automatically.
+
+```jsx
+<AppShell header={<ShellHeader brand={{ name: 'Acme' }} />} nav={<SideNav items={items} />}>
+  <h1>Dashboard</h1>
+</AppShell>
+```
+
+### Controlled open
+
+```jsx
+<AppShell header={header} nav={nav} open={open.value} onOpenChange={(v) => (open.value = v)}>
+  …
+</AppShell>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AppShell component (layout). Sticky-header + full-height side-nav + single-scroll-container layout with an animated, accessible nav toggle.
+
+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).
+
+AppShell is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-shell-aside-inline-size, --cascivo-shell-panel-inline-size, --cascivo-motion-emphasis, --cascivo-z-raised, --cascivo-z-overlay, --cascivo-color-foreground, --cascivo-color-background
+
+Accessibility: role "none", WCAG 2.2-AA, keyboard: Escape. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/aspect-ratio.md

@@ -0,0 +1,92 @@
+# AspectRatio
+
+**Category:** layout  
+**Description:** Constrains content to a fixed width-to-height ratio
+
+## When to use
+
+- Reserving a stable box for media that loads asynchronously, avoiding layout shift
+- Embedding responsive iframes (video, maps) at a known proportion
+- Keeping thumbnails or covers uniform across a grid
+
+## When NOT to use
+
+- Content whose height should grow with text — let it size naturally
+- A single fixed-pixel image where width and height are already known
+
+## Anti-patterns
+
+### A fixed ratio clips or distorts content that needs variable height
+
+**Bad:** `Wrapping text content that must expand to fit its lines`  
+**Good:** `Reserve AspectRatio for media; let prose flow at its intrinsic height`  
+**Why:** A fixed ratio clips or distorts content that needs variable height
+
+## Related components
+
+- **Card** (contained-by): Commonly holds a cover image inside a Card media region
+
+## Accessibility rationale
+
+Purely presentational wrapper with no role; the inner media element carries its own semantics and alt text
+
+## Props
+
+| Name       | Type        | Required | Default | Description                                                          |
+| ---------- | ----------- | -------- | ------- | -------------------------------------------------------------------- |
+| `ratio`    | `number`    | No       | 16 / 9  | Width-to-height ratio applied via the CSS aspect-ratio property      |
+| `children` | `ReactNode` | No       | —       | Content to fill the ratio box (typically an image, video, or iframe) |
+
+## Tokens
+
+- `--cascivo-aspect-ratio`
+
+## Examples
+
+### Image at 16:9
+
+```jsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/cover.jpg" alt="Cover" />
+</AspectRatio>
+```
+
+### Square
+
+```jsx
+<AspectRatio ratio={1}>
+  <img src="/avatar.jpg" alt="Avatar" />
+</AspectRatio>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                             |
+| ------------ | -------- | ---------------------------------------------------------------- |
+| ratio        | flexible | Any positive number; common values are 16/9, 4/3, 1, 3/2         |
+| child sizing | strict   | The single child is stretched to fill; provide one media element |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AspectRatio component (layout). Constrains content to a fixed width-to-height ratio
+
+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).
+
+AspectRatio is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-aspect-ratio
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): child sizing — The single child is stretched to fill; provide one media element
+Flexible: ratio.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/avatar-group.md

@@ -0,0 +1,111 @@
+# AvatarGroup
+
+**Category:** display  
+**Description:** Overlapping stack of avatars with a max cap and an i18n-labelled +N overflow chip
+
+## When to use
+
+- Showing several people compactly as an overlapping stack (collaborators, attendees, reviewers)
+- Capping a long list of avatars with a +N overflow chip
+- A facepile in a card header, table cell, or activity row
+
+## When NOT to use
+
+- A single identity with a name — use User or Avatar
+- A selectable list of people — use a list/menu with checkboxes
+
+## Anti-patterns
+
+### Without a max the row grows unbounded; a cap plus total keeps it compact and accurate
+
+**Bad:** `<AvatarGroup>{hundredsOfAvatars}</AvatarGroup> with no max`  
+**Good:** `<AvatarGroup max={5} total={120}>{avatars}</AvatarGroup>`  
+**Why:** Without a max the row grows unbounded; a cap plus total keeps it compact and accurate
+
+## Related components
+
+- **Avatar** (contains): AvatarGroup arranges Avatar children and adds an overflow chip
+- **User** (alternative): Use User for a single labelled identity row
+
+## Accessibility rationale
+
+The stack is a labelled group; the +N chip carries an i18n-defaulted aria-label ("{count} more") so the hidden count is announced, not conveyed by the chip text alone
+
+## Props
+
+| Name      | Type                   | Required | Default | Description                                                                |
+| --------- | ---------------------- | -------- | ------- | -------------------------------------------------------------------------- |
+| `max`     | `number`               | No       | —       | Cap the number of visible avatars                                          |
+| `total`   | `number`               | No       | —       | Override the total count used for the +N chip                              |
+| `spacing` | `'sm' \| 'md' \| 'lg'` | No       | md      | Spacing between items.                                                     |
+| `isGrid`  | `boolean`              | No       | false   | When true, lays the avatars out in a grid instead of an overlapping stack. |
+| `labels`  | `AvatarGroupLabels`    | No       | —       | Overrides for the component’s user-visible strings (i18n).                 |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-text-muted`
+- `--cascivo-space-2`
+- `--cascivo-text-xs`
+
+## Examples
+
+### Basic
+
+```jsx
+<AvatarGroup>
+  <Avatar fallback="A" />
+  <Avatar fallback="B" />
+  <Avatar fallback="C" />
+</AvatarGroup>
+```
+
+### With max
+
+```jsx
+<AvatarGroup max={3}>
+  {users.map((u) => (
+    <Avatar key={u.id} src={u.src} alt={u.name} />
+  ))}
+</AvatarGroup>
+```
+
+### Grid
+
+```jsx
+<AvatarGroup isGrid max={8}>
+  {avatars}
+</AvatarGroup>
+```
+
+## Boundaries
+
+| Area           | Level    | Note                                                                             |
+| -------------- | -------- | -------------------------------------------------------------------------------- |
+| spacing        | flexible | Pick the overlap that fits the surrounding density                               |
+| overflow label | strict   | The +N label must come from i18n (builtin.avatarGroup.more or a labels override) |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AvatarGroup component (display). Overlapping stack of avatars with a max cap and an i18n-labelled +N overflow chip
+
+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).
+
+AvatarGroup is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-text-muted, --cascivo-space-2, --cascivo-text-xs
+
+Accessibility: role "group", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): overflow label — The +N label must come from i18n (builtin.avatarGroup.more or a labels override)
+Flexible: spacing.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/avatar.md

@@ -0,0 +1,100 @@
+# Avatar
+
+**Category:** display  
+**Description:** Displays a user image with initials fallback
+
+## When to use
+
+- Representing a person or entity with a thumbnail image and initials fallback
+- Showing presence/status alongside an identity (status prop)
+- Compactly identifying authors in lists, comments, and headers
+
+## When NOT to use
+
+- Decorative imagery unrelated to identity — use a plain <img>
+- A generic icon or logo with no person/entity meaning
+
+## Anti-patterns
+
+### Without alt/fallback the identity is invisible to assistive tech and breaks on image load failure
+
+**Bad:** `<Avatar src="/logo.png" /> with no alt and no fallback`  
+**Good:** `<Avatar src="/jane.jpg" alt="Jane Doe" fallback="JD" />`  
+**Why:** Without alt/fallback the identity is invisible to assistive tech and breaks on image load failure
+
+## Related components
+
+- **Status** (alternative): Use Status for a standalone state dot not attached to an identity
+
+## Accessibility rationale
+
+role="img" with alt names the person; on image error it falls back to initials so the identity survives; the status dot carries an accessible label rather than relying on color alone
+
+## Props
+
+| Name       | Type                                   | Required | Default | Description                                           |
+| ---------- | -------------------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `src`      | `string`                               | No       | —       | Image source URL.                                     |
+| `alt`      | `string`                               | No       | —       | Alternative text describing the image.                |
+| `fallback` | `string`                               | No       | —       | Initials shown when no image is available             |
+| `size`     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+| `status`   | `'online' \| 'offline' \| 'busy'`      | No       | —       | Status state.                                         |
+
+## Tokens
+
+- `--cascivo-color-accent-subtle`
+- `--cascivo-color-success`
+- `--cascivo-color-destructive`
+- `--cascivo-radius-full`
+
+## Examples
+
+### Image
+
+```jsx
+<Avatar src="/jane.jpg" alt="Jane Doe" />
+```
+
+### Fallback
+
+```jsx
+<Avatar fallback="JD" alt="Jane Doe" />
+```
+
+### With status
+
+```jsx
+<Avatar fallback="JD" status="online" />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                    |
+| ----------- | -------- | ----------------------------------------------------------------------- |
+| size        | flexible | Pick the size that fits the surrounding density                         |
+| token names | strict   | Fallback and status colors must resolve to --cascivo-\* semantic tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Avatar component (display). Displays a user image with initials fallback
+
+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).
+
+Avatar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent-subtle, --cascivo-color-success, --cascivo-color-destructive, --cascivo-radius-full
+
+Accessibility: role "img", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Fallback and status colors must resolve to --cascivo-* semantic tokens
+Flexible: size.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/badge.md

@@ -0,0 +1,119 @@
+# Badge
+
+**Category:** display  
+**Description:** Small status label or category indicator
+
+## When to use
+
+- Labeling an item with a short, static status or category (e.g. "New", "Beta")
+- Annotating an element with a count or state that is not interactive
+
+## When NOT to use
+
+- A removable or interactive chip (filters, selections) — use Tag
+- A standalone system state with a colored dot — use Status
+
+## Anti-patterns
+
+### Badge is a non-interactive label; interactive/removable labels belong to Tag with proper button semantics
+
+**Bad:** `<Badge onClick={removeFilter}>Active</Badge>`  
+**Good:** `<Tag onDismiss={removeFilter}>Active</Tag>`  
+**Why:** Badge is a non-interactive label; interactive/removable labels belong to Tag with proper button semantics
+
+## Related components
+
+- **Tag** (alternative): Tag is the interactive, dismissible counterpart
+- **Status** (alternative): Status pairs a colored dot with a label for live system state
+
+## Accessibility rationale
+
+role="status" lets assistive tech expose the label as state; meaning is reinforced by text, never by color alone
+
+## Props
+
+| Name      | Type                                                                               | Required | Default | Description                                           |
+| --------- | ---------------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `variant` | `'default' \| 'secondary' \| 'success' \| 'warning' \| 'destructive' \| 'outline'` | No       | default | Selects the visual style variant.                     |
+| `size`    | `'sm' \| 'md'`                                                                     | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+
+## Tokens
+
+- `--cascivo-font-sans`
+- `--cascivo-font-medium`
+- `--cascivo-radius-badge`
+- `--cascivo-space-1`
+- `--cascivo-space-2`
+- `--cascivo-space-3`
+- `--cascivo-text-xs`
+- `--cascivo-leading-normal`
+- `--cascivo-color-accent`
+- `--cascivo-color-text-on-accent`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-success-subtle`
+- `--cascivo-color-success-foreground`
+- `--cascivo-color-warning-subtle`
+- `--cascivo-color-warning-foreground`
+- `--cascivo-color-destructive-subtle`
+- `--cascivo-color-destructive-foreground`
+- `--cascivo-color-primary`
+- `--cascivo-color-primary-content`
+- `--cascivo-color-info`
+- `--cascivo-color-info-content`
+- `--cascivo-color-error`
+- `--cascivo-color-error-content`
+
+## Examples
+
+### Default
+
+```jsx
+<Badge>New</Badge>
+```
+
+### Success
+
+```jsx
+<Badge variant="success">Active</Badge>
+```
+
+### Destructive
+
+```jsx
+<Badge variant="destructive">Deprecated</Badge>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                           |
+| ----------- | -------- | ------------------------------------------------------------------------------ |
+| variant     | flexible | Choose the variant that matches the semantic meaning                           |
+| token names | strict   | Colors and radius must resolve to --cascivo-\* tokens (--cascivo-radius-badge) |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Badge component (display). Small status label or category 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).
+
+Badge is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-sans, --cascivo-font-medium, --cascivo-radius-badge, --cascivo-space-1, --cascivo-space-2, --cascivo-space-3, --cascivo-text-xs, --cascivo-leading-normal, --cascivo-color-accent, --cascivo-color-text-on-accent, --cascivo-color-bg-subtle, --cascivo-color-text, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-success-subtle, --cascivo-color-success-foreground, --cascivo-color-warning-subtle, --cascivo-color-warning-foreground, --cascivo-color-destructive-subtle, --cascivo-color-destructive-foreground, --cascivo-color-primary, --cascivo-color-primary-content, --cascivo-color-info, --cascivo-color-info-content, --cascivo-color-error, --cascivo-color-error-content
+
+Accessibility: role "status", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Colors and radius must resolve to --cascivo-* tokens (--cascivo-radius-badge)
+Flexible: variant.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/console-app.md

@@ -0,0 +1,66 @@
+# ConsoleApp
+
+**Category:** display  
+**Description:** Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main content.
+
+## When to use
+
+- A Carbon-parity console shell with icon-rail nav, header panels, and aside
+- Admin or operations consoles needing dense, app-like navigation
+
+## When NOT to use
+
+- A simpler sidebar app — use SidebarApp
+- A bare shell to fully customise — use AppShell
+
+## Related components
+
+- **SidebarApp** (alternative): Use for a lighter, less dense sidebar app frame
+- **AppShell** (alternative): Use the bare shell to compose custom console chrome
+
+## Accessibility rationale
+
+Provides header, navigation, and complementary landmarks for screen reader orientation.
+
+## Tokens
+
+- `--cascivo-shell-header-block-size`
+- `--cascivo-shell-panel-inline-size`
+- `--cascivo-shell-aside-inline-size`
+- `--cascivo-color-border`
+- `--cascivo-color-surface`
+- `--cascivo-color-scrim`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Default
+
+Full console shell demo
+
+```jsx
+<ConsoleApp />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ConsoleApp component (display). Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main 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).
+
+ConsoleApp is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-shell-header-block-size, --cascivo-shell-panel-inline-size, --cascivo-shell-aside-inline-size, --cascivo-color-border, --cascivo-color-surface, --cascivo-color-scrim, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "generic", WCAG 2.1-AA, keyboard: Escape/Tab. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/dashboard-charts.md

@@ -0,0 +1,61 @@
+# DashboardCharts
+
+**Category:** display  
+**Description:** Dashboard layout with KPI tiles, line chart, bar chart, and pie chart.
+
+## When to use
+
+- A prebuilt dashboard with KPI tiles, line, bar, and pie charts
+- Quickly demonstrating or scaffolding an analytics overview
+
+## When NOT to use
+
+- You only need the layout frame — use DashboardLayout
+- A single metric display — use a Kpi card
+
+## Related components
+
+- **DashboardLayout** (contained-by): Composes the dashboard layout frame
+- **StatsCards** (alternative): Use when you only need the KPI tile row
+
+## Accessibility rationale
+
+Charts within render with role="img" and titled labels for screen readers.
+
+## Props
+
+| Name        | Type     | Required | Default | Description                                                              |
+| ----------- | -------- | -------- | ------- | ------------------------------------------------------------------------ |
+| `className` | `string` | No       | —       | Additional CSS class names merged onto the root DashboardLayout element. |
+
+## Examples
+
+### Default
+
+Charts dashboard demo
+
+```jsx
+<DashboardCharts />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo DashboardCharts component (display). Dashboard layout with KPI tiles, line chart, bar chart, and pie chart.
+
+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).
+
+DashboardCharts is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```