@mkbabb/glass-ui 3.12.0 → 4.0.0

package/dist/styles/dock/shell.css

@@ -64,6 +64,36 @@
            stacking-context guarantee). Covers every dock scale site. */
         scale: 1;
         position: relative;
+        /* AZ.W-ADAPTIVE-AUTO Arm 1 — the dock self-darkens over light backdrops by
+           default via the UNCONDITIONAL `:where(.glass-dock)` self-engage rule in
+           dock/morph.css (mirroring the overlay band's `ladder.css:169`): it re-points
+           the inheriting `--glass-tint-source`/`--glass-tint-strength` directly on the
+           dock root, so the shell + chassis + held/open tiers darken toward warm-ink
+           with NO consumer opt-in (a dock floats over arbitrary — frequently light —
+           page content). `--glass-backdrop: light` is KEPT here so a consumer's
+           DESCENDANT nested-glass inside the dock also reads the bright bucket via the
+           ancestor-querying `@container` block in dock/morph.css (CSS style queries
+           never self-match, so this declaration alone is inert for the dock's OWN
+           plate — the self-engage rule, not this token, darkens the dock). */
+        --glass-backdrop: light;
+        /* AY.W-A11Y-PERF O-4 — paint containment so the maximal-glass nested
+           backdrop-filter sample does not escape the dock box (the standard nested-
+           backdrop-cost mitigation; the Button-in-glass-in-dock stack re-samples the
+           already-blurred buffer at each level without it). */
+        /* BA.W-DOCK-GEOMETRY contain:paint AUDIT verdict (a) — the control-plate
+           clearance fix (the `--dock-control-safe-inset` painted-plate inset, scope
+           1) + the scroll-port cross-axis un-clip (scope 2) keep the maximal
+           hover/active control plate INSIDE the dock padding box: the inset plate is
+           centered in its cell (≥1px slack/side at hover), the cell sits flush at the
+           dock content edge, and the `--dock-padding-block` (≈6px) padding holds the
+           plate ≥7px clear of the `contain: paint` border-box edge on the block axis.
+           So `contain: paint` is the NON-proximate second clip box (the lane's
+           `probe-bottomdock-nocontain.png` forced-root probe proved the inner
+           scroll-port box was proximate, not this) and it is UNEDITED here — the
+           inset + freed cross axis suffice, no containment lift on the control-plate
+           band. The π readback (W-DOCK-GEOMETRY-DELTA.md) records the live
+           plate-inside-padding margin number that binds this verdict. */
+        contain: paint;
         display: inline-flex;
         align-items: center;
         /* AW.W1 — the dock does NOT establish a default inline-size container.
@@ -167,17 +197,33 @@
        scrolls — the scroll port only engages on real over-cap content. The
        block-axis morph clip stays `data-morphing`-gated above; this is the
        AT-REST port only. Consumers set `--dock-max-block-size` per-instance to
-       anchor the column to the viewport without re-deriving the scroll plumbing. */
-    .glass-dock.vertical.always-expanded:not([data-morphing]),
-    .glass-dock.vertical.expanded:not([data-morphing]) {
+       anchor the column to the viewport without re-deriving the scroll plumbing.
+
+       BA.W-DOCK-GEOMETRY (DC-1) — the port is now GATED behind the `dock-scroll-y`
+       opt-in (`overflow="scroll"`), NOT unconditional on every `.vertical.
+       always-expanded`. THE ROOT: `overflow-y: auto` is a scroll value, and CSS
+       Overflow §3 FORCES the sibling `overflow-x: visible` to COMPUTE to `auto` —
+       so the F6 pin never survived, and EVERY at-rest vertical dock (even a
+       fit-content shell that never scrolls) paid the cross-axis inline clip,
+       slicing a control's inset plate left/right (the live π readback measured
+       `overflow-x: auto` on the grow-to-fit SidebarDock). A vertical dock that
+       genuinely needs the cap+scroll opts IN via `overflow="scroll"` (the
+       `.dock-scroll-y` port in overflow.css, the SAME plumbing the F6 comment names);
+       a grow-to-fit vertical shell stays `overflow: visible` (line 186) on BOTH axes
+       so its inset control plate paints past the track. The fit-content shell pays
+       NO cross-axis clip for zero scroll benefit — the goal criterion's "the
+       scroll-port cross-axis clip no longer fires on a fit-content shell that never
+       scrolls", honored at the geometry root. */
+    .glass-dock.vertical.dock-scroll-y.always-expanded:not([data-morphing]),
+    .glass-dock.vertical.dock-scroll-y.expanded:not([data-morphing]) {
         overflow-x: visible;
         overflow-y: auto;
         scrollbar-width: none;
         overscroll-behavior-y: contain;
     }
 
-    .glass-dock.vertical.always-expanded:not([data-morphing])::-webkit-scrollbar,
-    .glass-dock.vertical.expanded:not([data-morphing])::-webkit-scrollbar {
+    .glass-dock.vertical.dock-scroll-y.always-expanded:not([data-morphing])::-webkit-scrollbar,
+    .glass-dock.vertical.dock-scroll-y.expanded:not([data-morphing])::-webkit-scrollbar {
         display: none;
     }
 
@@ -243,27 +289,42 @@
             scale var(--dock-motion-resize);
     }
 
-    .glass-dock.variant-rail {
+    /* AZ.W-DOCK-TAXONOMY — the vertical dock's surface plate (the prior
+       `.variant-rail` block; "rail-ness" is now `orientation="vertical"` + a
+       shape/density choice, not a variant). */
+    .glass-dock.vertical {
         padding: var(--dock-rail-padding, var(--dock-padding-inline, 0.5rem));
-        background: var(--glass-bg-dock, var(--glass-bg-wash));
+        /* AZ.W-ADAPTIVE-AUTO Arm 1 — the vertical dock threads the SAME element-level
+           oklab tint wrapper the shell base carries (NOT the pre-substituted
+           `--glass-bg-dock` token alone, whose inner tint baked at the `:root` 0%
+           strength before the `:where(.glass-dock)` self-engage re-points the
+           inheriting tint tokens — the substitution-vs-inheritance trap §3a names).
+           Wrapping HERE lets the self-engage darken reach the vertical dock's OWN
+           plate. Zero-delta at the `0%` rest default (the mix is a no-op =
+           byte-identical to the flat dock bg). */
+        background: color-mix(
+            in oklab,
+            var(--glass-bg-dock, var(--glass-bg-wash)),
+            var(--glass-tint-source) var(--glass-tint-strength)
+        );
         border-color: var(--glass-border-dock, var(--glass-border-wash));
     }
 
-    .glass-dock.variant-rail.shape-pill {
+    .glass-dock.vertical.shape-pill {
         border-radius: var(--radius-pill);
     }
 
-    .glass-dock.variant-rail.shape-rounded {
+    .glass-dock.vertical.shape-rounded {
         border-radius: var(--radius-xl);
     }
 
-    /* AW.W3b — horizontal-root shape rules. The `shape-*` class previously bound
-       ONLY under `.variant-rail`; on a horizontal `variant-dock` the prop silently
-       no-op'd (the root hardwired `--radius-dock` = `--radius-pill`). These rules
-       close that documented-but-dead prop — `shape="rounded"` / `shape="card"` now
-       paint on a horizontal dock. Scoped to `variant-dock:not(.vertical)` so the
-       rail + instrument-strip variants (which own their own radius) are untouched. */
-    .glass-dock.variant-dock:not(.vertical).shape-rounded {
+    /* AW.W3b — horizontal-root shape rules. The `shape-*` class once bound ONLY under
+       the vertical surface; on a horizontal dock the prop silently no-op'd (the root
+       hardwired `--radius-dock` = `--radius-pill`). These rules close that
+       documented-but-dead prop — `shape="rounded"` / `shape="card"` now paint on a
+       horizontal dock. Scoped to `:not(.vertical)` so the vertical dock (which owns
+       its own radius above) is untouched. */
+    .glass-dock:not(.vertical).shape-rounded {
         border-radius: var(--radius-xl);
     }
 
@@ -275,7 +336,7 @@
        prior two discrete `.shape-card` / `.shape-card.collapsed` rules + their
        reliance on the deleted `border-radius var(--dock-motion-resize)` transition
        are RETIRED for this single interpolation. */
-    .glass-dock.variant-dock:not(.vertical).shape-card {
+    .glass-dock:not(.vertical).shape-card {
         border-radius: calc(
             var(--radius-pill) +
                 (var(--dock-card-radius) - var(--radius-pill)) *
@@ -295,80 +356,18 @@
        condition tests the LITERAL `superellipse(2)` (a `var()` is not evaluable in
        an `@supports` query) — the same Chrome-139 feature the token resolves to. */
     @supports (corner-shape: superellipse(2)) {
-        .glass-dock.variant-dock:not(.vertical).shape-card {
+        .glass-dock:not(.vertical).shape-card {
             corner-shape: var(--corner-shape-bigdock);
         }
     }
 
-    /* AJ-W1-δ — `instrument-strip` variant (per G-AJ-D7 Path 1).
-     *
-     * The speedtest survey cockpit's vertical rail needs chassis-strip
-     * aesthetics, not the dock-rail's stadium-pill chrome. Adopts the
-     * surface vocabulary of the `<InstrumentChassis>` family so the
-     * strip reads as a journey-station slot — the same surface the
-     * speedtest + complete + thankyou stations ride.
-     *
-     * The variant intentionally inherits the rail variant's vertical
-     * layout (orientation: vertical; flex-direction: column) — the
-     * orientation + fitContent computeds in GlassDock.vue branch on
-     * `variant === "instrument-strip"` alongside the existing rail
-     * branch. Only the surface vocabulary changes vs the rail:
-     *   - Border-radius drops from `--radius-pill` to `--radius-card`
-     *     (matches `<InstrumentChassis> { border-radius: var(--radius-card) }`).
-     *   - Background plate routes through `--glass-bg-chassis` (0.28α
-     *     per tokens.css §V) instead of `--glass-bg-wash`.
-     *   - Border routes through `--glass-border-quiet` to match the
-     *     chassis primitive's at-rest stroke.
-     *   - Box-shadow routes through `--glass-shadow-quiet` plus the
-     *     inset-bottom hairline matching the chassis primitive
-     *     (instrument-chassis.css:42-45).
-     *
-     * The `.shape-pill` / `.shape-rounded` class hooks are still emitted
-     * by the template but no rule binds them under
-     * `.variant-instrument-strip` — chassis-strip carries ONE canonical
-     * border-radius (`--radius-card`), per the chassis family. */
-    .glass-dock.variant-instrument-strip {
-        padding: var(
-            --dock-instrument-strip-padding,
-            var(--dock-padding-inline, 0.75rem)
-        );
-        /* AX.W55 — the chassis-strip threads the SAME oklab tint wrapper the five
-           rungs + the dock shell (--glass-bg-dock) carry, so the adaptive darken
-           reaches it. Zero-delta at the `0%` rest default (the mix is 0% toward the
-           source = byte-identical to the flat `var(--glass-bg-chassis)`); it only
-           activates under the bright bucket below. */
-        background: color-mix(
-            in oklab,
-            var(--glass-bg-chassis, var(--glass-bg-wash)),
-            var(--glass-tint-source) var(--glass-tint-strength)
-        );
-        border: 1px solid var(--glass-border-quiet, var(--glass-border-resting));
-        border-radius: var(--radius-card);
-        box-shadow:
-            var(--glass-shadow-quiet, var(--shadow-dock)),
-            inset 0 -0.5px 0 0 rgb(0 0 0 / 0.06);
-    }
-
-    /* Engraved-bezel inner stroke — matches `<InstrumentChassis>::before`
-     * (instrument-chassis.css:85-93). The chassis-strip silhouette without
-     * this stroke reads as a flat plate; with it the strip reads as the
-     * polished sleeve of an instrument-panel module. The `::before`
-     * z-index sits above the chassis backdrop but below the slotted
-     * content (the MetricBadge stack), matching the chassis primitive's
-     * z-order. The host `.glass-dock` is already `position: relative`. */
-    .glass-dock.variant-instrument-strip::before {
-        content: "";
-        position: absolute;
-        inset: 0.5px;
-        border-radius: calc(var(--radius-card) - 0.5px);
-        border: 1px solid var(--surface-tint-4);
-        pointer-events: none;
-        z-index: 1;
-    }
-
-    .dark .glass-dock.variant-instrument-strip::before {
-        border-color: var(--surface-tint-6);
-    }
+    /* AZ.W-DOCK-TAXONOMY — the `instrument-strip` chassis-strip variant is RETIRED
+       (the ≥2-consumer bar). It carried the vocabulary of the InstrumentRail
+       component RETIRED at AY W-IC1; with the `variant` discriminant gone and no
+       live `variant="instrument-strip"` call-site in src/ or demo/, the chassis
+       paint has zero consumers. The cross-repo speedtest SurveyResultDock cockpit
+       re-pins in its own migration (recorded in MIGRATION.md). A consumer needing
+       the chassis surface composes `<InstrumentChassis>` directly. */
 
     .glass-dock:where(.fixed) {
         z-index: var(--z-dock);
@@ -426,32 +425,20 @@
         margin-block-start: var(--dock-layer-gap, 0.375rem);
     }
 
-    /* AX.W45-TUNE C7 — the VERTICAL three-region body. The vertical dock's default
-       slot is now wrapped in a structural `.dock-layers` column (parity with the
-       horizontal morph-region container) instead of a bare slot. A vertical dock is
-       always-expanded (no width morph), so this `.dock-layers` is NOT the grid-stacked
-       crossfade pair the horizontal `.dock-layers` is — it is a single column stack
-       carrying the dock's `--dock-layer-gap` rhythm so authored item groups +
-       `<DockSeparator>` rules read with the correct vertical cadence. The base
-       `.dock-layers { display: grid }` is re-pointed to a column flex here (the
-       vertical body is content-stacked, not pane-stacked). */
-    .glass-dock.vertical .dock-layer--vertical-body {
-        display: flex;
+    /* AZ.W-DOCK-TAXONOMY (move 2) — the VERTICAL dock's layer panes lay their content
+       out as a COLUMN. The dock body is now the SAME orientation-agnostic
+       `.dock-layers` full/summary morph pair the horizontal dock uses (the prior
+       static `.dock-layer--vertical-body` single-stack RETIRED — a vertical dock now
+       collapses its block axis too). The base `.dock-layer { display: flex;
+       align-items: center }` is row by default; here the full/summary panes flip to a
+       stretched column stack carrying the dock's `--dock-layer-gap` rhythm, so
+       authored item groups + `<DockSeparator>` rules read with the correct vertical
+       cadence. The block-axis morph aperture is owned by `.dock-layers` (layers.css —
+       `.glass-dock.vertical[data-morphing] .dock-layers` morphs `block-size`). */
+    .glass-dock.vertical .dock-layer {
         flex-direction: column;
         align-items: stretch;
         gap: var(--dock-layer-gap, 0.375rem);
         min-width: 0;
     }
-
-    /* The OPTIONAL trailing `#collapsed` section (the vertical analogue of the
-       horizontal summary pane) — a persistent secondary group below a structural
-       `<DockSeparator>`, sharing the column's gap rhythm. Renders only when the
-       consumer authors a `#collapsed` slot (GlassDock.vue guards it), so a vertical
-       dock with no collapsed slot keeps the prior single-stack body. */
-    .glass-dock.vertical .dock-layer--vertical-section {
-        display: flex;
-        flex-direction: column;
-        align-items: stretch;
-        gap: var(--dock-layer-gap, 0.375rem);
-    }
 }

package/dist/styles/dock-controls/dark-mode-toggle.css

@@ -0,0 +1,109 @@
+/* dock-controls/dark-mode-toggle.css — the `.dark-mode-toggle-button` control
+   family (AZ.W-CARVE partial 2 of 5; carved out of dock-controls.css).
+
+   The standalone toggle sizes (sm/md/lg/control) + the IN-DOCK glyph-inset
+   contract (AY.W-DOCK-CHROME §2 / AX.W06 USF-2 — the toggle glyph routes through
+   `--dock-control-glyph-size` so it is optically uniform with the nav glyphs when
+   docked). Opens its OWN `@layer components`; @import-ed after icon-button.css. */
+
+@layer components {
+    .dark-mode-toggle-button {
+        width: var(--dark-mode-toggle-size, 2.25rem);
+        height: var(--dark-mode-toggle-size, 2.25rem);
+        min-width: var(--dark-mode-toggle-size, 2.25rem);
+        min-height: var(--dark-mode-toggle-size, 2.25rem);
+        max-width: var(--dark-mode-toggle-size, 2.25rem);
+        max-height: var(--dark-mode-toggle-size, 2.25rem);
+        aspect-ratio: 1;
+        padding: var(--dark-mode-toggle-padding, 0.375rem);
+        transition:
+            opacity var(--dock-motion-standard),
+            background-color var(--dock-motion-standard),
+            box-shadow var(--dock-motion-fast);
+
+        & > svg {
+            width: 100%;
+            height: 100%;
+            max-width: 100%;
+            max-height: 100%;
+        }
+
+        &:hover,
+        &:focus {
+            background: var(--surface-tint-10);
+            opacity: 1;
+            outline: none;
+        }
+
+        &:focus-visible {
+            box-shadow: var(--focus-ring-shadow);
+        }
+
+        &[data-size="sm"] {
+            --dark-mode-toggle-size: 1.75rem;
+            --dark-mode-toggle-padding: 0.25rem;
+        }
+
+        &[data-size="md"] {
+            --dark-mode-toggle-size: 2.25rem;
+            --dark-mode-toggle-padding: 0.375rem;
+        }
+
+        &[data-size="lg"] {
+            --dark-mode-toggle-size: 2.75rem;
+            --dark-mode-toggle-padding: 0.5rem;
+        }
+
+        &[data-size="control"] {
+            --dark-mode-toggle-size: var(--control-size, 2.25rem);
+            --dark-mode-toggle-padding: var(--control-icon-padding, 0.375rem);
+        }
+    }
+
+    .dark-mode-toggle-button[data-size="dock"],
+    .glass-dock
+        .dark-mode-toggle-button:not([data-size="sm"]):not([data-size="lg"]):not(
+            [data-size="control"]
+        ) {
+        --dark-mode-toggle-size: var(--dock-control-size, var(--size-icon-btn));
+        /* AY.W-DOCK-CHROME §2 — the in-dock toggle GLYPH insets to the nav-glyph
+           register. The toggle SVG carries `h-full w-full` (the utility layer, which
+           BEATS the component-layer `> svg { width: --dock-control-glyph-size }` rule
+           below), so the glyph fills whatever the PADDED box leaves. Prior the in-dock
+           padding fell to `var(--dock-icon-padding, 0)` (the token is never defined →
+           0 pad → the glyph filled the whole 40px box edge-to-edge, ~2.5× the 16-20px
+           nav glyphs — the user's "too large" read). Pad the box by HALF the box↔glyph
+           difference so the `h-full` SVG lands at exactly `--dock-icon-glyph` (the
+           `--dock-scale`-keyed size the nav icons paint) — optically UNIFORM with the
+           nav glyphs through the utility-win path, not fighting it. */
+        --dark-mode-toggle-padding: calc(
+            (
+                    var(--dock-control-size, var(--size-icon-btn)) -
+                        var(--dock-icon-glyph, 1.25rem)
+                ) / 2
+        );
+    }
+
+    /* AX.W06 USF-2 — the dock-control optical-size contract. The
+       DarkModeToggle renders its OWN internal SVG `h-full w-full` (it bypasses
+       the `--dock-icon-glyph`-sized `> svg` slot the `.dock-icon-button` family
+       uses), so IN-DOCK it filled the whole control box edge-to-edge (~2.5× the
+       nav glyphs) — `--dock-icon-padding` is NEVER DEFINED, so the
+       `--dark-mode-toggle-padding: var(--dock-icon-padding, 0)` above fell to the
+       `0` fallback and zero padding let the SVG fill the box. Route the in-dock
+       toggle glyph through `--dock-control-glyph-size` (the ONE size the whole
+       dock-control family reads, default = `--dock-icon-glyph`, the same
+       `--dock-scale`-keyed glyph the nav icons paint), so the toggle is optically
+       UNIFORM with the nav glyphs WHEN DOCKED. The `h-full w-full` SVG stays
+       correct for the STANDALONE DarkModeToggle sizes (no `.glass-dock`
+       ancestor); this rule is scoped to the in-dock path only. Machine-checked by
+       the dock-control optical-parity gate, not eyeballed. */
+    .glass-dock
+        .dark-mode-toggle-button:not([data-size="sm"]):not([data-size="lg"]):not(
+            [data-size="control"]
+        )
+        > svg {
+        width: var(--dock-control-glyph-size, var(--dock-icon-glyph, 1.25rem));
+        height: var(--dock-control-glyph-size, var(--dock-icon-glyph, 1.25rem));
+    }
+}

package/dist/styles/dock-controls/icon-button.css

@@ -0,0 +1,143 @@
+/* dock-controls/icon-button.css — the `.dock-icon-button` control family
+   (AZ.W-CARVE partial 1 of 5; carved out of dock-controls.css).
+
+   The base rule (size/radius/legibility colour/transition), the glass icon-hover
+   fill (AT.W7-dock-b / AX.W45 DK2), the iOS press DARKEN-plus-shrink
+   (AZ.W-REGISTER-IOS), the focus + active-paint cohort (O.W6 Lane B), the
+   library-owned glyph sizing (AX.W45 D15), + the `--compact` size override.
+
+   Opens its OWN `@layer components` (same layer as the carve siblings) so the
+   carve is cascade-isomorphic. @import-ed after the shared `:where()` group at
+   the dock-controls.css root. */
+
+@layer components {
+    .dock-icon-button {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        flex-shrink: 0;
+        /* AQ.W3 §W3.2 identity base */
+        scale: 1;
+        width: var(--dock-control-size, var(--size-icon-btn));
+        height: var(--dock-control-size, var(--size-icon-btn));
+        /* BA.W-DOCK-GEOMETRY — the control-plate clearance inset (DC-2). The HIT
+           BOX stays the full `--dock-control-size` (the WCAG 2.5.5 touch floor on
+           the CELL), while the inset padding + `background-clip: content-box`
+           insets the PAINTED plate within it: the hover/active fill paints only the
+           content box (the cell minus the inset on every side), so the maximal
+           hover (×1.1) / active circle clears the cross-axis clip edge with ≥1px
+           margin — the lozenge dies at the plate diameter, not at the clip box. The
+           inset falls back to the prior `--dock-icon-padding` (0) when no dock
+           ancestor sets `--dock-control-safe-inset` (a standalone icon button). */
+        padding: var(--dock-icon-padding, var(--dock-control-safe-inset, 0));
+        cursor: pointer;
+        border: none;
+        background: transparent;
+        background-clip: content-box;
+        border-radius: var(--dock-control-radius, var(--radius-pill));
+        /* Foreground base routes through `--dock-fg-on-aurora` (defaults to
+           `--foreground`, byte-identical to before) so a consumer floating the
+           dock over an aurora can lift contrast per-backdrop. The muted icon
+           weight mixes that base down with `--opacity-icon-muted`. */
+        color: color-mix(
+            in srgb,
+            var(--dock-fg-on-aurora, var(--foreground))
+                calc(var(--opacity-icon-muted) * 100%),
+            transparent
+        );
+        outline: none;
+        transition:
+            background-color var(--dock-motion-fast),
+            color var(--dock-motion-fast),
+            /* AT.W7-dock-b — `scale` carries the press micro-feedback spring
+               (transform-scoped only; the surface fades stay on the flat ease). */
+                scale var(--dock-press-spring),
+            opacity var(--dock-motion-fast),
+            /* The box-shadow fade now carries ONLY the focus-visible ring (shared
+               `:focus-visible` group in dock.css) + the active-state
+               `--dock-active-shadow` — the AX.W09-retired hover `--glass-highlight`
+               specular no longer rides it. */
+                box-shadow var(--dock-motion-fast);
+
+        /* AT.W7-dock-b — glass icon-hover. The icon-button hover reads as a glass
+           surface, not a flat `--muted` plate: a translucent card-tinted fill is
+           the hover affordance. A consumer retunes the fill via `--dock-icon-hover-bg`.
+
+           AX.W09 — the dock control's SECOND specular (the `--glass-highlight`
+           hover box-shadow, AT.W7-dock-b) is RETIRED. The dock-icon-button is a
+           member of the unified `.glass-material` group (glass.css), so the moving
+           `::before` catch-light is now its SOLE specular owner — one light per
+           surface (the §0 "excise or fail" discipline). Stacking the
+           `--glass-highlight` inset box-shadow on the most-hovered, slides-floated
+           surface was the worst-offending double-light blowout; the card-tinted
+           hover fill carries the affordance without a second catch-light, and
+           dropping it also removes the `:not(:focus-visible)` specular-vs-ring
+           juggle. */
+        /* AX.W45 DK2 — the hover reads the FAMILY token `--dock-control-hover-bg`
+           (the per-control `--dock-icon-hover-bg` still wins if a consumer set it),
+           so the whole dock-control family shares ONE glass-translucent hover fill.
+           One source per state across icon/tab/picker (no four-vocabulary drift). */
+        &:hover:not(:disabled) {
+            background: var(
+                --dock-icon-hover-bg,
+                var(--dock-control-hover-bg)
+            );
+            color: var(--btn-hover-color, var(--foreground));
+            scale: var(--scale-hover-dock);
+        }
+
+        /* AZ.W-REGISTER-IOS — the iOS press DARKEN-plus-shrink. Press lands the
+           glass-darken (`--dock-control-press-bg`, a tier below resting) alongside
+           the existing scale-press, so a tap reads "darken + shrink" (C4-INV-4 was
+           scale-only). Token-first — a consumer retunes via `--dock-control-press-bg`. */
+        &:active:not(:disabled) {
+            background: var(--dock-control-press-bg);
+            scale: var(--scale-press-dock);
+        }
+
+        &:focus:not(:focus-visible) {
+            box-shadow: none;
+            outline: none;
+        }
+
+        /* O.W6 Lane B — token-ladder active paint. Defaults match the prior
+           hardcoded recipe (--muted bg + --foreground color, no transform / border
+           / shadow). Consumers override the active variant via the
+           `--dock-active-{bg,color,scale,border,shadow}` cohort scoped to a parent
+           (e.g. bbnf-buddy `ToolsLayer.vue` audacious active treatment) — no
+           `:deep()` escapes required. See tokens.css §10 (dock geometry block). */
+        &:is(.is-active, .active, [aria-expanded="true"], [aria-pressed="true"]) {
+            background: var(--dock-active-bg);
+            color: var(--dock-active-color);
+            scale: var(--dock-active-scale);
+            border: var(--dock-active-border);
+            box-shadow: var(--dock-active-shadow);
+        }
+    }
+
+    /* focus-visible ring + disabled paint hoisted to the shared `:where()`
+       group in dock.css. The box-shadow fade transition lives on the base
+       `.dock-icon-button` rule (it carries the focus-ring + active-shadow fade
+       since AX.W09 retired the hover `--glass-highlight` specular), so no
+       per-state transition override is needed. */
+
+    /* AX.W45 D15 — LIBRARY GLYPH OWNERSHIP. The dock icon-button now sizes its glyph
+       (mirroring `.dark-mode-toggle-button > svg`), so the glyph scales WITH the box
+       on the `--dock-scale` multiplier instead of swimming at a fixed consumer size.
+       `--dock-icon-glyph: calc(1.25rem * var(--dock-scale))` (tokens.css) rides the
+       multiplier — at 1.5× the glyph is 30px in a 60px box, the desktop proportion.
+       A consumer passing an explicit lucide size class still WINS (utility layer >
+       component layer) — a DEFAULT, not a ceiling, matching the `.dock-tab-button`
+       font-size precedent. */
+    .dock-icon-button > svg {
+        width: var(--dock-icon-glyph, 1.25rem);
+        height: var(--dock-icon-glyph, 1.25rem);
+    }
+
+    .dock-icon-button--compact {
+        width: var(--dock-compact-control-size, auto);
+        height: var(--dock-compact-control-size, auto);
+        min-width: var(--dock-compact-control-min-width, 0);
+        padding: var(--dock-compact-control-padding, 0.25rem);
+    }
+}