@d4gger/design-system 3.0.0 → 3.0.1

package/dist/docs/components/floating-panel.md

@@ -146,8 +146,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Shell radius | `var(--dsx-rounded-xl)` | Panel corner radius. |
 | Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Panel edge. |
 | Shell fill | `var(--dsx-color-panel-translucent)` | Panel surface. |
-| Shell shadow (rest) | `var(--dsx-shadow-md)` | Resting elevation. |
-| Shell shadow (dragging) | `var(--dsx-shadow-xl)` | Active elevation. |
+| Shell shadow (rest) | `var(--dsx-shadow-elevation-2)` | Resting elevation. |
+| Shell shadow (dragging) | `var(--dsx-shadow-elevation-5)` | Active elevation. |
 | Shell overflow | `hidden` (raw) | Contain children. |
 | Shell z-index | `var(--dsx-z-index-overlay-local)` | Above page content. |
 | Header padding | `var(--dsx-space-sm)` block, `var(--dsx-space-md)` inline | Inner gutter. |
@@ -341,8 +341,8 @@ The package does not yet publish a Penpot asset for FloatingPanel. Recipe is vis
 | Shell | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 | Shell | stroke | `--dsx-color-outline` | Color | `strokes` |
 | Shell | radius | `--dsx-rounded-xl` | Radius | `radius` |
-| Shell | shadow | `--dsx-shadow-md` | Effect | `shadow` |
-| Shell (dragging) | shadow | `--dsx-shadow-xl` | Effect | `shadow` (state) |
+| Shell | shadow | `--dsx-shadow-elevation-2` | Effect | `shadow` |
+| Shell (dragging) | shadow | `--dsx-shadow-elevation-5` | Effect | `shadow` (state) |
 | Header | fill | `--dsx-color-surface-raised` | Color | `fills` |
 | Header | stroke | `--dsx-color-outline-variant` | Color | `strokes` |
 | Content | padding | `--dsx-space-md` | Spacing | `padding` |
@@ -356,10 +356,10 @@ The package does not yet publish a Penpot asset for FloatingPanel. Recipe is vis
 
 | State | Shell shadow | Header cursor | Close fill | Handle opacity |
 |---|---|---|---|---|
-| `default` | `--dsx-shadow-md` | `grab` | `transparent` | `--dsx-opacity-muted` |
-| `dragging` | `--dsx-shadow-xl` | `grabbing` | `transparent` | `1` |
-| `close-hover` | `--dsx-shadow-md` | `grab` | `--dsx-effect-hover-layer` | `--dsx-opacity-muted` |
-| `handle-hover` | `--dsx-shadow-md` | `grab` | `transparent` | `1` |
+| `default` | `--dsx-shadow-elevation-2` | `grab` | `transparent` | `--dsx-opacity-muted` |
+| `dragging` | `--dsx-shadow-elevation-5` | `grabbing` | `transparent` | `1` |
+| `close-hover` | `--dsx-shadow-elevation-2` | `grab` | `--dsx-effect-hover-layer` | `--dsx-opacity-muted` |
+| `handle-hover` | `--dsx-shadow-elevation-2` | `grab` | `transparent` | `1` |
 
 ### Variant model
 

package/dist/docs/components/icon-button.md

@@ -64,7 +64,7 @@ Rules:
 | `data-high-contrast` | `true` | `.dsx-icon-button:where([data-variant='outline'])[data-high-contrast='true']` etc. (variant-specific HC overrides) | `icon-button.css` |
 | `data-loading` | `true` | `.dsx-icon-button[data-loading='true']` | `icon-button.css` |
 | `data-disabled` | `true` | `.dsx-icon-button[data-disabled='true']` | `icon-button.css` |
-| `aria-pressed` | `true` | n/a (CSS does not target this attribute) | n/a |
+| `aria-pressed` | `true` | pressed overlay for `primary`/`secondary` (same layers as Button) | n/a |
 
 **Internal classes** (implementation detail, not public slots):
 
@@ -127,6 +127,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Text (destructive) | `var(--dsx-color-on-error)` | Destructive icon. |
 | Border (destructive) | `var(--dsx-color-error)` | Destructive edge. |
 | Background (destructive hover) | `linear-gradient(var(--dsx-effect-hover-secondary), var(--dsx-effect-hover-secondary)), var(--dsx-color-error)` | Destructive hover overlay. |
+| Background (primary pressed) | `linear-gradient(var(--dsx-effect-pressed-primary), var(--dsx-effect-pressed-primary)), var(--dsx-color-accent-track)` | Primary pressed overlay (Button parity). |
+| Background (secondary pressed) | `linear-gradient(var(--dsx-effect-pressed-layer), var(--dsx-effect-pressed-layer)), var(--dsx-color-secondary)` | Secondary pressed overlay (Button parity). |
+| Box shadow (halo) | `var(--dsx-shadow-accent-ring)` | Resting halo on every variant (`data-halo`), locked 2026-09-22 — same model as Button. |
 | Background (destructive HC) | `var(--dsx-color-error)` | High-contrast destructive fill. |
 | Border (destructive HC) | `var(--dsx-color-high-contrast-border)` | High-contrast destructive edge. |
 | Focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus ring on `:focus-visible`. |

package/dist/docs/components/item.md

@@ -25,7 +25,7 @@ A generic list-row surface for settings, notifications, or selectable summaries.
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Item` (root) | `<div>` (or `Slot` host) | Root + class | The row surface. Writes `dsx-item`, `data-variant`, `data-size`, and (when `interactive={true}`) `data-interactive="true"`. |
+| `Item` (root) | `<div>` (or `Slot` host) | Root + class | The row surface. Writes `dsx-item`, a size modifier, a non-default variant modifier, and (when `interactive={true}`) `data-interactive="true"`. |
 | `Item.Media` | `<div>` (or `Slot` host) | Slot class | Leading visual slot (icon, avatar, image). Writes `dsx-item__media`. |
 | `Item.Content` | `<div>` (or `Slot` host) | Slot class | Text + metadata wrapper. Writes `dsx-item__content`. |
 | `Item.Title` | `<h4>` (or `Slot` host) | Slot class | Row title. Writes `dsx-item__title`. |
@@ -40,8 +40,8 @@ The root is a flex row with `gap: var(--dsx-space-md)`. `Item.Media`, `Item.Cont
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Surface treatment; writes `data-variant`. | no |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Minimum height; writes `data-size`. `xs` and `sm` are row-density; `md` and `lg` are content-density. | no |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Surface treatment through modifier classes. | no |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Minimum height and vertical padding through modifier classes. Padding increases from space-xs to space-sm, space-md, and space-lg. | no |
 | `interactive` | `boolean` | `false` | no | When `true`, adds `cursor: pointer` to the root; writes `data-interactive="true"`. The component does not add hover or focus styles; consumers that want a fully interactive row should wrap with their own Button or `asChild` onto a button. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-item`. | no |
@@ -57,19 +57,19 @@ Each slot also accepts the standard HTML attributes for its host element.
 
 Rules:
 
-- The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. The contract calls for `data-variant`, `data-size`, and `data-interactive` only.
-- `data-interactive` is emitted only when `interactive={true}`. The CSS does not currently hook it, but the prop is part of the public contract.
+- The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. Variant and size use classes; `data-interactive` is the only owned state attribute.
+- `data-interactive` is emitted only when `interactive={true}`. The CSS hooks it to apply the pointer cursor.
 
 ## CSS class contract
 
 **Root class:** `dsx-item`
 
-**Modifier classes** (driven by `data-*` attributes written by the component):
+**Modifier classes** (written directly by the component):
 
-| Attribute | Allowed values | Class | CSS file |
+| Prop | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `default`, `outline`, `muted` | `.dsx-item[data-variant='outline']`, `.dsx-item[data-variant='muted']` | `item.css` |
-| `data-size` | `xs`, `sm`, `md`, `lg` | `.dsx-item[data-size='xs']`, `.dsx-item[data-size='sm']`, `.dsx-item[data-size='md']`, `.dsx-item[data-size='lg']` | `item.css` |
+| `variant` | `default`, `outline`, `muted` | `.dsx-item--outline`, `.dsx-item--muted` | `item.css` |
+| `size` | `xs`, `sm`, `md`, `lg` | `.dsx-item--xs`, `.dsx-item--sm`, `.dsx-item--md`, `.dsx-item--lg` | `item.css` |
 | `data-interactive` | `true` | `.dsx-item[data-interactive='true']` | `item.css` |
 
 **Slot classes:**
@@ -87,6 +87,8 @@ Rules:
 
 - The component does not write `@media` rules. `size` and `variant` are single-value only.
 
+- Content can shrink and long labels wrap. Root and trailing actions wrap intrinsically when their combined width exceeds the row, keeping commands reachable without a breakpoint.
+
 **Reduced motion:**
 
 - The component is static. No motion is applied.
@@ -109,7 +111,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Interactive cursor | `pointer` | Pointer cursor when `interactive={true}` |
 | Min-height (xs) | `var(--dsx-size-lg)` | xs row min-height |
 | Min-height (sm) | `var(--dsx-size-xl)` | sm row min-height |
-| Min-height (md, lg) | `var(--dsx-size-2xl)` | md/lg row min-height |
+| Min-height (md) | `var(--dsx-size-2xl)` | md row min-height |
+| Min-height (lg) | `var(--dsx-size-3xl)` | lg row min-height |
 | Media dimensions | `var(--dsx-size-xl)` | Media slot dimensions |
 | Content display | `grid` | Title + description layout |
 | Content gap | `var(--dsx-space-xs)` | Space between Title and Description |
@@ -161,11 +164,11 @@ The component is static.
 
 **Variant story:**
 
-- Renders three items with `variant="default"`, `variant="outline"`, and `variant="muted"`. Asserts the matching `data-variant` attribute.
+- Renders three items with `variant="default"`, `variant="outline"`, and `variant="muted"`. Asserts the matching non-default variant class.
 
 **Size story:**
 
-- Renders four items with `size="xs"`, `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute.
+- Renders four items with `size="xs"`, `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching size class and measures distinct rendered heights for identical content.
 
 **State story:**
 
@@ -207,10 +210,12 @@ The component is static.
 
 **State boundaries:**
 
-- Owned by Item: the `data-variant`, `data-size`, and `data-interactive` attributes, the flex row layout, and the `dsx-item__*` slot classes.
+- Owned by Item: the variant/size classes and `data-interactive` attribute, the flex row layout, and the `dsx-item__*` slot classes.
 - Owned by the consumer: the row content, the interactive behavior, the surrounding list semantics, and the heading level on `Item.Title`.
 
 **Boundary rules:**
 
 - App-owned data: the row content, the action handlers, the selection state, and the surrounding list semantics.
 - DS-owned visuals: token bindings, slot classes, variant surfaces, and the size min-height.
+
+The playground size comparison uses identical content and aligns row starts, avoiding flex stretch that would make all sizes inherit the largest sibling height. Both the variant gallery and the live example show the density scale.

package/dist/docs/components/marquee.md

@@ -24,7 +24,7 @@ A horizontally scrolling content strip that animates a duplicated child track ac
 |---|---|---|---|
 | `Marquee` (root) | `<div>` | DS primitive + class | Wrapper that owns the `--dsx-marquee-duration`, `--dsx-marquee-direction`, and `--dsx-marquee-edge-fade-width` CSS variables plus the `data-pause-on-hover` and optional `data-edge-fade` attributes. |
 | internal track | `<div class="dsx-marquee__track">` | internal layout | Flex row that runs the `dsx-marquee-scroll` keyframe. |
-| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"` clone. The duplication is what makes the loop seamless. |
+| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"`, inert clone. The duplication is what makes the loop seamless. |
 
 The track and content nodes are internal layout, not public slots. The two `dsx-marquee__content` rows are siblings inside the track.
 
@@ -130,7 +130,7 @@ Rules:
 
 **Focus:**
 
-- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the `aria-hidden="true"` clone handles the announcement side.
+- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the duplicate is both `aria-hidden` and inert, so it cannot add duplicate keyboard stops. Focus within the original pauses animation regardless of `pauseOnHover`.
 
 **Reduced motion:**
 

package/dist/docs/components/menu.md

@@ -166,7 +166,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 | Content transform origin | `var(--radix-dropdown-menu-content-transform-origin)` | Radix-provided anchor (not a token). |
 | Item gap | `var(--dsx-space-sm)` | Gap between item content. |
 | Item padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Inner gutter. |
-| Item radius | `var(--dsx-rounded-sm)` | Rounded highlight surface. |
+| Item radius | `0` (square); menu first/last/only-child edge rules restore frame-concentric corners | Stacked items read as one joined block instead of floating pills — checked washes, hover washes, and focus rings share one flush geometry. |
 | Item typography | `var(--dsx-typography-body-medium-*` | Body ramp. |
 | Item color | `var(--dsx-color-on-surface)` | Resting text. |
 | Item highlight background | `var(--dsx-effect-hover-ghost)` | Hover / keyboard-focus highlight. |
@@ -175,6 +175,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 | Separator margin | `var(--dsx-space-xs)` calc(-1) | Inset margin. |
 | Separator background | `var(--dsx-color-outline-variant)` | Divider color. |
 | Overlay z-index | `calc(var(--dsx-z-index-dropdown) - 1)` | Just under the content. |
+| Nested content z-index | `calc(var(--dsx-z-index-modal, 90) + 2)` | Menu-tier content nested inside a modal-tier host (carries `dsx-menu__nested`). |
 | Animation duration | `var(--dsx-motion-duration-fast)` | Open / close keyframes. |
 | Animation easing (in) | `var(--dsx-motion-easing-emphasized)` | Open easing. |
 | Animation easing (out) | `var(--dsx-motion-easing-in)` | Close easing. |
@@ -187,6 +188,7 @@ Rules:
 - `menu.css` no longer declares `background`, `border`, `border-radius`, `padding`, `min-width`, or `box-shadow` on `.dsx-menu`/`.dsx-menu__content`. Those properties are owned solely by the public surface CSS (`dropdown-menu.css`, `context-menu.css`, `menubar.css`), which already agreed on the same recipe (`--dsx-color-panel-translucent`, `--dsx-rounded-lg`, `--dsx-size-menu-min-width`, `--dsx-shadow-elevation-3`-via-`baseMenu.css`). Previously `menu.css` was imported last in `components.css` and, at equal selector specificity, silently overrode that recipe with a stale one (`surface-raised`, `rounded-md`, hard-coded `8rem`, `shadow-md`/elevation-2) for `DropdownMenu` and `ContextMenu` only — `Menubar` was unaffected because `MenubarContent` never carried the `dsx-menu` class, which is why the three surfaces looked subtly different despite sharing a spec.
 - The Radix CSS variables (`--radix-dropdown-menu-content-available-height`, `--radix-dropdown-menu-content-transform-origin`) are provided by Radix at runtime and are not design tokens. They are the boundary between the Radix positioning layer and the package's visual layer; the spec keeps them explicit so consumers do not treat them as themable.
 - Item hover, focus, selected, and disabled states that are shared across the menu family (DropdownMenu, ContextMenu, Menubar, NavigationMenu trigger/link/viewport) live in `_internal/baseMenu.css` rather than `menu.css`. The public menu surfaces import `baseMenu.css` to inherit those rules.
+- **Nested floating tier (shared layering contract).** Menu-tier content (`Select`, `Combobox`, `DropdownMenu`/`ContextMenu`/`Menubar` via `MenuContent`) paints at the dropdown tier (50); modal-tier hosts (`Popover.Content` at `modal + 1`, `Dialog.Content` at `modal` — both body-portaled, with Radix copying the content `z-index` onto its wrapper) sit above it, so a menu opened inside one of those hosts paints behind its own host. Hosts provide `_internal/floatingLayer` `FloatingLayerHostContext` from their content; menu contents consume it and add `dsx-menu__nested`, resolved to `modal + 2` by `_internal/baseMenu.css`. A flat bump of `--dsx-z-index-dropdown` is rejected: a nested menu must clear 91 while a standalone page menu must stay below the modal overlay (80) so an open Dialog still masks page content — one static value cannot do both. Standalone menus never carry the class. The signal is provided at content level (not root) so `Combobox` — itself a `Popover` — never self-escalates. `AlertDialog.Content` inherits the host behavior through `Dialog.Content`. `Drawer` (vaul, own overlay tier) is out of scope.
 
 ## Motion contract
 
@@ -272,6 +274,7 @@ The `test_path` is `packages/d4gger-design-system/src/test/components/menu-migra
 - `_internal/usePrefersReducedMotion`: gates the framer-motion preset.
 - `framer-motion` (re-exported from `@d4gger/design-system/motion`): `motion` and `AnimatePresence` for the content animation.
 - `_internal/baseMenu.css`: shared item hover, focus, selected, and disabled rules. The public menu surfaces import `baseMenu.css` to inherit those rules; the `Menu` CSS file does not import it directly.
+- `_internal/floatingLayer`: `FloatingLayerHostContext` / `useFloatingLayerHost` for the nested floating tier. `MenuContent` consumes it and adds `dsx-menu__nested` when rendered inside a modal-tier host (see the Token mapping contract above).
 
 **Used by:**
 

package/dist/docs/components/metric.md

@@ -29,7 +29,7 @@ A surface-neutral metric anatomy for labels, tabular values, and semantic change
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Metric scale inherited by all slots. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Value typography scale inherited through context; label and delta retain their supporting type ramps. | no |
 | `asChild` | `boolean` | `false` | no | Uses the consumer host for the root. | no |
 | `className` | `string` | `undefined` | no | Appended root class. | no |
 
@@ -40,6 +40,7 @@ A surface-neutral metric anatomy for labels, tabular values, and semantic change
 - Root: `dsx-metric`; slots: `dsx-metric__label`, `dsx-metric__value`, `dsx-metric__delta`.
 - Root writes `data-size="sm|md|lg"`; Delta writes `data-tone="positive|negative|neutral"`.
 - The component is static and breakpoint-agnostic.
+- The root shrinks within the available width and wraps unbroken values or identifiers. Delta content can wrap without creating horizontal overflow. Consumers retain responsibility for meaningful number formatting.
 
 ## Token mapping
 
@@ -68,3 +69,5 @@ Show a default Metric, all three sizes, all three delta tones, a full compositio
 ## Wiring notes
 
 Metric owns anatomy, typography, tabular numerals, and delta presentation. Consumers own values, trend calculations, localization, and the surrounding Card or layout. `StatCard` composes this anatomy while preserving its legacy public contract.
+
+Playground appearance follows the global theme switcher. Accent demonstrations inherit that appearance; no forced light/dark example overrides it.

package/dist/docs/components/pagination.md

@@ -5,7 +5,8 @@ category: Components
 archetype: composite
 depends_on:
   - "@radix-ui/react-slot (powers `asChild` on the root, list, item, link, and ellipsis slots)"
-  - Icon (the `chevron-left` / `chevron-right` glyphs on `Previous` / `Next`; the `dots-horizontal` glyph on `Ellipsis`)
+  - Icon (the `chevron-left` / `chevron-right` glyphs on `Previous` / `Next`; the `chevrons-left` / `chevrons-right` glyphs on `First` / `Last`; the `dots-horizontal` glyph on `Ellipsis`)
+  - Select (powers `Pagination.PageSize`; the option list rides the shared menu tier)
 ---
 
 # Pagination
@@ -14,11 +15,11 @@ depends_on:
 
 ## Purpose
 
-A page-based dataset navigation surface that exposes the previous, next, and numbered links, an ellipsis for truncated ranges, an info summary, and a page-size selector. The DS `Pagination` is a flat composite (no Radix primitive), built directly on HTML elements plus the `Slot` helper for `asChild`. It is the canonical surface for page-based datasets; the roster lists `Button` as a composed-from surface because the page links render as button or anchor elements.
+A page-based dataset navigation surface that exposes the previous, next, and numbered links, an ellipsis for truncated ranges, an info summary, a static page-status indicator, and a page-size selector. The DS `Pagination` is a flat composite (no Radix primitive), built directly on HTML elements plus the `Slot` helper for `asChild`. It is the canonical surface for page-based datasets; the roster lists `Button` as a composed-from surface because the page links render as button or anchor elements.
 
 ## 2.6 contract
 
-`PaginationBar` uses seven page slots whenever more than seven pages exist, including expanded boundary neighbours so first, middle, and final windows have equal width. `messages` localizes range formatting, zero results, previous/next labels, and page-size options. English remains default; a Russian formatter such as `(start, end, total) => `${start}–${end} из ${total}`` produces `1–8 из 47`.
+`PaginationBar` uses seven page slots whenever more than seven pages exist, including expanded boundary neighbours so first, middle, and final windows have equal width. `messages` localizes range formatting, zero results, previous/next/first/last labels, page-size options, and the page-input `Page` / `of M` text. English remains default; a Russian formatter such as `(start, end, total) => `${start}–${end} из ${total}`` produces `1–8 из 47`. First/Last links and the page-jump input are opt-in (`showFirstLast`, `showPageInput`, both default `false`) so existing bars render unchanged.
 
 ## Anatomy & slots
 
@@ -34,11 +35,15 @@ A page-based dataset navigation surface that exposes the previous, next, and num
 | `Pagination.Link` | `<a>` (when `href` is set and not disabled), `<button>` (otherwise), or `Slot` child when `asChild` | `dsx-pagination__link` + `--active` modifier (when active) + `--disabled` modifier (when disabled) + optional `data-disabled` + `aria-current="page"` (when active) + `aria-disabled` (when disabled) | A page link. |
 | `Pagination.Previous` | wraps `Pagination.Link` | `dsx-pagination__link--edge` + `chevron-left` icon + default `aria-label="Previous page"` + default text `Previous` | The previous-page link. |
 | `Pagination.Next` | wraps `Pagination.Link` | `dsx-pagination__link--edge` + `chevron-right` icon + default `aria-label="Next page"` + default text `Next` | The next-page link. |
+| `Pagination.First` | wraps `Pagination.Link` | `dsx-pagination__link--edge` + `chevrons-left` icon + default `aria-label="First page"` + default text `First` | The first-page link (round-2 gap fill). Opt-in via `showFirstLast` on `PaginationBar` / `DataTablePagination`. |
+| `Pagination.Last` | wraps `Pagination.Link` | `dsx-pagination__link--edge` + `chevrons-right` icon + default `aria-label="Last page"` + default text `Last` | The last-page link (round-2 gap fill). Opt-in via `showFirstLast` on `PaginationBar` / `DataTablePagination`. |
+| `Pagination.PageInput` | `<span>` wrapping a native `<input type="number">` | `dsx-pagination__page-input` + `aria-label="Page number, page N of M"` on the input + visible `Page` / `of M` text | Direct page jump (round-2 gap fill: "Page N of M"). Opt-in via `showPageInput` on `PaginationBar` / `DataTablePagination`. Commits on Enter or blur, clamped to `1..totalPages`. |
 | `Pagination.Ellipsis` | `<span>` (or `Slot` child when `asChild`) | `dsx-pagination__ellipsis` + `aria-hidden="true"` + `dots-horizontal` icon | A non-interactive truncation marker. |
 | `Pagination.Info` | `<span>` | `dsx-pagination__info` | A summary of the visible range (for example `Showing 21–40 of 137`). |
-| `Pagination.PageSize` | `<select>` | `dsx-pagination__page-size` | The page-size selector with the standard `[20, 50, 100]` options. |
+| `Pagination.Status` | `<span role="status">` | `dsx-pagination__status` | A static page position (for example `Page 1 of 2`). The non-interactive counterpart to `PageInput`: consumers show Status or the Info range, never both (same dedup rule `DataTablePagination` applies in dense mode). `formatStatus` localizes the text; English default. |
+| `Pagination.PageSize` | shared `Select` | `dsx-pagination__page-size` on the trigger | The page-size selector with the standard `[10, 25, 50, 100]` options. The open list is Select content, so it paints in the design language and inherits the shared floating tier. |
 
-The roster's `Parent / Slots` column lists `Pagination.Root`, `Pagination.List`, `Pagination.Item`, `Pagination.Link`, `Pagination.Previous`, `Pagination.Next`, `Pagination.Ellipsis`, `Pagination.Info`, `Pagination.PageSize`. The source exports `Pagination` as the root (no `Object.assign` accessor for `.Root`) and the rest as named exports; `Pagination.Content` is an alias of `Pagination.List`. The spec records the runtime shape; the roster's `Pagination.Root` style is the would-be public API if a `Root` accessor were added.
+The roster's `Parent / Slots` column lists `Pagination.Root`, `Pagination.List`, `Pagination.Item`, `Pagination.Link`, `Pagination.Previous`, `Pagination.Next`, `Pagination.First`, `Pagination.Last`, `Pagination.Ellipsis`, `Pagination.Info`, `Pagination.Status`, `Pagination.PageInput`, `Pagination.PageSize`. The source exports `Pagination` as the root (no `Object.assign` accessor for `.Root`) and the rest as named exports; `Pagination.Content` is an alias of `Pagination.List`. The spec records the runtime shape; the roster's `Pagination.Root` style is the would-be public API if a `Root` accessor were added.
 
 ## Props contract
 
@@ -85,6 +90,32 @@ The roster's `Parent / Slots` column lists `Pagination.Root`, `Pagination.List`,
 | `className` | `string` | `undefined` | no | Extra classes appended to the edge modifier. | no |
 | `children` | `React.ReactNode` | `'Previous'` / `'Next'` | no | The text shown next to the chevron. | no |
 
+### `Pagination.First` and `Pagination.Last`
+
+Same surface as `Previous` / `Next` (thin wrappers over `Link`), with defaults `aria-label="First page"` / `"Last page"` and children `"First"` / `"Last"`.
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `active` | `boolean` | `false` | no | Forwarded to the underlying `Pagination.Link`. | no |
+| `disabled` | `boolean` | `false` | no | Forwarded to the underlying `Pagination.Link`. | no |
+| `asChild` | `boolean` | `false` | no | Forwarded to the underlying `Pagination.Link`. | no |
+| `href` | `string` | `undefined` | no | Forwarded to the underlying `Pagination.Link`. | no |
+| `aria-label` | `string` | `'First page'` / `'Last page'` | no | Landmark label. The default is applied when the consumer does not pass one. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the edge modifier. | no |
+| `children` | `React.ReactNode` | `'First'` / `'Last'` | no | The text shown next to the chevron. | no |
+
+### `Pagination.PageInput`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `page` | `number` | (required) | yes | Current 1-based page. The input shows this value until the consumer types a draft. | no |
+| `totalPages` | `number` | (required) | yes | Total page count. Clamps commits to `1..max(1, totalPages)` and renders the `of M` text. | no |
+| `onPageChange` | `(page: number) => void` | (required) | yes | Called with the clamped page on Enter or blur. Non-numeric drafts are discarded. | no |
+| `pageLabel` | `React.ReactNode` | `'Page'` | no | Visible label before the input. | no |
+| `formatOf` | `(totalPages: number) => React.ReactNode` | `` (t) => `of ${t}` `` | no | Renders the visible `of M` text after the input. | no |
+| `aria-label` | `string` | `'Page number, page N of M'` | no | Accessible name on the input. The default is applied when the consumer does not pass one. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pagination__page-input`. | no |
+
 ### `Pagination.Ellipsis`
 
 | Prop | Type | Default | Required | Description | Responsive |
@@ -101,19 +132,29 @@ The roster's `Parent / Slots` column lists `Pagination.Root`, `Pagination.List`,
 | `offset` | `number` | (required) | yes | Zero-based offset of the first record on the current page. | no |
 | `limit` | `number` | (required) | yes | Page size. The end of the range is `min(offset + limit, totalCount)`. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pagination__info`. | no |
+| `formatRange` | `(start: number, end: number, totalCount: number) => React.ReactNode` | `` (s, e, t) => `Showing ${s}–${e} of ${t}` `` | no | Renders the visible range text. | no |
+
+### `Pagination.Status`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `page` | `number` | (required) | yes | Current 1-based page. Clamped for display to `1..max(1, totalPages)`. | no |
+| `totalPages` | `number` | (required) | yes | Total page count. | no |
+| `formatStatus` | `(page: number, totalPages: number) => React.ReactNode` | `` (p, t) => `Page ${p} of ${t}` `` | no | Renders the visible status text. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pagination__status`. | no |
 
 ### `Pagination.PageSize`
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `value` | `number` | (required) | yes | Current page size. | no |
-| `options` | `number[]` | `[20, 50, 100]` | no | Available page-size options. | no |
-| `onChange` | `(limit: number) => void` | (required) | yes | Called with the parsed numeric value when the consumer changes the select. | no |
+| `options` | `number[]` | `[10, 25, 50, 100]` | no | Available page-size options. | no |
+| `onChange` | `(limit: number) => void` | (required) | yes | Called with the parsed numeric value when the consumer picks an option. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pagination__page-size`. | no |
 
 Rules:
 
-- The root, list, item, link, and ellipsis slots all run through `extractProps` with the matching prop def bag. `Previous` and `Next` are thin wrappers over `Link` and inherit the prop surface.
+- The root, list, item, link, and ellipsis slots all run through `extractProps` with the matching prop def bag. `Previous`, `Next`, `First`, and `Last` are thin wrappers over `Link` and inherit the prop surface.
 - `Link` is polymorphic: it renders `<a>` when `href` is set and the link is not `disabled`, otherwise `<button type="button" disabled>` when `disabled`, otherwise `Slot` when `asChild` is set. The `aria-current`, `aria-disabled`, and `data-disabled` attributes are written in every branch.
 
 ## CSS class contract
@@ -138,8 +179,11 @@ Rules:
 | `Pagination.Link` (active) | `dsx-pagination__link--active` | `pagination.css` |
 | `Pagination.Link` (disabled) | `dsx-pagination__link--disabled` | `pagination.css` |
 | `Pagination.Previous` / `Pagination.Next` | `dsx-pagination__link` + `dsx-pagination__link--edge` | `pagination.css` |
+| `Pagination.First` / `Pagination.Last` | `dsx-pagination__link` + `dsx-pagination__link--edge` | `pagination.css` |
+| `Pagination.PageInput` | `dsx-pagination__page-input` | `pagination.css` |
 | `Pagination.Ellipsis` | `dsx-pagination__ellipsis` | `pagination.css` |
 | `Pagination.Info` | `dsx-pagination__info` | `pagination.css` |
+| `Pagination.Status` | `dsx-pagination__status` | `pagination.css` |
 | `Pagination.PageSize` | `dsx-pagination__page-size` | `pagination.css` |
 
 **Responsive behavior:**
@@ -170,7 +214,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Link typography | `var(--dsx-typography-label-large-*)` | Font family, size, weight. |
 | Link hover background | `var(--dsx-effect-hover-ghost)` | Hover surface. |
 | Link focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` ring. |
-| Link active background | `var(--dsx-color-accent-indicator)` | Active fill. |
+| Link active background | `var(--dsx-color-accent-track)` | Active fill (fill step, vivid in both themes — the text-step `accent-indicator` renders near-black in light theme). |
 | Link active color | `var(--dsx-color-on-primary)` | Active text. |
 | Link active weight | `var(--dsx-typography-label-large-font-weight, 600)` | Active weight. |
 | Link edge color | `var(--dsx-color-on-surface-variant)` | Edge variant text. |
@@ -179,12 +223,23 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Ellipsis color | `var(--dsx-color-on-surface-variant)` | Ellipsis text. |
 | Info color | `var(--dsx-color-on-surface-variant)` | Info text. |
 | Info typography | `var(--dsx-typography-body-medium-*)` | Info font family and size. |
-| PageSize height | `var(--dsx-size-lg)` | Select height. |
+| PageSize height | `var(--dsx-size-lg)` | Trigger height. |
+| PageSize min-width | `8rem` | Fits the `N per page` label. |
 | PageSize padding | `0 var(--dsx-space-sm)` | Internal gutter. |
-| PageSize border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Select edge. |
-| PageSize background | `var(--dsx-color-surface)` | Select surface. |
-| PageSize typography | `var(--dsx-typography-label-large-*)` | Select font family and size. |
+| PageSize border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Trigger edge. |
+| PageSize typography | `var(--dsx-typography-label-large-*)` | Trigger font family and size. |
 | PageSize focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` ring. |
+| PageSize option list | (shared `Select` tokens) | The open list rides `select.css` and the shared menu tier. |
+| PageInput text | `var(--dsx-color-on-surface-variant)` | `Page` / `of M` label text. |
+| PageInput typography | `var(--dsx-typography-body-medium-*)` | Label font family and size. |
+| PageInput input width | `var(--dsx-size-3xl)` | Fixed input width for 2–3 digit pages. |
+| PageInput input height | `var(--dsx-size-lg)` | Input height matching link touch targets. |
+| PageInput input padding | `0 var(--dsx-space-sm)` | Internal gutter. |
+| PageInput input border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Input edge. |
+| PageInput input radius | `var(--dsx-rounded-md)` | Corner roundness. |
+| PageInput input background | `var(--dsx-color-surface)` | Input surface. |
+| PageInput input color | `var(--dsx-color-on-surface)` | Input text. |
+| PageInput focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` ring. |
 | Motion duration | `var(--dsx-motion-duration-fast, 150ms)` | Link transitions. |
 | Motion easing | `var(--dsx-motion-easing-standard, ease)` | Link easing. |
 
@@ -210,9 +265,12 @@ Rules:
 - `Pagination.List` is a `<ul>`; `Pagination.Item` is a `<li>`.
 - `Pagination.Link` is an `<a>` (or a `<button disabled>` when `disabled` and no `href`, or a `Slot` child when `asChild`). The active link carries `aria-current="page"`. The disabled link carries `aria-disabled`.
 - `Pagination.Previous` and `Pagination.Next` carry an `aria-label` (default `Previous page` / `Next page`).
+- `Pagination.First` and `Pagination.Last` carry an `aria-label` (default `First page` / `Last page`).
+- `Pagination.PageInput` is a native number `<input>` with a default `aria-label="Page number, page N of M"`. The visible `Page` / `of M` text is presentational; the input stays operable by keyboard (type, Enter to commit, blur to commit).
 - `Pagination.Ellipsis` is a non-interactive `<span aria-hidden="true">`.
 - `Pagination.Info` is a non-interactive `<span>`.
-- `Pagination.PageSize` is a native `<select>` with the standard browser semantics.
+- `Pagination.Status` is a non-interactive `<span role="status">` announcing the current page position.
+- `Pagination.PageSize` is the shared `Select` with the standard option semantics.
 
 **Keyboard:**
 
@@ -221,11 +279,11 @@ Rules:
 | `Tab` | Moves focus to or from the pagination landmark. |
 | `Enter` (focused link) | Activates the link. |
 | `Space` (focused link) | Activates the link. |
-| `Tab` (focused `PageSize`) | Moves through the page-size options. |
+| `Tab` (focused `PageSize`) | Opens the option list; arrows move, Enter picks. |
 
 **Focus:**
 
-- The CSS file paints a `var(--dsx-shadow-focus-ring)` ring on `:focus-visible` for the link and the page-size select. The ring stays visible on dark and light surfaces.
+- The CSS file paints a `var(--dsx-shadow-focus-ring)` ring on `:focus-visible` for the link and the page-size trigger. The ring stays visible on dark and light surfaces.
 
 **Reduced motion:**
 
@@ -239,6 +297,11 @@ Rules:
 
 - The `Pagination` landmark has a default `aria-label="Pagination"`. The edge links have default `aria-label` values (`Previous page`, `Next page`). Override the labels when the landmark or edge needs product-specific copy.
 
+**Responsive (narrow shells):**
+
+- `PaginationBar` wraps into stacked rows (info → controls) with no width breakpoints; the pager list wraps its page links the same way. Verified at 320px: zero overflowing descendants, desktop single-row layout unchanged. Narrow stacking is component behavior, not composition guidance — screens arrange the bar, never its internals.
+- Opt-in `dense` mode (`PaginationBar`, mirrored on `DataTablePagination`): info summary + pager only. The page-size block is omitted, and on `DataTablePagination` the "Page X of Y" status (which duplicates the info range) is omitted with it. Default behavior is unchanged — narrow shells opt in explicitly; the component never decides by width, so no breakpoint, container query, or resize observer is involved. Narrow shells that let users choose page size keep the default mode.
+
 ## Playground demo spec
 
 **Default story:**
@@ -256,6 +319,12 @@ Rules:
 **Composition story:**
 
 - Renders a `Pagination.List` with `Previous`, an `Ellipsis`, numbered links, another `Ellipsis`, and `Next`. Asserts the list, the ellipsis (with `aria-hidden="true"`), and the edge links all render with their classes.
+- Renders `First` and `Last` edge links with default `aria-label="First page"` / `"Last page"` and the `dsx-pagination__link--edge` modifier.
+- Renders a `PageInput` with `page` / `totalPages`; asserts the input carries the page-number label and commits a clamped page on Enter.
+
+**PaginationBar story:**
+
+- Renders `PaginationBar` with `showFirstLast` and `showPageInput`; asserts First/Last links and the page-jump input render alongside info, page-size, and numbered links. Without the flags the bar renders info + page-size + Previous/numbered/Next only (default, unchanged). With `dense`, asserts the page-size block is absent and info + pager remain.
 
 **Token story:**
 
@@ -277,11 +346,13 @@ Rules:
 
 - `@radix-ui/react-slot`: enables `asChild` on the root, list, item, link, and ellipsis slots.
 - `_internal/helpers/extractProps`: turns the prop defs into merged class + style output.
-- `Icon`: the `chevron-left` / `chevron-right` glyphs on `Previous` / `Next`; the `dots-horizontal` glyph on `Ellipsis`.
+- `Icon`: the `chevron-left` / `chevron-right` glyphs on `Previous` / `Next`; the `chevrons-left` / `chevrons-right` glyphs on `First` / `Last`; the `dots-horizontal` glyph on `Ellipsis`.
+- `Select`: powers the `PageSize` trigger and option list.
 
 **Used by:**
 
 - App-level paginated lists. The roster lists `DataTable` as a consumer because the table wraps `Pagination` for its bottom toolbar.
+- `DataTable` positions its pagination footer via `paginationPosition` (`top` / `bottom` / `both`, default `bottom`) and justifies it via `paginationAlign` (`start` / `center` / `end`; unset keeps info-left/controls-right). `DataTable` passes `paginationFirstLast` / `paginationPageInput` through to its internal `DataTablePagination` (`showFirstLast` / `showPageInput`). Placement is a `DataTable`-side concern; this spec owns the link/ellipsis/info/page-size/page-input surface only.
 
 **State boundaries:**
 

package/dist/docs/components/pills.md

@@ -15,7 +15,7 @@ depends_on:
 
 ## Purpose
 
-A compact cluster of selectable or status pills rendered as a horizontal flex list. Use Pills for filter chips, tag clusters, segmented status indicators, and removable tags. For a single label surface, use `Badge`. For mutually exclusive options rendered as a segmented control, use `SegmentedControl` or `ToggleGroup`.
+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.
 
 ## Anatomy & slots
 

package/dist/docs/components/popover.md

@@ -237,6 +237,7 @@ Rules:
 - `@radix-ui/react-slot`: enables `asChild` on the positioner, arrow, and content.
 - `framer-motion`: provides the `motion.div` for mount and exit. The reduced motion preset is read from `usePrefersReducedMotion`.
 - `baseDialog.css`: the shared overlay surface and theme-mirror utilities.
+- `_internal/floatingLayer`: `Popover.Content` provides `FloatingLayerHostContext` to its body, so menu-tier content (`Select`, `Combobox`, `DropdownMenu`) nested inside the popover escalates via `dsx-menu__nested` (see the shared nested floating tier contract in `menu.md`).
 
 **Used by:**
 
@@ -247,6 +248,7 @@ Rules:
 **State boundaries:**
 
 - Owned by `Popover`: open state when uncontrolled, presence context, portal theme mirroring, motion preset, and the auto-wired `aria-labelledby` / `aria-describedby`.
+- Owned by `Popover`: the nested-host signal — `Popover.Content` marks its body as a modal-tier host for the shared nested floating tier contract.
 - Owned by the consumer: the trigger label, the popover body, and the close behavior (via `Popover.Close` or `Escape`).
 
 **Boundary rules:**

package/dist/docs/components/prose.md

@@ -19,6 +19,10 @@ Read-side article typography with an approximately `68ch` measure and `1.65` rea
 
 Consumers preserve heading order, stable IDs, meaningful image alt text, captions, and table headers. Wide tables scroll horizontally rather than hiding data.
 
+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.
+
 ## Playground demo spec
 
-Render all supported semantic elements, sanitized HTML, a wide table at mobile width, and each exported authored-node renderer.
+Render all supported semantic elements, sanitized HTML, a wide table at mobile width, and authored blocks in the separate ArticleNodes stream.
+
+The live example is a coherent server-selection article with ordered headings, lists, blockquote, a working fragment link, inline/block code, a table with row/column headers, and an image with caption. ArticleNodes stays in the blocks stream.

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

@@ -30,7 +30,7 @@ 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 | Container size; selects one of the internal `sizeMap` values (`sm: 128`, `md: 192`, `lg: 256` px) and writes `data-size`. The CSS overrides the rendered SVG width and height with sizing tokens. | 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 |
 | `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 |
 | `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 |
@@ -43,7 +43,8 @@ No slots: flat export. The component renders a single `<div>` host element (or a
 Rules that apply to this row:
 
 - The component extends `Omit<ComponentPropsWithoutRef<'div'>, 'value'>` because `value` is redefined by the QR-specific prop. Native `<div>` attributes that are not prop def keys are forwarded.
-- `size` is wired through `extractProps` and writes both the modifier class and `data-size`. The runtime `sizeMap` (`sm: 128`, `md: 192`, `lg: 256`) is the actual SVG pixel size; the CSS further constrains the rendered SVG width and height to the `size-{xs|md|xl}` sizing tokens so the visual size matches the container.
+- The three size modifier selectors share the base SVG display and corner treatment; matrix dimensions remain runtime-owned.
+- `size` is wired through `extractProps` and writes both the modifier class and `data-size`. The runtime `sizeMap` (`sm: 128`, `md: 192`, `lg: 256`) is the actual SVG pixel size, painted verbatim through the adapter's own width/height attributes. The `dsx-size-{xs|md|xl}` sizing tokens are NOT applied to the QR matrix — a former revision constrained the SVG to those tokens (16/24/40px) and rendered unscannable codes; the override was removed and must not return.
 - `level`, `marginSize`, `fgColor`, and `bgColor` are NOT in the prop def bag; they are typed in the `QRCodeProps` interface and consumed in the render path. The prop def only declares `asChild` and `size`. The interface-level defaults (`'M'`, `0`, token fallbacks) are applied at the destructuring site, not via `extractProps`.
 - The component does not currently expose a `data-high-contrast` prop or write that attribute, even though `qr-code.css` has a high-contrast block. The CSS block is a hook for downstream apps; the runtime does not emit the attribute today (see Anomalies).
 
@@ -82,9 +83,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with runtime fal
 | Background | `var(--dsx-color-surface-raised)` | Container surface. |
 | Border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Edge. |
 | SVG border radius | `var(--dsx-rounded-sm)` | SVG corners. |
-| Size `sm` | `var(--dsx-size-xs)` | Rendered SVG width and height at the `sm` size. |
-| Size `md` | `var(--dsx-size-md)` | Rendered SVG width and height at the `md` size. |
-| Size `lg` | `var(--dsx-size-xl)` | Rendered SVG width and height at the `lg` size. |
+| Size `sm` | (runtime `128` px) | Painted SVG width and height at the `sm` size — no token. |
+| Size `md` | (runtime `192` px) | Painted SVG width and height at the `md` size — no token. |
+| Size `lg` | (runtime `256` px) | Painted SVG width and height at the `lg` size — no token. |
 | Module color (default) | `var(--dsx-color-on-surface)` (runtime fallback) | QR modules. |
 | Background color (default) | `var(--dsx-color-surface-raised)` (runtime fallback) | Quiet zone. |
 | High-contrast surface | `var(--dsx-color-surface-raised)` | High-contrast container. |
@@ -93,7 +94,7 @@ 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. The CSS overrides the visible width and height with the `size-{xs|md|xl}` sizing tokens. The mismatch between the runtime px and the CSS px means the adapter still draws a sharp matrix; the CSS only constrains the rendered size.
+- 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.
 
@@ -140,11 +141,11 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Default story:**
 
-- Renders `QRCode` with `value="https://d4gger.example"` and no other props. Asserts the root class is `dsx-qr-code`, the inner element is an `svg`, the `data-size` attribute is `md`, and the SVG width and height resolve to `var(--dsx-size-md)`.
+- Renders `QRCode` with `value="https://d4gger.example"` and no other props. Asserts the root class is `dsx-qr-code`, the inner element is an `svg`, the `data-size` attribute is `md`, and the SVG width and height attributes are `192`.
 
 **Variant story** (one per size):
 
-- Renders QRCode with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `dsx-qr-code-size-{sm|md|lg}` class and `data-size` value. Also asserts the SVG width and height resolve to the corresponding sizing token.
+- Renders QRCode with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `dsx-qr-code-size-{sm|md|lg}` class and `data-size` value. Also asserts the SVG width and height attributes are `128` / `192` / `256` — never a sizing token.
 
 **Composition story** (for `asChild`):
 
@@ -194,7 +195,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 **Boundary rules:**
 
 - App-owned data: the encoded payload, the persistence of the payload, the security/rotation policy, the print/download lifecycle, and any analytics on scan events.
-- DS-owned visuals: token bindings (`--dsx-space-md`, `--dsx-rounded-xl`, `--dsx-rounded-sm`, `--dsx-color-surface-raised`, `--dsx-color-outline`, `--dsx-color-on-surface`, `--dsx-color-high-contrast-border`, `--dsx-color-high-contrast`, `--dsx-border-width-sm`, `--dsx-size-{xs|md|xl}`), the `dsx-qr-code` root class, the `dsx-qr-code-size-{sm|md|lg}` modifier classes, and the high-contrast CSS hook.
+- DS-owned visuals: token bindings (`--dsx-space-md`, `--dsx-rounded-xl`, `--dsx-rounded-sm`, `--dsx-color-surface-raised`, `--dsx-color-outline`, `--dsx-color-on-surface`, `--dsx-color-high-contrast-border`, `--dsx-color-high-contrast`, `--dsx-border-width-sm`), the `dsx-qr-code` root class, the `dsx-qr-code-size-{sm|md|lg}` modifier classes, the runtime painted sizes (`128`/`192`/`256`), and the high-contrast CSS hook. The `dsx-size-*` tokens are explicitly NOT bound to the matrix.
 
 ## Penpot build recipe
 
@@ -205,7 +206,7 @@ The package does not yet publish a Penpot asset for QRCode. Recipe is visual ref
 ### Root board
 
 - **Name**: `Components / QRCode`.
-- **Dimensions**: `var(--dsx-size-md)` × `var(--dsx-size-md)` at the default `md` size; `var(--dsx-size-xs)` at `sm`; `var(--dsx-size-xl)` at `lg`.
+- **Dimensions**: `192` × `192` px at the default `md` size; `128` px at `sm`; `256` px at `lg` (runtime painted sizes, not tokens).
 - **Layout**: `Fixed`.
 - **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
 
@@ -225,9 +226,9 @@ The package does not yet publish a Penpot asset for QRCode. Recipe is visual ref
 | Root | stroke | `--dsx-color-outline` | Color | `strokes` |
 | Root | padding | `--dsx-space-md` | Spacing | `padding` |
 | Root | corner radius | `--dsx-rounded-xl` | Radius | `radius` |
-| Root (size sm) | width, height | `--dsx-size-xs` | Sizing | `size` |
-| Root (size md) | width, height | `--dsx-size-md` | Sizing | `size` |
-| Root (size lg) | width, height | `--dsx-size-xl` | Sizing | `size` |
+| Root (size sm) | width, height | `128` px (runtime, no token) | Sizing | `size` |
+| Root (size md) | width, height | `192` px (runtime, no token) | Sizing | `size` |
+| Root (size lg) | width, height | `256` px (runtime, no token) | Sizing | `size` |
 | Matrix | fill | `--dsx-color-on-surface` | Color | `fills` |
 | Matrix (high-contrast) | fill | `--dsx-color-high-contrast` | Color | `fills` (state) |