@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{calendar.md → components/calendar.md}

@@ -3,20 +3,13 @@ title: Calendar
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/calendar/Calendar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/calendar.css
-props_path: packages/d4gger-design-system/src/components/calendar/calendar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Calendar.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - react-day-picker
 ---
 
 # Calendar
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{callout.md → components/callout.md}

@@ -3,13 +3,6 @@ title: Callout
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/callout/Callout.tsx
-css_path: packages/d4gger-design-system/src/styles/components/callout.css
-props_path: packages/d4gger-design-system/src/components/callout/callout.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Callout.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
@@ -19,7 +12,7 @@ depends_on: []
 
 `tone` is `info | warning | success | danger`, independent of the retained `soft | surface | outline` variants. `Callout.Title` is the authored heading slot. Rich-text serialization stores tone and optional title in stable `data-dsx-*` attributes while nested content remains semantic HTML.
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{card.md → components/card.md}

@@ -3,20 +3,13 @@ title: Card
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/card/Card.tsx
-css_path: packages/d4gger-design-system/src/styles/components/card.css
-props_path: packages/d4gger-design-system/src/components/card/card.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Card.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Box
 ---
 
 # Card
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -48,6 +41,7 @@ The root is a flex column with `gap: var(--dsx-space-md)`. Header, Content, and
 | `variant` | `'default' \| 'glass' \| 'elevated' \| 'filled' \| 'outline'` | `'default'` | no | Visual treatment; writes `data-variant`. Canonical variants are `default` and `glass`. `elevated` and `filled` are package-shipped; `outline` is compatibility-only and is normalized to `data-variant="default"` plus a `dsx-card--outline` class. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Padding scale; writes `data-size`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
+| `interactive` | `boolean` | `true` | no | When `false`, writes `data-interactive="false"` and suppresses the *generic* `:hover` effect (border-color tint, background wash, elevated box-shadow) in `baseCard.css` — for a static, non-clickable card (comparison layouts, dashboards) that shouldn't look actionable. Default preserves existing behavior for every other consumer unchanged. Found live 2026-08-26: a static card with its own accent-colored border (set via inline `style`, which does survive `:hover` — cascade rules confirmed) still looked like its color vanished on hover, because the *background* and *box-shadow* were changing underneath it regardless. Round 7 correction (2026-08-26): suppressing hover entirely was an overcorrection, not the actual intent — a card that also carries `data-accent-color` (its own local accent) still gets a hover highlight in that color (`border-color`, a 1px accent ring, and a 10%-mixed accent background wash), since `interactive=false` means "don't look clickable," not "never react to hover." No accent, no hover feedback at all — unchanged from the original fix. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-card`. | no |
 
 **Slot props (Header, Title, Description, Content, Footer):**
@@ -99,6 +93,7 @@ The normalization is a one-way mapping: `outline` is the only variant that produ
 **Responsive behavior:**
 
 - The component does not write `@media` rules. `size`, `variant`, and `radius` are single-value only.
+- The root can shrink within its parent and is capped at the available width. Unbroken headings and identifiers wrap without truncation; Content and Footer retain their wrapping layout.
 
 **Reduced motion:**
 
@@ -127,6 +122,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Border (default) | `var(--dsx-color-outline)` (light) / `var(--dsx-panel-border-color, var(--dsx-color-outline))` (any) | Card edge |
 | Shadow (default) | `var(--dsx-shadow-1, var(--dsx-effect-shadow-1))` | Default elevation |
 | Surface (glass) | `var(--dsx-color-panel-translucent)` → `var(--dsx-effect-panel-glass-background)` | Theme-aware 70% translucent glass surface |
+| Glass top rim | `var(--dsx-effect-panel-glass-rim-highlight)` | Theme-aware light-catching top edge |
+| Glass inset rim | `var(--dsx-effect-panel-glass-rim)` | Theme-aware subtle inset perimeter |
+| Glass border | `var(--dsx-effect-panel-glass-border)` | Theme-aware outer edge |
 | Shadow (glass) | `var(--dsx-shadow-panel-shadow)` | Glass shadow |
 | Glass backdrop | `var(--dsx-effect-panel-glass-backdrop-filter)` | Glass blur |
 | Surface (elevated) | `var(--dsx-color-surface-raised)` | Elevated surface |
@@ -192,7 +190,7 @@ The component is static. Hover state changes are instant; no transition is appli
 
 **Radius story:**
 
-- Renders cards with `radius="none"`, `radius="sm"`, `radius="md"`, `radius="lg"`, `radius="xl"`, `radius="2xl"`, and `radius="full"`. Asserts the matching `data-radius` attribute.
+- Renders cards with `radius="none"`, `radius="sm"`, `radius="md"`, `radius="lg"`, `radius="xl"`, and `radius="2xl"`. Asserts the matching `data-radius` attribute. `full` is deliberately not offered — pill radius on a content card lets content kiss the edge.
 
 **State story:**
 

package/dist/docs/{carousel.md → components/carousel.md}

@@ -3,19 +3,17 @@ title: Carousel
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/carousel/Carousel.tsx
-css_path: packages/d4gger-design-system/src/styles/components/carousel.css
-props_path: packages/d4gger-design-system/src/components/carousel/carousel.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Carousel.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Embla (declared adapter per the roster; the current runtime implements its own slide math, see Anomalies)
-  - Icon (lucide-react `ChevronLeft`, `ChevronRight`)
+  - Icon (lucide-react `ChevronLeft`, `ChevronRight`, `ChevronUp`, `ChevronDown`)
+  - Button
 ---
 
 # Carousel
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+`asChild` accepts one consumer host containing the normal Viewport/navigation/indicator slots. The package preserves that host and arranges its slots inside it; navigation and slide-count behavior remain the same as the default host.
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -36,7 +34,7 @@ A horizontal content carousel with optional autoplay, loop, vertical orientation
 | `Carousel.Item` | `<div>` | `dsx-carousel__item` | One slide. Flexes to `flex: 0 0 100%` so the track measures by item count. |
 | `Carousel.Previous` | `<button>` | `dsx-carousel__nav`, `dsx-carousel__nav--previous` | Calls `prev` from context. `aria-label="Previous slide"`. |
 | `Carousel.Next` | `<button>` | `dsx-carousel__nav`, `dsx-carousel__nav--next` | Calls `next` from context. `aria-label="Next slide"`. |
-| `Carousel.Indicators` | `<div>` | `dsx-carousel__indicators` | Renders a `<button>` per slide; renders nothing when `slideCount <= 1`. The indicator row uses `role="tablist"` and the buttons use `role="tab"`. |
+| `Carousel.Indicators` | `<div>` | `dsx-carousel__indicators` | Renders a `<button>` per slide; renders nothing when `slideCount <= 1`. The indicator row is a named `group` of native buttons; the active button has `aria-disabled="true"`. Each target is 24px with a smaller painted dot. |
 
 **Adapter host:**
 
@@ -49,10 +47,10 @@ The current runtime does not use a third-party adapter. The slide transform is c
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Slide direction. The `orientation` prop def has `className: 'dsx-carousel--'`, so the runtime emits `dsx-carousel--{orientation}` on the root; the CSS only consumes `[data-orientation='vertical']` on the viewport, so the root modifier class is currently a no-op CSS hook (see Anomalies). | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drives `data-size` on the root. The size prop def has no `className`, so the runtime only writes the attribute. The CSS does not currently consume `data-size` on the root, so this is a forward-looking hook (see Anomalies). | no |
-| `initialIndex` | `number` | `0` | no | Initial slide index. Consumed by `useState`. | no |
-| `loop` | `boolean` | `false` | no | When `true`, `next` and `prev` wrap around. The autoplay timer always wraps. | no |
-| `autoPlay` | `boolean` | `false` | no | Enables the autoplay `setInterval`. No-op when `slideCount < 2`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drives `data-size` on the root. The size prop def has no `className`, so the runtime only writes the attribute. The CSS consumes this attribute to size the navigation buttons (sm 24px, md 32px, lg 40px). | no |
+| `initialIndex` | `number` | `0` | no | Initial slide index, normalized to a finite integer and clamped to the available slides. An empty carousel stays at zero; removing slides reclamps the index. | no |
+| `loop` | `boolean` | `false` | no | When `true`, manual and automatic navigation wrap around. Otherwise navigation stops at the endpoints and the corresponding nav button is disabled. | no |
+| `autoPlay` | `boolean` | `false` | no | Enables automatic rotation and a built-in stop/start Button before the viewport. No-op with fewer than two slides or reduced motion. Hover pauses temporarily; focus or pointer interaction with slide content/navigation stops until explicitly restarted. | no |
 | `autoPlayInterval` | `number` (ms) | `3000` | no | Autoplay tick interval. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. The slot attachments stay on the same host. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Must include a single `Carousel.Viewport` and may include `Carousel.Indicators`. `Previous` and `Next` are accepted either at the root or inside the viewport. The runtime filters and re-parents the navigation buttons to live inside the viewport. | no |
@@ -74,11 +72,11 @@ Standard `React.ComponentPropsWithoutRef<'div'>` plus `className`. The slot is `
 
 ### `Carousel.Previous` and `Carousel.Next` props
 
-Standard `React.ComponentPropsWithoutRef<'button'>` plus `className`. The runtime wires `onClick` to the context's `prev` / `next` handlers and sets the `aria-label`.
+Standard `React.ComponentPropsWithoutRef<'button'>` plus `className`. The runtime defaults `type` to button, preserves a consumer accessible name, and invokes the consumer click handler before navigation. `preventDefault()` cancels navigation. Disabled applies at non-looping boundaries and with fewer than two slides.
 
 ### `Carousel.Indicators` props
 
-Standard `React.ComponentPropsWithoutRef<'div'>` plus `className`. The runtime renders a `<button role="tab">` per slide; the row itself is `role="tablist"` with `aria-label="Slide indicators"`. Returns `null` when `slideCount <= 1`.
+Standard `React.ComponentPropsWithoutRef<'div'>` plus `className`. The runtime renders a native button per slide; the row is a `group` with `aria-label="Slide indicators"`. The active picker has `aria-disabled="true"`. Returns `null` when `slideCount <= 1`.
 
 ## CSS class contract
 
@@ -126,8 +124,8 @@ The runtime also writes `dsx-carousel--{orientation}` on the root via the `orien
 
 **Reduced motion:**
 
-- The track transitions `transform` against `var(--dsx-motion-duration-normal)` and `var(--dsx-motion-easing-in-out)`. The runtime does not import `usePrefersReducedMotion`; rely on the global stylesheet to honor the media query.
-- Autoplay is JS-driven; when `prefers-reduced-motion` matches, the runtime should not start the autoplay interval. The current source does not gate the autoplay timer on the media query; see Anomalies.
+- The track transitions `transform` against `var(--dsx-motion-duration-normal)` and `var(--dsx-motion-easing-in-out)`. The runtime imports `usePrefersReducedMotion` to gate rotation, and component CSS disables track, nav, and indicator transitions when the query matches.
+- Autoplay is JS-driven; the runtime does not start its interval while the reduced-motion hook matches.
 
 ## Token mapping
 
@@ -142,12 +140,12 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item size | `flex: 0 0 100%` | Each slide takes the full viewport width or height. |
 | Nav position (vertical center) | `top: 50%` + `translateY(-50%)` | Centering. |
 | Nav size | `var(--dsx-size-lg)` square | Tap target. |
-| Nav border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Resting edge. |
+| Nav border | `var(--dsx-border-width-sm)` + `var(--dsx-panel-border-color)` | Resting edge. |
 | Nav radius | `var(--dsx-rounded-full)` | Round affordance. |
-| Nav fill | `var(--dsx-color-surface-overlay)` | Resting surface. |
+| Nav fill | `var(--dsx-color-panel-translucent)` | Resting surface. |
 | Nav text color | `var(--dsx-color-on-surface)` | Glyph color. |
 | Nav z-index | `var(--dsx-z-index-elevated)` | Above the slide content. |
-| Nav shadow | `var(--dsx-shadow-2)` | Resting shadow. |
+| Nav shadow | `var(--dsx-shadow-elevation-2)` | Resting shadow. |
 | Nav hover fill | `var(--dsx-color-surface-raised)` | Hover surface. |
 | Nav hover border | `var(--dsx-color-primary)` | Hover edge. |
 | Nav hover text | `var(--dsx-color-primary)` | Hover glyph color. |
@@ -156,7 +154,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Indicator row gap | `var(--dsx-space-xs)` | Gap between indicator dots. |
 | Indicator size | `var(--dsx-space-xs)` square | Dot size. |
 | Indicator radius | `var(--dsx-rounded-full)` | Round dot. |
-| Indicator fill | `var(--dsx-color-outline-variant)` | Inactive dot. |
+| Indicator fill | `var(--dsx-color-outline)` | Inactive dot. |
 | Indicator active fill | `var(--dsx-color-primary)` | Active dot. |
 | Indicator active width | `var(--dsx-space-md)` | Active dot width. |
 | Indicator motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Active dot transition. |
@@ -170,9 +168,9 @@ Rules:
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| Track transform (slide animation) | `var(--dsx-motion-duration-normal)` + `var(--dsx-motion-easing-in-out)` | `translateX(-{currentIndex * 100}%)` or `translateY(-{currentIndex * 100}%)` on transition | `none` — relies on the global `prefers-reduced-motion` stylesheet. The runtime does not gate the autoplay timer on the media query. |
-| Nav and indicator transitions | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Background, border, and indicator width transitions | `none` — relies on the global stylesheet. |
-| Autoplay timer | `setInterval(autoPlayInterval, ms)` | Default `3000`ms | The runtime should skip the autoplay interval when `prefers-reduced-motion: reduce` matches. The current source does not. |
+| Track transform (slide animation) | `var(--dsx-motion-duration-normal)` + `var(--dsx-motion-easing-in-out)` | `translateX(-{currentIndex * 100}%)` or `translateY(-{currentIndex * 100}%)` on transition | `none` — the component owns a `prefers-reduced-motion` rule. The runtime skips the timer when the reduced-motion hook matches. |
+| Nav and indicator transitions | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Background, border, and indicator width transitions | `none` — the component media query disables these transitions. |
+| Autoplay timer | `setInterval(autoPlayInterval, ms)` | Default `3000`ms | The runtime skips the interval when `prefers-reduced-motion: reduce` matches; hover and user pause also stop the interval. |
 
 Rules:
 
@@ -183,8 +181,8 @@ Rules:
 
 **Roles:**
 
-- The root is a `<div>` with no implicit role. `Carousel.Indicators` writes `role="tablist"` and the indicator buttons write `role="tab"`. The slide list itself does not declare `role="region"`; consumers that need it can wrap the root.
-- `aria-live` is not set on the viewport. Consumers that need slide-change announcements should add `aria-live="polite"` to the track or viewport in their app.
+- The root defaults to `role="group"` with `aria-roledescription="carousel"`; consumers provide a name and may opt into a region role. Internal slide wrappers are numbered groups with `aria-roledescription="slide"`. Offscreen wrappers are aria-hidden and inert, preventing offscreen controls from entering the focus order. Picker controls are grouped buttons rather than incomplete tabs.
+- The track is `aria-live="off"` during rotation and `polite` otherwise, with `aria-atomic="false"`. The rotation control precedes the viewport and supports keyboard and touch. Focusing slide content or navigation stops rotation until explicitly restarted; the stop/start control handles its own focus so activation can restart. Hover pauses while the pointer remains over the carousel.
 
 **Keyboard:**
 
@@ -196,25 +194,25 @@ Rules:
 
 **Focus:**
 
-- The Previous and Next buttons get the standard focus ring. The indicator buttons get the standard focus ring.
+- Arrow and indicator buttons use `--dsx-shadow-focus-ring` on `:focus-visible`, replacing the browser-default outline.
 - The track itself is not focusable.
 
 **Reduced motion:**
 
-- The track CSS transition honors the global `prefers-reduced-motion` media query. The autoplay timer does not currently gate on the media query; the next promotion should skip the interval when the query matches.
+- The component CSS disables the track, nav, and indicator transitions when `prefers-reduced-motion` matches. The autoplay timer is disabled while the query matches; manual navigation remains available.
 
 **Color and meaning:**
 
-- The active indicator is communicated by the `--dsx-color-primary` fill and the wider width. Color is not the only signal; the `aria-selected` attribute is set on the active indicator and `role="tab"` provides assistive-tech semantics.
+- The active indicator is communicated by the `--dsx-color-primary` fill and the wider width. Color is not the only signal; the active picker has `aria-disabled="true"` within a named group of native buttons.
 
 **Naming:**
 
 - The Previous and Next buttons are auto-labeled `Previous slide` and `Next slide`. The indicator row is labeled `Slide indicators`, and each indicator button is labeled `Go to slide ${index + 1}`.
-- The root region has no implicit name. Consumers that need a region name should add `aria-label` or `aria-labelledby`.
+- Consumers supply the root name through `aria-label` or `aria-labelledby`. The root does not fabricate a name.
 
 ## Playground demo spec
 
-The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+The shared docs route at `demo_path` renders `/docs/carousel` from `apps/playground/lib/registry/data.tsx`. All examples supply a meaningful root name. The live fixture includes a named picker-only composition with full-width slide content.
 
 **Default story:**
 
@@ -239,7 +237,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **A11y story:**
 
-- Uses `vitest-axe` against the rendered default carousel. Asserts the navigation buttons have accessible names and the indicator row has an accessible name.
+- Uses `vitest-axe` against the rendered default carousel. Asserts the navigation buttons have accessible names and the grouped picker row has an accessible name. Also verify empty/dynamic slides, form containment, cancelable navigation, and offscreen focus isolation.
 
 **Props exposed in the playground controls:**
 
@@ -263,7 +261,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Used by:**
 
-- App-level hero strips, image galleries, testimonial rows, and any horizontal content surface that needs swipe-like progression. No DS component currently wraps `Carousel`; the pattern is the intended app-side composition.
+- App-level hero strips, image galleries, testimonial rows, and content surfaces navigated with buttons. Swipe gestures are not implemented by the shipped native runtime. No DS component currently wraps `Carousel`; the pattern is the intended app-side composition.
 
 **State boundaries:**
 
@@ -273,15 +271,15 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 **Boundary rules:**
 
 - App-owned data: the slide content, the persistence of `currentIndex` (no built-in URL sync), the per-slide analytics, and any keyboard navigation beyond the default focus order.
-- DS-owned visuals: token bindings, the `dsx-carousel` and slot classes, the `data-orientation` and `data-size` attributes, the nav and indicator `aria-label` templates, the `role="tablist"` / `role="tab"` semantics on the indicator row, and the autoplay timer interval.
+- DS-owned visuals: token bindings, the `dsx-carousel` and slot classes, the `data-orientation` and `data-size` attributes, the nav and indicator `aria-label` templates, the grouped-button semantics on the picker row, and the autoplay timer interval.
 - When the canonical Embla adapter lands, the DS shell, the slot hierarchy, the class names, and the prop defs stay unchanged. The runtime will swap the in-source slide math for an Embla instance and forward Embla events through the existing `CarouselContext`.
 
 **Anomalies** (open items that this spec flags for the next promotion):
 
 1. **Adapter mismatch.** The roster and the archetype guide say Carousel is `adapter-backed` with `Embla`. The runtime does not import Embla and does not declare it under `peerDependencies` or `peerDependenciesMeta`. The slide transform is hand-rolled in `CarouselViewport`.
 2. **Orientation modifier class is a no-op.** The `orientation` prop def has `className: 'dsx-carousel--'`, so the runtime emits `dsx-carousel--horizontal` / `dsx-carousel--vertical` on the root. The CSS does not define either class. Visual orientation is driven by `data-orientation` on the viewport and `dsx-carousel__track--vertical` on the track.
-3. **Size prop has no CSS consumer.** The `size` prop def has no `className`, so the runtime only writes `data-size` on the root. The CSS does not consume `data-size` on `dsx-carousel`. The class is reserved for a future size variant.
-4. **Autoplay timer is not reduced-motion aware.** The autoplay `useEffect` does not consult `prefers-reduced-motion` before starting the interval.
+3. **Size consumer confirmed.** Navigation buttons consume root `data-size`: sm 24px, md 32px, lg 40px.
+4. **Autoplay controls repaired (2026-10-03).** Reduced motion, hover pause, interaction stop, and a visible stop/start control now gate the timer. Non-looping autoplay respects the endpoint.
 5. **Vertical viewport height has no token.** The CSS uses `var(--dsx-carousel-vertical-height, 320px)`. There is no `--dsx-carousel-vertical-height` token in `tokens/`; the `320px` value is a fallback only.
 
 ## Penpot build recipe
@@ -319,13 +317,13 @@ The package does not yet publish a Penpot asset for Carousel. Recipe is visual r
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
 | Viewport | radius | `--dsx-rounded-xl` | Radius | `radius` |
-| Nav | fill | `--dsx-color-surface-overlay` | Color | `fills` |
+| Nav | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 | Nav | stroke | `--dsx-color-outline` | Color | `strokes` |
-| Nav | shadow | `--dsx-shadow-2` | Effect | `shadow` |
+| Nav | shadow | `--dsx-shadow-elevation-2` | Effect | `shadow` |
 | Nav (hover) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
 | Nav (hover) | text | `--dsx-color-primary` | Color | `fills` (state) |
 | Nav (active) | fill | `--dsx-effect-pressed-layer` | Effect | `fills` (state) |
-| Indicator | fill | `--dsx-color-outline-variant` | Color | `fills` |
+| Indicator | fill | `--dsx-color-outline` | Color | `fills` |
 | Indicator (active) | fill | `--dsx-color-primary` | Color | `fills` (state) |
 | Track | motion | `--dsx-motion-duration-normal` + `--dsx-motion-easing-in-out` | Motion | `motion` |
 
@@ -333,15 +331,15 @@ The package does not yet publish a Penpot asset for Carousel. Recipe is visual r
 
 | State | Track transform | Nav fill | Indicator fill |
 |---|---|---|---|
-| `default` | `translateX(-0%)` | `--dsx-color-surface-overlay` | `--dsx-color-outline-variant` |
-| `next` | `translateX(-{currentIndex * 100}%)` | `--dsx-color-surface-overlay` | `--dsx-color-primary` (active index) |
+| `default` | `translateX(-0%)` | `--dsx-color-panel-translucent` | `--dsx-color-outline` |
+| `next` | `translateX(-{currentIndex * 100}%)` | `--dsx-color-panel-translucent` | `--dsx-color-primary` (active index) |
 | `nav-hover` | (unchanged) | `--dsx-color-surface-raised` | (unchanged) |
-| `vertical` | `translateY(-{currentIndex * 100}%)` | `--dsx-color-surface-overlay` | (unchanged) |
+| `vertical` | `translateY(-{currentIndex * 100}%)` | `--dsx-color-panel-translucent` | (unchanged) |
 
 ### Variant model
 
 - `orientation`: `horizontal`, `vertical`. Default `horizontal`.
-- `size`: `sm`, `md`, `lg`. Default `md`. (CSS consumer pending; see Anomalies.)
+- `size`: `sm`, `md`, `lg`. Default `md`. Navigation buttons and the reserved slide gutter consume this scale.
 - `loop`: `true`, `false`. Default `false`. (Affects wrap-around only; no visual model.)
 - `autoPlay`: `true`, `false`. Default `false`. (Affects motion only; no visual model.)
 - Total members: 2 × 3 = 6 for the visual variant matrix.
@@ -354,3 +352,23 @@ The package does not yet publish a Penpot asset for Carousel. Recipe is visual r
 - [ ] Indicator active state uses both fill and width change so sighted and low-vision users see the same cue.
 - [ ] Previous, Next, and indicator button `aria-label` strings are baked in; do not treat them as themable in Penpot.
 - [ ] When the canonical Embla adapter lands, re-run the spec QA and re-validate the Penpot recipe against the new runtime.
+
+## Package review, 2026-10-03
+
+The vertical track is exactly one viewport high; each internal slide wrapper occupies one viewport, so `translateY(-100%)` advances one slide. Up/down glyphs and vertically separated controls replace the sideways glyphs. The horizontal layout and named exports remain intact. The root and viewport stay bounded by their container.
+
+The indicator hit box is 24px (`size-md`); its `::before` paints the existing 8px dot or 16px active pill. Offscreen slide controls are inert. Runtime-only autoplay props are consumed rather than leaked to the DOM, and the slide-count callback fires on count changes.
+
+Research: [WAI APG carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/), using its grouped native-button model and explicit rotation control. The existing Embla migration remains an architectural follow-up; this review repairs the shipped native runtime.
+
+## Navigation clearance follow-up, 2026-10-03
+
+One internal nav-size variable drives both the button diameter (24/32/40px) and the slide inset. Each occupied inset reserves the button, space-md edge offset, and space-xs clearance. Buttons and slide items use border-box sizing. Large controls therefore remain outside slide content. Size changes control density and reserved space; the consumer owns slide dimensions. Native named buttons remain the navigation implementation.
+
+The circular navigation paint has an invisible square pseudo-element across its full button box. This makes the small control's 24px floor real at its corners, as confirmed by elementFromPoint; no visible diameter changes.
+
+## Research follow-up, 2026-10-03
+
+Round native buttons and grouped pickers remain the chosen model. Control density (24/32/40px) is independent from consumer-owned slide dimensions. A viewport reserves an inset only where a Previous/Next slot exists. Both horizontal controls reserve both sides; a single control reserves its own side; vertical controls share the right-side rail. Without arrows, slides use the full viewport width. Slot-driven `:has()` selectors make this intrinsic rather than viewport-triggered.
+
+Component CSS supplies the canonical focus ring for arrows and pickers and disables transitions under reduced motion. Runtime rotation already respects reduced motion. Research references and the existing Embla/swipe boundary remain in the batch decision record. No public prop or dependency changed.

package/dist/docs/{chart.md → components/chart.md}

@@ -3,13 +3,6 @@ title: Chart
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/chart/Chart.tsx
-css_path: packages/d4gger-design-system/src/styles/components/chart.css
-props_path: packages/d4gger-design-system/src/components/chart/chart.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Chart.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/data.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - recharts
   - "@radix-ui/react-slot"
@@ -17,11 +10,11 @@ depends_on:
 
 # Chart
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-A token-aligned chart shell that exposes line, bar, and pie primitives on top of `recharts`. The package owns the chart shell, the class wiring, the chart palette tokens, and the responsive container. The adapter (`recharts`) owns the chart math, axis rendering, tooltips, and the legend. Apps own analytics semantics, custom tooltips, axis formatting, and any data joins beyond the default `ChartDatum` shape.
+A token-aligned chart family that exposes line, bar, pie, donut, radial, and area primitives on top of `recharts`. The package owns the chart shell, the class wiring, the chart palette tokens, and the responsive container. The adapter (`recharts`) owns the chart math, axis rendering, tooltips, and the legend. Apps own analytics semantics, custom tooltips, axis formatting, and any data joins beyond the documented shapes. The shell is a bare plot surface — no card chrome. Cards, stat headers, and dashboard composition live in app code (see the composition story).
 
 ## Anatomy & slots
 
@@ -32,20 +25,23 @@ A token-aligned chart shell that exposes line, bar, and pie primitives on top of
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
 | `Chart.Container` (alias `Chart`) | `<div>` (or `Slot` when `asChild`) | DS shell, `dsx-chart` | Root host. Carries `data-slot="chart-container"`. |
-| `Chart.Line` | `<div>` | `dsx-chart` with `data-chart-type="line"` | Hosts a Recharts `LineChart` inside a `ResponsiveContainer`. |
-| `Chart.Bar` | `<div>` | `dsx-chart` with `data-chart-type="bar"` | Hosts a Recharts `BarChart` inside a `ResponsiveContainer`. |
+| `Chart.Line` | `<div>` | `dsx-chart` with `data-chart-type="line"` | Hosts a Recharts `LineChart` inside a `ResponsiveContainer`. Accepts an optional `series` array for multi-series lines. |
+| `Chart.Bar` | `<div>` | `dsx-chart` with `data-chart-type="bar"` | Hosts a Recharts `BarChart` inside a `ResponsiveContainer`. Accepts an optional `series` array (grouped, or `stacked` for stacked bars). |
 | `Chart.Pie` | `<div>` | `dsx-chart` with `data-chart-type="pie"` | Hosts a Recharts `PieChart` inside a `ResponsiveContainer`. Pie data points are auto-mapped to the chart palette tokens. |
+| `Chart.Donut` | `<div>` | `dsx-chart` with `data-chart-type="donut"` | Ring variant of the pie with an optional center `label` slot (`dsx-chart__center-label`). |
+| `Chart.Radial` | `<div>` | `dsx-chart` with `data-chart-type="radial"` | Single-value progress ring (`value` / `max`) with an optional center `label` slot. |
+| `Chart.Area` | `<div>` | `dsx-chart` with `data-chart-type="area"` | Hosts a Recharts `AreaChart`. Accepts `series` like line/bar; `spark` strips axes, grid, legend, and tooltip for stat-card sparklines. |
 | `Chart.Empty` | `<div>` | `dsx-chart__empty` | DS-owned empty-state surface for the host. |
 | `Chart.Legend` | `<div>` | `dsx-chart__legend` | DS-owned legend container. |
 | `Chart.LegendItem` | `<span>` | `dsx-chart__legend-item` | DS-owned legend row. Accepts an optional `color` prop that writes `--dsx-chart-legend-color` to the inline style. |
 
 **Adapter host:**
 
-`Chart.Line`, `Chart.Bar`, and `Chart.Pie` wrap a Recharts `ResponsiveContainer` (`width="100%"`, `height={350}`). The container always renders a `CartesianGrid` (line and bar), `XAxis` keyed by `name`, `YAxis`, the Recharts `Tooltip`, and the Recharts `Legend`. The single data series is keyed by `value` and uses `var(--dsx-color-primary)` for fill or stroke. Pie slices cycle through `var(--dsx-chart-1)` through `var(--dsx-chart-5)` based on the slice index modulo 5.
+`Chart.Line`, `Chart.Bar`, `Chart.Area`, `Chart.Pie`, `Chart.Donut`, and `Chart.Radial` wrap a Recharts `ResponsiveContainer` (`width="100%"`, `height="100%"` — the frame's aspect ratio owns the height, so the svg can never overflow the rounded shell). Cartesian slots (`Line`, `Bar`, `Area`) always render a `CartesianGrid`, `XAxis` keyed by `name`, `YAxis`, the Recharts `Tooltip`, and the Recharts `Legend`, except `Area` with `spark`, which strips axes, grid, legend, and tooltip for stat sparklines. `Pie`/`Donut` render a `Pie` with per-slice `Cell` fills plus tooltip and legend; `Donut` uses an inner radius at 62% of the outer radius and `Radial` renders a `RadialBarChart` progress ring. The single data series is keyed by `value` and uses `var(--dsx-color-primary)` for fill or stroke. Pie and donut slices cycle through `var(--dsx-chart-1)` through `var(--dsx-chart-5)` based on the slice index modulo 5. Line and bar charts reserve an inset margin so axis ticks never clip against the rounded shell, and both axes render without tick or axis lines with muted 12px ticks.
 
 **Compatibility exports:**
 
-The module also re-exports raw `BarChart`, `CartesianGrid`, `LineChart`, `PieChart`, `XAxis`, `YAxis`, `ResponsiveContainer`, `ChartTooltip` (alias of `RechartsTooltip`), `RechartsLegend`, `ChartContainer`, `ChartBar`, `ChartEmpty`, `ChartLegend`, `ChartLegendItem`, `ChartLine`, and `ChartPie`. These are package-authoring escape hatches for apps that need a non-tokenized Recharts surface. The `Chart` namespace plus its named subcomponents is the canonical surface for new app code.
+The module also re-exports raw `AreaChart`, `BarChart`, `CartesianGrid`, `LineChart`, `PieChart`, `RadialBarChart`, `XAxis`, `YAxis`, `ResponsiveContainer`, `ChartTooltip` (alias of `RechartsTooltip`), `RechartsLegend`, `ChartContainer`, `ChartArea`, `ChartBar`, `ChartDonut`, `ChartEmpty`, `ChartLegend`, `ChartLegendItem`, `ChartLine`, `ChartPie`, and `ChartRadial`. These are package-authoring escape hatches for apps that need a non-tokenized Recharts surface. The `Chart` namespace plus its named subcomponents is the canonical surface for new app code.
 
 ## Props contract
 
@@ -63,10 +59,40 @@ The container extends `React.HTMLAttributes<HTMLDivElement>` minus the `children
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `data` | `ChartDatum[]` | (required) | yes | Data series. Each entry is `{ id?: number \| string; name: string; value: number }`. The X axis is keyed by `name`; the single series is keyed by `value`. | no |
+| `data` | `ChartDatum[] \| ChartRow[]` | (required) | yes | Data series. Single-series entries are `{ id?: number \| string; name: string; value: number }`; multi-series rows add one numeric field per series key. The X axis is keyed by `name`. | no |
+| `series` | `{ dataKey: string; name?: string; fill?: string }[]` | `undefined` | no | Multi-series definition. Omitted = single `value` series. `name` feeds the legend (defaults to the dataKey); `fill` defaults to the palette cycle. | no |
+| `stacked` | `boolean` | `false` | no | Stacks bar series (bar only meaningful, accepted on both). | no |
+| `name` | `string` | `'value'` | no | Legend label for the single-series case. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
 
-These two slots also accept all `Chart.Container` HTML attributes and forward them to the host. Recharts internals (`Line`, `Bar`, axes, grid) are not exposed as props; the line and bar variants are intentionally fixed to a single series with `isAnimationActive={false}`.
+These two slots also accept all `Chart.Container` HTML attributes and forward them to the host. Recharts internals (axes, grid) are not exposed as props; animation stays disabled via `isAnimationActive={false}`.
+
+### `Chart.Donut` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `data` | `ChartDatum[]` | (required) | yes | Ring segments; fills cycle the palette like pie. | no |
+| `label` | `React.ReactNode` | `undefined` | no | Center label rendered in `dsx-chart__center-label` (e.g. a total with caption). | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
+
+### `Chart.Radial` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `number` | (required) | yes | Current value; clamped to `max`. | no |
+| `max` | `number` | `100` | no | Scale maximum. | no |
+| `label` | `React.ReactNode` | `undefined` | no | Center label rendered in `dsx-chart__center-label`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
+
+### `Chart.Area` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `data` | `ChartDatum[] \| ChartRow[]` | (required) | yes | Same shapes as line/bar. | no |
+| `series` | `{ dataKey: string; name?: string; fill?: string }[]` | `undefined` | no | Multi-series areas; omitted = single `value` area at 10% fill opacity. | no |
+| `name` | `string` | `'value'` | no | Legend label for the single-series case. | no |
+| `spark` | `boolean` | `false` | no | Strips axes, grid, legend, and tooltip and switches to a 3:1 strip for stat-card sparklines. Writes `data-spark`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
 
 ### `Chart.Pie` props
 
@@ -123,15 +149,16 @@ The type is exported as `ChartDatum` from the package barrel.
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-chart-type` | `line`, `bar`, `pie` | `.dsx-chart[data-chart-type='line']`, `.dsx-chart[data-chart-type='bar']`, `.dsx-chart[data-chart-type='pie']` | `chart.css` |
+| `data-chart-type` | `line`, `bar`, `pie`, `donut`, `radial`, `area` | `.dsx-chart[data-chart-type='line']`, `.dsx-chart[data-chart-type='bar']`, `.dsx-chart[data-chart-type='pie']`, `.dsx-chart[data-chart-type='donut']`, `.dsx-chart[data-chart-type='radial']`, `.dsx-chart[data-chart-type='area']` | `chart.css` |
 
-`data-chart-type="pie"` overrides the aspect ratio custom property to `1` for square pies.
+`data-chart-type="pie"`, `"donut"`, and `"radial"` override the aspect ratio custom property to `1` for square plots. `data-chart-type="area"` with `data-spark="true"` overrides it to `3` for the spark strip and resets the root min-height to `0`.
 
 **Slot classes:**
 
 | Slot | Class | CSS file |
 |---|---|---|
 | Container | `dsx-chart` | `chart.css` |
+| Center label (donut / radial) | `dsx-chart__center-label` | `chart.css` |
 | Empty | `dsx-chart__empty` | `chart.css` |
 | Legend | `dsx-chart__legend` | `chart.css` |
 | Legend item | `dsx-chart__legend-item` | `chart.css` |
@@ -147,6 +174,8 @@ The type is exported as `ChartDatum` from the package barrel.
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`.
 - The component's CSS file is breakpoint-agnostic.
 
+- The plot shell has `min-width: 0` and `max-width: 100%` to contain its aspect-ratio sizing in narrow hosts. Grid demo tracks use `minmax(0, 1fr)` so plot intrinsic width cannot expand their cards. Explicit host sizing still applies; this does not set a new shell width.
+
 **Reduced motion:**
 
 - The component does not add motion of its own. Recharts animation is explicitly disabled via `isAnimationActive={false}` on every primitive. Hover, focus, and selection transitions are expected to honor the global `prefers-reduced-motion` stylesheet when the host application adds them.
@@ -157,7 +186,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Root min-height | `var(--dsx-chart-min-height)` | Minimum chart height when the host width is large. |
+| Root min-height | `var(--dsx-chart-min-height, 240px)` | Minimum chart height when the host width is large. The `240px` fallback mirrors `tokens/component-geometry.json` so the floor holds even when the generated tokens layer is absent. |
 | Root aspect ratio | `var(--dsx-chart-aspect-ratio, 1.7778)` | Default 16:9. Overridden to `1` for pies. |
 | Root border | `var(--dsx-semantic-border)` | Edge. |
 | Root radius | `var(--dsx-rounded-xl)` | Corner roundness. |
@@ -216,15 +245,23 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Variant stories** (one per chart type):
 
-- Renders `Chart.Bar`, `Chart.Line`, and `Chart.Pie` with a sample `data` array. Asserts `data-chart-type` matches the variant on the host element.
+- Renders `Chart.Bar`, `Chart.Line`, `Chart.Pie`, `Chart.Donut`, `Chart.Radial`, and `Chart.Area` with sample data. Asserts `data-chart-type` matches the variant on the host element.
+- Renders `Chart.Bar` with two `series` and asserts two legend rows with the series names. Renders `Chart.Bar` with `stacked` and asserts a single stacked group per category.
+- Renders `Chart.Area` with `spark` and asserts axes, grid, legend, and tooltip are absent and `data-spark` is set.
 
 **Composition story:**
 
-- Renders `Chart.Legend` with two `Chart.LegendItem` rows, one with `color="var(--dsx-chart-1)"` and one with `color="var(--dsx-chart-3)"`. Asserts the inline `--dsx-chart-legend-color` custom property is set on each row and the swatch `::before` is visible.
+- Renders dashboard cards (`Card` + stat header + chart + `Chart.Legend`): a multi-series bar card, a stacked bar card, a donut card with center total and status-named data, a radial progress card, a full `area` card, a pie card, and a line card on a sunken plot well. Asserts each composition renders real chart content inside a titled card — never a bare chart where a dashboard meaning belongs.
+- Renders the spark-in-`StatCard` composition (`StatCard.Label` + `StatCard.Value` + `Chart.Area spark` + `StatCard.Footer` with `StatCard.Trend`) and the spark-inside-`Card.Content` variant. Both spark hosts are block wrappers with an explicit `min-height` and a definite width (see the host-sizing rule below) — bare content-sized wrappers collapse the spark to 0×0 inside flex-row card content (verified live 2026-09-21).
 
 **State story:**
 
 - Renders `Chart.Empty` inside a `Chart.Container`. Asserts the empty slot is rendered with `dsx-chart__empty` and no chart data is present.
+- Renders `Skeleton` loading hosts per plot geometry (cartesian 16:9, square, spark strip), each an explicitly-sized host with `aria-busy`. Loading is app-owned: the chart family ships no loading prop by design (see the boundary rules).
+
+**Host-sizing rule (demo and apps):**
+
+- Every chart story wrapper is a block box with an explicit `min-height` (`280px` cartesian, `320px` square, `96px` spark strip, `280px` radial) and a definite width (`width: 100%`, plus `max-width` for square plots). Card content rows are flex rows, so the wrappers also carry `width: 100%` to fill the row. Never place a chart type — especially `spark` — in a bare content-sized box.
 
 **Props exposed in the playground controls:**
 
@@ -234,7 +271,7 @@ The `Chart.Container` exposes only `asChild` from its prop defs. `Chart.Line`, `
 
 **Composes from:**
 
-- `recharts`: the adapter engine. `LineChart`, `BarChart`, `PieChart`, `Line`, `Bar`, `Pie`, `CartesianGrid`, `XAxis`, `YAxis`, `Tooltip`, `Legend`, and `ResponsiveContainer` are imported from `recharts`.
+- `recharts`: the adapter engine. `LineChart`, `BarChart`, `AreaChart`, `PieChart`, `RadialBarChart`, `Line`, `Bar`, `Area`, `Pie`, `RadialBar`, `Cell`, `CartesianGrid`, `XAxis`, `YAxis`, `Tooltip`, `Legend`, and `ResponsiveContainer` are imported from `recharts`. `Scatter`/`ScatterChart`/`ZAxis` are intentionally not imported (see anomaly 5).
 - `@radix-ui/react-slot`: enables `asChild` on the container.
 - `classnames`: used to merge `dsx-chart` with the caller's `className` on every slot.
 
@@ -246,7 +283,7 @@ The `Chart.Container` exposes only `asChild` from its prop defs. `Chart.Line`, `
 
 - Owned by this component: the DS shell class wiring, the chart palette token references, the `data-chart-type` attribute, the `dsx-chart` and `dsx-chart__*` slot classes, and the `ChartDatum` type.
 - Owned by the adapter: chart math, axis math, tooltip rendering, the Recharts legend, animation, and the responsive size observer.
-- Owned by the consumer: the data array, the semantic meaning of the data, custom tooltips, custom axis formatting, and any deviation from the single-series single-axis default.
+- Owned by the consumer: the data array, the semantic meaning of the data, custom tooltips, custom axis formatting, the host box that gives the shell a definite size (explicit `min-height` + width per the host-sizing rule), loading placeholders (`Skeleton` in an explicitly-sized host — there is intentionally no chart loading prop), and any deviation from the single-series single-axis default.
 
 **Boundary rules:**
 
@@ -263,6 +300,12 @@ The `Chart.Container` exposes only `asChild` from its prop defs. `Chart.Line`, `
 
 4. **Chart.Legend's missing color swatches were a symptom of the Cell bug, not a separate defect.** The Recharts `<Legend>` component (aliased as `RechartsLegend`, used inside `ChartBar`, `ChartLine`, and `ChartPie`) automatically derives each series/slice's swatch color from its corresponding fill value. When `<Cell>` elements were not rendering (bug #2 above), the legend had no per-slice fill to read, so every swatch rendered with the default color. Fixing the Cell bug (adding explicit Cell elements with correct fill values) automatically corrected the legend swatches as a side effect — no separate CSS or component fix was needed for the legend itself.
 
+5. **Bubble/scatter gap verdict (F12, 2026-09-21): DEFERRED, not added.** Finance-dashboard reference imagery shows bubble charts alongside bars/radials. The adapter supports it — `recharts@3.8.1` ships `ScatterChart`, `Scatter`, `XAxis`/`YAxis` (numeric mode), and `ZAxis`. The package still does not add `Chart.Scatter`/`Chart.Bubble`, for three reasons: (a) scatter/bubble needs numeric x/y axes plus a z-scale, which breaks the family's `name`-keyed category-axis + `ChartDatum` (`{ name, value }`) contract that every slot, the palette auto-mapping, and `qa:contracts` assume — it would be a second data contract, not a seventh slot; (b) neither F12 reference demands it (antd core has no charts; the dashboard has one bespoke bar), so there is no app-side correlation/distribution need to design against; (c) the F12 brief verdict is verify-only ("no anatomy change"), and a scatter slot is new anatomy. Revisit when an app needs correlation/distribution plots: add `Chart.Scatter` with its own `{ x, y, z? }` datum shape, numeric-axis contract, and `ZAxis` range mapping — do not shoehorn it into `ChartDatum`.
+
+6. **Spark collapsed to 0×0 in the playground demo (F12, 2026-09-21).** The Conversion-rate spark (`ChartArea spark` in a bare `<div style={{ marginTop: 8 }}>` inside flex-row `Card.Content`) measured `0×0` with no svg: `spark` sets `min-height: 0`, so with no definite size on either axis the 3:1 aspect ratio cannot resolve, and the `ResponsiveContainer` percentage child contributes no intrinsic size for the flex item to transfer. Non-spark types survived only via the 240px min-height transfer. This is a host-sizing failure, not a shell bug — the shell intentionally keeps the spark floor at 0 (a 240px floor inside a ~60px spark cell renders cropped). FIXED demo-side: every chart story wrapper is now a block box with an explicit `min-height` and definite width per the host-sizing rule; apps must do the same. No shell layout change (a shell-level `width: 100%` would retarget every app's flex-row chart heights — breaking).
+
+7. **Loading has no chart prop by design (F12, 2026-09-21).** Empty is DS-owned (`Chart.Empty`); loading is app-owned (`Skeleton` in an explicitly-sized host, `aria-busy` on the wrapper). The demo shows one skeleton host per plot geometry (cartesian, square, spark strip) and the suite covers empty-data renders per type. Do not add `isLoading`/`fallback` props to the chart slots without a spec-first API decision.
+
 ## Penpot build recipe
 
 > Optional. Penpot is a visual reference, not a code authority. The package source is the only authority.
@@ -318,12 +361,16 @@ The `Chart.Container` exposes only `asChild` from its prop defs. `Chart.Line`, `
 
 ### Variant model
 
-- `data-chart-type`: `line`, `bar`, `pie`. Default `line`.
+- `data-chart-type`: `line`, `bar`, `pie`, `donut`, `radial`, `area`. No default (each slot writes its own).
 - `asChild`: `true`, `false`. Default `false`.
-- Total members: 6 (3 chart types × 2 `asChild` values).
+- Total members: 12 (6 chart types × 2 `asChild` values).
 
 ### Validation checklist
 
 - [ ] Token bindings resolve at the values `DESIGN.md` describes.
 - [ ] Component is promoted to Main Component under `Components`.
 - [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+
+## Package review, 2026-10-03
+
+Pie and donut use measured container dimensions and legend height to cap the radius at 100 while shrinking to the available plot area (including the Recharts default 5px plot margins). Large plots retain the 100/62 radius pair. The donut center label excludes the measured legend band, so wrapping the legend does not shift the label away from the ring. Long center-label content wraps inside the shell. No viewport breakpoint or new public prop is introduced.