@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/carousel.md

@@ -5,11 +5,14 @@ category: Components
 archetype: adapter-backed
 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
 
+`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
@@ -31,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:**
 
@@ -44,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 |
@@ -69,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
 
@@ -121,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
 
@@ -137,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-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. |
@@ -151,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. |
@@ -165,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:
 
@@ -178,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:**
 
@@ -191,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:**
 
@@ -234,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:**
 
@@ -258,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:**
 
@@ -268,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
@@ -316,11 +319,11 @@ The package does not yet publish a Penpot asset for Carousel. Recipe is visual r
 | Viewport | radius | `--dsx-rounded-xl` | Radius | `radius` |
 | 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` |
 
@@ -328,7 +331,7 @@ 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-panel-translucent` | `--dsx-color-outline-variant` |
+| `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-panel-translucent` | (unchanged) |
@@ -336,7 +339,7 @@ The package does not yet publish a Penpot asset for Carousel. Recipe is visual r
 ### 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.
@@ -349,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/components/chart.md

@@ -37,7 +37,7 @@ A token-aligned chart family that exposes line, bar, pie, donut, radial, and are
 
 **Adapter host:**
 
-`Chart.Line`, `Chart.Bar`, and `Chart.Pie` 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). 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. 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.
+`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:**
 
@@ -149,9 +149,9 @@ 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:**
 
@@ -174,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.
@@ -184,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. |
@@ -249,11 +251,17 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders dashboard cards (`Card` + stat header + chart + `Chart.Legend`): a multi-series bar card, a donut card with center total, a radial progress card, and a sparkline stat card. Asserts each composition renders real chart content inside a titled card — never a bare chart where a dashboard meaning belongs.
+- 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:**
 
@@ -263,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.
 
@@ -275,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:**
 
@@ -292,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.
@@ -356,3 +370,7 @@ The `Chart.Container` exposes only `asChild` from its prop defs. `Chart.Line`, `
 - [ ] 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.

package/dist/docs/components/checkbox.md

@@ -83,6 +83,10 @@ Rules:
 
 - The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
 
+**Hit area:**
+
+- The visual box stays 20/24/32px per `size`, but a `::before` layer extends the pointer target to 44px (WCAG 2.5.8 minimum 24px, TMA touch 44px). Absolutely positioned — never affects layout.
+
 **Reduced motion:**
 
 - The `transition` properties on `dsx-checkbox` collapse to `none` when `@media (prefers-reduced-motion: reduce)` matches. The rule is in `checkbox.css`.