@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{pagination.md → components/pagination.md}

@@ -3,30 +3,23 @@ title: Pagination
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/pagination/Pagination.tsx
-css_path: packages/d4gger-design-system/src/styles/components/pagination.css
-props_path: packages/d4gger-design-system/src/components/pagination/pagination.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Pagination.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-slot (powers `asChild` on the root, list, item, link, and ellipsis slots)"
-  - _internal/helpers/extractProps (turns the prop defs on `Pagination`, `Pagination.List`, `Pagination.Item`, `Pagination.Link`, and `Pagination.Ellipsis` 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 `Pagination.PageSize`; the option list rides the shared menu tier)
 ---
 
 # Pagination
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## 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
 
@@ -42,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
 
@@ -93,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 |
@@ -109,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
@@ -146,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:**
@@ -178,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. |
@@ -187,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. |
 
@@ -218,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:**
 
@@ -229,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:**
 
@@ -247,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:**
@@ -264,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:**
 
@@ -285,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/{password-input.md → components/password-input.md}

@@ -3,23 +3,17 @@ title: PasswordInput
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/passwordInput/PasswordInput.tsx
-css_path: packages/d4gger-design-system/src/styles/components/password-input.css
-props_path: packages/d4gger-design-system/src/components/passwordInput/passwordInput.props.ts
-test_path: packages/d4gger-design-system/src/test/components/PasswordInput.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Input (the inner `<input>` reuses the body-medium typography and the disabled / autofill contract from `baseInput.css`; the runtime does not import the `Input` component, but the visual treatment is aligned with the `Input` shell)
   - IconButton (the visibility toggle is a native `<button>` styled to match the `IconButton` primitive at the same size; the TSX does not import `IconButton`)
   - Icon (lucide-react `Eye`, `EyeOff`)
-  - "_internal/baseInput.css (shared placeholder color, disabled cursor, autofill, and the `dsx-input-shell` styling reused on the inner shell)"
   - Field (form-row wrapper; `PasswordInput` is the intended leaf inside a `Field.Root` for password form rows)
   - "@radix-ui/react-slot"
 ---
 
 # PasswordInput
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -87,8 +81,8 @@ Rules that apply to this row:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | `dsx-password-input--sm`, `dsx-password-input--md`, `dsx-password-input--lg` (applied in TSX, not via `extractProps`); no CSS rule for `[data-size='...']` | `password-input.css` |
-| `data-variant` | `surface`, `classic`, `ghost` | (no CSS rule declared today; reserved) | `password-input.css` |
-| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no CSS rule declared today; reserved) | `password-input.css` |
+| `data-variant` | `surface`, `classic`, `ghost` | Classic paints raised fill + elevation; ghost is transparent until focus. | `password-input.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | Shell border-radius follows the matching `var(--dsx-rounded-*)` token. | `password-input.css` |
 
 **Slot classes:**
 
@@ -276,8 +270,8 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 ## Anomalies
 
 - **`density` prop writes `data-size`, not `data-density`.** The prop is named `density` on the bag, but the runtime writes `data-size="sm"\|"md"\|"lg"`. The CSS consumes the modifier class `dsx-password-input--{value}` (added in the TSX), not the `data-size` attribute. The naming split is intentional in the source but the attribute name is misleading for consumers that inspect the DOM. A future revision should align the attribute name with the prop name (or rename the prop to `size`).
-- **`data-variant` is not CSS-backed.** `variant` is declared on the prop bag with `surface`, `classic`, and `ghost` values, but `password-input.css` has no `[data-variant='...']` rules. All three variants render with the same shell treatment today; the contract is reserved.
-- **`data-radius` is not CSS-backed.** The attribute is written by the runtime and listed on the prop bag, but `password-input.css` has no `[data-radius='...']` rule. The shell uses the default `var(--dsx-rounded-md)` from `baseInput.css`. The contract is reserved.
+- **`data-variant` is CSS-backed.** `classic` paints raised fill + elevation, `ghost` is transparent until focus — see `password-input.css`.
+- **`data-radius` is CSS-backed.** The shell border-radius follows the matching `var(--dsx-rounded-*)` token.
 - **Toggle button is not in the tab order.** `tabIndex={-1}` is hard-coded in the TSX. The intent is to keep the natural tab order between fields, but keyboard users that need to toggle visibility (and screen reader users that reach the toggle) cannot focus the button without a script. A future revision should expose `toggleTabIndex` (or remove the `tabIndex={-1}`) so the toggle is reachable by default.
 - **Roster reconciled to primitive.** The roster originally listed `PasswordInput` as `composite` with `Composed From: Input, IconButton`. The runtime is a single forwardRef without `Object.assign`; the inner input and toggle are implementation details, not named slots. The roster was updated to `primitive` and the `Composed From` column was cleared. The spec follows that classification.
 - **The roster's `Composed From` column lists `Input` and `IconButton`, but the TSX does not import either.** The alignment is via shared CSS classes and tokens, not via React composition. The `depends_on` block at the top of this spec records both relationships.

package/dist/docs/components/phone-input.md

@@ -0,0 +1,74 @@
+---
+title: PhoneInput
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - Label (the label slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
+  - Text (the helper and error text slots render through the `Text` primitive at the `label-small` ramp)
+  - "libphonenumber-js (optional peer: country list, dial codes, as-you-type formatting, E.164 parsing)"
+  - "@radix-ui/react-slot"
+---
+
+# PhoneInput
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+An international phone-number entry control. A custom country dropdown feeds the dial prefix into a national `<input>` powered by the `react-phone-number-input/input` engine (parsing, as-you-type formatting, smart caret — no CSS taken from the lib); the component value is always an E.164 string (`+15551234567`) or `undefined` when empty. Country switching re-parses the current value under the new prefix. No flag assets: countries render as text codes (`US +1`), no emoji. Use `PhoneInput` for any phone collection; for plain numeric entry use `NumberInput`.
+
+## Anatomy & slots
+
+**Parent:** `PhoneInput` (flat export, no compound subcomponents).
+
+No slots: the component renders a root `<div>` (`dsx-phone-input` + density/variant/invalid modifiers, `data-size`/`data-variant`), a `Label`, a shell `<div>` hosting the country dropdown (`dsx-phone-input__country`: button + searchable listbox, divider stretches full shell height via `align-self: stretch`) and the engine-driven national `<input type="tel" inputMode="tel" autoComplete="tel">` (`dsx-phone-input__input`), plus helper/error text.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` (E.164) | `undefined` | no | Controlled value. When set, the component is controlled. | no |
+| `defaultValue` | `string` (E.164) | `undefined` | no | Initial value for uncontrolled mode. The initial country is detected from it. | no |
+| `onChange` | `(value: string \| undefined) => void` | `undefined` | no | Called with the E.164 value on every change; `undefined` when the field is cleared. | no |
+| `defaultCountry` | `CountryCode` | `'US'` | no | Fallback country when the value carries no detectable prefix. | no |
+| `countries` | `readonly CountryCode[]` | all `getCountries()` | no | Allowed country list for the select, sorted by English region name. | no |
+| `label` | `string` | `undefined` | no | Optional label string bound via `htmlFor`. | no |
+| `helperText` | `string` | `undefined` | no | Optional helper text, hidden when invalid. | no |
+| `errorText` | `string` | `undefined` | no | Optional error message, shown only when `invalid` is `true`. | no |
+| `id` | `string` | `undefined` | no | Input id for the label association. | no |
+| `invalid` | `boolean` | `false` | no | Error state: modifier class + `aria-invalid` on the input + error text swap. | no |
+| `density` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height. Writes `data-size`. | no |
+| `variant` | `'surface' \| 'classic' \| 'soft'` | `'surface'` | no | Shell treatment; classic is raised fill + elevation (family rule). | no |
+| `placeholder` | `string` | `undefined` | no | National-input placeholder. | no |
+| `disabled` | `boolean` | `false` | no | Disables select and input. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot`. | no |
+
+Rules:
+
+- The national display is owned by the engine (`react-phone-number-input/input` with `smartCaret`): parsing, as-you-type formatting, and caret behavior come from the lib, exactly the input-otp playbook. Our code owns the shell, the dropdown, validation display, and the E.164 contract.
+- Typing stores `parsed.number` (E.164) whenever the text parses; clearing the field stores `undefined`.
+- Country options render as SVG flag + text code (`US +1`) with full region names in the searchable list; flags come from the optional `@d4gger/design-system/flags.css` entrypoint (`country-flag-icons` sprite, no emoji, no external requests). Without that import the codes still read — flags are progressive enhancement.
+- The country-block divider bleeds into the shell padding per density (negative-margin contract in `phone-input.css`) so it runs edge to edge at every size.
+- The `countries` prop restricts the list; the select falls back to `defaultCountry` when the active country is not in the list.
+
+## CSS class contract
+
+**Root class:** `dsx-phone-input`
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-phone-input--sm/md/lg` (shell heights) | `phone-input.css` |
+| `data-variant` | `surface`, `classic`, `soft` | `dsx-phone-input--{variant}` | `phone-input.css` |
+
+**Slot classes:** `dsx-phone-input__label`, `dsx-phone-input__shell`, `dsx-phone-input__country`, `dsx-phone-input__input`, `dsx-phone-input__error`, `dsx-phone-input__helper`. Invalid root modifier: `dsx-phone-input--invalid`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token. Shell, border, focus, disabled, and autofill contracts come from `_internal/baseInput.css`; classic/soft follow the input-family rule (raised fill + `var(--dsx-shadow-elevation-2)`).
+
+## Accessibility
+
+- The country `<select>` carries `aria-label="Country code"`; the national input is labelled by `label`/`id` like `TextField`.
+- `aria-invalid` is set on the national input when `invalid` is `true`.
+- The select is a native control: full keyboard and screen-reader support with no extra code.

package/dist/docs/{pills.md → components/pills.md}

@@ -3,13 +3,6 @@ title: Pills
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/pills/Pills.tsx
-css_path: packages/d4gger-design-system/src/styles/components/pills.css
-props_path: packages/d4gger-design-system/src/components/pills/pills.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Pills.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Badge
   - Button
@@ -18,11 +11,11 @@ depends_on:
 
 # Pills
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## 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
 
@@ -43,8 +36,8 @@ The compound is split across two prop-def bags: `pillsPropDefs` for the root and
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | no | Cluster variant. The root's `data-variant` is informational; the visible variant is set per `Pill` via its own `variant` prop. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Cluster size. The root's `data-size` is informational; the visible size is set per `Pill` via its own `size` prop. | no |
+| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | no | Cluster variant. Cascades to every `Pill` via context (`solid`→`default`, `soft`→`soft`, `outline`→`outline`); a per-pill `variant` overrides it. The root's own `data-variant` carries no CSS. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Cluster size. Cascades to every `Pill` via context; a per-pill `size` overrides it. | no |
 | `color` | `string` | `undefined` | no | Free-form accent override; writes `data-accent-color` when provided. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius token; writes `data-radius` when provided. The default is the CSS's `var(--dsx-rounded-full)`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
@@ -54,9 +47,10 @@ The compound is split across two prop-def bags: `pillsPropDefs` for the root and
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | no | Per-pill variant. Emits one of the modifier classes `dsx-pill--default`, `dsx-pill--secondary`, `dsx-pill--destructive`, `dsx-pill--outline`, `dsx-pill--ghost`, `dsx-pill--link`. | no |
+| `variant` | `'default' \| 'secondary' \| 'soft' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | no | Per-pill variant. Emits one of the modifier classes `dsx-pill--default`, `dsx-pill--secondary`, `dsx-pill--soft` (accent-3 tint + indicator text, the family soft recipe), `dsx-pill--destructive`, `dsx-pill--outline`, `dsx-pill--ghost`, `dsx-pill--link`. Inherits the root cluster variant when omitted. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Per-pill size. Emits one of the modifier classes `dsx-pill--sm`, `dsx-pill--md`, `dsx-pill--lg`. | no |
 | `removable` | `boolean` | `false` | no | When `true`, renders a trailing remove button with `aria-label="Remove"`. | no |
+| `tone` | `'success' \| 'warning' \| 'error' \| 'info'` | `undefined` | no | Status tone. Writes `data-tone`; paints the container tint + on-container ink (directions-panel language, shared with badge / callout / toast). Overrides the variant fill. | no |
 | `onRemove` | `() => void` | `undefined` | no | Click handler for the remove button. Only meaningful when `removable={true}`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the pill through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pill`. | no |
@@ -71,7 +65,7 @@ Each pill also accepts the standard HTML attributes for its host element. The `c
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `solid`, `soft`, `outline` | (no rule in `pills.css`; attribute is informational) | n/a |
+| `data-variant` | `solid`, `soft`, `outline` | (no rule in `pills.css`; the value cascades to pills via context) | n/a |
 | `data-size` | `sm`, `md`, `lg` | (no rule in `pills.css`; attribute is informational) | n/a |
 | `data-accent-color` | any string | (no rule in `pills.css`; attribute is forwarded) | n/a |
 | `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no rule in `pills.css`; attribute is forwarded) | n/a |

package/dist/docs/{popover.md → components/popover.md}

@@ -3,19 +3,12 @@ title: Popover
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/popover/Popover.tsx
-css_path: packages/d4gger-design-system/src/styles/components/popover.css
-props_path: packages/d4gger-design-system/src/components/popover/popover.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Popover.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Popover
 
-> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -142,7 +135,8 @@ Rules:
 | Title typography | `var(--dsx-typography-headline-medium-*)` | Title. |
 | Description typography | `var(--dsx-typography-body-medium-*)` | Description. |
 | Description color | `var(--dsx-color-on-surface-variant)` | Body copy. |
-| Positioner z-index | `var(--dsx-z-index-popover, 50)` | Stacking. |
+| 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. |
 | Motion duration | `var(--dsx-motion-duration-*)` | Mount and exit. |
@@ -243,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:**
 
@@ -253,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:**
@@ -285,7 +281,7 @@ Rules:
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Content frame>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Content frame>` | radius | `var(--dsx-rounded-lg)` | Radius | `borderRadius` |
 | `<Content frame>` | spacing | `var(--dsx-space-md)` | Spacing | `padding` |
 | `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
@@ -296,8 +292,8 @@ Rules:
 
 | State | Content fill | Content shadow |
 |---|---|---|
-| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-2)` |
-| `open` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
+| `default` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-2)` |
+| `open` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-3)` |
 
 ### Variant model
 

package/dist/docs/{progress.md → components/progress.md}

@@ -3,20 +3,13 @@ title: Progress
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/progress/Progress.tsx
-css_path: packages/d4gger-design-system/src/styles/components/progress.css
-props_path: packages/d4gger-design-system/src/components/progress/progress.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Progress.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - '@radix-ui/react-progress (Root + Indicator, internal)'
 ---
 
 # Progress
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{prose.md → components/prose.md}

@@ -3,8 +3,6 @@ title: Prose
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/prose/Prose.tsx
-css_path: packages/d4gger-design-system/src/styles/components/prose.css
 ---
 
 # Prose
@@ -21,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.