@d4gger/design-system 3.0.0 → 4.0.0

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:**
 
@@ -292,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 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. 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. |
 
@@ -237,6 +236,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 +247,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:**
@@ -304,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

@@ -19,6 +19,19 @@ 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.
+
+## 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 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

@@ -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 | 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 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 |
@@ -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).
 
@@ -59,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:**
 
@@ -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,9 +94,9 @@ 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 `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 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 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
 
@@ -112,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:**
 
@@ -128,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:**
 
@@ -136,15 +137,15 @@ 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:**
 
-- 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`):
 
@@ -156,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:**
 
@@ -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) |
 

package/dist/docs/components/quote.md

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

package/dist/docs/components/radio-group.md

@@ -47,7 +47,7 @@ A mutually exclusive selection cluster backed by `@radix-ui/react-radio-group`.
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `value` | `string` | — | yes | Unique value for this item. | no |
-| `size` | `'sm' \| 'md'` | `'md'` | no | Item-level size override. Drives the `dsx-radio-item--{size}` class. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Item-level size override. Drives the `dsx-radio-item--{size}` class. | no |
 | `label` | `ReactNode` | `undefined` | no | When set, the item wraps itself in a `<label class="dsx-radio-option">` and renders the label inside a `dsx-radio-option__label` span. | no |
 | `description` | `ReactNode` | `undefined` | no | When set, the item renders a `dsx-radio-option__description` span under the label. | no |
 | `asChild` | `boolean` | `false` | no | Renders the item host through `Slot`. | no |
@@ -79,6 +79,7 @@ Rules:
 | `RadioGroupItem` (host) | `dsx-radio-item` | `radio-group.css` |
 | `RadioGroupItem` (size sm) | `dsx-radio-item--sm` | `radio-group.css` |
 | `RadioGroupItem` (size md) | `dsx-radio-item--md` | `radio-group.css` |
+| `RadioGroupItem` (size lg) | `dsx-radio-item--lg` | `radio-group.css` |
 | Item indicator | `dsx-radio-item__indicator` | `radio-group.css` |
 | Item dot | `dsx-radio-item__dot` | `radio-group.css` |
 | Option wrapper | `dsx-radio-option` | `radio-group.css` |
@@ -106,7 +107,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Option label/description typography | `var(--dsx-typography-body-medium-*)` | Body ramp. |
 | Option description color | `var(--dsx-color-on-surface-variant)` | Muted description. |
 | Item size (default) | `var(--dsx-size-md)` | Default control. |
-| Item size (sm) | `var(--dsx-size-sm)` | Small control. |
+| Item size (sm) | `var(--dsx-size-sm)` | Small control (20px). |
+| Item size (lg) | `var(--dsx-size-lg)` | Large control (32px). |
+| Item hit area | `max(100% + 16px, 44px)` via `::before` | Layout-neutral 44px pointer target (WCAG 2.5.8, TMA touch). |
 | Item radius | `var(--dsx-rounded-full)` | Round. |
 | Item border | `var(--dsx-border-width-md)` solid `var(--dsx-color-outline-variant)` | Resting edge. |
 | Item background | `var(--dsx-color-surface)` | Resting fill. |

package/dist/docs/components/rating.md

@@ -79,6 +79,8 @@ Rules:
 
 - The component does not write `@media` rules.
 
+- The `sm` star remains 20px visually. A centered `::before` layer expands its pointer target to the 24px `size-md` token, filling the existing 4px gap without overlapping neighboring targets.
+
 **Reduced motion:**
 
 - Item transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)` for color, transform, opacity, and box-shadow. No explicit `prefers-reduced-motion` gate is present in the CSS.