@d4gger/design-system 4.0.0 → 4.0.1

package/dist/docs/components/notification-center.md

@@ -29,7 +29,7 @@ An inbox-style notification surface that groups header, list, and footer regions
 | `NotificationCenter.List` | `<div>` (or `Slot` host) | `dsx-notification-center__list` | Vertical list of items. Capped at `max-height: 400px` with `overflow-y: auto`. |
 | `NotificationCenter.Footer` | `<div>` (or `Slot` host) | `dsx-notification-center__footer` | Footer row (typically a "View all" link or button). |
 | `NotificationCenter.Item` | `<div>` (or `Slot` host) | `dsx-notification-center__item` (with `--unread` modifier when `unread` is true) | A single notification row. The CSS file ships helper classes `dsx-notification-center__item-title`, `dsx-notification-center__item-description`, and `dsx-notification-center__item-time` for the typical layout. |
-| `NotificationCenter.Trigger` | `IconButton` containing Icon + Badge | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger (size `sm`, variant `ghost`) with an accessible unread-count name. The badge sits at the bell's upper trailing corner (capped at `'99+'`); the host reserves the count's width and asChild preserves child/ref composition. |
+| `NotificationCenter.Trigger` | `IconButton` containing Icon + Badge | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger (size `sm`, variant `ghost`) with an accessible unread-count name. The count hangs on the bell's upper trailing corner (capped at `'99+'`, or at `{max}+` when `max` is set) and the hover highlight covers the bell only; asChild preserves child/ref composition. |
 
 **Internal layout:**
 
@@ -37,7 +37,7 @@ An inbox-style notification surface that groups header, list, and footer regions
 - In the `popover` variant (the default), the root is sized `width: var(--dsx-sheet-width-sm), max-width: 100%`, has a `var(--dsx-rounded-lg)` radius, a 1px outline, an `var(--dsx-color-panel-translucent)` background, and a `var(--dsx-shadow-card-md)` shadow.
 - In the `sidebar` variant, the root is full-width / full-height with a flat `var(--dsx-color-surface)` background and no border or shadow.
 - `NotificationCenter.Item` rows have a `var(--dsx-space-md)` padding and a 1px bottom border. The last item drops the bottom border. The item background switches to `var(--dsx-color-surface-raised)` with a 1px primary left border when `unread` is true.
-- `NotificationCenter.Trigger` is an `inline-flex` button with intrinsic width and a 44px minimum width/height (`size-xl + space-xs`). The 16px badge is raised by 8px at the bell's trailing corner, with a 4px horizontal overlap and 8px host padding. Normal flow reserves the badge width; increasing counts grow toward the trailing edge rather than covering the bell. The badge uses rounded-full and label-small typography.
+- `NotificationCenter.Trigger` is an ordinary `IconButton` (size `sm`, 32px, the same shape as every other header icon), so its hover highlight covers the bell only (G-20, 2026-10-05; it used to be a 59×44 pill that wrapped the count). The count is absolutely positioned on the bell's upper trailing corner: raised by `space-sm`, starting `space-xs` past the glyph's centre, so a constant 4px of it overlaps the bell and wider counts grow toward the trailing edge. The trigger reserves `space-md` after itself for the count, always, so the controls after it do not move when a count appears. A pseudo-element keeps the hit area at 44px (`size-xl + space-xs`) around the 32px highlight. The badge uses rounded-full and label-small typography.
 
 ## Props contract
 
@@ -64,7 +64,8 @@ These three slots accept only `asChild` plus the standard HTML attribute surface
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `unreadCount` | `number` | `undefined` | no | Unread count rendered as a `Badge` (capped at `'99+'`). The badge is only rendered when the count is greater than zero. | no |
+| `unreadCount` | `number` | `undefined` | no | Unread count rendered as a `Badge` (capped at `max`, `'99+'` by default). The badge is only rendered when the count is greater than zero. | no |
+| `max` | `number` | `99` | no | Largest count the badge draws; above it the badge reads `{max}+` (core's bell uses `9`). A value that is not a positive whole number falls back to `99`. The accessible name keeps the real count (“Notifications, 12 unread”), and `max` is not written to the DOM. Follows MUI `Badge` `max` and Ant Design `overflowCount`. | no |
 | `aria-label` | `string` | `'Notifications'` | no | Accessible name on the underlying `IconButton`. Override to localize or to disambiguate when more than one trigger is on the page. | no |
 | `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
 
@@ -138,9 +139,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item time type ramp | `var(--dsx-typography-label-small-*)` | Item time text |
 | Footer padding | `var(--dsx-space-sm)` | Footer gutter |
 | Footer border-top | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Footer separator |
-| Trigger width / minimum dimensions | `auto` / `calc(var(--dsx-size-xl) + var(--dsx-space-xs))` | Count expands the 44px button |
-| Trigger gap / inline padding | `0` / `var(--dsx-space-sm)` | Count corner containment |
-| Badge placement | relative, raised by space-sm, negative space-xs inline margin | Upper trailing corner; reserves count width |
+| Trigger size | the `IconButton` `sm` size (32px), no override | An ordinary header icon button; the highlight covers the bell only (G-20) |
+| Trigger inline-end margin | `var(--dsx-space-md)` | Reserves the room the hanging count needs, always, so the controls after the bell do not move when a count appears |
+| Trigger hit area | `::after`, `inset: calc((100% - (var(--dsx-size-xl) + var(--dsx-space-xs))) / 2)` | A 44px target around the 32px highlight (the inset shrinks to nothing on a larger size) |
+| Badge placement | absolute, `top: calc(-1 * var(--dsx-space-sm))`, `inset-inline-start: calc(50% + var(--dsx-space-xs))` | Upper trailing corner, a constant 4px overlap with the bell glyph; wider counts grow toward the trailing edge |
 | Badge min-width | `var(--dsx-size-sm)` | Badge min width |
 | Badge height | `var(--dsx-size-sm)` | Badge height |
 | Badge radius | `var(--dsx-rounded-full)` | Badge roundness |
@@ -160,7 +162,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 - The root renders as a `<div>` without an explicit `role`. The canonical pattern is to wrap the panel in a `Popover` or `Sheet`; the wrapping surface is responsible for the modal / non-modal role and focus management.
 - `NotificationCenter.List` is a plain `<div>`. If the consumer wants to expose the list as an `aria-live` region (e.g. for incoming notifications), they can add the `aria-live` and `aria-relevant` attributes manually.
-- `NotificationCenter.Trigger` renders an IconButton named “Notifications” at zero, or “Notifications, N unread” when positive. An explicit aria-label overrides this fallback. The visual badge is aria-hidden; it stays at the bell's upper trailing corner inside the trigger host.
+- `NotificationCenter.Trigger` renders an IconButton named “Notifications” at zero, or “Notifications, N unread” when positive. An explicit aria-label overrides this fallback. The visual badge is aria-hidden; it hangs on the bell's upper trailing corner.
 
 **Keyboard:**
 
@@ -172,7 +174,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Focus:**
 
 - The component does not render a focus ring on items or panels. Interactive content provides its own ring.
-- The trigger button gets the standard `IconButton` focus ring and a minimum 44px target containing both the bell and count.
+- The trigger button gets the standard `IconButton` focus ring. Its visible box is 32px; a pseudo-element extends the hit area to 44px around the bell. The count hangs outside the box and is not part of the target (it is aria-hidden; the accessible name carries the number).
 
 **Reduced motion:**
 
@@ -204,6 +206,9 @@ The component has no motion. The panel itself is static; transitions on open / c
 - Renders an `Item` with `unread`. Asserts `data-unread="true"` and the `--unread` modifier class.
 - Renders a `Trigger` with `unreadCount={5}`. Asserts the badge text is `'5'`.
 - Renders a `Trigger` with `unreadCount={150}`. Asserts the badge text is `'99+'`.
+- Renders a `Trigger` with `unreadCount={12}` and `max={9}`. Asserts the badge text is `'9+'` and the accessible name still reads “Notifications, 12 unread”. A count equal to `max` draws the number; an invalid `max` (0, negative, fractional, NaN) falls back to `'99+'`.
+
+- `src/test/styles/shell-look-pass.test.ts` guards the trigger's CSS contract (an ordinary icon button, a corner-anchored count, the 44px hit-area pseudo-element, the reserved margin); `apps/playground/tests/overlay-feedback-review.spec.ts` measures the geometry and the hit area at 1280 / 390 / 320px. They supersede the earlier contract (a control of at least 44×44 with the count contained in it) (G-20, 2026-10-05).
 
 **Composition story:**
 
@@ -229,7 +234,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Composes from:**
 
 - `IconButton` (`src/components/iconButton`): the trigger renders a small ghost `IconButton`. The trigger forwards all `IconButton` props and defaults `aria-label="Notifications"`.
-- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="primary"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` for counts greater than 99.
+- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="primary"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` (or `{max}+` when `max` is set) for counts greater than the cap.
 - `@radix-ui/react-slot`: enables `asChild` on the root and on the named slots.
 
 **Used by:**

package/dist/docs/components/page-header.md

@@ -13,7 +13,7 @@ depends_on:
 
 ## Purpose
 
-A fixed-height header bar for the content area of a cabinet/shell layout: a title on the left, trailing actions on the right. Designed to be the first child inside `.dsx-sidebar__inset` (the content column `Sidebar` leaves for the app to fill), so every app screen shares one header height and padding scale instead of inventing its own.
+A fixed-height header bar for the content area of a cabinet/shell layout: a title on the left, trailing actions on the right. Designed to be the first child inside `.dsx-sidebar__inset` (the content column `Sidebar` leaves for the app to fill), so every app screen shares one header height and padding scale instead of inventing its own. A `floating` variant draws the same bar as a glass panel with its own edge, for shells whose content column sits beside a floating sidebar (direction C of the `frontend` vision).
 
 ## Anatomy & slots
 
@@ -23,7 +23,7 @@ A fixed-height header bar for the content area of a cabinet/shell layout: a titl
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `PageHeader.Root` | `<div>` | `dsx-page-header` | Fixed-height flex row, `justify-content: space-between`. Holds `Title` and `Actions`. |
+| `PageHeader.Root` | `<div>` | `dsx-page-header` + `data-variant` | Fixed-height flex row, `justify-content: space-between`. Holds `Title` and `Actions`. |
 | `PageHeader.Title` | `<h1>` | `dsx-page-header__title` | The page's h1. Single-line, truncates with ellipsis rather than wrapping. |
 | `PageHeader.Actions` | `<div>` | `dsx-page-header__actions` | Trailing flex row for buttons/icon buttons. Optional — a header with only a title is valid (see empty-state test). |
 
@@ -31,6 +31,7 @@ A fixed-height header bar for the content area of a cabinet/shell layout: a titl
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
+| `variant` | `'default' \| 'floating'` | `'default'` | no | Surface treatment; writes `data-variant`. `default`: the flat opaque bar with a bottom rule. `floating`: a glass panel with its own edge, radius and shadow (the `Card variant="glass"` recipe). The height and the slots are the same in both. | no |
 | `asChild` | `boolean` | `false` | no | Renders `Root` through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-page-header`. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Typically `PageHeader.Title` followed by an optional `PageHeader.Actions`. | no |
@@ -39,14 +40,14 @@ A fixed-height header bar for the content area of a cabinet/shell layout: a titl
 
 Rules that apply to this row:
 
-- `PageHeader` is a behavioral/layout composite, not a styled variant surface. It does not run a `variant` or `size` prop def — one shape, one height.
+- `PageHeader` has one height at every width and no `size` axis. Its only axis is `variant` (`default` / `floating`), which changes the surface, never the height. An unknown value falls back to `default`.
 - `PageHeader.Title` renders `h1` by default. A page should have exactly one; nested `Theme`/route-level headings should not duplicate it.
 
 ## CSS class contract
 
 **Root class:** `dsx-page-header`
 
-**Modifier classes:** none. No `data-variant`/`data-size` — the header has one fixed shape.
+**Modifier attributes:** `data-variant` (`default`, `floating`), written by the component; `.dsx-page-header:where([data-variant='floating'])` in `page-header.css` carries the glass surface. No `data-size` — the header has one fixed height.
 
 **Slot classes:**
 
@@ -73,6 +74,12 @@ Rules that apply to this row:
 | Gap | `var(--dsx-space-md)` | Gap between title and actions when both are near the edge. |
 | Border (bottom) | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline-variant)` | Separates the header from scrolled content below it. |
 | Background | `var(--dsx-color-surface)` | Matches the surrounding shell surface. |
+| Floating edge | `var(--dsx-border-width-sm)` + `var(--dsx-effect-panel-glass-border)` on all four sides | `variant="floating"`; replaces the bottom rule. |
+| Floating radius | `var(--dsx-rounded-lg)` | `variant="floating"`; the same as `Card`'s default radius. |
+| Floating surface | `var(--dsx-color-panel-translucent)` | `variant="floating"`; the glass fill. |
+| Floating rim | `var(--dsx-effect-panel-glass-rim-highlight)`, `var(--dsx-effect-panel-glass-rim)` | `variant="floating"`; the same two inset layers as `Card variant="glass"`. |
+| Floating shadow | `0 var(--dsx-shadow-offset-lg) var(--dsx-shadow-blur-md) calc(-1 * var(--dsx-shadow-offset-lg)) var(--dsx-effect-shadow-card-strong)` | `variant="floating"`; the shadow falls below the bar only (offset equals the negative spread, so it starts at the bar's bottom edge). The bar sits flush at the edge of a scroll container (`Sidebar.Inset`, `overflow: auto`) that clips what is painted past its left, right and top edges, so the full-ring `--dsx-shadow-panel-shadow` ended in a vertical cut at the bar's side in the light theme (G-21). This is the one place the floating bar differs from `Card variant="glass"`. Guarded by `src/test/styles/page-header-shadow.test.ts`. |
+| Floating blur | `var(--dsx-effect-panel-glass-backdrop-filter)` | `variant="floating"`; declared as `-webkit-backdrop-filter` first, `backdrop-filter` last (see `card.md`). |
 | Title font | `var(--dsx-typography-headline-medium-*)` family | 24px/600, the DS's headline-medium scale — sized for a 72px bar. |
 | Title color | `var(--dsx-color-on-surface)` | Primary text. |
 | Actions gap | `var(--dsx-space-sm)` | Gap between action buttons. |
@@ -80,6 +87,7 @@ Rules that apply to this row:
 Rules:
 
 - No raw px/color values in `page-header.css`. The 72px height is a `calc()` of two spacing tokens, not a hardcoded value.
+- The floating blur only shows when content passes under the bar (a sticky header over a scrolling page). The DS does not make the bar sticky or give it a margin: the page decides where it sits.
 
 ## Motion contract
 
@@ -131,6 +139,10 @@ The live example uses a compact named icon action so the title remains readable
 
 - Renders `PageHeader` with both `Title` and `Actions` (one or two buttons). Asserts both slots render with their classes.
 
+**Variant story:**
+
+- Renders `PageHeader` with `variant="default"` and `variant="floating"`. Asserts the matching `data-variant` attribute; the floating bar keeps the title and actions slots and the same height.
+
 **Empty-state story:**
 
 - Renders `PageHeader` with only `Title`, no `Actions` — the header still renders correctly with no trailing content.
@@ -145,7 +157,7 @@ The live example uses a compact named icon action so the title remains readable
 |---|---|---|
 | (not exposed) | n/a | n/a |
 
-`PageHeader` has no variant/size axis to expose; the playground demonstrates it via a static composition fixture (title + actions) rather than a controls panel.
+`PageHeader` has no size axis, and its `variant` is shown as two fixtures (default and floating) in one composition rather than a controls panel.
 
 ## Wiring notes
 
@@ -159,7 +171,7 @@ The live example uses a compact named icon action so the title remains readable
 
 **State boundaries:**
 
-- Owned by `PageHeader`: the root class, fixed height, padding, and the two slot classes.
+- Owned by `PageHeader`: the root class, `data-variant`, the fixed height, padding, the surface of each variant, and the two slot classes.
 - Owned by the consumer: the title text, which actions render, and their handlers.
 
 **Boundary rules:**

package/dist/docs/components/sidebar.md

@@ -46,14 +46,14 @@ A panel and cabinet shell navigation surface. The DS `Sidebar` exposes a provide
 | `Sidebar.MenuBadge` | `<span>` | `dsx-sidebar__menu-badge` plus the text Badge classes or the `--ring` / `--accent` modifier + `data-slot="sidebar-menu-badge"` + `data-state` | A count, proportional usage ring, or quiet accent value. Remains in the DOM but is visually hidden when the panel collapses. |
 | `Sidebar.MenuAction` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-action dsx-button` + `data-slot="sidebar-menu-action"` + `data-state` | An action button revealed on hover. |
 | `Sidebar.MenuButton` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-button dsx-button` + `dsx-sidebar__menu-button-text` (when children are a string or number) + `data-slot="sidebar-menu-button"` + `data-active` + `data-state` | A menu button. |
-| `Sidebar.MenuSkeleton` | `<div>` | `dsx-sidebar__menu-skeleton` + `dsx-skeleton dsx-skeleton--circle` (icon) + `dsx-skeleton dsx-skeleton--text-line` (label) + `data-slot="sidebar-menu-skeleton"` + `data-show-icon` + `data-state` | A loading placeholder for a menu row. |
+| `Sidebar.MenuSkeleton` | `<div>` | `dsx-sidebar__menu-skeleton` + `dsx-skeleton dsx-skeleton--circle` (icon) + `dsx-skeleton dsx-skeleton--text-line` (label) + `data-slot="sidebar-menu-skeleton"` + `data-show-icon` + `data-state` | A loading placeholder for a menu row. Inside a `Sidebar.MenuItem` (a flex row) it takes the item's width (`.dsx-sidebar__menu-item > .dsx-sidebar__menu-skeleton { flex: 1 }`); on its own it is as wide as its parent. |
 | `Sidebar.MenuSub` | `<ul>` | `dsx-sidebar__menu-sub` + `data-slot="sidebar-menu-sub"` + `data-state` | A nested menu list. |
 | `Sidebar.MenuSubItem` | `<li>` | `dsx-sidebar__menu-sub-item` + `data-slot="sidebar-menu-sub-item"` + `data-state` | A nested menu row. |
 | `Sidebar.MenuSubButton` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-sub-button dsx-button` + `dsx-sidebar__menu-button-text` (when children are a string or number) + `data-slot="sidebar-menu-sub-button"` + `data-active` + `data-state` | A nested menu button. |
 | `Sidebar.MenuSubTrigger` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-sub-trigger dsx-button` + `dsx-sidebar__menu-sub-trigger-chevron` (`chevron-right`, rotates 90° on open) + `data-slot="sidebar-menu-sub-trigger"` + `data-state` (`open` \| `closed`) + `aria-expanded` | The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collapsible` primitive. Decided in Direction #4 Q5; `mode="both"` is rejected. |
 | `Sidebar.Separator` | `<div role="separator" aria-orientation="horizontal">` | `dsx-sidebar__separator dsx-separator dsx-separator--decorative` + `data-slot="sidebar-separator"` + `data-state` | A horizontal divider. |
 | `Sidebar.Trigger` | `<button aria-label="Expand sidebar" \| "Collapse sidebar" \| "Pin sidebar" \| "Unpin sidebar">` | `dsx-sidebar__trigger dsx-button` + `dsx-button__icon` (panel-state glyph) + `dsx-sidebar__trigger-label` (text) + `data-slot="sidebar-trigger"` + `data-state` | A toggle button used inside the panel or the inset. Hover-preview mode uses dashed/solid panel semantics instead of directional chevrons. |
-| `Sidebar.mobile-trigger` (internal) | `<button aria-label="Open sidebar">` | `dsx-sidebar__mobile-trigger` + `data-slot="sidebar-mobile-trigger"` | The mobile sheet trigger, mounted by `Sidebar.Provider` when `mobile="sheet"` and the viewport is below `mobileBreakpoint`. |
+| `Sidebar.mobile-trigger` (internal) | `<button aria-label="Open sidebar">` | `dsx-sidebar__mobile-trigger` + `data-slot="sidebar-mobile-trigger"` | The mobile sheet trigger, mounted by `Sidebar.Provider` when `mobile="sheet"` and the viewport is below `mobileBreakpoint`, unless `mobileTrigger` is `false`. |
 | `Sidebar.SkipLink` | `<a>` | `dsx-sidebar__skip-link` | Focus-revealed skip link targeting `targetId` (`main` by default). |
 
 The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset` and `Sidebar.Trigger`. The source exports the full set through `Object.assign` on `Sidebar` (alias of `Sidebar.Root`), and also re-exports the named components individually. The spec records the runtime shape; the roster's slot list is the contract for canonical anatomy.
@@ -71,6 +71,7 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `hoverExpand` | `boolean` | `false` | no | In icon mode, temporarily expands the collapsed rail on pointer hover or keyboard focus. The preview overlays the inset and never changes the persisted preference. `Escape` closes a keyboard-opened preview. | no |
 | `previewOpen` | `boolean` | `false` | no | Holds the temporary icon-mode preview open for a consumer-owned flyout or other adjacent interaction. It does not change the persisted preference. | no |
 | `mobile` | `'sheet' \| 'drawer' \| 'none'` | `'sheet'` | no | Mobile fallback mode. `sheet` mounts a `Sheet` trigger; `none` skips the mobile fallback. | no |
+| `mobileTrigger` | `boolean` | `true` | no | Whether the provider mounts its floating "Open sidebar" button in mobile sheet mode. Set `false` when the app opens the drawer from its own control, a header button or a dock item (`BottomDock`'s "More"), with `useSidebar().setMobileSheetOpen(true)`. The drawer, its own close button and its focus handling are unchanged; with `mobile="none"` the prop has no effect. Not written to the DOM. | no |
 | `mobileBreakpoint` | `number` | `768` | no | Viewport width below which the provider treats the device as mobile. The provider also matches `(pointer: coarse)`. | no |
 | `defaultSubmenuMode` | `'click' \| 'hover'` | `'click'` | no | Default toggle mode for every `Sidebar.MenuSubTrigger` under this provider. Individual triggers override per-section. | no |
 | `submenuOpenOnActive` | `boolean` | `true` | no | Default for `openOnActive` on every `Sidebar.MenuSubTrigger` under this provider. | no |
@@ -107,7 +108,7 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 
 ### `Sidebar.MenuSubTrigger`
 
-The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collapsible` primitive: the open state lives on a consumer-owned `Collapsible` root (`asChild` over the `MenuItem`), this trigger owns the click toggle and mirrors `open` / `onOpenChange` for hover timers, Arrow keys, and auto-open. `CollapsibleTrigger` is deliberately NOT in the composition (its span + chevron pair breaks Radix Slot's single-child rule). `CollapsibleContent` takes `forceMount` so the closed sub stays in the DOM and `openOnActive` can see an active descendant on mount. Direction #4 Q5 verdict: `click` is the default mode, `hover` is opt-in per trigger, `both` is rejected (hover/click race conditions). Hover mode is suppressed on coarse pointers and degrades to tap-to-toggle.
+The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collapsible` primitive: the open state lives on a consumer-owned `Collapsible` root (`asChild` over the `MenuItem`), this trigger owns the click toggle and mirrors `open` / `onOpenChange` for hover timers, Arrow keys, and auto-open. `CollapsibleTrigger` is deliberately NOT in the composition (its span + chevron pair breaks Radix Slot's single-child rule). `CollapsibleContent` takes `forceMount` so the closed sub stays in the DOM and `openOnActive` can see an active descendant on mount; a sub that mounts closed is hidden at rest by the Collapsible's motion styles (`collapsible.md` § Force-mounted content, G-14), and a collapsed one is out of the tab order. The trigger is a row like any `MenuButton` (same padding, icon column, fill and type: G-13). Direction #4 Q5 verdict: `click` is the default mode, `hover` is opt-in per trigger, `both` is rejected (hover/click race conditions). Hover mode is suppressed on coarse pointers and degrades to tap-to-toggle.
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
@@ -268,6 +269,8 @@ Rules:
 
 - The CSS file collapses the panel through the `data-state` attribute. The mobile sheet fallback is mounted by `Sidebar.Provider` based on `window.innerWidth` and `matchMedia('(pointer: coarse)')`, gated by `mobileBreakpoint` and the `mobile` prop.
 - The component does not write `@media` rules; the mobile behavior is runtime-driven, not CSS-driven.
+- `dsx-sidebar__menu-sub-trigger` shares the base rule of `dsx-sidebar__menu-button` (display, `--dsx-space-sm` padding, transparent fill, no border, label type, `--dsx-shadow-focus-ring` on `:focus-visible`), so a parent row and a plain row have one geometry: the icon in the same column, no browser button fill when the parent is neither open nor active. Open and active states are the parent's own rules after it.
+- The mobile drawer (`dsx-sidebar__mobile-sheet`) is flush with the viewport on three sides, so it keeps the structural border on its free inline-end edge only (`border-block-width: 0`, `border-inline-start-width: 0`), and it does not scroll itself (`overflow: hidden`): the nav fills it (`height: 100%`) and its content area owns the scrolling. The base dialog surface that Drawer shares draws the border all round, which is right for a floating panel and wrong for a full-height sheet.
 
 **Reduced motion:**
 
@@ -287,7 +290,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Panel width (icon collapsed) | `var(--dsx-sidebar-width-collapsed)` | Persistent slim icon rail. |
 | Panel preview layout | `calc(var(--dsx-sidebar-width-collapsed) - var(--dsx-sidebar-width))` | Negative inline-end margin lets temporary expansion overlay rather than reflow the inset. |
 | Panel background | `var(--dsx-color-surface)` | Panel surface. |
-| Panel ambient effect | `var(--dsx-color-accent-9)` mixed with transparency | Optional subscription-aware accent wash without a literal starfield. |
+| Panel ambient effect | `var(--dsx-color-accent-9)` mixed with transparency at `var(--dsx-effect-ambient-strength)` (10% in dark, 16% in light), from the top-left corner, plus a second source at the foot: an ellipse anchored to the bottom edge at 0.9× the same strength | Optional subscription-aware accent wash without a literal starfield. The strength is theme-aware (G-16): the same wash read about half as strong on the pale light surface. The foot glow (G-17, 2026-10-05) lights the lower half the corner radial never reached (about 35% of the panel) and leaves the nav a calm middle. |
+| Trigger | transparent fill, `inset 0 0 0 var(--dsx-border-width-sm) var(--dsx-color-accent-7)` ring, `var(--dsx-color-accent-11)` glyph; hover fill `var(--dsx-color-accent-3)` and ring `var(--dsx-color-accent-8)` | A quiet outline (G-18, 2026-10-05). The raised disc it replaced (`surface-raised` fill, drop shadow) vanished on dark, where shadows do not read, and on the tinted panel. Scale jobs: border step 7, text step 11, one step up on hover. The focus ring still replaces the ring; the pin / unpin glyphs of hover-expand mode live in the same button. |
+| Active row wash (light) | `var(--dsx-color-accent-4)` on `MenuButton`, `MenuSubButton` and `MenuSubTrigger` when `data-active='true'`, under `:where([data-dsx-theme='light'])`; dark keeps `accent-3` at 50% | G-19 (2026-10-05): 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. |
 | Panel border | `none` (CSS keyword) | The slim shell uses surface contrast and elevation instead of a boxed edge. |
 | Panel shadow | `var(--dsx-effect-shadow-1)` | Panel elevation. |
 | Floating: provider padding and gap | `var(--dsx-space-3)` | The space around the panel and between the panel and the inset. Never a sidebar margin: the preview and pin-docking motion animate `margin-inline-end` and `width`. |
@@ -368,7 +373,7 @@ Rules:
 - Offcanvas collapsed content is removed from interaction and the accessibility
   tree. The external recovery rail owns `aria-controls` and `aria-expanded`.
 - `Sidebar.GroupLabel` is a non-semantic `<div>`; consumers can set `role="heading"` plus `aria-level` when the label needs to be a heading.
-- The mobile sheet trigger (when mounted by `Sidebar.Provider`) is a button with `aria-label="Open sidebar"`.
+- The mobile sheet trigger (when mounted by `Sidebar.Provider`) is a button with `aria-label="Open sidebar"`. With `mobileTrigger={false}` the app's own control carries that role and must be a real button with its own accessible name. The drawer's own labels ("Close navigation", "Navigation") are fixed English strings today.
 - `useSidebar` returns a no-op fallback when the consumer renders a sidebar slot outside `Sidebar.Provider`, so the component never throws.
 
 **Keyboard:**
@@ -421,13 +426,19 @@ Submenu parent triggers use `--dsx-rounded-sm`, matching navigation rows rather
 - Renders a `MenuButton` with `isActive` and asserts `data-active="true"` plus the `dsx-sidebar-menu-button-active` class. Toggles the panel via the `Rail` click and asserts the `data-state` flips on the provider, the panel, the header, the footer, and the content. Renders a `MenuBadge` with text `12` and asserts the badge stays in the DOM when the panel collapses while CSS visually hides it.
 - Renders `MenuBadge variant="accent"` as quiet numeric metadata without the filled Badge surface; `variant="ring"` remains reserved for a genuine `value / max` ratio.
 
+**Mobile story:**
+
+- At a phone width in `mobile="sheet"` mode, asserts the floating "Open sidebar" button is mounted by default, is absent with `mobileTrigger={false}` (checked next to a default provider, because the drawer's chunk is lazy), and that an app control calling `useSidebar().setMobileSheetOpen(true)` still opens the drawer. The registry has no phone-width fixture for this: the drawer is a portal bound to the window, so `Sidebar.test.tsx` and the `frontend` user-shell render carry it. `src/test/styles/sidebar-mobile-sheet.test.ts` guards the sheet's three CSS rules (free-edge border only, no own scroll, nav sized to the sheet); jsdom has no layout, so the scrollbar and outline themselves are proved in the browser (`docs/feature/design-system/sidebar-sheet-chrome/verification.md`).
+
 **Composition story:**
 
 - Renders a `Sidebar.Content` with two `Sidebar.Group` blocks, each containing a `GroupLabel`, a `GroupContent`, and a `Menu` with `MenuItem` and `MenuButton` rows. Adds a `Sidebar.Separator` between the groups and a `Sidebar.MenuSub` with `Sidebar.MenuSubItem` and `Sidebar.MenuSubButton` rows in one of the menus. Asserts every slot renders the right `dsx-sidebar__*` class.
+- `src/test/styles/sidebar-sub-trigger-row.test.ts` guards the shared row base of `MenuButton` and `MenuSubTrigger` (padding, fill, border, focus ring): the parent row sat 8px right of the others and showed a grey button fill when idle (G-13, 2026-10-05). `Collapsible.test.tsx` guards the closed force-mounted panel (G-14).
+- `src/test/styles/shell-look-pass.test.ts` guards the ambient wash's second source (G-17), the outline trigger and the order of its focus ring (G-18), and the light active-row wash with its (0,2,0) selector and source order (G-19); `apps/playground/tests/user-shell-frame-browser.spec.ts` measures all three on the user-shell frame for Rift, Warp and Ray in both themes.
 
 **Token story:**
 
-- Sidebar does not own a `data-accent-color` hook, so the token story is omitted. The active menu button background tracks `var(--dsx-color-accent-surface)` and the active text tracks `var(--dsx-color-accent-indicator)`, which are theme-aware.
+- Sidebar does not own a `data-accent-color` hook, so the token story is omitted. The active row's wash is `var(--dsx-color-accent-3)` at 50% in dark and `var(--dsx-color-accent-4)` in light (G-19), and its text tracks `var(--dsx-color-accent-indicator)`, which is theme-aware.
 
 **A11y story:**
 

package/dist/docs/consumer-guide.md

@@ -33,6 +33,13 @@ The optional `brand-effects.css` provides `dsx-brand-ambient`,
 `dsx-brand-starfield`, and `dsx-brand-shimmer`. Apply them to a page wrapper;
 core styles do not enable product atmosphere automatically.
 
+The accent haze of `dsx-brand-ambient` (and of `Sidebar effect="ambient"`) follows
+the theme-aware token `--dsx-effect-ambient-strength` (10% in dark, 16% in light;
+the three washes of `dsx-brand-ambient` are 2.2×, 1.2× and 0.8× of it). Raise or
+lower the haze for a theme by overriding the token on that theme's boundary, not by
+copying the gradients. The sidebar's wash has two sources, the top-left corner and
+the foot (the foot at 0.9× the same token), so one override moves both.
+
 Starfield density can be selected with `dsx-brand-starfield--sparse` or
 `dsx-brand-starfield--dense`. Fine-tune an individual wrapper with
 `--dsx-brand-starfield-opacity`, `--dsx-brand-starfield-dot-size`, and
@@ -847,12 +854,12 @@ const connectivity = dsxIconCatalog.filter(
 |---|---|
 | Theme | `sun`, `moon`, `monitor` |
 | Navigation | `arrow-left`, `arrow-right`, `chevron-down`, `chevron-up`, `chevron-left`, `chevron-right`, `menu`, `x`, `plus`, `minus`, `dots-horizontal`, `dots-vertical`, `external-link`, `home`, `search`, `settings`, `user` |
-| Feedback | `check`, `check-circle`, `info`, `help-circle`, `alert-triangle`, `bell`, `loader`, `sparkles`, `star` |
+| Feedback | `check`, `check-circle`, `info`, `help-circle`, `alert-triangle`, `circle-alert`, `bell`, `loader`, `sparkles`, `star` |
 | Security | `shield`, `shield-check`, `lock`, `lock-keyhole`, `unlock`, `key`, `fingerprint`, `eye`, `eye-off` |
-| Connectivity | `wifi`, `signal`, `globe`, `server`, `hard-drive`, `activity`, `zap` |
-| Communication | `mail`, `send` |
+| Connectivity | `wifi`, `signal`, `globe`, `server`, `hard-drive`, `smartphone`, `activity`, `zap` |
+| Communication | `mail`, `send`, `message-square` |
 | Commerce | `banknote`, `circle-dollar-sign`, `gem`, `quote`, `receipt-text`, `russian-ruble` |
-| Forms & Actions | `edit`, `trash`, `copy`, `eraser`, `calendar`, `clock`, `code`, `file`, `image`, `link`, `list`, `list-ordered`, `upload`, `bold`, `italic`, `strikethrough`, `quote`, `heading-1`, `heading-2`, `heading-3`, `undo`, `redo` |
+| Forms & Actions | `edit`, `trash`, `copy`, `eraser`, `calendar`, `clock`, `code`, `file`, `image`, `link`, `list`, `list-ordered`, `upload`, `paperclip`, `bold`, `italic`, `strikethrough`, `quote`, `heading-1`, `heading-2`, `heading-3`, `undo`, `redo`, `refresh-cw` |
 | Brand & Social | `apple`, `discord`, `facebook`, `github`, `gitlab`, `google`, `instagram`, `netflix`, `npm`, `paypal`, `reddit`, `spotify`, `stripe`, `supabase`, `telegram`, `twitch`, `twitter`, `vercel`, `youtube` |
 | App Specific | `home`, `rocket` |