@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/text.md

@@ -12,7 +12,7 @@ depends_on: []
 
 ## Purpose
 
-The app-level body text primitive. Renders a `<span>` (or the consumer's host element) with token-aligned typography, a token-backed color prop, a `tone` modifier for muted or inverse contexts, a responsive `size` scale, and the shared margin, padding, alignment, wrap, trim, weight, truncate, high-contrast, and `asChild` infra.
+The app-level body text primitive. Renders a `<span>` (or a consumer host through `asChild`) with token-aligned typography, a token-backed color prop, a `tone` modifier for muted or inverse contexts, a nine-step `size` scale, and the shared margin, padding, alignment, wrap, trim, weight, truncate, high-contrast, and `asChild` infra.
 
 ## Anatomy & slots
 
@@ -20,7 +20,7 @@ The app-level body text primitive. Renders a `<span>` (or the consumer's host el
 
 **Slots:**
 
-No slots: flat export. The component renders a single `<span>` host element (or the consumer's host element when `as` or `asChild` is set) with the `dsx-text` root class, the variant modifier class (when no `size` is set), and any `tone` modifier class.
+No slots: flat export. The component renders a single `<span>` host element (or the consumer's host element when `asChild` is set) with the `dsx-text` root class, the variant modifier class (when no `size` is set), and any `tone` modifier class.
 
 ## Props contract
 
@@ -28,16 +28,16 @@ No slots: flat export. The component renders a single `<span>` host element (or
 |---|---|---|---|---|---|
 | `variant` | `'body-large' \| 'body-medium' \| 'body-small' \| 'label-large' \| 'label-medium' \| 'label-small'` | `'body-medium'` | no | Typography ramp. Writes the `dsx-text--{variant}` modifier class. Omitted when `size` is set. | no |
 | `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-text--{tone}` for `muted` and `inverse`. | no |
-| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Responsive size scale. When set, the `size` class (`dsx-r-text-size-{1..9}`) replaces the variant class. Accepts a responsive value (`{ initial, sm, md, lg, xl, 2xl }`). | yes |
-| `color` | token name string | `undefined` | no | Free-form color token reference. Writes `data-accent-color` and the matching `dsx-r-color-{name}` class. Accepts a responsive value. | yes |
-| `weight` | `string` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. Accepts a responsive value. | yes |
-| `align` | `string` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. Accepts a responsive value. | yes |
-| `wrap` | `string` | `undefined` | no | Text wrap. Writes the `dsx-r-wrap-{name}` class. | no |
+| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Scalar size scale. When set, the size class replaces the variant class. | no |
+| `color` | shared semantic color enum | `undefined` | no | Values are listed in the class contract below. Writes `data-accent-color` and the matching `dsx-r-color-{name}` class. | no |
+| `weight` | `'light' \| 'regular' \| 'medium' \| 'bold'` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. | no |
+| `align` | `'left' \| 'center' \| 'right' \| 'justify'` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. | no |
+| `wrap` | `'wrap' \| 'nowrap' \| 'pretty' \| 'balance'` | `undefined` | no | Text wrap. Writes the `dsx-r-tw-{name}` class. | no |
 | `truncate` | `boolean` | `undefined` | no | When set, writes the `dsx-truncate` class. | no |
-| `trim` | `string` | `undefined` | no | Leading-trim behavior. Writes the `dsx-r-lt-{name}` class. | no |
+| `trim` | `'normal' \| 'start' \| 'end' \| 'both'` | `undefined` | no | Leading-trim behavior. Writes the `dsx-r-lt-{name}` class. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | no |
-| `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Margin style props from the `margin.prop` def. | no |
-| `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py` | `string` | `undefined` | no | Padding style props from the `padding.prop` def. | no |
+| `margin`, `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Scalar margin style props from the `margin.prop` def. | no |
+| `padding`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py` | `string` | `undefined` | no | Scalar padding style props from the `padding.prop` def. | no |
 | `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-text`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
@@ -54,18 +54,18 @@ Rules that apply to this row:
 
 **Root class:** `dsx-text`
 
-**Modifier classes** (driven by the prop def bag and the responsive helpers):
+**Modifier classes** (driven by the scalar prop def bag and shared class extraction):
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | (class) | `body-large`, `body-medium`, `body-small`, `label-large`, `label-medium`, `label-small` | `dsx-text--{variant}` (omitted when `size` is set) | `text.css` |
 | (class) | `muted`, `inverse` | `dsx-text--muted`, `dsx-text--inverse` | `text.css` |
-| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | `dsx-r-text-size-{n}` (and breakpoint-prefixed `sm:`, `md:`, `lg:`, `xl:`, `2xl:`) | `text.css` (and `src/styles/responsive/*.css`) |
-| `data-accent-color` | any token name | `dsx-r-color-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any weight name | `dsx-r-weight-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any align name | `dsx-r-ta-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any wrap name | `dsx-r-wrap-{name}` | `src/styles/responsive/*.css` |
-| (class) | any trim name | `dsx-r-lt-{name}` | `src/styles/responsive/*.css` |
+| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | `dsx-r-text-size-{n}` | `text.css` |
+| `data-accent-color` | `primary`, `primary-container`, `secondary`, `secondary-container`, `tertiary`, `tertiary-container`, `success`, `success-container`, `error`, `error-container`, `surface`, `surface-raised`, `surface-overlay`, `surface-sunken`, `background`, `outline`, `outline-variant` | `dsx-r-color-{name}` | `src/styles/responsive/*.css` |
+| (class) | `light`, `regular`, `medium`, `bold` | `dsx-r-weight-{name}` | `src/styles/responsive/*.css` |
+| (class) | `left`, `center`, `right`, `justify` | `dsx-r-ta-{name}` | `src/styles/responsive/*.css` |
+| (class) | `wrap`, `nowrap`, `pretty`, `balance` | `dsx-r-tw-{name}` | `src/styles/responsive/*.css` |
+| (class) | `normal`, `start`, `end`, `both` | `dsx-r-lt-{name}` | `src/styles/responsive/*.css` |
 | (class) | `true` (truncate) | `dsx-truncate` | `src/styles/responsive/truncate.css` |
 | `data-high-contrast` | `true` | `.dsx-text[data-high-contrast='true']` | `text.css` |
 
@@ -73,13 +73,15 @@ Rules that apply to this row:
 
 **Responsive behavior:**
 
-- `size`, `color`, `weight`, and `align` are `responsive: true` in the prop def bag. The prop def bag applies breakpoint-prefixed classes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) through the `responsive/*` style layer.
-- The component itself does not write `@media` rules. The `responsive/*` files are the source of the breakpoint-prefixed classes.
+- All typography and spacing props are scalar. This family emits no breakpoint-prefixed classes and has no viewport rules. Responsive page layout belongs to `Box`, `Flex` and `Grid`.
+- The maintainer approved removing the previous responsive typography API on 2026-10-04: “better to do it best versions from the get go and dont make backwards”. This is a breaking type change; release classification must reflect it.
 
 **Reduced motion:**
 
 - Text has no motion. No transitions or animations are declared in `text.css`.
 
+High contrast preserves `on-inverse-background` when `tone="inverse"` is used on its paired surface. Normal-surface high-contrast ink must not replace an inverse foreground.
+
 ## Token mapping
 
 Every CSS value the component paints is a `var(--dsx-*)` token.
@@ -97,12 +99,16 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Color (muted) | `var(--dsx-color-on-surface-variant)` | Muted tone. |
 | Color (inverse) | `var(--dsx-color-on-inverse-background)` | Inverse-context color. |
 | Color (high-contrast) | `var(--dsx-color-high-contrast)` | High-contrast shift. |
-| Responsive size 1–9 | `var(--dsx-typography-*-font-size)` | `dsx-r-text-size-1` through `dsx-r-text-size-9` map to the same typography tokens. |
-| Margin / padding | `var(--dsx-r-m*)`, `var(--dsx-r-p*)` | The `margin.prop` and `padding.prop` defs write `--dsx-r-*` variables that the responsive layer consumes. |
+| Scalar size 1–9 | `var(--dsx-typography-*-font-size)` | `dsx-r-text-size-1` through `dsx-r-text-size-9` map to the same typography tokens. |
+| Margin / padding | `var(--dsx-r-margin-{top,right,bottom,left})`, `var(--dsx-r-p*)` | Numeric, named and arbitrary spacing utilities resolve the local margins and padding. |
 
 Rules:
 
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; the responsive size classes are the second axis.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; the size classes are the second axis.
+
+Spacing custom properties are reset locally so ancestor padding and margins do not leak into this element. Named margins use the same resolved directional variables as numeric and arbitrary values. Weight utilities resolve to 300 / 400 / 500 / 700.
+
+The scalar size scale paints font size and the matching role line height. Its existing role-derived size mapping is preserved. Responsive objects are outside the public contract; compose responsive page layout with Box, Flex or Grid.
 
 ## Motion contract
 
@@ -118,7 +124,7 @@ Rules:
 
 **Roles:**
 
-- The component renders a `<span>` by default (or the consumer's host element when `as` / `asChild` is set). It has no implicit role. Consumers that need a paragraph should set `as="p"`.
+- The component renders a `<span>` by default (or the consumer's host element when `asChild` is set). It has no implicit role. Consumers that need a paragraph should use `asChild` with a `<p>`.
 
 **Keyboard:**
 
@@ -154,11 +160,11 @@ Rules:
 
 **Size story:**
 
-- Renders Text with each `size` value. Asserts the `data-size` attribute and the `dsx-r-text-size-{n}` class. Responsive `size` produces breakpoint-prefixed classes.
+- Renders Text with each `size` value. Asserts the `data-size` attribute and the `dsx-r-text-size-{n}` class. Size remains unchanged when the viewport changes; responsive maps are rejected by the public type.
 
 **Color story:**
 
-- Renders Text with each `color` token name. Asserts the `data-accent-color` attribute and the `dsx-r-color-{name}` class. Responsive `color` produces breakpoint-prefixed classes.
+- Renders Text with each `color` token name. Asserts the `data-accent-color` attribute and the `dsx-r-color-{name}` class. Color is scalar; responsive maps are rejected by the public type.
 
 **Composition story** (for `asChild`):
 
@@ -170,7 +176,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
 
 **A11y story:**
 
@@ -206,8 +212,8 @@ Rules:
 
 **State boundaries:**
 
-- Owned by Text: the root class, the variant and tone modifier classes, the responsive size class, the color and weight responsive classes, the alignment, wrap, trim, and truncate classes, the high-contrast attribute, the `data-size` and `data-accent-color` attributes, and the prop def bag.
-- Owned by the consumer: the text body, the host element when `as` / `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
+- Owned by Text: the root class, the variant and tone modifier classes, the size class, the color and weight classes, the alignment, wrap, trim, and truncate classes, the high-contrast attribute, the `data-size` and `data-accent-color` attributes, and the prop def bag.
+- Owned by the consumer: the text body, the host element when `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
 
 **Boundary rules:**
 

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

@@ -131,36 +131,11 @@ The component has no motion.
 
 - The `label` prop should be the human-readable token name ("Mode", "Accent", "Density"). The `value` should be the current setting ("dark", "amber", "compact"). When the row is interactive, the consumer is responsible for the accessible name of the interactive control.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders a `ThemePanel` with three `Row`s: `label="Mode" value="dark"`, `label="Accent" value="amber"`, `label="Radius" value="medium"`. Asserts the root class is `dsx-theme-panel` and each row renders the matching label and `Badge` value.
-
-**Variant story:**
-
-- The component has no variant. Skip the variant story.
-
-**State story:**
-
-- Renders a row with custom `children` (e.g. a `<span data-testid="custom">` element). Asserts the custom content is rendered and the default `Badge` is suppressed.
-- Renders a `ThemePanel asChild` wrapping a `<section>` and asserts the root class is moved onto the host element.
+The live example explains that the panel displays app-supplied values and reflects the playground preferences; it is not a built-in theme editor.
 
-**Composition story:**
-
-- Renders the full panel: six rows covering `Mode`, `Accent`, `Gray`, `Radius`, `Density`, `Scaling`. Asserts all six labels and values resolve, and the `dsx-theme-panel__row` class is applied to every row.
-
-**Token story:**
-
-- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the panel surface tracks `--dsx-color-panel-translucent` and is unaffected by the accent token; the value chip's text color is driven by the `Badge` component.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the default story. Asserts no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-The playground registry for `theme-panel` does not expose prop controls. The component has no variants or size scale; the registry render explains that the panel is mounted live inside `ConfigDrawer` and a second inline instance would conflict with the active one.
+The compact render and full live example show values supplied from the playground theme context. The live description explains application ownership; current appearance/accent/gray/radius/density/scaling update with preferences, and a custom row shows consumer content. The panel does not modify the theme itself.
 
 ## Wiring notes
 

package/dist/docs/components/theme.md

@@ -90,7 +90,10 @@ Rules:
 
 - The wrapper does not paint border, padding, or radius. Surface application is the only visible effect; the rest of the surface family comes from downstream components reacting to the attributes.
 - `data-dsx-scaling` is removed (rather than set to `undefined`) when no scaling is resolved. The token layer treats the missing attribute as the default `100%` scale.
-- Accent roles are semantic, not four names for one color. `accent-track` owns solid fills, `accent-contrast` owns their foreground, `accent-indicator` owns accent-as-foreground/indicator paint, and `accent-surface` owns subtle tinted backgrounds.
+- Accent roles are semantic, distinct jobs. `accent-track` owns solid fills, `accent-contrast` owns their foreground, `accent-indicator` owns accent-as-foreground/indicator paint, and `accent-surface` owns subtle tinted backgrounds.
+- Decorative rules use accent-border (light step 8 / dark step 11); readable foreground, focus and selection keep accent-indicator.
+- Generated appearance derivatives resolve on the nearest Theme host; accent mappings do not use appearance ancestor selectors. Dependent rings, seams, shadows and neutral code aliases rebind on theme/accent/gray boundaries.
+- The normal accent indicator resolves to ramp step 11 in both themes; light mode keeps a visible hue. Substantial soft containers use the opaque primary-container/on-primary-container pair, while accent-surface remains a translucent state layer.
 - Light mode intentionally separates bright track values from darker indicator values. Local `data-accent-color` overrides inherit the nearest Theme's appearance palette, including when the accent attribute is on a descendant component rather than the Theme host.
 
 ## Motion contract
@@ -135,11 +138,12 @@ Rules:
 
 **Default story:**
 
-- The registry render returns a description block (no live `Theme` mount). Consumers exercise the component by visiting the `/lab/theme` route, which renders the wrapper under the active `ThemeProvider`.
+- The registry render returns a description block (no live `Theme` mount). Consumers exercise the component by visiting the `/tokens#color-role-review` route, which renders the wrapper under the active `ThemeProvider`.
 
 **Variant story:**
 
-- The `/lab/theme` route shows the wrapper mounted with several `accentColor`, `density`, and `radius` permutations. The expected attributes (`data-accent-color`, `data-dsx-density`, `data-dsx-radius`, `data-dsx-theme`) are inspected through the runtime.
+- The `/tokens#color-role-review` route shows all five accents with light/dark appearances, both gray palettes and opposite-appearance nesting. The expected attributes (`data-accent-color`, `data-dsx-density`, `data-dsx-radius`, `data-dsx-theme`) are inspected through the runtime.
+- A fixed tinted/neutral side-by-side comparison exposes text, neutral dividers, resting TextField borders and Code wash in both appearances. Large background surfaces are shared by the two gray palettes; changing gray is not a page-background switch.
 
 **Composition story:**
 

package/dist/docs/components/timeline.md

@@ -34,8 +34,9 @@ A vertical or alternating event timeline for activity feeds, audit logs, and ord
 **Internal layout:**
 
 - The root renders a flex column. Items are stacked vertically.
+- Rail/connector geometry is shared with Stepper's vertical rail engine (see `stepper.md` and `stepper.css` `.dsx-stepper--vertical .dsx-stepper__item:not(:last-child)::after`): the connector is item-local, anchored at the marker bottom (`top` = marker size) and stretched to the item bottom (`bottom: 0`), centered on the dot column via `calc(marker-size / 2 - rail-width / 2)` with size-aware overrides per `data-size`. Timeline keeps its own `Connector` DOM node (Stepper draws via `::after` and hides its `Separator`) and its own rail width (`--dsx-border-width-sm`); the geometry recipe is shared, the slot API and ARIA roles stay distinct. The two components are never merged: Stepper answers "where am I in a process" (`role="progressbar"`), Timeline answers "what happened, when" (per-event states, no progress semantics). Precedent: antd Timeline renders `<Steps type="dot">`.
 - In the `left` variant (the default), every item is a flex row with `gap: var(--dsx-space-lg)`. The marker sits on the left rail; the content fills the remaining space.
-- In the `alternate` variant, every item is a full-width flex row; the consumer is responsible for the alternating side-by-side layout (CSS does not alternate automatically).
+- In the `alternate` variant, every item is a three-column grid (`minmax(0, 1fr) auto minmax(0, 1fr)`): the `1fr` tracks exist without any spacer element, so equal `fr` shares keep the marker exactly on the dot column in both parities. Odd items place content in column 1 (`text-align: right`), even items in column 3; the marker is always column 2. Placement is explicit (`grid-column` + `grid-row: 1`), so DOM order is irrelevant. The connector runs down the item's vertical centerline (`left: calc(50% - rail-width / 2)`), which is the marker center. DOM order stays Marker-then-Content by convention; the split is pure CSS, so no prop or slot change was needed.
 - `Timeline.Marker` is a square (`var(--dsx-size-md)`) fully rounded element with a 1px outline. It accepts arbitrary children, typically an `Icon` or a number from the consumer.
 - `Timeline.Connector` is an absolutely positioned vertical bar inside the item. It begins at the bottom of the marker and extends to the bottom of the item. Width is `var(--dsx-border-width-sm)` and color is `var(--dsx-color-outline-variant)`. The active state recolors it to `var(--dsx-color-primary)`.
 - `Timeline.Content` is the consumer's content surface. The CSS file defines helper classes `dsx-timeline__content-title`, `dsx-timeline__content-description`, and `dsx-timeline__content-time` for the typical title/body/time pattern, but the consumer is free to compose any children.
@@ -95,6 +96,8 @@ These three slots accept only `asChild` plus the standard HTML attribute surface
 
 - The component does not write `@media` rules. Responsive layout comes from the layout primitives' responsive classes when the consumer wraps the timeline in a responsive shell.
 
+- Items and content can shrink to the container; long identifiers wrap. Alternate tracks have a zero minimum so content cannot displace the centered marker rail. Error connectors use the same error token as their marker.
+
 **Reduced motion:**
 
 - The component is static. No motion is applied.
@@ -174,7 +177,7 @@ The component has no motion. It is a static read surface.
 
 **Variant story:**
 
-- Renders one `Timeline` with `variant="left"` and one with `variant="alternate"`. Asserts the `dsx-timeline--left` and `dsx-timeline--alternate` classes.
+- Renders one `Timeline` with `variant="left"` (deployment feed) and one with `variant="alternate"` (centered spine, three items covering odd/even parity). Asserts the `dsx-timeline--left` and `dsx-timeline--alternate` classes.
 
 **State story:**
 
@@ -186,7 +189,7 @@ The component has no motion. It is a static read surface.
 
 **Token story:**
 
-- Renders the default timeline inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute is forwarded, but the active marker color tracks `--dsx-color-primary` and is not affected by the accent token.
+- Renders the default timeline inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute is forwarded, but the active marker color tracks `--dsx-color-primary` and is not affected by the accent token.
 
 **A11y story:**
 
@@ -204,6 +207,7 @@ The component has no motion. It is a static read surface.
 **Composes from:**
 
 - `@radix-ui/react-slot`: enables `asChild` on the root and on every named slot.
+- Stepper's vertical rail engine (CSS recipe only, no component dependency): Timeline reuses the dot-column centering calc, the marker-bottom anchor, and the size-aware offsets. The two components share geometry, never API or ARIA roles.
 
 **Used by:**
 
@@ -223,8 +227,8 @@ The component has no motion. It is a static read surface.
 
 1. **Content block layout collapsed; title, description, time rendered run-together.** The `.dsx-timeline__content` slot had no `display`, `flex-direction`, or `gap`, causing its children (the title `<span>`, description `<span>`, and time `<span>`, typically rendered bare by consumers) to render as inline siblings on a single line ("Project createdInitial scaffold2 hours ago"). FIXED 2026-07-03: added `display: flex; flex-direction: column; gap: var(--dsx-space-2xs);` to `.dsx-timeline__content`, plus `flex: 1; padding-bottom: var(--dsx-space-lg);` to preserve the item gap semantics and support the connector's absolute positioning.
 
-2. **Alternate variant had no CSS implementation; items never alternated.** The `variant="alternate"` prop def wrote the `dsx-timeline--alternate` modifier class on the root, but the CSS file contained no rules targeting that modifier — the layout was identical to the `left` variant. FIXED 2026-07-03: added per-item zigzag rules for the `alternate` variant: even-indexed items get `flex-direction: row-reverse` (marker on the right), `text-align: right` on content, and the connector repositioned from `left` to `right` with size-aware recalculation per `data-size` (sm/md/lg). This is a per-item flip, not a shared centered spine — the connector is item-local, not a continuous centerline. A future polish iteration may introduce a centered-column connector pattern.
+2. **Alternate variant had no CSS implementation; items never alternated.** The `variant="alternate"` prop def wrote the `dsx-timeline--alternate` modifier class on the root, but the CSS file contained no rules targeting that modifier — the layout was identical to the `left` variant. FIXED 2026-07-03: added per-item zigzag rules for the `alternate` variant: even-indexed items get `flex-direction: row-reverse` (marker on the right), `text-align: right` on content, and the connector repositioned from `left` to `right` with size-aware recalculation per `data-size` (sm/md/lg). REDESIGNED 2026-09-21 (F12 brief §4): replaced the per-item flip with a centered-spine recipe shared with Stepper's vertical rail engine — each item is a three-column flex row (half | marker | half) with the `::before` pseudo as the empty half, content split on parity (odd left, even right), and the connector on the item centerline. The flip is obsolete; the spine is the contract.
 
 3. **Connector appeared missing but was symptom of layout bug, not a separate defect.** The connector (an absolutely positioned vertical bar inside each item) appeared invisible or extremely short (~18px) in rendered demos. Investigation revealed the connector itself was present with correct background color and dimensions; the visual symptom was a side effect of the spacing bug (#1 above). When `.dsx-timeline__content` had no flex layout, its children ran together in ~20px of vertical space, making the item itself tiny, and the connector's absolute `top: marker-bottom; bottom: 0` was proportionally tiny too. Fixing the spacing bug (adding the flex column layout) expanded the item's natural height, and the connector automatically became visible. No separate CSS fix was needed for the connector; it was never the root cause.
 
-4. **Playground fixture uses invalid state values.** The registry fixture at `apps/playground/lib/registry/data.tsx` (Timeline entry, "Default" story) passes `state="complete"` and `state="pending"` to `TimelineItem`, but `timeline.props.ts`'s `timelineItemPropDefs.state` enum only allows `'default' | 'active' | 'error' | 'disabled'`. Invalid enum values silently fall through to the default modifier class (no visible error). This is a fixture-honesty gap (the fixture uses API values that the type definitions reject) and is deferred to the next promotion batch.
+4. **Playground fixture uses invalid state values.** The registry fixture at `apps/playground/lib/registry/data.tsx` (Timeline entry, "Default" story) passes `state="complete"` and `state="pending"` to `TimelineItem`, but `timeline.props.ts`'s `timelineItemPropDefs.state` enum only allows `'default' | 'active' | 'error' | 'disabled'`. Invalid enum values silently fall through to the default modifier class (no visible error). FIXED 2026-09-21: fixture rewritten with valid states only — a timestamped deployment feed (left rail), a three-item alternate story covering odd/even parity, an error + disabled story, and a token story over `rift`/`warp`/`ray`.

package/dist/docs/components/toast.md

@@ -137,7 +137,7 @@ The close also accepts the full `ComponentPropsWithoutRef<typeof ToastPrimitive.
 
 | Attribute | Source |
 |---|---|
-| `data-accent-color` | Document `data-accent-color` (defaults to `'amber'`). |
+| `data-accent-color` | Document `data-accent-color` (defaults to `'rift'`). |
 | `data-gray-color` | Document `data-gray-color` (defaults to `'auto'`). |
 | `data-dsx-theme` | Document `data-dsx-theme` on `body` or `documentElement` (defaults to `'dark'`). |
 | `data-panel-background` | Document `data-panel-background` (defaults to `'translucent'`). |
@@ -148,7 +148,7 @@ The `useThemeContext` value wins when a `Theme` provider is in scope; the docume
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`.
-- The viewport's CSS file includes a `max-width: 640px` block to switch the mobile inset to `var(--dsx-toast-viewport-mobile-inset)` and the padding to `var(--dsx-space-sm)`. The breakpoint is literal because CSS custom properties cannot be used inside the media query.
+- The viewport uses the same intrinsic viewport cap, padding and inset at every width. No width media query is present.
 
 **Reduced motion:**
 
@@ -166,15 +166,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Viewport gap | `var(--dsx-space-md)` | Space between toasts. |
 | Viewport width | `min(var(--dsx-toast-viewport-width), calc(100vw - var(--dsx-dialog-viewport-gap)))` | Width cap. |
 | Viewport offset | `var(--dsx-space-md)` | Default inset. |
-| Viewport mobile inset | `var(--dsx-toast-viewport-mobile-inset)` | Mobile inset. |
-| Viewport mobile padding | `var(--dsx-space-sm)` | Mobile padding. |
 | Toast padding block | `var(--dsx-space-sm)` | Toast vertical padding. |
 | Toast padding inline | `var(--dsx-space-md)` | Toast horizontal padding. |
-| Toast gap | `var(--dsx-space-md)` | Gap between icon, title, description, and buttons. |
+| Toast row / column gap | `var(--dsx-space-xs)` / `var(--dsx-space-sm)` (md) | Title and trailing Close share the first row; description and action have full-width rows below. |
 | Toast background | `var(--dsx-color-surface)` | Resting toast surface. |
 | Toast radius | `var(--dsx-rounded-md)` | Toast corner roundness. |
 | Toast border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Toast edge. |
-| Toast shadow | `var(--dsx-shadow-elevation-2)` | Toast elevation. |
+| Toast shadow | `var(--dsx-shadow-elevation-5)` | Spotlight: below dialogs, above all menus (B4 Q3). |
 | Destructive background | `var(--dsx-color-error-container)` | Destructive variant surface. |
 | Destructive border | `var(--dsx-color-error)` | Destructive variant edge. |
 | Destructive text | `var(--dsx-color-on-error-container)` | Destructive variant text. |
@@ -185,7 +183,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Action typography | `var(--dsx-typography-label-medium-*)` | Action button. |
 | Action padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Action padding. |
 | Action radius | `var(--dsx-rounded-sm)` | Action corner roundness. |
-| Close padding | `var(--dsx-space-xs)` | Close padding. |
+| Close dimensions / padding | `var(--dsx-size-md)` / `0` | 24px square, aligned to the trailing top edge. |
 | Close radius | `var(--dsx-rounded-sm)` | Close corner roundness. |
 | Close text | `var(--dsx-color-on-surface-variant)` | Default close color. |
 | Close hover background | `var(--dsx-color-high-contrast-container)` | Hover affordance. |
@@ -194,6 +192,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Trigger radius | `var(--dsx-rounded-sm)` | Trigger corner roundness. |
 | Trigger text | `var(--dsx-color-on-surface-variant)` | Default trigger color. |
 
+Title and Close share the first row. Description and Action each occupy a full-width row below; actions do not squeeze long descriptions into a narrow side column. Action is at least 32px tall and retains its intrinsic label width.
+
 ## Motion contract
 
 | Region | Token | Default | Reduced |
@@ -218,8 +218,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Focus:**
 
-- Visible focus ring via the host application's focus styles. The DS does not add a custom focus ring; apps that need a custom ring can target the action and close buttons from the host.
-- The Radix primitive moves focus to the toast when it appears and returns focus to the trigger on dismissal when a `Toast.Trigger` is in scope.
+- Action and close have the package focus ring.
+- Opening a toast keeps focus on the current control. Radix provides a viewport hotkey (default `F8`) and keyboard traversal into the notification; `Escape` dismisses a focused toast. `Toast.Trigger` is a convenience button; consumers own toast state and any application-specific focus return.
 
 **Reduced motion:**
 
@@ -254,7 +254,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Token story:**
 
-- Renders a `Theme` wrapper with `accentColor="silver"`, mounts a `Toast.Viewport` outside the wrapper, and asserts the viewport host carries `data-accent-color="silver"` after the document theme mirror runs.
+- Renders a `Theme` wrapper with `accentColor="astral"`, mounts a `Toast.Viewport` outside the wrapper, and asserts the viewport host carries `data-accent-color="astral"` after the document theme mirror runs.
 
 **Props exposed in the playground controls:**
 
@@ -275,7 +275,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Used by:**
 
-- `NotificationCenter`: composes `Toast` plus `Sonner`, `Card`, and `DataList` for the inbox-style notification surface. The pattern-level `NotificationCenter` is the intended product composition; `Toast` itself is a leaf surface.
+- Consumers compose transient notifications with `Toast`; `NotificationCenter` is a separate inbox surface and does not render this primitive internally.
 
 **State boundaries:**
 
@@ -337,12 +337,26 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 ### Variant model
 
-- `variant`: `default`, `destructive`. Default `default`.
+- `variant`: `default`, `success`, `warning`, `destructive`, `info`. Default `default`.
 - `size`: `sm`, `md`, `lg`. Default `md`.
-- Total members: 6 (2 variants × 3 sizes).
+- Total members: 15 (5 variants × 3 sizes).
 
 ### Validation checklist
 
 - [ ] 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.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+## Overlay review viewport
+
+The viewport uses its existing intrinsic min(preferred width, viewport minus
+dialog-viewport-gap) cap at every width, with space-md padding and bottom/right
+insets. The legacy 640px width media query is removed. `/docs/toast` launches
+and closes real notifications, compares all five variants and three size bands,
+and provides a working Undo or Retry action. Notifications do not auto-open
+in the matrix. Each example owns its Provider and Viewport; render only one
+active example at a time when comparing fixed-position notifications.
+
+The document accent fallback accepts all five canonical accents and reads the
+root attribute when the body has none. Theme context still takes precedence.
+Regression tests cover provider-free rift/warp/ray/astral/spark; invalid values
+fall back to rift.

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

@@ -14,7 +14,7 @@ depends_on:
 
 ## Purpose
 
-A coordinated cluster of toggle buttons backed by `@radix-ui/react-toggle-group`. Items can run in single or multiple selection, share a single border with collapsed inner radii, and lift the focused child above its siblings. The component is the right fit for view selectors and formatting clusters; for single-select with a sliding indicator use `SegmentedControl` instead.
+A coordinated cluster of toggle buttons backed by `@radix-ui/react-toggle-group`. Items can run in single or multiple selection, share a single border with collapsed inner radii, and lift the focused child above its siblings. The component is the right fit for view selectors and formatting clusters; for single-select with a sliding indicator use `SegmentedControl` instead. Boundary rule (F6 brief): ToggleGroup is frameless toolbar buttons with no thumb and no container fill — the moment a design needs a sliding indicator, it is a SegmentedControl, not a styled ToggleGroup.
 
 ## Anatomy & slots
 
@@ -79,6 +79,7 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and variant are single-value only.
+- Narrow containers: the root caps at `max-width: 100%` with `overflow-x: auto` — the fused frame cannot wrap, so an over-wide group scrolls instead of hard-clipping its last item (proven 2026-09-23 in a definite 272px column: group caps at 272, full content reachable by touch scroll).
 
 **Reduced motion:**