@d4gger/design-system 3.0.1 → 4.0.0

package/dist/docs/components/notification-center.md

@@ -29,15 +29,15 @@ An inbox-style notification surface that groups header, list, and footer regions
 | `NotificationCenter.List` | `<div>` (or `Slot` host) | `dsx-notification-center__list` | Vertical list of items. Capped at `max-height: 400px` with `overflow-y: auto`. |
 | `NotificationCenter.Footer` | `<div>` (or `Slot` host) | `dsx-notification-center__footer` | Footer row (typically a "View all" link or button). |
 | `NotificationCenter.Item` | `<div>` (or `Slot` host) | `dsx-notification-center__item` (with `--unread` modifier when `unread` is true) | A single notification row. The CSS file ships helper classes `dsx-notification-center__item-title`, `dsx-notification-center__item-description`, and `dsx-notification-center__item-time` for the typical layout. |
-| `NotificationCenter.Trigger` | `IconButton` + `Badge` fragment | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger. Wraps an `IconButton` (size `sm`, variant `ghost`, default `aria-label="Notifications"`) and conditionally renders a `Badge` with the unread count (capped at `'99+'`). The trigger is rendered as a React fragment so it can be placed anywhere. |
+| `NotificationCenter.Trigger` | `IconButton` containing Icon + Badge | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger (size `sm`, variant `ghost`) with an accessible unread-count name. The badge sits at the bell's upper trailing corner (capped at `'99+'`); the host reserves the count's width and asChild preserves child/ref composition. |
 
 **Internal layout:**
 
 - The root is a flex column. The header sits at the top, the list fills the middle, the footer sits at the bottom.
-- In the `popover` variant (the default), the root is sized `width: 320px`, has a `var(--dsx-rounded-lg)` radius, a 1px outline, an `var(--dsx-color-panel-translucent)` background, and a `var(--dsx-shadow-card-md)` shadow.
+- In the `popover` variant (the default), the root is sized `width: var(--dsx-sheet-width-sm), max-width: 100%`, has a `var(--dsx-rounded-lg)` radius, a 1px outline, an `var(--dsx-color-panel-translucent)` background, and a `var(--dsx-shadow-card-md)` shadow.
 - In the `sidebar` variant, the root is full-width / full-height with a flat `var(--dsx-color-surface)` background and no border or shadow.
 - `NotificationCenter.Item` rows have a `var(--dsx-space-md)` padding and a 1px bottom border. The last item drops the bottom border. The item background switches to `var(--dsx-color-surface-raised)` with a 1px primary left border when `unread` is true.
-- `NotificationCenter.Trigger` is a positioned `inline-flex` container. The badge is absolutely positioned in the top-right corner with a `-var(--dsx-space-xs)` offset, a `var(--dsx-rounded-full)` radius, and label-small typography.
+- `NotificationCenter.Trigger` is an `inline-flex` button with intrinsic width and a 44px minimum width/height (`size-xl + space-xs`). The 16px badge is raised by 8px at the bell's trailing corner, with a 4px horizontal overlap and 8px host padding. Normal flow reserves the badge width; increasing counts grow toward the trailing edge rather than covering the bell. The badge uses rounded-full and label-small typography.
 
 ## Props contract
 
@@ -101,7 +101,7 @@ The trigger is a thin wrapper around `IconButton`; it forwards all of `IconButto
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. The `popover` variant uses a fixed 320px width; on small screens the consumer is expected to swap in a different layout (e.g. a full-screen Sheet) and render the same items in `NotificationCenter` with the `sidebar` variant.
+- The component does not write width media queries. The popover variant prefers `--dsx-sheet-width-sm` (320px) and caps to its parent width. Header actions wrap intrinsically; the list shrinks and scrolls. Use sidebar to fill a containing panel.
 
 **Reduced motion:**
 
@@ -113,7 +113,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Popover width | `320px` | Popover variant width |
+| Popover width | `var(--dsx-sheet-width-sm)` with max-width=100% | Preferred width, parent-contained |
 | Popover border-radius | `var(--dsx-rounded-lg)` | Popover roundness |
 | Popover border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Popover edge |
 | Popover background | `var(--dsx-color-panel-translucent)` | Popover surface |
@@ -138,10 +138,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item time type ramp | `var(--dsx-typography-label-small-*)` | Item time text |
 | Footer padding | `var(--dsx-space-sm)` | Footer gutter |
 | Footer border-top | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Footer separator |
-| Trigger position | `relative` | Anchors the badge |
-| Badge position | `absolute` with `-var(--dsx-space-xs)` offsets | Badge placement |
-| Badge min-width | `var(--dsx-size-xs)` | Badge min width |
-| Badge height | `var(--dsx-size-xs)` | Badge height |
+| Trigger width / minimum dimensions | `auto` / `calc(var(--dsx-size-xl) + var(--dsx-space-xs))` | Count expands the 44px button |
+| Trigger gap / inline padding | `0` / `var(--dsx-space-sm)` | Count corner containment |
+| Badge placement | relative, raised by space-sm, negative space-xs inline margin | Upper trailing corner; reserves count width |
+| Badge min-width | `var(--dsx-size-sm)` | Badge min width |
+| Badge height | `var(--dsx-size-sm)` | Badge height |
 | Badge radius | `var(--dsx-rounded-full)` | Badge roundness |
 | Badge type ramp | `var(--dsx-typography-label-small-*)` | Badge text |
 
@@ -159,7 +160,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 - The root renders as a `<div>` without an explicit `role`. The canonical pattern is to wrap the panel in a `Popover` or `Sheet`; the wrapping surface is responsible for the modal / non-modal role and focus management.
 - `NotificationCenter.List` is a plain `<div>`. If the consumer wants to expose the list as an `aria-live` region (e.g. for incoming notifications), they can add the `aria-live` and `aria-relevant` attributes manually.
-- `NotificationCenter.Trigger` renders an `IconButton` with `role="button"` and a default `aria-label` of `'Notifications'`. The accompanying badge is announced through the `aria-label` (`Notifications: 5 unread`, or similar — the consumer is responsible for composing the full accessible name when the count is non-zero).
+- `NotificationCenter.Trigger` renders an IconButton named “Notifications” at zero, or “Notifications, N unread” when positive. An explicit aria-label overrides this fallback. The visual badge is aria-hidden; it stays at the bell's upper trailing corner inside the trigger host.
 
 **Keyboard:**
 
@@ -171,7 +172,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Focus:**
 
 - The component does not render a focus ring on items or panels. Interactive content provides its own ring.
-- The trigger button gets the standard `IconButton` focus ring.
+- The trigger button gets the standard `IconButton` focus ring and a minimum 44px target containing both the bell and count.
 
 **Reduced motion:**
 
@@ -180,7 +181,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Color and meaning:**
 
 - Unread state is communicated by both the left border accent and the background lift. The text is unchanged; consumers can add an `aria-label="Unread"` to make the state screen-reader-accessible.
-- The trigger badge is a red `Badge` (`variant="error"`). The label is the numeric count.
+- The trigger badge is an accent `Badge` (`variant="primary"`), using accent-track and accent-contrast from the inherited Theme. The label is the numeric count.
 
 **Naming:**
 
@@ -210,7 +211,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 **Token story:**
 
-- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the unread item border tracks `--dsx-color-primary` and is not affected by the accent token.
+- Renders the default panel inside a `Theme` wrapper with `accentColor="astral"` and `accentColor="spark"`. Asserts the unread item border tracks `--dsx-color-primary` and is not affected by the accent token.
 
 **A11y story:**
 
@@ -228,7 +229,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Composes from:**
 
 - `IconButton` (`src/components/iconButton`): the trigger renders a small ghost `IconButton`. The trigger forwards all `IconButton` props and defaults `aria-label="Notifications"`.
-- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="error"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` for counts greater than 99.
+- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="primary"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` for counts greater than 99.
 - `@radix-ui/react-slot`: enables `asChild` on the root and on the named slots.
 
 **Used by:**
@@ -244,3 +245,12 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 - App-owned data: notification text, timestamps, action handlers, and the unread count source.
 - DS-owned visuals: token bindings, slot classes, unread state styling, and the trigger badge geometry.
+
+## Overlay review fixture
+
+`/docs/notification-center` shows native button rows that mark themselves read,
+Mark all read, Reset inbox, a real Popover and trigger counts 0/1/5/150. Item
+button hosts have width=100%, inherited typography, start-aligned wrapping text,
+and hover/focus/pressed feedback. The list is min-height=0 and flexes; header
+and footer remain nonshrinking. Payload, routing and read persistence are
+consumer-owned. Trigger asChild preserves host/ref/click composition.

package/dist/docs/components/page-header.md

@@ -119,6 +119,8 @@ Rules:
 
 ## Playground demo spec
 
+The live example uses a compact named icon action so the title remains readable in a 320px review frame, plus a title-only header. Header height and title ellipsis behavior remain canonical.
+
 `PageHeader` is registered in `apps/playground/lib/registry/display.tsx` under the `page-header` key.
 
 **Default story:**

package/dist/docs/components/pagination.md

@@ -363,3 +363,7 @@ Rules:
 
 - App-owned data: the pagination strategy (offset / limit vs cursor), the page-size policy, the link generation, and the total count.
 - DS-owned visuals: the `dsx-pagination` root class, the slot classes, the token bindings, and the `data-*` and ARIA attribute contract.
+
+## Reconciliation stories
+
+The live PaginationBar owns page and limit state, commits first/last/previous/next and page input, resets to page 1 when the limit changes, and shows a dense single-page boundary reference. Controls remain visible and wrap within narrow hosts.

package/dist/docs/components/pills.md

@@ -15,7 +15,7 @@ depends_on:
 
 ## Purpose
 
-A compact cluster of selectable pills rendered as a horizontal flex list. Use Pills for filter chips, multi-select chip rows, and segmented status indicators. For a single label surface, use `Badge`. For a lone removable label, use `Tag`. For mutually exclusive options rendered as a segmented control, use `SegmentedControl` or `ToggleGroup`. Cardinality rule (F6 brief): a row of chips with selection state is Pills; one chip with a remove action is a Tag. Pills claims selection, never lone dismissal.
+A compact cluster of selectable pills rendered as a horizontal flex list. Use Pills for filter chips, multi-select chip rows, and segmented status indicators. For a single label surface, use `Badge`. For a lone removable label, use `Tag`. For mutually exclusive options rendered as a segmented control, use `SegmentedControl` or `ToggleGroup`. Cardinality rule (F6 brief): a row of chips with selection state is Pills; one chip with a remove action is a Tag. Selection is consumer-owned: a plain `Pill` is a list item, not an interactive selection control. Compose a button with `aria-pressed` or an existing Toggle inside the item when selection is required.
 
 ## Anatomy & slots
 
@@ -97,7 +97,7 @@ Each pill also accepts the standard HTML attributes for its host element. The `c
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. `size`, `variant`, `color`, and `radius` are single-value only.
+- The component does not write `@media` rules. `size`, `variant`, `color`, and `radius` are single-value only. The cluster always wraps; each item is capped to the available width and breaks long labels. The remove button reserves a non-shrinking 24px square (`size-md`).
 
 **Reduced motion:**
 
@@ -179,7 +179,7 @@ The component is static. Hover and focus states are instant.
 
 **Naming:**
 
-- The pill's `children` are the accessible name. The remove button has a hard-coded `aria-label="Remove"`; consumers that need a contextual label should override the `aria-label` via the standard HTML attribute spread.
+- The pill's `children` are the accessible name. The built-in remove button has a fixed `aria-label="Remove"`. Attributes on the `Pill` host do not override this child button. A consumer needing a contextual action name can compose its own labelled button inside `Pill` instead of using `removable`.
 
 ## Playground demo spec
 
@@ -205,7 +205,7 @@ The component is static. Hover and focus states are instant.
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Pills with a `color` prop track `data-accent-color`; the story asserts the destructive and link pills do not flip color because they read from the error and primary palettes.
+- Renders inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Pills with a `color` prop track `data-accent-color`; the story asserts the destructive and link pills do not flip color because they read from the error and primary palettes.
 
 **A11y story:**
 
@@ -244,3 +244,12 @@ The component is static. Hover and focus states are instant.
 
 - App-owned data: the cluster items, the per-pill labels, the selection state (for filter chips), and the dismiss callbacks.
 - DS-owned visuals: token bindings, the modifier classes, the per-pill surface palette, and the remove button.
+
+## Reconciliation stories
+
+`Pill asChild` slots a single consumer host and appends its built-in removal
+button inside that host. The host remains responsible for valid list semantics;
+use a list item when placing it directly in `Pills`. Slotted selection controls
+and removable slotted items must mount without a multiple-child Slot error.
+
+The live example removes and resets actual filter labels, includes a long wrapping label, and demonstrates consumer-owned selection with labelled aria-pressed buttons inside list items. Static variants are labelled as visual references.

package/dist/docs/components/popover.md

@@ -82,7 +82,7 @@ An interactive floating surface anchored to a trigger. `Popover` is more interac
 
 **Close props:**
 
-`Popover.Close` accepts the standard Radix `Close` props.
+`Popover.Close` accepts the standard Radix `Close` props. It is an inline dismissal action, normally composed with `asChild` over a Button. It has no fixed corner position or icon-only dimensions; consumers own the label and placement. When composed over Button, its rest palette and border are preserved; Button state selectors own hover, pressed, disabled and high-contrast behavior.
 
 Rules:
 
@@ -137,8 +137,7 @@ Rules:
 | Description color | `var(--dsx-color-on-surface-variant)` | Body copy. |
 | Content z-index | `calc(var(--dsx-z-index-modal, 90) + 1)` | Keeps portaled content above both sticky chrome and a modal-tier surface that owns its trigger. |
 | Positioner z-index | `var(--dsx-z-index-popover, 60)` | Stacking for an explicitly composed positioner. |
-| Close button size | `var(--dsx-size-lg)` | Square tap target. |
-| Close button radius | `var(--dsx-rounded-full)` | Round close. |
+| Close minimum dimensions | `var(--dsx-size-md)` | 24px floor; composed Button supplies its own dimensions and radius. |
 | Motion duration | `var(--dsx-motion-duration-*)` | Mount and exit. |
 | Motion easing | `var(--dsx-motion-easing-*)` | Mount and exit. |
 
@@ -306,3 +305,11 @@ Rules:
 - [ ] 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.
+
+## Overlay review containment
+
+Content has one minmax(0, 1fr) grid track and wraps long words. This prevents
+a child panel’s preferred width from enlarging an implicit track beyond the
+viewport-capped surface and being clipped by overflow=hidden. The live example
+sets and applies a real density preference; NotificationCenter also composes
+inside this surface with proper Title and Description.

package/dist/docs/components/prose.md

@@ -21,6 +21,15 @@ Consumers preserve heading order, stable IDs, meaningful image alt text, caption
 
 The root can shrink within its parent. Long words, URLs, and identifiers wrap inside the reading measure; preformatted code and tables retain their explicit horizontal scrolling.
 
+## Color roles
+
+Inline code and preformatted blocks use `--dsx-code-soft-background`, the
+same contextual neutral wash as soft Code (existing gray-alpha-3 effect).
+A `pre > code` child stays transparent to avoid painting the wash twice.
+Blockquotes use the 1px boundary-divider width with decorative accent-border
+(light step 8 / dark step 11). Links retain readable accent-indicator ink.
+Local Theme and gray changes recompute these paint aliases.
+
 ## Playground demo spec
 
 Render all supported semantic elements, sanitized HTML, a wide table at mobile width, and authored blocks in the separate ArticleNodes stream.

package/dist/docs/components/qr-code.md

@@ -13,7 +13,7 @@ depends_on:
 
 ## Purpose
 
-A token-aligned QR code surface that renders a scannable `QRCodeSVG` from `qrcode.react` inside a styled container, with a size scale and high-contrast mode for accessibility. The component owns the shell and token binding; the app owns the encoded payload, error-correction level, and any persistence.
+A token-aligned QR code surface that renders a scannable `QRCodeSVG` from `qrcode.react` inside a styled container, with a fixed matrix size scale and a legacy CSS high-contrast hook. The component owns the shell and token binding; the app owns the encoded payload, error-correction level, and any persistence.
 
 ## Anatomy & slots
 
@@ -21,7 +21,7 @@ A token-aligned QR code surface that renders a scannable `QRCodeSVG` from `qrcod
 
 **Slots:**
 
-No slots: flat export. The component renders a single `<div>` host element (or a slotted child when `asChild` is set) that wraps the `QRCodeSVG` adapter output. The encoded value, the error-correction level, the margin, and the module colors are all props on the host. The component does not own a label, caption, or download action; consumers compose those around the surface.
+No slots: flat export. The component renders a single role=img `<div>` host element (or a consumer-supplied slotted child when `asChild` is set) that wraps the `QRCodeSVG` adapter output. The encoded value, the error-correction level, the margin, and the module colors are all props on the host. The component does not own a label, caption, or download action; consumers compose those around the surface.
 
 **Adapter host:** `QRCodeSVG` from `qrcode.react`. The adapter is wrapped in a styled container; the adapter is a `peerDependency` and the package does not own the rendered SVG paths.
 
@@ -30,9 +30,9 @@ No slots: flat export. The component renders a single `<div>` host element (or a
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `value` | `string` | `undefined` | yes | String payload encoded into the QR modules. Required by `QRCodeSVG`; the host element also omits the native `value` attribute. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Painted size; selects one of the internal `sizeMap` values (`sm: 128`, `md: 192`, `lg: 256` px) and writes `data-size` plus the matching `dsx-qr-code-size-*` class. The SVG paints at exactly the `sizeMap` dimensions — the CSS never constrains it, so every size is scannable. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Painted size; selects one of the internal `sizeMap` values (`sm: 128`, `md: 192`, `lg: 256` px) and writes `data-size` plus the matching `dsx-qr-code-size-*` class. The SVG retains sizeMap dimensions, never flex-shrinks and overrides generic SVG max-width rules. Hosts narrower than the matrix must supply scrolling. | no |
 | `level` | `'L' \| 'M' \| 'Q' \| 'H'` | `'M'` | no | Error-correction level passed through to `QRCodeSVG`. `L` is ~7%, `M` is ~15%, `Q` is ~25%, `H` is ~30% recovery. | no |
-| `marginSize` | `number` | `0` | no | Quiet-zone margin passed through to `QRCodeSVG`. Default `0` matches the adapter default and is the spec baseline. | no |
+| `marginSize` | `number` | `0` | no | Quiet-zone margin passed through to `QRCodeSVG`. Default 0 matches the adapter baseline; scan/share examples explicitly set 4 modules of quiet zone. | no |
 | `fgColor` | `string` | `var(--dsx-color-on-surface)` | no | Module (foreground) color. Default falls back to the token CSS variable; pass an explicit value to override. | no |
 | `bgColor` | `string` | `var(--dsx-color-surface-raised)` | no | Quiet-zone (background) color. Default falls back to the token CSS variable; pass an explicit value to override. | no |
 | `asChild` | `boolean` | `false` | no | Renders the QR code container through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
@@ -60,7 +60,7 @@ Rules that apply to this row:
 | `data-slot` | `qr-code` | (CSS hook only) | n/a |
 | `data-high-contrast` | `true` | `.dsx-qr-code[data-high-contrast='true']` (hook only; runtime does not currently emit) | `qr-code.css` |
 
-**Slot classes:** none. The inner `svg` is targeted by `.dsx-qr-code svg` and the `rect[fill]` modules by `.dsx-qr-code svg rect[fill]`. These are CSS hooks, not public slots.
+**Slot classes:** none. The inner svg is targeted by .dsx-qr-code svg; the legacy high-contrast hook targets first/last paths from qrcode.react 4.2. These are CSS hooks, not public slots.
 
 **Responsive behavior:**
 
@@ -95,8 +95,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with runtime fal
 Rules:
 
 - The runtime SVG dimensions (`128`, `192`, `256`) are NOT tokens; they are the adapter's own pixel size used to compute the QR matrix, painted verbatim. The CSS must never override the visible width and height with sizing tokens — that revision shipped 16/24/40px unscannable codes.
-- The `fgColor` and `bgColor` props are passed as CSS variable references (`'var(--dsx-color-on-surface)'`, `'var(--dsx-color-surface-raised)'`) when the consumer does not pass explicit values. The adapter forwards these into SVG attributes; token-driven theming therefore requires the `qr-code.css` rules to win on the modules, which is what the high-contrast block does.
-- The high-contrast block uses `svg rect[fill]:first-of-type` to recolor the background module; this relies on the adapter emitting the background as a single `<rect>`. If the adapter's output changes, the high-contrast fallback breaks.
+- The `fgColor` and `bgColor` props are passed as CSS variable references (`'var(--dsx-color-on-surface)'`, `'var(--dsx-color-surface-raised)'`) when the consumer does not pass explicit values. The adapter forwards CSS variable references into SVG fill attributes; ordinary theme inheritance resolves them. The legacy high-contrast CSS hook overrides paths when an app explicitly supplies its attribute.
+- The high-contrast hook colors the first path as background and last path as modules, matching the installed adapter output. Adapter output changes require a fresh paint check.
 
 ## Motion contract
 
@@ -113,7 +113,7 @@ Rules:
 
 **Roles:**
 
-- `img` (QR code). The component renders a non-text graphic; consumers must supply an accessible name via `aria-label`, an `aria-labelledby` reference, or a sibling label. The runtime does not currently set `role` or `aria-label` (see Anomalies).
+- `img` (QR code). The component renders a non-text graphic; consumers must supply an accessible name via `aria-label`, an `aria-labelledby` reference, or a sibling label. The runtime sets role=img and forwards the consumer accessible name.
 
 **Keyboard:**
 
@@ -129,7 +129,7 @@ Rules:
 
 **Color and meaning:**
 
-- The QR modules carry the data; the rendered colors are decorative. A high-contrast CSS hook is available for accessible contexts, but the runtime does not currently expose a `data-high-contrast` prop. Apps that need high-contrast mode should toggle the attribute on the host element directly or fork the component.
+- The QR modules carry the data; the rendered colors are decorative. A legacy high-contrast CSS hook is available through a native data-high-contrast attribute; there is no highContrast prop. Apps own scanner compatibility and may explicitly select positive dark-on-light fgColor/bgColor for physical scan contexts.
 
 **Naming:**
 
@@ -137,7 +137,7 @@ Rules:
 
 ## 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 /docs/qr-code registry supplies wrapped comparisons and a scrollable host for matrices wider than their container. It never shrinks the SVG to fit.
 
 **Default story:**
 
@@ -157,11 +157,11 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. The QR module color is token-driven via the `fgColor` runtime default; the story asserts the modules track the `on-surface` token across the three accents.
+- Renders inside a `Theme` wrapper with the five supported accents (Rift, Warp, Ray, Astral, Spark). The QR module color is token-driven via the `fgColor` runtime default; the story asserts the modules track the `on-surface` token across all five accents.
 
 **A11y story:**
 
-- Uses `vitest-axe` against the rendered default QR code wrapped in a labelled element. Asserts there are no axe violations only when the host carries an accessible name. The default story alone is expected to flag a missing accessible name and is documented in the playground as a known issue.
+- Uses `vitest-axe` against the rendered default QR code wrapped in a labelled element. Asserts there are no axe violations only when the host carries an accessible name. Unlabelled caller output does not satisfy the naming contract.
 
 **Props exposed in the playground controls:**
 

package/dist/docs/components/quote.md

@@ -56,18 +56,23 @@ Rules that apply to this row:
 
 ## Token mapping
 
-Every CSS value the component paints is a CSS keyword or hard-code; there are no `var(--dsx-*)` tokens in `quote.css`. The italic style matches the HTML `<q>` element's expected visual treatment.
+Every CSS value the component paints is a CSS keyword or hard-code; there are no `var(--dsx-*)` tokens in `quote.css`. Italics are this package's visual choice; HTML quotation semantics come from `<q>` and its generated quotation marks.
 
 | Property | Token | Role |
 |---|---|---|
 | `quotes` | `auto` (CSS keyword) | Lets the browser pick the right opening and closing quote glyphs from the document language. |
-| Font style | `italic` (hard-coded) | Visual convention for inline quotation; matches the HTML `<q>` default and is not overridable through a prop. |
+| Font style | `italic` (hard-coded) | Package convention for inline quotation, not an HTML requirement; consumer style can override it. |
 
 Rules:
 
-- `DESIGN.md` and the generated `tokens.css` do not define a `quotes` or italic typography token. Both are CSS hard-codes, consistent with the HTML `<q>` element's default behavior.
+- `DESIGN.md` and the generated `tokens.css` do not define a `quotes` or italic typography token. Language-aware quotation marks follow native `<q>` behavior; the italic treatment is authored by this package.
 - No raw color, spacing, or motion values are introduced by this component.
 
+Large opening/closing quotation glyphs, icons and source captions belong to a
+consumer's block quotation composition using `Blockquote`, not an inline
+Quote variant. Em marks stress emphasis; Quote marks words quoted from a
+source even though both share an italic treatment.
+
 ## Motion contract
 
 | Region | Token | Default | Reduced |
@@ -108,7 +113,7 @@ Rules:
 
 ## Playground demo spec
 
-`Quote` is registered in `apps/playground/lib/registry/typography.tsx` under the `quote` key. The registry entry imports `quotePropDefs` and renders the component with a sample inline quotation. Per-component route: `/docs/quote`.
+`Quote` is registered in `apps/playground/lib/registry/typography.tsx` under the `quote` key. The registry entry imports `quotePropDefs` and renders the component with a sample inline quotation. Per-component route: `/docs/quote`. The live example uses English and Russian quotations, a nested quote and a slotted span.
 
 **Default story:**
 

package/dist/docs/components/resizable.md

@@ -17,25 +17,25 @@ A resizable panel group with draggable handles. The package owns the shell, the
 
 ## Anatomy & slots
 
-**Parent:** `Resizable` (alias of `Resizable.PanelGroup`).
+**Parent:** `Resizable` (alias of `ResizablePanelGroup`).
 
 **Slots:**
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Resizable.PanelGroup` (alias `Resizable`) | `<div>` (the `Group` from `react-resizable-panels`) | `dsx-resizable-group` | Hosts the orientation attribute and the panel layout. Carries `data-orientation` and `data-slot="resizable-group"`. |
+| `ResizablePanelGroup` (alias `Resizable`) | `<div>` (the `Group` from `react-resizable-panels`) | `dsx-resizable-group` | Hosts the orientation attribute and the panel layout. Carries `data-orientation` and `data-slot="resizable-group"`. |
 | `Resizable.Panel` | `<div>` (the `Panel` from `react-resizable-panels`) | `dsx-resizable-panel` | One resizable child. Carries `data-slot="resizable-panel"`. |
 | `Resizable.Handle` | `<div>` (the `Separator` from `react-resizable-panels`) | `dsx-resizable-handle` | The draggable separator between two panels. Carries `data-slot="resizable-handle"` and `data-grip="true"` when `withGrip` is set. When `withGrip` is set, a child `<div>` with `dsx-resizable-handle__grip` is rendered. |
 
 **Adapter host:**
 
-`Resizable.PanelGroup` wraps the `Group` from `react-resizable-panels`. The package translates the DS `direction` prop (`'horizontal'` or `'vertical'`) into the adapter's `orientation` prop. The package also passes `elementRef` through `composeRefs` so the `forwardRef` and any app-supplied ref both see the host element.
+`ResizablePanelGroup` wraps the `Group` from `react-resizable-panels`. The package translates the DS `direction` prop (`'horizontal'` or `'vertical'`) into the adapter's `orientation` prop. The package also passes `elementRef` through `composeRefs` so the `forwardRef` and any app-supplied ref both see the host element.
 
 `Resizable.Handle` wraps the `Separator` from `react-resizable-panels`. `withGrip` adds a visual grip indicator inside the handle; the adapter still owns the drag interaction and the keyboard arrow support.
 
 ## Props contract
 
-### `Resizable.PanelGroup` props
+### `ResizablePanelGroup` props
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
@@ -43,7 +43,7 @@ A resizable panel group with draggable handles. The package owns the shell, the
 | `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Drives `data-orientation` on the group. Mapped to the adapter's `orientation` prop. The CSS file uses the inline `[data-orientation='…']` selectors and the modifier `dsx-resizable-group-direction-horizontal` / `dsx-resizable-group-direction-vertical` class. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-resizable-group`. | no |
 
-The group also accepts the full `GroupProps` from `react-resizable-panels` minus `orientation` (which is replaced by the DS `direction` prop) and `elementRef` (which the package routes through `composeRefs`). `autoSaveId`, `id`, `onLayout`, `storage`, `defaultLayout`, and `keyboardResizeBy` are forwarded verbatim.
+The group also accepts the full `GroupProps` from `react-resizable-panels` minus `orientation` (which is replaced by the DS `direction` prop) and `elementRef` (which the package routes through `composeRefs`). `id`, `defaultLayout`, `onLayoutChange`, `onLayoutChanged`, `disabled`, `groupRef` and `resizeTargetMinimumSize` follow the installed v4 adapter contract. Persistence belongs to the app; v3-only props are not promised.
 
 ### `Resizable.Panel` props
 
@@ -52,7 +52,7 @@ The group also accepts the full `GroupProps` from `react-resizable-panels` minus
 | `asChild` | `boolean` | `false` | no | Extracted from prop defs but the `Panel` host always renders a `<div>`. The prop is reserved for future use. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-resizable-panel`. | no |
 
-The panel also accepts the full `PanelProps` from `react-resizable-panels` minus `elementRef`. `defaultSize`, `minSize`, `maxSize`, `collapsible`, `collapsedSize`, `onCollapse`, `onExpand`, `onResize`, `id`, `order`, and `ref` are forwarded verbatim.
+The panel also accepts the full `PanelProps` from `react-resizable-panels` minus `elementRef`. `defaultSize`, `minSize`, `maxSize`, `collapsible`, `collapsedSize`, `onResize`, `id`, `panelRef` and `groupResizeBehavior` follow the installed v4 adapter contract. Use explicit percentage strings such as "50%"; numeric sizes represent pixels.
 
 ### `Resizable.Handle` props
 
@@ -62,7 +62,7 @@ The panel also accepts the full `PanelProps` from `react-resizable-panels` minus
 | `withGrip` | `boolean` | `false` | no | When `true`, renders a `dsx-resizable-handle__grip` indicator inside the handle and sets `data-grip="true"`. The CSS file uses the `data-grip` attribute and the `dsx-resizable-handle-grip` modifier class to color the indicator. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-resizable-handle`. | no |
 
-The handle also accepts the full `SeparatorProps` from `react-resizable-panels` minus `elementRef` and `withGrip`. `id`, `disabled`, `hitAreaMargins`, and the adapter drag attributes are forwarded verbatim.
+The handle also accepts the full `SeparatorProps` from `react-resizable-panels` minus `elementRef` and `withGrip`. `id`, `disabled` and native attributes follow SeparatorProps. Group resizeTargetMinimumSize controls adapter hit geometry; v3 hitAreaMargins is not promised.
 
 ## CSS class contract
 
@@ -96,12 +96,12 @@ The handle also accepts the full `SeparatorProps` from `react-resizable-panels`
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component has no viewport-width media rules. None of its prop defs are `responsive: true`.
 - The component's CSS file is breakpoint-agnostic.
 
 **Reduced motion:**
 
-- The handle background and the grip indicator transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query. The adapter's drag interaction is layout-only and does not animate.
+- The handle background and the grip indicator transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. Its own `prefers-reduced-motion` gate disables handle and track transitions. The adapter's drag interaction is layout-only and does not animate.
 
 ## Token mapping
 
@@ -119,7 +119,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Handle active background | `var(--dsx-color-high-contrast-container)` | Active affordance. |
 | Handle cursor | `col-resize` (horizontal), `row-resize` (vertical) | Cursor. |
 | Handle touch action | `none` | Prevent browser scroll on touch. |
-| Handle thickness | `var(--dsx-resizable-handle-thickness-active)` | Visible thickness. |
+| Handle thickness | `max(var(--dsx-size-md), var(--dsx-resizable-handle-thickness-active))` | Actual hit box, at least 24px; the painted line stays thin. |
 | Handle track | `var(--dsx-border-width-md, var(--dsx-resizable-handle-thickness))` | Inactive track thickness. |
 | Handle track color | `var(--dsx-control-separator-color-strong)` | Track color. |
 | Handle track hover color | `var(--dsx-color-high-contrast)` | Hover color. |
@@ -127,6 +127,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Grip width | `var(--dsx-resizable-grip-width)` | Grip indicator width. |
 | Grip height | `var(--dsx-resizable-grip-height)` | Grip indicator height. |
 | Grip radius | `var(--dsx-resizable-grip-radius)` | Grip indicator roundness. |
+| Handle z-index | `var(--dsx-z-index-elevated)` | Preserve the entire target above pane content. |
 | Grip z-index | `var(--dsx-z-index-elevated)` | Grip stack order. |
 | Grip horizontal size | `var(--dsx-space-xs)` × `var(--dsx-size-xs)` | Horizontal handle grip dimensions. |
 | Grip vertical size | `var(--dsx-size-xs)` × `var(--dsx-space-xs)` | Vertical handle grip dimensions. |
@@ -136,8 +137,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| Handle background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover and active background transition. | Relies on the global `prefers-reduced-motion` stylesheet. |
-| Handle track and grip | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Track color, grip background, and transform transition. | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Handle background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover and active background transition. | Own CSS disables handle transitions under prefers-reduced-motion. |
+| Handle track and grip | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Track color, grip background, and transform transition. | Own CSS disables handle transitions under prefers-reduced-motion. |
 
 ## Accessibility
 
@@ -152,20 +153,20 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|
 | `Tab` | Moves focus to the next focusable element. The handle is focusable by default. |
 | `Enter`, `Space` | Toggles the panel state when the handle supports collapsing. |
-| `Arrow keys` | The adapter handles arrow-key resize by the `keyboardResizeBy` step. |
+| `Arrow keys` | The installed v4 adapter handles arrow-key resizing. |
 | `Home`, `End` | The adapter collapses or expands the panel to its minimum or maximum size when supported. |
 
 **Focus:**
 
-- The handle receives a visible focus ring via the browser default for `[role="separator"]` plus the global focus stylesheet. The DS does not add a custom ring; apps that need a custom ring can target `[role="separator"]:focus-visible` from the host.
+- The DS paints `var(--dsx-shadow-focus-ring)` on `.dsx-resizable-handle:focus-visible`. The handle stays above adjacent pane content so its full target receives input.
 
 **Reduced motion:**
 
-- The handle transitions collapse under the global `prefers-reduced-motion` stylesheet. The drag interaction is layout-only and does not animate.
+- The handle and track transitions are disabled by their own `prefers-reduced-motion` rules. The drag interaction is layout-only and does not animate.
 
 **Color and meaning:**
 
-- The handle and the grip use semantic tokens (`var(--dsx-color-high-contrast-container)` and `var(--dsx-color-on-surface-variant)`) so light and dark themes are covered. The track thickness increases from `var(--dsx-resizable-handle-thickness)` to `var(--dsx-resizable-handle-thickness-active)` on hover to communicate the drag affordance.
+- The handle and the grip use semantic tokens (`var(--dsx-color-high-contrast-container)` and `var(--dsx-color-on-surface-variant)`) so light and dark themes are covered. The thin track keeps its thickness on hover; semantic color changes communicate the drag affordance.
 
 **Naming:**
 
@@ -198,6 +199,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 `withGrip` is wired through the composition story rather than the prop table.
 
+## Review examples
+
+The horizontal workspace preserves scrollable outline and draft panes, minimum
+20% panel sizes and a live proportions summary. The vertical example exercises
+its own resize axis. Handles have visible keyboard focus; both directions
+retain a 24px minimum box while the visual divider remains thin.
+
 ## Wiring notes
 
 **Composes from:**
@@ -212,8 +220,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 **State boundaries:**
 
 - Owned by this component: the DS shell class wiring, the `direction` to `orientation` translation, the `withGrip` rendering, the `data-orientation` and `data-slot` attributes, and the `composeRefs` helper.
-- Owned by the adapter: panel math, drag interaction, keyboard arrow resize, the `autoSaveId` persistence, the percentage bookkeeping, and the `role="separator"` semantics.
-- Owned by the consumer: the number of panels, the `defaultSize`, `minSize`, `maxSize`, and `collapsible` configuration, the content of each panel, the `onLayout` callback, and any business policy that wraps the layout state.
+- Owned by the adapter: panel math, drag interaction, keyboard arrow resize, the percentage bookkeeping, and the `role="separator"` semantics.
+- Owned by the consumer: the number of panels, the `defaultSize`, `minSize`, `maxSize`, and `collapsible` configuration, the content of each panel, the adapter layout callbacks, and any business policy that wraps the layout state.
 
 **Boundary rules:**