@d4gger/design-system 3.0.1 → 4.0.1

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 count hangs on the bell's upper trailing corner (capped at `'99+'`, or at `{max}+` when `max` is set) and the hover highlight covers the bell only; 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 ordinary `IconButton` (size `sm`, 32px, the same shape as every other header icon), so its hover highlight covers the bell only (G-20, 2026-10-05; it used to be a 59×44 pill that wrapped the count). The count is absolutely positioned on the bell's upper trailing corner: raised by `space-sm`, starting `space-xs` past the glyph's centre, so a constant 4px of it overlaps the bell and wider counts grow toward the trailing edge. The trigger reserves `space-md` after itself for the count, always, so the controls after it do not move when a count appears. A pseudo-element keeps the hit area at 44px (`size-xl + space-xs`) around the 32px highlight. The badge uses rounded-full and label-small typography.
 
 ## Props contract
 
@@ -64,7 +64,8 @@ These three slots accept only `asChild` plus the standard HTML attribute surface
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `unreadCount` | `number` | `undefined` | no | Unread count rendered as a `Badge` (capped at `'99+'`). The badge is only rendered when the count is greater than zero. | no |
+| `unreadCount` | `number` | `undefined` | no | Unread count rendered as a `Badge` (capped at `max`, `'99+'` by default). The badge is only rendered when the count is greater than zero. | no |
+| `max` | `number` | `99` | no | Largest count the badge draws; above it the badge reads `{max}+` (core's bell uses `9`). A value that is not a positive whole number falls back to `99`. The accessible name keeps the real count (“Notifications, 12 unread”), and `max` is not written to the DOM. Follows MUI `Badge` `max` and Ant Design `overflowCount`. | no |
 | `aria-label` | `string` | `'Notifications'` | no | Accessible name on the underlying `IconButton`. Override to localize or to disambiguate when more than one trigger is on the page. | no |
 | `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
 
@@ -101,7 +102,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 +114,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 +139,12 @@ 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 size | the `IconButton` `sm` size (32px), no override | An ordinary header icon button; the highlight covers the bell only (G-20) |
+| Trigger inline-end margin | `var(--dsx-space-md)` | Reserves the room the hanging count needs, always, so the controls after the bell do not move when a count appears |
+| Trigger hit area | `::after`, `inset: calc((100% - (var(--dsx-size-xl) + var(--dsx-space-xs))) / 2)` | A 44px target around the 32px highlight (the inset shrinks to nothing on a larger size) |
+| Badge placement | absolute, `top: calc(-1 * var(--dsx-space-sm))`, `inset-inline-start: calc(50% + var(--dsx-space-xs))` | Upper trailing corner, a constant 4px overlap with the bell glyph; wider counts grow toward the trailing edge |
+| 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 +162,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 hangs on the bell's upper trailing corner.
 
 **Keyboard:**
 
@@ -171,7 +174,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. Its visible box is 32px; a pseudo-element extends the hit area to 44px around the bell. The count hangs outside the box and is not part of the target (it is aria-hidden; the accessible name carries the number).
 
 **Reduced motion:**
 
@@ -180,7 +183,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:**
 
@@ -203,6 +206,9 @@ The component has no motion. The panel itself is static; transitions on open / c
 - Renders an `Item` with `unread`. Asserts `data-unread="true"` and the `--unread` modifier class.
 - Renders a `Trigger` with `unreadCount={5}`. Asserts the badge text is `'5'`.
 - Renders a `Trigger` with `unreadCount={150}`. Asserts the badge text is `'99+'`.
+- Renders a `Trigger` with `unreadCount={12}` and `max={9}`. Asserts the badge text is `'9+'` and the accessible name still reads “Notifications, 12 unread”. A count equal to `max` draws the number; an invalid `max` (0, negative, fractional, NaN) falls back to `'99+'`.
+
+- `src/test/styles/shell-look-pass.test.ts` guards the trigger's CSS contract (an ordinary icon button, a corner-anchored count, the 44px hit-area pseudo-element, the reserved margin); `apps/playground/tests/overlay-feedback-review.spec.ts` measures the geometry and the hit area at 1280 / 390 / 320px. They supersede the earlier contract (a control of at least 44×44 with the count contained in it) (G-20, 2026-10-05).
 
 **Composition story:**
 
@@ -210,7 +216,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 +234,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+'` (or `{max}+` when `max` is set) for counts greater than the cap.
 - `@radix-ui/react-slot`: enables `asChild` on the root and on the named slots.
 
 **Used by:**
@@ -244,3 +250,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

@@ -13,7 +13,7 @@ depends_on:
 
 ## Purpose
 
-A fixed-height header bar for the content area of a cabinet/shell layout: a title on the left, trailing actions on the right. Designed to be the first child inside `.dsx-sidebar__inset` (the content column `Sidebar` leaves for the app to fill), so every app screen shares one header height and padding scale instead of inventing its own.
+A fixed-height header bar for the content area of a cabinet/shell layout: a title on the left, trailing actions on the right. Designed to be the first child inside `.dsx-sidebar__inset` (the content column `Sidebar` leaves for the app to fill), so every app screen shares one header height and padding scale instead of inventing its own. A `floating` variant draws the same bar as a glass panel with its own edge, for shells whose content column sits beside a floating sidebar (direction C of the `frontend` vision).
 
 ## Anatomy & slots
 
@@ -23,7 +23,7 @@ A fixed-height header bar for the content area of a cabinet/shell layout: a titl
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `PageHeader.Root` | `<div>` | `dsx-page-header` | Fixed-height flex row, `justify-content: space-between`. Holds `Title` and `Actions`. |
+| `PageHeader.Root` | `<div>` | `dsx-page-header` + `data-variant` | Fixed-height flex row, `justify-content: space-between`. Holds `Title` and `Actions`. |
 | `PageHeader.Title` | `<h1>` | `dsx-page-header__title` | The page's h1. Single-line, truncates with ellipsis rather than wrapping. |
 | `PageHeader.Actions` | `<div>` | `dsx-page-header__actions` | Trailing flex row for buttons/icon buttons. Optional — a header with only a title is valid (see empty-state test). |
 
@@ -31,6 +31,7 @@ A fixed-height header bar for the content area of a cabinet/shell layout: a titl
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
+| `variant` | `'default' \| 'floating'` | `'default'` | no | Surface treatment; writes `data-variant`. `default`: the flat opaque bar with a bottom rule. `floating`: a glass panel with its own edge, radius and shadow (the `Card variant="glass"` recipe). The height and the slots are the same in both. | no |
 | `asChild` | `boolean` | `false` | no | Renders `Root` through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-page-header`. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Typically `PageHeader.Title` followed by an optional `PageHeader.Actions`. | no |
@@ -39,14 +40,14 @@ A fixed-height header bar for the content area of a cabinet/shell layout: a titl
 
 Rules that apply to this row:
 
-- `PageHeader` is a behavioral/layout composite, not a styled variant surface. It does not run a `variant` or `size` prop def — one shape, one height.
+- `PageHeader` has one height at every width and no `size` axis. Its only axis is `variant` (`default` / `floating`), which changes the surface, never the height. An unknown value falls back to `default`.
 - `PageHeader.Title` renders `h1` by default. A page should have exactly one; nested `Theme`/route-level headings should not duplicate it.
 
 ## CSS class contract
 
 **Root class:** `dsx-page-header`
 
-**Modifier classes:** none. No `data-variant`/`data-size` — the header has one fixed shape.
+**Modifier attributes:** `data-variant` (`default`, `floating`), written by the component; `.dsx-page-header:where([data-variant='floating'])` in `page-header.css` carries the glass surface. No `data-size` — the header has one fixed height.
 
 **Slot classes:**
 
@@ -73,6 +74,12 @@ Rules that apply to this row:
 | Gap | `var(--dsx-space-md)` | Gap between title and actions when both are near the edge. |
 | Border (bottom) | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline-variant)` | Separates the header from scrolled content below it. |
 | Background | `var(--dsx-color-surface)` | Matches the surrounding shell surface. |
+| Floating edge | `var(--dsx-border-width-sm)` + `var(--dsx-effect-panel-glass-border)` on all four sides | `variant="floating"`; replaces the bottom rule. |
+| Floating radius | `var(--dsx-rounded-lg)` | `variant="floating"`; the same as `Card`'s default radius. |
+| Floating surface | `var(--dsx-color-panel-translucent)` | `variant="floating"`; the glass fill. |
+| Floating rim | `var(--dsx-effect-panel-glass-rim-highlight)`, `var(--dsx-effect-panel-glass-rim)` | `variant="floating"`; the same two inset layers as `Card variant="glass"`. |
+| Floating shadow | `0 var(--dsx-shadow-offset-lg) var(--dsx-shadow-blur-md) calc(-1 * var(--dsx-shadow-offset-lg)) var(--dsx-effect-shadow-card-strong)` | `variant="floating"`; the shadow falls below the bar only (offset equals the negative spread, so it starts at the bar's bottom edge). The bar sits flush at the edge of a scroll container (`Sidebar.Inset`, `overflow: auto`) that clips what is painted past its left, right and top edges, so the full-ring `--dsx-shadow-panel-shadow` ended in a vertical cut at the bar's side in the light theme (G-21). This is the one place the floating bar differs from `Card variant="glass"`. Guarded by `src/test/styles/page-header-shadow.test.ts`. |
+| Floating blur | `var(--dsx-effect-panel-glass-backdrop-filter)` | `variant="floating"`; declared as `-webkit-backdrop-filter` first, `backdrop-filter` last (see `card.md`). |
 | Title font | `var(--dsx-typography-headline-medium-*)` family | 24px/600, the DS's headline-medium scale — sized for a 72px bar. |
 | Title color | `var(--dsx-color-on-surface)` | Primary text. |
 | Actions gap | `var(--dsx-space-sm)` | Gap between action buttons. |
@@ -80,6 +87,7 @@ Rules that apply to this row:
 Rules:
 
 - No raw px/color values in `page-header.css`. The 72px height is a `calc()` of two spacing tokens, not a hardcoded value.
+- The floating blur only shows when content passes under the bar (a sticky header over a scrolling page). The DS does not make the bar sticky or give it a margin: the page decides where it sits.
 
 ## Motion contract
 
@@ -119,6 +127,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:**
@@ -129,6 +139,10 @@ Rules:
 
 - Renders `PageHeader` with both `Title` and `Actions` (one or two buttons). Asserts both slots render with their classes.
 
+**Variant story:**
+
+- Renders `PageHeader` with `variant="default"` and `variant="floating"`. Asserts the matching `data-variant` attribute; the floating bar keeps the title and actions slots and the same height.
+
 **Empty-state story:**
 
 - Renders `PageHeader` with only `Title`, no `Actions` — the header still renders correctly with no trailing content.
@@ -143,7 +157,7 @@ Rules:
 |---|---|---|
 | (not exposed) | n/a | n/a |
 
-`PageHeader` has no variant/size axis to expose; the playground demonstrates it via a static composition fixture (title + actions) rather than a controls panel.
+`PageHeader` has no size axis, and its `variant` is shown as two fixtures (default and floating) in one composition rather than a controls panel.
 
 ## Wiring notes
 
@@ -157,7 +171,7 @@ Rules:
 
 **State boundaries:**
 
-- Owned by `PageHeader`: the root class, fixed height, padding, and the two slot classes.
+- Owned by `PageHeader`: the root class, `data-variant`, the fixed height, padding, the surface of each variant, and the two slot classes.
 - Owned by the consumer: the title text, which actions render, and their handlers.
 
 **Boundary rules:**

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:**