@d4gger/design-system 4.0.0 → 4.0.1

package/dist/components/sidebar.css

@@ -73,12 +73,23 @@
 .dsx-sidebar[data-effect='ambient'] {
   background-color: var(--dsx-color-surface);
   /* Softened 2026-09-19: accent-9 at 18% painted a visible color blob
-     (worst on bright accents like spark) instead of an ambient wash. */
-  background-image: radial-gradient(
-    circle at var(--dsx-space-xl) var(--dsx-space-lg),
-    color-mix(in srgb, var(--dsx-color-accent-9) 10%, transparent),
-    transparent 58%
-  );
+     (worst on bright accents like spark) instead of an ambient wash. The strength is a theme-aware token (G-16, 2026-10-05):
+     10% in dark, as before; raised in light, where the same wash read about half as strong on the pale surface.
+     A second source at the foot (G-17, 2026-10-05): the corner radial alone reached about 35% of the panel and left the lower
+     half flat. The foot glow is the same colour at 0.9x the same strength, an ellipse anchored to the bottom edge, so the panel
+     is lit at both ends and the nav keeps a calm middle (the account row gets the light the logo gets). House-style, picked by
+     the maintainer in the look lab over a full-height column and a single tall radial. */
+  background-image:
+    radial-gradient(
+      circle at var(--dsx-space-xl) var(--dsx-space-lg),
+      color-mix(in srgb, var(--dsx-color-accent-9) var(--dsx-effect-ambient-strength), transparent),
+      transparent 58%
+    ),
+    radial-gradient(
+      ellipse 130% 38% at 85% 100%,
+      color-mix(in srgb, var(--dsx-color-accent-9) calc(var(--dsx-effect-ambient-strength) * 0.9), transparent),
+      transparent 100%
+    );
   background-repeat: no-repeat;
 }
 
@@ -217,8 +228,14 @@
   overflow: auto;
 }
 
+/* G-12: the drawer is flush with the viewport on three sides, so only its free (inline-end) edge is a boundary. The
+   base dialog surface draws the structural border all round, which painted a light outline along the screen edge and
+   made the 100dvh nav 2px taller than the sheet's content box, so the sheet scrolled. The nav owns its own scrolling. */
 .dsx-sidebar__mobile-sheet {
   padding: 0;
+  border-block-width: 0;
+  border-inline-start-width: 0;
+  overflow: hidden;
 }
 
 /* The mobile Drawer carries drawer's own content padding; the X sits over
@@ -253,7 +270,7 @@
 .dsx-sidebar__mobile-sheet > .dsx-sidebar {
   position: relative;
   width: 100%;
-  height: 100dvh;
+  height: 100%;
   box-shadow: none;
 }
 
@@ -278,6 +295,7 @@
 
 .dsx-sidebar__rail:focus-visible,
 .dsx-sidebar__menu-button:focus-visible,
+.dsx-sidebar__menu-sub-trigger:focus-visible,
 .dsx-sidebar__menu-sub-button:focus-visible {
   outline: none;
   box-shadow: var(--dsx-shadow-focus-ring);
@@ -474,7 +492,11 @@
   opacity: 1;
 }
 
-.dsx-sidebar__menu-button {
+/* One row geometry for a plain row and for a parent row that opens a sub-list (G-13, 2026-10-05). The parent is a `.dsx-button` too, and
+   without this base it kept the button's 16px padding (its icon sat 8px right of every other row) and the browser's grey button
+   fill whenever it was neither open nor active. */
+.dsx-sidebar__menu-button,
+.dsx-sidebar__menu-sub-trigger {
   display: flex;
   align-items: center;
   gap: var(--dsx-space-sm);
@@ -645,6 +667,17 @@
   box-shadow: var(--dsx-shadow-active-inset-outline);
 }
 
+/* G-19 (2026-10-05): the active row's own wash in the light theme. Accent-3 at 50% over a tinted light panel is nearly the
+   panel's colour, so in light the row was marked only by its underline and text. Step 4 is the scale's "soft component" step
+   (selected / hover); it reads on Rift, Warp and Ray without a primary fill. Dark keeps the rules above, unchanged. The
+   `:where()` keeps the selector at (0,2,0) (the qa:selectors policy); the tie with the three rules above is decided by
+   source order, so this block stays after them. */
+:where([data-dsx-theme='light']) .dsx-sidebar__menu-button[data-active='true'],
+:where([data-dsx-theme='light']) .dsx-sidebar__menu-sub-button[data-active='true'],
+:where([data-dsx-theme='light']) .dsx-sidebar__menu-sub-trigger[data-active='true'] {
+  background: var(--dsx-color-accent-4);
+}
+
 .dsx-sidebar__menu-sub-trigger-chevron {
   margin-inline-start: auto;
   flex-shrink: 0;
@@ -692,6 +725,13 @@
   min-height: var(--dsx-size-sm);
 }
 
+/* Inside a menu item (a flex row) the skeleton is an auto-width flex item, so its 100%-wide label collapses and the
+   row draws as two small pills. Let it take the item's width. */
+.dsx-sidebar__menu-item > .dsx-sidebar__menu-skeleton {
+  flex: 1;
+  min-width: 0;
+}
+
 .dsx-sidebar__menu-button-text {
   min-width: 0;
   overflow: hidden;
@@ -699,6 +739,11 @@
   white-space: nowrap;
 }
 
+/* G-18 (2026-10-05): a quiet outline in the accent, not a raised disc. The disc was a `surface-raised` fill with a drop shadow:
+   shadows do not read on dark, and on the tinted panel the fill is nearly the panel's own colour, so the control vanished in
+   both themes. The ring is the scale's "normal border" step (7), the glyph its text step (11), the hover one step up (fill 3,
+   ring 8): the Radix 12-step jobs, one purposeful step per state. The ring is an inset shadow so the 32px box does not move,
+   and the focus ring below still replaces it. The pin / unpin glyphs of hover-expand mode live inside the same button. */
 .dsx-sidebar__trigger {
   display: inline-flex;
   align-items: center;
@@ -710,14 +755,14 @@
   padding: 0;
   border: 0;
   border-radius: var(--dsx-rounded-full);
-  background: var(--dsx-color-surface-raised);
-  color: var(--dsx-color-on-surface-variant);
-  box-shadow: var(--dsx-effect-shadow-1);
+  background: transparent;
+  color: var(--dsx-color-accent-11);
+  box-shadow: inset 0 0 0 var(--dsx-border-width-sm) var(--dsx-color-accent-7);
 }
 
 .dsx-sidebar__trigger:hover {
-  background: var(--dsx-effect-hover-ghost);
-  color: var(--dsx-color-on-surface);
+  background: var(--dsx-color-accent-3);
+  box-shadow: inset 0 0 0 var(--dsx-border-width-sm) var(--dsx-color-accent-8);
 }
 
 .dsx-sidebar__trigger:focus-visible {

package/dist/components.css

@@ -21,6 +21,7 @@
 @import 'components/color-swatch.css';
 @import 'components/dropdown-menu.css';
 @import 'components/empty-state.css';
+@import 'components/environment-ribbon.css';
 @import 'components/editable.css';
 @import 'components/em.css';
 @import 'components/menu.css';

package/dist/docs/README.md

@@ -97,6 +97,7 @@ They describe public intent and contracts; TypeScript declarations remain the ex
 - [DropdownMenu](./components/dropdown-menu.md)
 - [Editable](./components/editable.md)
 - [EmptyState](./components/empty-state.md)
+- [EnvironmentRibbon](./components/environment-ribbon.md)
 - [Field](./components/field.md)
 - [FileUpload](./components/file-upload.md)
 - [FilterBar](./components/filter-bar.md)

package/dist/docs/component-contract.md

@@ -85,6 +85,7 @@ from the closest RT category (see legend).
 | Editable | Custom → TextField | ✓ | ✓ | — | ✓ | — | Inline edit; variant+size+radius |
 | Em | RT Em | — | — | — | — | — | Typographic; no props in RT |
 | EmptyState | Custom → none | ✓ | ✓ | — | — | — | Size + variant (`default`/`unavailable`) |
+| EnvironmentRibbon | Custom → none | — | — | — | — | — | Floating non-production pill; `placement` / `haze` are not tracked styling attrs |
 | Field | Custom → none | — | ✓ | — | — | — | Form field wrapper; size only |
 | FileUpload | Custom → TextField | — | ✓ | — | — | — | Input-like; size only |
 | FilterBar | Custom → none | — | ✓ | — | — | — | Toolbar composition; size only on the root (Rules/Rule/Builder/Search write no V/C/R/H attrs) |
@@ -117,7 +118,7 @@ from the closest RT category (see legend).
 | PasswordInput | Custom → TextField | ✓ | ✓ | — | ✓ | — | Input-like; variant+size+radius |
 | PhoneInput | Custom → TextField | ✓ | ✓ | — | — | — | Input-like; variant+size (density writes data-size); no accent/radius/high-contrast |
 | PageContent | Custom → none | — | — | — | — | — | Padding is represented by classes, not tracked attributes |
-| PageHeader | Custom → none | — | — | — | — | — | Structural page composition; no styling attrs |
+| PageHeader | Custom → none | ✓ | — | — | — | — | Variant only (`default`, `floating`); one fixed height, no size or accent attrs |
 | Pills | Custom → Badge | ✓ | ✓ | ✓ | ✓ | — | Badge-like chip list; V+S+C+R |
 | Popover | Primitive → Dialog | — | ✓ | — | — | — | Content size by Dialog analogy |
 | Progress | RT Progress | ✓ | ✓ | ✓ | — | ✓ | RT Progress: no radius |
@@ -188,13 +189,14 @@ from the closest RT category (see legend).
 | V+S+R | Editable, NumberInput, PasswordInput, SearchBar, TagsInput | 5 |
 | V+S+H | Toggle, ToggleGroup | 2 |
 | V+S | Card, DataList, NativeSelect, SegmentedControl, Select, StatCard, Table, TabNav, Tabs, Toast | 10 |
+| V only | PageHeader | 1 |
 | S+C+H | Heading, Link, Text | 3 |
 | S+C | SegmentedMeter, Separator, Status | 3 |
 | S+R | InputOtp, ScrollArea | 2 |
 | S only | AlertDialog, Breadcrumb, ButtonGroup, Calendar (see above), Carousel, CodeInput,<br>ColorPicker, ColorSwatch, Command, Container, ContextMenu, CopyField, DataTable,<br>DatePicker, Dialog, Drawer, DropdownMenu, EmptyState, Field, FileUpload, FilterBar,<br>FloatingPanel, HoverCard, Icon, InputGroup, Kbd, Label, Menu, Menubar, Metric,<br>NavigationMenu, Pagination, Popover, QrCode, Section, Sheet, Spinner, Stepper,<br>Timeline, TimePicker, ToggleTip, Toolbar, TreeView | 43 |
-| None | AccessibleIcon, Accordion, ArticleNodes, AspectRatio, Banner, Blockquote, BottomDock, Box, Chart,<br>Collapsible, CommentThread, ConfigDrawer, DirectionProvider, Em, Flex, FontProvider,<br>Form, Grid, Inset, Item, Marquee, NotificationCenter, PageContent, PageHeader, Prose, Quote,<br>Resizable, Result, RichTextEditor, Sidebar, Skeleton, Slot, Sonner, SortableList, Stack, Strong,<br>TableOfContents, Theme, ThemePanel, ThemeProvider, Tooltip, VisuallyHidden | 41 |
+| None | AccessibleIcon, Accordion, ArticleNodes, AspectRatio, Banner, Blockquote, BottomDock, Box, Chart,<br>Collapsible, CommentThread, ConfigDrawer, DirectionProvider, Em, EnvironmentRibbon, Flex, FontProvider,<br>Form, Grid, Inset, Item, Marquee, NotificationCenter, PageContent, Prose, Quote,<br>Resizable, Result, RichTextEditor, Sidebar, Skeleton, Slot, Sonner, SortableList, Stack, Strong,<br>TableOfContents, Theme, ThemePanel, ThemeProvider, Tooltip, VisuallyHidden | 41 |
 
-**Total components covered: 132**
+**Total components covered: 133**
 
 ---
 

package/dist/docs/component-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "4.0.0",
+  "packageVersion": "4.0.1",
   "generatedFrom": "docs/design-system",
   "components": [
     {
@@ -651,6 +651,14 @@
       "status": "canonical",
       "documentation": "./components/empty-state.md"
     },
+    {
+      "name": "EnvironmentRibbon",
+      "slug": "environment-ribbon",
+      "category": "Components",
+      "archetype": "primitive",
+      "status": "canonical",
+      "documentation": "./components/environment-ribbon.md"
+    },
     {
       "name": "Field",
       "slug": "field",

package/dist/docs/components/alert.md

@@ -27,17 +27,20 @@ An inline status, warning, or info banner that lives in the page flow. Use Alert
 | `Alert` (root) | `<div>` (or `Slot` host) | Static surface + class | Writes `dsx-alert`, `data-variant`, `data-size`, `data-high-contrast`, `data-accent-color`. Defaults `role` to `"alert"`; consumers can override with a custom `role` prop. Hovering the status surface does not change its semantic color or elevation. |
 | `Alert.Title` | `<h5>` (or `Slot` host) | Slot class | Title text. Writes `dsx-alert__title`. |
 | `Alert.Description` | `<p>` (or `Slot` host) | Slot class | Description text. Writes `dsx-alert__description`. |
-| `Alert.Action` | `<div>` | Slot class | Trailing action container (typically a Button or IconButton). Writes `dsx-alert__action`. |
+| `Alert.Action` | `<div>` | Slot class | Trailing action container (typically a Button or IconButton). Writes `dsx-alert__action`. A direct child of `Alert` is hoisted out of the content container into one `dsx-alert__actions` group: the group trails the row, and wraps below the text as a whole, under the text, when the alert is narrow. |
 
 **Internal layout:**
 
-The root renders a flex row with three regions, in this order:
+The root renders a flex row of two columns, in this order:
 
 1. An icon container (`<span aria-hidden="true" class="dsx-alert__icon">`) that holds the resolved icon. The icon is hidden when `icon === null` and replaced wholesale when `icon` is a `ReactNode`.
-2. A content container (`<div class="dsx-alert__content">`) that wraps whatever the consumer passes as children (typically `Alert.Title` and `Alert.Description`).
-3. The optional `Alert.Action` slot, if the consumer composes it as a child.
+2. A main column (`<div class="dsx-alert__main">`), a wrapping flex row, that holds:
+   1. a content container (`<div class="dsx-alert__content">`) that wraps whatever the consumer passes as children (typically `Alert.Title` and `Alert.Description`);
+   2. when there is at least one direct-child `Alert.Action`, one actions group (`<div class="dsx-alert__actions">`) that holds each of them, in order.
 
-The `Alert.Action` slot is independent of the rest of the layout; the consumer can place it inside the content area or as a sibling of `Alert.Title` / `Alert.Description` to control alignment.
+A direct-child `Alert.Action` is hoisted out of the content container (`Alert.Title` and `Alert.Description` stay inside it), also when the root is an `asChild` host. The group trails the row (the content grows to push it to the end). Only the main column wraps (`flex-wrap`), so when the text would fall under its readable width the group drops below it as a whole and starts at the text column, under the text and not under the icon; the actions never split across rows. The group has no auto margin, because that would push a wrapped group to the far edge. An action the consumer nests in their own wrapper is not hoisted and stays in the content container. (G-15, 2026-10-05.)
+
+With a trailing action, the icon, the first line of text and the action share one centre at any width: all three get a control-height row (`var(--dsx-size-lg)`), and the first line's box is that tall (`::first-line`). An alert without an action is laid out as before.
 
 ## Props contract
 
@@ -63,6 +66,12 @@ The `Alert.Action` slot is independent of the rest of the layout; the consumer c
 
 `Alert.Title` and `Alert.Description` also accept the standard HTML attributes for their host elements (`<h5>` and `<p>` respectively). `Alert.Action` accepts standard `<div>` attributes.
 
+**`Alert.Description` own prop:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `lineClamp` | `number` | `undefined` | no | Clamp the text to this many lines; the rest is clipped with an ellipsis. Only a whole number of 1 or more clamps; anything else (0, a negative, a fraction, `NaN`) leaves the text unclamped. Writes `data-line-clamp` and the custom property `--dsx-alert-line-clamp` on the description (a consumer `style` is kept); the prop name itself is not written to the DOM. Whether the text is clipped, and how to reveal it, is the consumer's: measure the element (`scrollHeight > clientHeight`) and drop the prop to show everything. | no |
+
 **Variant default icons (when `icon` is `undefined`):**
 
 | `variant` | Icon `name` |
@@ -86,6 +95,7 @@ The icon is rendered with `size="md"` and `strokeWidth="var(--dsx-icon-stroke-wi
 | `data-size` | `sm`, `md`, `lg` | `.dsx-alert[data-size=…]` | `alert.css` |
 | `data-accent-color` | any string | (no rule in `alert.css`; attribute is forwarded) | n/a |
 | `data-high-contrast` | `true` | `.dsx-alert[data-high-contrast='true']` | `baseCard.css` |
+| `data-line-clamp` (on `Alert.Description`) | a whole number of 1 or more | `.dsx-alert__description[data-line-clamp]` | `alert.css` |
 
 **Slot classes:**
 
@@ -93,14 +103,16 @@ The icon is rendered with `size="md"` and `strokeWidth="var(--dsx-icon-stroke-wi
 |---|---|---|
 | `Alert` (root) | `dsx-alert` | `alert.css` |
 | Root icon container | `dsx-alert__icon` | `alert.css` |
+| Root main column (content and actions) | `dsx-alert__main` | `alert.css` |
 | Root content container | `dsx-alert__content` | `alert.css` |
+| Root actions group | `dsx-alert__actions` | `alert.css` |
 | `Alert.Action` | `dsx-alert__action` | `alert.css` |
 | `Alert.Title` | `dsx-alert__title` | `alert.css` |
 | `Alert.Description` | `dsx-alert__description` | `alert.css` |
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. `size`, `variant`, `color`, and `highContrast` are single-value only.
+- The component does not write `@media` rules. `size`, `variant`, `color`, and `highContrast` are single-value only. The action wrap is intrinsic (`flex-wrap` on the main column), not a breakpoint, so it follows the alert's own width, not the window's.
 
 **Reduced motion:**
 
@@ -120,6 +132,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Root text color | `var(--dsx-color-on-surface)` | Default text color |
 | Icon / action minimum size | `var(--dsx-size-md)` | Icon and action slot dimensions |
 | Icon / action color | `currentColor` | Inherits the alert surface color |
+| Content basis | `min(calc(var(--dsx-size-xl) * 5), calc(100% - var(--dsx-size-md) - var(--dsx-space-md)))` | The readable width the text keeps before a trailing action wraps below it; the `min()` stops it forcing the text under the icon in a very narrow alert |
+| Control row (with an action) | `var(--dsx-size-lg)` | Min height of the icon and action, and the line box of the first line, so the three share a centre |
+| Clamped first line (with an action) | `padding-block-start: calc((var(--dsx-size-lg) - 1lh) / 2)` | `::first-line` cannot reach into the `-webkit-box` a clamped description is, so the first line is centred on the control row with padding instead |
+| Line clamp | `--dsx-alert-line-clamp` (written by the component from `lineClamp`) | The number of lines the description keeps; read by `-webkit-line-clamp` |
 | Title type ramp | `var(--dsx-typography-label-large-*)` | Title text scale |
 | Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text scale |
 | Description opacity | `var(--dsx-opacity-subtle, 0.85)` | Subtle fade for description text |
@@ -186,7 +202,11 @@ The component has no motion. It is a static inline surface.
 
 **Composition story:**
 
-- Renders an alert with `Alert.Title`, `Alert.Description`, and `Alert.Action` populated. Asserts the `dsx-alert__title`, `dsx-alert__description`, and `dsx-alert__action` classes are present.
+- Renders an alert with `Alert.Title`, `Alert.Description`, and `Alert.Action` populated. Asserts the `dsx-alert__title`, `dsx-alert__description`, and `dsx-alert__action` classes are present, and that the action sits in the one `dsx-alert__actions` group after the content container inside `dsx-alert__main`, not inside the content (several actions share the one group). `src/test/styles/alert-wrap-layout.test.ts` guards the rules that make the group wrap as a whole under the text column. A second composition nests the action in the consumer's own wrapper and asserts it stays in the content.
+
+**Clamp story:**
+
+- Renders an alert whose `Alert.Description` has `lineClamp={2}` and a long text, with a trailing action. Asserts `data-line-clamp="2"` and the `--dsx-alert-line-clamp` property; the registry row shows the text clipped to two lines with an ellipsis and the icon, first line and action on one centre. A value that is not a whole number of 1 or more leaves the text unclamped (tested).
 
 **Token story:**
 
@@ -230,7 +250,7 @@ The component has no motion. It is a static inline surface.
 ## Overlay review composition
 
 Content has min-width=0 and wraps long copy; the optional icon does not shrink.
-Actions wrap and align to the content start. Light-mode semantic borders retain
+A trailing action shares the row with the text and wraps below it, at the alert's start edge, when the text would drop under its readable width. Light-mode semantic borders retain
 warning/success/error roles after the shared card base rules. Default accent
 styling and highContrast remain token-driven. `/docs/alert` demonstrates all
 four tones, reconnect feedback and dismiss/restore through real actions.

package/dist/docs/components/bottom-dock.md

@@ -46,7 +46,7 @@ navigation bar (2–5 destinations; the selected destination always shows its la
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `placement` | `'fixed' \| 'contained'` | `'fixed'` | no | `fixed` pins the dock to the viewport bottom and adds `--dsx-safe-area-inset-bottom`; `contained` positions it absolutely inside the nearest positioned ancestor (demos, framed compositions). | no |
-| `labels` | `'active' \| 'always'` | `'active'` | no | `active`: only the current item draws its label (Material 3); `always`: every item draws its label (HIG-style). Hidden labels stay in the accessible name. | no |
+| `labels` | `'active' \| 'always' \| 'none'` | `'active'` | no | `active`: only the current item draws its label (Material 3); `always`: every item draws its label (HIG-style); `none`: no label is drawn and the items are icon-only, for widths where five labels do not fit (about 340px and below), picked by the app by width. Hidden labels stay in the accessible name in every mode. | no |
 | `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. | no |
 | `aria-label` | `string` | `'Bottom navigation'` | no | The landmark name; override with product copy. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-bottom-dock`. | no |
@@ -77,7 +77,7 @@ Rules:
 | Attribute | Allowed values | Hook | CSS file |
 |---|---|---|---|
 | `data-placement` | `fixed`, `contained` | `.dsx-bottom-dock:where([data-placement='contained'])` switches to absolute positioning | `bottom-dock.css` |
-| `data-labels` | `active`, `always` | recorded for consumers and tests; the visible/hidden decision is per item through `data-label` | `bottom-dock.css` |
+| `data-labels` | `active`, `always`, `none` | `none` shares the width between icon-only items (`.dsx-bottom-dock:where([data-labels='none']) .dsx-bottom-dock__item`); the visible/hidden decision is per item through `data-label` | `bottom-dock.css` |
 | `data-active` | `true` | `.dsx-bottom-dock__item:where([data-active='true'])` — the opaque accent container | `bottom-dock.css` |
 | `data-label` | `visible`, `hidden` | recorded on the item for consumers and tests; the hidden label is removed from the layout through `VisuallyHidden` | `bottom-dock.css` |
 | `data-slot` | `bottom-dock-*` | hooks | `bottom-dock.css` |
@@ -119,7 +119,7 @@ Rules: no raw colour, spacing, radius or motion values in `bottom-dock.css`.
 ## Accessibility
 
 - `BottomDock` is a named `nav` landmark.
-- The current item has `aria-current="page"`; the active state is also carried by the container fill and the visible label (not colour alone).
+- The current item has `aria-current="page"`; the active state is also carried by the container fill and the visible label (not colour alone). With `labels="none"` no label is visible, so the container fill (the opaque primary container, not the accent colour alone) and `aria-current` carry it, and every label stays in the accessible name.
 - Every item has an accessible name: its `BottomDock.Label` (kept in the DOM through `VisuallyHidden` when not drawn) or its own `aria-label`.
 - Touch targets are at least 44px; focus is a visible ring; the whole dock is reachable in normal tab order.
 - A badge with text is part of the item's accessible name ("Devices 3"); an empty dot badge adds nothing. Place the badge inside `BottomDock.Icon` to sit on the glyph (the icon wrapper is `aria-hidden`, so a count placed there is not announced).
@@ -127,7 +127,7 @@ Rules: no raw colour, spacing, radius or motion values in `bottom-dock.css`.
 ## Playground demo spec
 
 **Default story:** four `BottomDock.Item`s (icon + label) in a `contained` dock, the first active.
-**Variant stories:** `labels="always"` beside the default `active`; `placement="contained"` is the demo default.
+**Variant stories:** `labels="always"` and `labels="none"` beside the default `active`; `placement="contained"` is the demo default. The `none` fixture sits in a 320px-wide frame with five items.
 **State stories:** an active item; an item with a count badge; an item with a dot badge; keyboard focus.
 **Composition story:** the dock with a "More" item that opens a `Sidebar` drawer (mobile) — documented, driven by `useSidebar()`.
 **Token story:** inside `Theme` with each of the five accents (the active container and the badge vary by accent).

package/dist/docs/components/card.md

@@ -126,7 +126,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Glass inset rim | `var(--dsx-effect-panel-glass-rim)` | Theme-aware subtle inset perimeter |
 | Glass border | `var(--dsx-effect-panel-glass-border)` | Theme-aware outer edge |
 | Shadow (glass) | `var(--dsx-shadow-panel-shadow)` | Glass shadow |
-| Glass backdrop | `var(--dsx-effect-panel-glass-backdrop-filter)` | Glass blur |
+| Glass backdrop | `var(--dsx-effect-panel-glass-backdrop-filter)` | Glass blur. Declared as `-webkit-backdrop-filter` first and the standard `backdrop-filter` last: the Next/Turbopack CSS pipeline drops the standard line when it comes first, and the blur silently disappears (B-1, 2026-10-04). This spec directs that order in `_internal/baseCard.css`; `src/test/styles/backdrop-filter-order.test.ts` guards it for every rule in the package. |
 | Surface (elevated) | `var(--dsx-color-surface-raised)` | Elevated surface |
 | Shadow (elevated) | `var(--dsx-shadow-elevation-3, var(--dsx-effect-shadow-3))` (hover: `--elevation-4`) | Elevated shadow |
 | Surface (filled) | `var(--dsx-color-surface)` | Filled surface (no shadow) |

package/dist/docs/components/collapsible.md

@@ -88,6 +88,10 @@ Rules:
   ```
   The expand/collapse keyframes (`dsx-collapsible-expand`, `dsx-collapsible-collapse`) are gated off when the user prefers reduced motion. The chevron rotation uses `var(--dsx-motion-duration-fast)` and is disabled in component CSS under reduced motion.
 
+**Force-mounted content** (`Collapsible.Content forceMount`, used by `Sidebar.MenuSubTrigger`):
+
+- The closed look of the content is the end frame of `dsx-collapsible-collapse` (`height: 0`, `opacity: 0`, `visibility: hidden`, held by the `both` fill). A force-mounted panel that first mounts closed never plays that animation, because Radix suppresses the mount animation by writing `animation-name: none` on the element. The runtime-inserted style block therefore hides it at rest: `.dsx-collapsible__content[data-state='closed']:where([style*='animation-name: none']) { display: none; }`. After any toggle Radix puts the animation back and the panel animates out as usual. Without this rule a closed sidebar parent listed all of its children (G-14, 2026-10-05).
+
 ## Token mapping
 
 Every CSS value the component paints is a `var(--dsx-*)` token.
@@ -132,6 +136,7 @@ Content height and vertical padding animate together from zero to their measured
 **Focus:**
 
 - The trigger renders a visible focus ring via `box-shadow: var(--dsx-shadow-focus-ring)` on `:focus-visible`.
+- A collapsed force-mounted panel is out of the tab order: the end frame of the collapse animation sets `visibility: hidden`, and a panel that mounted closed is `display: none`. Radix unmounts a panel that is not force-mounted.
 
 **Reduced motion:**
 

package/dist/docs/components/dialog.md

@@ -180,7 +180,7 @@ Rules:
 | Close button size | `var(--dsx-size-lg)` | Square tap target. |
 | Close button radius | `var(--dsx-rounded-full)` | Round close. |
 | Close button offset | `var(--dsx-space-md)` | Distance from the corner. |
-| Backdrop blur | `var(--dsx-blur-md, 8px)` | Optional blur. |
+| Backdrop blur | `var(--dsx-blur-md, 8px)` | Optional blur. `-webkit-backdrop-filter` is declared before `backdrop-filter` so the bundler keeps the standard line (see `card.md`, B-1). |
 | 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. |

package/dist/docs/components/environment-ribbon.md

@@ -0,0 +1,126 @@
+---
+title: EnvironmentRibbon
+status: canonical
+category: Components
+archetype: primitive
+depends_on:
+  - "@radix-ui/react-slot (powers `asChild`)"
+---
+
+# EnvironmentRibbon
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A floating warning pill that says the app is not running in production, with a warm haze behind the top edge so the warning reads on
+every page without taking layout. It is a static label: no close control, no action, no environment logic. The app decides when to
+render it (off production only) and passes the label (for example "Staging environment"); the component is only the surface.
+
+It is **not** a `Banner` (a hero mass: label, headline value), an `Alert` (an in-flow message with actions) or a `Badge` (an inline chip
+that cannot float or carry a haze). One fixed hue, the `warning` ramp, for every environment: the label tells STAGE from DEV.
+
+Wild references (decisions in `docs/feature/design-system/environment-ribbon/decisions.md`): `django-admin-env-notice` (a label and colour per
+environment, fixed to the top or floating), `wp-environment-ribbon` (a slim ribbon on every admin screen, hidden in production), the GOV.UK
+phase banner (a tag and a sentence on every page of a service).
+
+## Anatomy & slots
+
+**Parent:** `EnvironmentRibbon`, a flat export with no slots. It renders two siblings: an optional decorative haze, then the pill.
+
+| Part | Element | Renders | Notes |
+|---|---|---|---|
+| pill | `<div role="status">` (or `Slot` child when `asChild`) | `dsx-environment-ribbon` + `data-slot="environment-ribbon"` + `data-placement` | The label is its children; put an `Icon` inside for a glyph. |
+| haze | `<span aria-hidden="true">` | `dsx-environment-ribbon__haze` + `data-slot="environment-ribbon-haze"` + `data-placement` | Decorative; omitted with `haze={false}`. Not a public slot. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `placement` | `'fixed' \| 'contained'` | `'fixed'` | no | `fixed` pins the pill to the viewport top and the haze to the viewport; `contained` positions both absolutely inside the nearest positioned ancestor (demos, framed compositions). | no |
+| `haze` | `boolean` | `true` | no | Draws the warm haze behind the top edge. `false` draws the pill alone. | no |
+| `asChild` | `boolean` | `false` | no | Renders the pill through `Slot`; the consumer supplies the host element. | no |
+| `role` | `string` | `'status'` | no | Native attribute; override only with a reason. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-environment-ribbon`. | no |
+
+Rules:
+
+- Children are the label: one short line. A label wider than the room truncates with an ellipsis; shorten the label rather than expect a wrap.
+- The component knows no environment. The app renders it only when the environment is not production.
+- The haze needs an isolated ancestor (`isolation: isolate`, as `.dsx-brand-ambient` is). It paints behind in-flow content and glass panels, over
+  that ancestor's background. Without an isolated ancestor the haze can fall behind an opaque wrapper background and not show.
+- Render it once per frame, not per page.
+
+## CSS class contract
+
+**Root class:** `dsx-environment-ribbon`
+
+| Attribute | Allowed values | Hook | CSS file |
+|---|---|---|---|
+| `data-placement` | `fixed`, `contained` | `.dsx-environment-ribbon:where([data-placement='contained'])` and the haze's twin switch to absolute positioning | `environment-ribbon.css` |
+| `data-slot` | `environment-ribbon`, `environment-ribbon-haze` | hooks | `environment-ribbon.css` |
+
+**Classes:** `dsx-environment-ribbon`, `dsx-environment-ribbon__haze`.
+
+No `data-variant`, `data-size`, `data-accent-color`, `data-radius` or `data-high-contrast` is written (contract profile: none).
+
+**Responsive behavior:** none in CSS. On a phone the frame reserves the row the pill occupies; the component writes no breakpoints.
+
+**Reduced motion:** not applicable; the ribbon has no motion.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Position (fixed) | `inset-block-start: var(--dsx-space-sm)`; `inset-inline: var(--dsx-space-3)`, `margin-inline: auto`, `inline-size: fit-content` | centred with logical properties, so it holds in right-to-left |
+| Width cap | `max-inline-size: calc(100% - 2 * var(--dsx-space-3))` | the containing block less the two gutters; without it `nowrap` makes the pill refuse to shrink (min-content equals max-content), so a long label would spill instead of truncating |
+| Stacking | `var(--dsx-z-index-fixed)` | above sticky chrome, below overlays and modals |
+| Surface | `var(--dsx-color-warning-container)` | the `Badge` warning recipe, the look passed in the vision |
+| Ink | `var(--dsx-color-on-warning-container)` | paired ink |
+| Border | `var(--dsx-border-width-sm) solid var(--dsx-color-warning)` | keeps the edge over the haze; survives forced-colors |
+| Shadow | `var(--dsx-panel-shadow)` | floating elevation |
+| Radius | `var(--dsx-rounded-full)` | pill |
+| Padding | `var(--dsx-space-xs)` block, `var(--dsx-space-sm)` inline | as `Badge` |
+| Min height | `var(--dsx-size-md)` | as `Badge` size md |
+| Type | `var(--dsx-typography-label-small-*)` | compact label |
+| Haze colour | `color-mix(in srgb, var(--dsx-color-warning) calc(var(--dsx-effect-ambient-strength) * <multiple>), transparent)` | a multiple (3.2, written inline in the rule, as Sidebar's ambient wash does) of the theme-aware accent-haze strength: 32% in dark, about 51% in light. Tuned in the browser and kept (batch `decisions.md` D-10); stronger than the accent haze's primary wash (2.2) on purpose, since a warning has to read on every page |
+| Haze stacking | `z-index: -1` | behind panels and in-flow content, over the isolated ancestor's background |
+
+The haze geometry is a radial gradient in rem, anchored at the top centre and fading to transparent; no raw colour.
+
+Rules: no raw colour, spacing, radius or motion values in `environment-ribbon.css`.
+
+## Accessibility
+
+- The pill is `role="status"`: advisory information, not an alert (MDN, `status` role). It is a polite live region by definition. The
+  component does not rely on a screen reader announcing it when it appears (MDN does not say whether static content at load is announced);
+  its text is the region's content, in the reading order. The `status` role takes no accessible name from content and needs none; a consumer
+  who wants a name passes `aria-label`. Verification reads the browser's accessibility tree.
+- Never focusable and never takes focus. Not dismissible (PASSPORT R-13: it must read as a warning on every page).
+- The meaning is in the words, not the colour: the label says which environment. The haze is `aria-hidden` and decorative.
+- Contrast: the pill uses the container pair that `Badge variant="warning"` uses (`qa:contrast` covers the pair); the haze carries no text.
+- Forced colors: the hairline border keeps the pill's edge when fills are replaced.
+
+## Playground demo spec
+
+**Default story:** a framed, isolated box with a `contained` ribbon reading "Staging environment", haze on.
+**Variant stories:** `haze={false}` (the pill alone) beside the default; `placement="contained"` is the demo default (`fixed` pins to the playground
+viewport and is documented only).
+**State stories:** a long label in a 320px frame (truncation, no overflow).
+**Composition story:** the ribbon over a glass panel inside a `dsx-brand-ambient` wrapper, showing the layering (haze behind the panel's blur, pill on top).
+**Token story:** inside `Theme` with each of the five accents (the warning hue does not change; the accent haze beside it does).
+**A11y story:** `EnvironmentRibbon.test.tsx` runs `vitest-axe`.
+
+| Prop | Control | Default |
+|---|---|---|
+| `placement` | select | `contained` (demo) |
+| `haze` | boolean | `true` |
+
+## Wiring notes
+
+**Composes from:** `@radix-ui/react-slot`.
+
+**State boundaries:** owned by `EnvironmentRibbon`: nothing persistent. Owned by the consumer: whether to render it (not in production), the label and its
+translation, the room the pill takes at phone widths, and the isolated ancestor the haze needs.
+
+**Used by (planned):** the `frontend-admin` shell frame (`frontend/admin/shell`), once per frame, only when the admin context's environment is STAGE or DEV.

package/dist/docs/components/field.md

@@ -92,6 +92,7 @@ Rules:
 **Responsive behavior:**
 
 - The `responsive` orientation uses `grid-template-columns: repeat(auto-fit, minmax(var(--dsx-size-popover-min-width), 1fr))`. The CSS does not write `@media` rules directly. None of the prop defs are `responsive: true`.
+- The `vertical` orientation, the control region (`Field.Content`), `Field.Group` and `Field.Set` have one column, `minmax(0, 1fr)`, so a control with a wide intrinsic width (a password input at about 300px) shrinks with a narrow container instead of widening the row past it (G-22, `docs/feature/design-system/field-narrow-track/`).
 
 **Reduced motion:**
 
@@ -105,6 +106,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Row gap | `var(--dsx-space-xs)` | Default row gap. |
 | Row min-width | `0` | Allows the grid to shrink. |
+| Column (vertical orientation, control region, group, fieldset) | `minmax(0, 1fr)` | One column that fills the container and never asks for more. Without it the implicit `auto` track is sized from the controls' min-content (a native input is about 20 characters wide), so a field spilled past a narrow card. |
 | Horizontal label column | `minmax(var(--dsx-size-field-label-min), var(--dsx-size-field-label-max))` | Label column size for `horizontal` orientation. |
 | Horizontal label alignment | `end` | Label text magnetizes toward the control in `horizontal` orientation. |
 | Horizontal row column gap | `var(--dsx-space-md)` | Row gap for `horizontal` orientation. |

package/dist/docs/components/icon.md

@@ -40,6 +40,7 @@ Rules:
 - `Icon` extends `Omit<React.ComponentPropsWithoutRef<'svg'>, 'color'>` because `color` is redefined. The runtime uses `LucideComponent` or `SimpleIconComponent` for the underlying SVG; both forward standard SVG attributes.
 - The `name` prop is the only visual contract. The internal `isDSXIconName` guard returns `null` for unknown names so callers do not need to handle a missing icon fallback at the call site.
 - The component always writes `data-size` and `class="dsx-icon"`. The `aria-hidden` and `role` attributes are managed by the runtime based on whether `title` is provided.
+- A name lives in four hand-kept lists: the component map, the `DSXIconName` tuple, `dsxIconCatalog` and one named export in `icons.tsx` (`check` → `CheckIcon`). `Icon.test.tsx` keeps them in step (every catalog name renders an `svg`, and the catalog names and the named exports are the same set). One glyph has one name: `dots-horizontal` is Lucide's `Ellipsis`, and no `ellipsis` alias exists.
 
 ## CSS class contract