@koobiq/components 20.4.2 → 21.0.0

package/tags/tag.scss

@@ -1,6 +1,8 @@
+@use '../core/styles/common/animation';
 @use '../core/styles/common/tokens' as *;
 @use '../core/styles/common/vendor-prefixes';
 @use '../core/styles/common/input';
+@use '../core/styles/common/squircle' as *;
 
 .kbq-tag {
     @include vendor-prefixes.user-select(none);
@@ -14,7 +16,7 @@
 
     padding: var(--kbq-tag-size-padding-vertical) var(--kbq-tag-size-padding-horizontal);
 
-    border-radius: 4px;
+    @include kbq-squircle(4px);
 
     cursor: default;
 
@@ -48,6 +50,20 @@
         margin: 0 var(--kbq-tag-size-content-gap-horizontal);
     }
 
+    & .kbq-tag-prefix {
+        flex-shrink: 0;
+        margin-inline-start: var(--kbq-tag-size-icon-margin-left);
+    }
+
+    & .kbq-tag-suffix {
+        flex-shrink: 0;
+    }
+
+    & .kbq-tag-suffix:not(.kbq-tag-remove, .kbq-tag-edit-submit) {
+        margin-inline-end: var(--kbq-tag-size-close-button-margin-right);
+    }
+
+    // @deprecated Use `.kbq-tag-prefix` (`kbqTagPrefix`) instead. Will be removed in 22.0.0.
     & .kbq-icon_left {
         margin-left: var(--kbq-tag-size-icon-margin-left);
     }
@@ -75,6 +91,8 @@
 
     &.cdk-drag-animating {
         transition: transform 300ms cubic-bezier(0, 0, 0.2, 1);
+
+        @include animation.kbq-animations-off();
     }
 }
 

package/time-range/time-range.scss

@@ -1,3 +1,7 @@
+// Layout only: the package paints nothing of its own, so it intentionally ships no
+// `time-range-tokens.scss` and no `_time-range-theme.scss`. Every colour on screen comes from the
+// composed components - link, radio, form-field, datepicker, timepicker, popover and button.
+
 .kbq-time-range {
     .kbq-time-range__trigger {
         display: block;
@@ -15,7 +19,12 @@
 .kbq-time-range__editor {
     display: block;
 
+    // The radiogroup holds only radios, so the from/to block is a sibling of it rather than a child.
+    // The gap reproduces the spacing the range block used to get from its own flex column.
     .kbq-time-range-editor__container {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kbq-size-s);
         width: 100%;
     }
 

package/timezone/timezone-option.component.scss

@@ -1,7 +1,3 @@
-@use '../core/styles/common/tokens' as *;
-
-@use './timezone-option-theme' as *;
-
 .kbq-timezone-option.kbq-option {
     display: flex;
     flex-direction: row;
@@ -26,6 +22,10 @@
 .kbq-timezone-option__cities {
     display: -webkit-box;
     -webkit-box-orient: vertical;
+    /* Kept in the stylesheet rather than written by KbqTimezoneOptionTooltip, so the clamp survives an
+       option imported without that directive. Mirrors TOOLTIP_VISIBLE_ROWS_COUNT, which decides from the
+       same number whether the overflow tooltip is needed. */
+    -webkit-line-clamp: 3;
     max-height: var(--kbq-timezone-option-size-max-height);
     overflow: hidden;
 }
@@ -39,6 +39,3 @@
         bottom: calc(-1 * var(--kbq-size-3xs));
     }
 }
-
-@include kbq-timezone-option-theme();
-@include kbq-timezone-option-typography();

package/timezone/timezone-select.component.scss

@@ -9,5 +9,8 @@
     }
 }
 
+// Included here and nowhere else. Both components render with `ViewEncapsulation.None`, so a second
+// include would emit every rule below twice into the global stylesheet; the select owns them because
+// every one of them is scoped to the panel it renders, as is `timezone-option-tokens.scss`.
 @include kbq-timezone-option-theme();
 @include kbq-timezone-option-typography();

package/toast/_toast-theme.scss

@@ -35,11 +35,8 @@
 }
 
 @mixin kbq-toast-typography() {
+    // `.kbq-toast__title` inherits this level, so emitting the identical one for it changed nothing.
     .kbq-toast {
         @include kbq-typography-level-to-styles-css-variables(typography, text-normal);
     }
-
-    .kbq-toast__title {
-        @include kbq-typography-level-to-styles-css-variables(typography, text-normal);
-    }
 }

package/toast/toast-container.component.scss

@@ -3,36 +3,42 @@
 .kbq-toast-container {
     display: flex;
     flex-direction: column;
+
+    // Matches the default `KbqToastPosition.TOP_RIGHT`; every other anchor overrides it below.
     align-items: flex-end;
 
     gap: var(--kbq-toast-stack-size-gap);
 
     // @see KbqToastPosition
-    &.kbq-toast-container-top-right {
-        margin-top: var(--kbq-toast-stack-size-margin-vertical);
-        margin-right: var(--kbq-toast-stack-size-margin-horizontal);
-    }
-
-    &.kbq-toast-container-top-left {
+    &.kbq-toast-container-top-right,
+    &.kbq-toast-container-top-left,
+    &.kbq-toast-container-top-center {
         margin-top: var(--kbq-toast-stack-size-margin-vertical);
-        margin-left: var(--kbq-toast-stack-size-margin-horizontal);
     }
 
-    &.kbq-toast-container-top-center {
-        margin-top: var(--kbq-toast-stack-size-margin-vertical);
+    &.kbq-toast-container-bottom-right,
+    &.kbq-toast-container-bottom-left,
+    &.kbq-toast-container-bottom-center {
+        margin-bottom: var(--kbq-toast-stack-size-margin-vertical);
     }
 
+    &.kbq-toast-container-top-right,
     &.kbq-toast-container-bottom-right {
-        margin-bottom: var(--kbq-toast-stack-size-margin-vertical);
         margin-right: var(--kbq-toast-stack-size-margin-horizontal);
     }
 
+    &.kbq-toast-container-top-left,
     &.kbq-toast-container-bottom-left {
-        margin-bottom: var(--kbq-toast-stack-size-margin-vertical);
+        align-items: flex-start;
+
         margin-left: var(--kbq-toast-stack-size-margin-horizontal);
     }
 
-    &.kbq-toast-container-bottom-center {
-        margin-bottom: var(--kbq-toast-stack-size-margin-vertical);
+    // `KbqToastPosition.CENTER` deliberately carries no stack margin: the overlay is centred on both axes, so a
+    // margin would push the stack off centre instead of insetting it from an edge.
+    &.kbq-toast-container-top-center,
+    &.kbq-toast-container-bottom-center,
+    &.kbq-toast-container-center {
+        align-items: center;
     }
 }

package/toast/toast-tokens.scss

@@ -1,8 +1,4 @@
 :where(.kbq-toast-container) {
-    // @deprecated use --kbq-toast-stack-size-margin-vertical
-    --kbq-toast-stack-size-margin-top: var(--kbq-size-m);
-    // @deprecated use --kbq-toast-stack-size-margin-horizontal
-    --kbq-toast-stack-size-margin-right: var(--kbq-size-m);
     --kbq-toast-stack-size-margin-vertical: var(--kbq-size-m);
     --kbq-toast-stack-size-margin-horizontal: var(--kbq-size-m);
     --kbq-toast-stack-size-gap: var(--kbq-size-s);
@@ -16,8 +12,18 @@
     --kbq-toast-size-icon-width: var(--kbq-size-l);
     --kbq-toast-size-icon-height: var(--kbq-size-l);
     --kbq-toast-size-icon-margin-right: var(--kbq-size-s);
-    --kbq-toast-size-icon-border-radius: 50%;
-    --kbq-toast-size-close-button-margin-top: var(--kbq-size-m);
+    // The icon box repeats the corner of the toast it sits in, so it follows the container radius by default.
+    --kbq-toast-size-icon-border-radius: var(--kbq-toast-size-container-border-radius);
+    --kbq-toast-size-close-button-padding: var(--kbq-size-xxs);
+    --kbq-toast-size-close-button-icon-size: 16px;
+    --kbq-toast-size-close-button-height: calc(
+        var(--kbq-toast-size-close-button-icon-size) + var(--kbq-toast-size-close-button-padding) * 2
+    );
+    // Centers the close button on the first line of the title instead of on the padding box.
+    --kbq-toast-size-close-button-margin-top: calc(
+        var(--kbq-toast-size-content-padding-top) -
+            (var(--kbq-toast-size-close-button-height) - var(--kbq-typography-text-normal-line-height)) / 2
+    );
     --kbq-toast-size-close-button-margin-right: var(--kbq-size-xxs);
     --kbq-toast-size-button-stack-padding-top: var(--kbq-size-s);
     --kbq-toast-size-button-stack-content-gap-horizontal: var(--kbq-size-m);

package/toast/toast.component.scss

@@ -1,6 +1,6 @@
-@use '../core/styles/common/tokens' as *;
-
+@use '../core/styles/common/animation';
 @use './toast-theme' as *;
+@use '../core/styles/common/squircle' as *;
 
 .kbq-toast {
     display: flex;
@@ -10,20 +10,55 @@
 
     height: auto;
 
-    border-radius: var(--kbq-toast-size-container-border-radius);
+    @include kbq-squircle(var(--kbq-toast-size-container-border-radius));
 
     padding-left: var(--kbq-toast-size-container-padding-left);
     padding-right: var(--kbq-toast-size-container-padding-right);
+
+    animation: kbq-toast-enter 150ms ease-out;
+
+    &.kbq-toast_leaving {
+        pointer-events: none;
+        animation: kbq-toast-leave 300ms ease-in forwards;
+
+        @include animation.kbq-animations-off();
+    }
+
+    @include animation.kbq-animations-off();
+}
+
+@keyframes kbq-toast-enter {
+    from {
+        transform: translateX(100%);
+        opacity: 0;
+    }
+}
+
+@keyframes kbq-toast-leave {
+    from {
+        height: var(--kbq-toast-leaving-height);
+    }
+
+    to {
+        transform: translateX(50%);
+        opacity: 0;
+        height: 0;
+    }
 }
 
 .kbq-toast__icon-container {
+    // Self-contained layout: the component must not depend on the global `layout-*` utility bundle.
+    display: flex;
+    align-items: flex-start;
+    justify-content: flex-start;
+
     flex-shrink: 0;
     width: var(--kbq-toast-size-icon-width);
     max-width: var(--kbq-toast-size-icon-width);
     height: var(--kbq-toast-size-icon-height);
     max-height: var(--kbq-toast-size-icon-height);
 
-    border-radius: var(--kbq-toast-size-container-border-radius);
+    border-radius: var(--kbq-toast-size-icon-border-radius);
 
     margin-right: var(--kbq-toast-size-icon-margin-right);
 
@@ -93,24 +128,12 @@
 }
 
 .kbq-toast__close-button {
-    margin-top: kbq-difference-series-css-variables(
-        [toast-size-content-padding-top,
-        calc(
-                kbq-difference-series-css-variables(
-                        [kbq-sum-series-css-variables(
-                            [calc(var(--kbq-icon-button-size-small-vertical-padding) * 2),
-                            16px]
-                        ),
-                        typography-text-normal-line-height]
-                    ) /
-                    2
-            )]
-    );
+    margin-top: var(--kbq-toast-size-close-button-margin-top);
     margin-right: var(--kbq-toast-size-close-button-margin-right);
 
     &.kbq-icon-button {
-        --kbq-icon-button-size-normal-horizontal-padding: 4px;
-        --kbq-icon-button-size-normal-vertical-padding: 4px;
+        --kbq-icon-button-size-normal-horizontal-padding: var(--kbq-toast-size-close-button-padding);
+        --kbq-icon-button-size-normal-vertical-padding: var(--kbq-toast-size-close-button-padding);
     }
 }
 

package/toggle/_toggle-theme.scss

@@ -66,7 +66,8 @@
     .kbq-toggle {
         @include _kbq-toggle-color(theme);
 
-        &.kbq-error {
+        &.kbq-error,
+        &.kbq-invalid {
             @include _kbq-toggle-color(error);
         }
 
@@ -84,7 +85,8 @@
             }
         }
 
-        .kbq-hint .kbq-hint__text {
+        // A projected `kbq-error` is a hint too, and keeps its own color. `:where` leaves the specificity as it was.
+        .kbq-hint:where(:not(.kbq-error)) .kbq-hint__text {
             color: var(--kbq-foreground-contrast-secondary);
         }
     }
@@ -97,10 +99,6 @@
         & .kbq-hint .kbq-hint__text {
             @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-compact);
         }
-
-        & .kbq-toggle-bar-container {
-            @include tokens.kbq-css-font-variable(typography, text-compact, line-height, '');
-        }
     }
 
     .kbq-toggle.kbq-toggle_big {
@@ -109,9 +107,5 @@
         & .kbq-hint .kbq-hint__text {
             @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-normal);
         }
-
-        & .kbq-toggle-bar-container {
-            @include tokens.kbq-css-font-variable(typography, text-big, line-height, '');
-        }
     }
 }

package/toggle/toggle.scss

@@ -1,7 +1,8 @@
-@use '../core/styles/common/tokens';
 @use '../core/styles/common/animation';
 @use './toggle-theme' as theme;
 
+// The `.kbq-progress` loading state used by this component is emitted globally by `kbq-core()`.
+
 $toggle-thumb-offset: 8px;
 
 .kbq-toggle {
@@ -9,6 +10,7 @@ $toggle-thumb-offset: 8px;
 
     .kbq-toggle__circle {
         position: absolute;
+        left: 3px;
 
         border-radius: 50%;
 
@@ -16,27 +18,46 @@ $toggle-thumb-offset: 8px;
 
         height: 10px;
         width: 10px;
+
+        transition: left 100ms;
+
+        @include animation.kbq-animations-off();
+
+        &.kbq-toggle__circle_checked {
+            left: calc(100% - 11px);
+        }
+
+        &.kbq-toggle__circle_indeterminate {
+            left: 10px;
+            visibility: hidden;
+        }
     }
 
     .kbq-toggle-layout {
-        display: flex;
+        display: inline-flex;
+        box-sizing: border-box;
+        width: 100%;
         flex-direction: row;
         align-items: flex-start;
 
+        // Keeps the host's own line box in charge of the baseline, so that the box a toggle
+        // occupies in text is exactly one line tall.
+        vertical-align: top;
+
         cursor: inherit;
 
         &.kbq-toggle-layout_left {
             flex-direction: row-reverse;
         }
-
-        &:has(.kbq-toggle-label:not(:empty)) .kbq-toggle-bar-container {
-            padding-top: tokens.kbq-css-half-difference(typography-text-normal-line-height, toggle-size-normal-height);
-        }
     }
 
     .kbq-toggle-bar-container {
         display: flex;
         align-items: center;
+
+        // The switch is centred in a box at least as tall as one line of the label, so that a toggle
+        // keeps the same height whether it has a label or not, and still grows with a taller bar.
+        min-height: var(--kbq-typography-text-normal-line-height);
     }
 
     .kbq-toggle-bar {
@@ -56,6 +77,8 @@ $toggle-thumb-offset: 8px;
         height: var(--kbq-toggle-size-normal-height);
         width: var(--kbq-toggle-size-normal-width);
 
+        @include animation.kbq-animations-off();
+
         .kbq-toggle__thumb {
             position: absolute;
             left: $toggle-thumb-offset;
@@ -66,9 +89,34 @@ $toggle-thumb-offset: 8px;
             height: 2px;
             border-radius: var(--kbq-size-border-width);
             transition: left 50ms ease-in-out;
+
+            @include animation.kbq-animations-off();
         }
     }
 
+    .kbq-toggle__content {
+        display: flex;
+        flex-direction: column;
+
+        flex: 1;
+
+        &:has(.kbq-toggle-label:not(:empty)) {
+            &.kbq-toggle__content_left {
+                margin-right: var(--kbq-toggle-size-normal-horizontal-content-padding);
+            }
+
+            &.kbq-toggle__content_right {
+                margin-left: var(--kbq-toggle-size-normal-horizontal-content-padding);
+            }
+        }
+    }
+
+    // Keeps the projected hint a block-level flex item, exactly as it was before it got its own wrapper.
+    .kbq-toggle__hint {
+        display: flex;
+        flex-direction: column;
+    }
+
     .kbq-hint {
         margin-top: var(--kbq-size-3xs);
     }
@@ -96,32 +144,25 @@ $toggle-thumb-offset: 8px;
     }
 }
 
-.kbq-toggle__content {
-    display: flex;
-    flex-direction: column;
-
-    flex: 1;
-
-    &:has(.kbq-toggle-label:not(:empty)) {
-        &.kbq-toggle__content_left {
-            margin-right: var(--kbq-toggle-size-normal-horizontal-content-padding);
-        }
-
-        &.kbq-toggle__content_right {
-            margin-left: var(--kbq-toggle-size-normal-horizontal-content-padding);
-        }
-    }
-}
-
+// The `big` variant deliberately resolves to the same switch dimensions as the normal one - it only
+// changes typography. The rules below stay so the `--kbq-toggle-size-big-*` tokens remain overridable.
 .kbq-toggle.kbq-toggle_big {
     & .kbq-toggle-bar {
         height: var(--kbq-toggle-size-big-height);
         width: var(--kbq-toggle-size-big-width);
     }
 
-    .kbq-toggle-layout {
-        &:has(.kbq-toggle-label:not(:empty)) .kbq-toggle-bar-container {
-            padding-top: tokens.kbq-css-half-difference(typography-text-big-line-height, toggle-size-big-height);
+    .kbq-toggle-bar-container {
+        min-height: var(--kbq-typography-text-big-line-height);
+    }
+
+    .kbq-toggle__content:has(.kbq-toggle-label:not(:empty)) {
+        &.kbq-toggle__content_left {
+            margin-right: var(--kbq-toggle-size-big-horizontal-content-padding);
+        }
+
+        &.kbq-toggle__content_right {
+            margin-left: var(--kbq-toggle-size-big-horizontal-content-padding);
         }
     }
 }

package/tooltip/_tooltip-theme.scss

@@ -12,7 +12,13 @@
     }
 
     & .kbq-tooltip__arrow {
-        background-color: var(--kbq-tooltip-#{$style-name}-background);
+        // Same gradient-over-opaque-base trick as the body: the variant backgrounds may be translucent, and
+        // without an opaque layer underneath the arrow would blend with the page instead of with the tooltip.
+        background-image: linear-gradient(
+            var(--kbq-tooltip-#{$style-name}-background),
+            var(--kbq-tooltip-#{$style-name}-background)
+        );
+        background-color: var(--kbq-background-bg);
     }
 
     &.kbq-tooltip_arrowless {

package/tooltip/tooltip-tokens.scss

@@ -1,4 +1,5 @@
 .kbq-tooltip {
+    /* Product constant, not a size token: the documentation states the tooltip never grows past 300px. */
     --kbq-tooltip-size-max-width: 300px;
     --kbq-tooltip-size-border-radius: var(--kbq-size-s);
     --kbq-tooltip-size-padding-horizontal: var(--kbq-size-m);
@@ -20,6 +21,4 @@
     --kbq-tooltip-error-fade-off-background: var(--kbq-background-error);
     --kbq-tooltip-error-fade-off-text: var(--kbq-foreground-white);
     --kbq-tooltip-error-fade-off-shadow: none;
-
-    --kbq-tooltip-borderless-shadow: 0 2px 8px var(--kbq-shadow-key), 0 3px 8px var(--kbq-shadow-ambient);
 }

package/tooltip/tooltip.scss

@@ -1,48 +1,62 @@
 @use '../core/pop-up/pop-up';
+@use '../core/styles/common/animation';
 
 @use '../core/styles/common/tokens' as *;
 
 @use './tooltip-theme' as *;
+@use '../core/styles/common/squircle' as *;
 
 $trigger-margin: 8px;
 $trigger-margin_without-arrow: 4px;
 
+// `KbqNavbarItem` puts this class on the overlay pane — the parent of `.kbq-tooltip` — so the shared
+// `pop-up.popup-margins` mixin, which matches the placement class on the tooltip itself, cannot express it.
+// The extra pixel over `$trigger-margin` compensates for the horizontal navbar's own 1px border.
+$navbar-trigger-margin: $trigger-margin + 1px;
+
 .kbq-tooltip-panel_horizontal-navbar {
     &:has(.kbq-tooltip_placement-top),
     &:has(.kbq-tooltip_placement-top-left),
     &:has(.kbq-tooltip_placement-top-right) {
-        margin-bottom: 9px;
+        margin-bottom: $navbar-trigger-margin;
     }
 
     &:has(.kbq-tooltip_placement-right),
     &:has(.kbq-tooltip_placement-right-top),
     &:has(.kbq-tooltip_placement-right-bottom) {
-        margin-left: 9px;
+        margin-left: $navbar-trigger-margin;
     }
 
     &:has(.kbq-tooltip_placement-bottom),
     &:has(.kbq-tooltip_placement-bottom-left),
     &:has(.kbq-tooltip_placement-bottom-right) {
-        margin-top: 9px;
+        margin-top: $navbar-trigger-margin;
     }
 
     &:has(.kbq-tooltip_placement-left),
     &:has(.kbq-tooltip_placement-left-top),
     &:has(.kbq-tooltip_placement-left-bottom) {
-        margin-right: 9px;
+        margin-right: $navbar-trigger-margin;
     }
 }
 
+// `forDisabledComponent` makes the wrapper of a disabled control focusable so its tooltip stays reachable by
+// keyboard. Only the ring color is set, leaving the browser's own focus outline to decide when to draw it.
+.kbq-tooltip-trigger_for-disabled {
+    outline-color: var(--kbq-states-line-focus-theme);
+}
+
 .kbq-tooltip__inner {
-    border-radius: var(--kbq-tooltip-size-border-radius);
-    /* stylelint-disable-next-line declaration-property-value-keyword-no-deprecated */
-    word-break: break-word;
+    @include kbq-squircle(var(--kbq-tooltip-size-border-radius));
+    overflow-wrap: break-word;
 }
 
 .kbq-tooltip {
     box-sizing: border-box;
 
-    border-radius: var(--kbq-tooltip-size-border-radius);
+    // Kept alongside the radius of `.kbq-tooltip__inner`: this element is the one carrying `box-shadow`
+    // (see `_tooltip-theme.scss`), and without a radius here the shadow is cast with square corners.
+    @include kbq-squircle(var(--kbq-tooltip-size-border-radius));
 
     white-space: pre-line;
 
@@ -50,6 +64,10 @@ $trigger-margin_without-arrow: 4px;
 
     max-width: var(--kbq-tooltip-size-max-width);
 
+    // Shown once `KbqPopUp.show()` has made it visible.
+    opacity: 0;
+    transform: scale(0);
+
     .kbq-tooltip__inner {
         padding: var(--kbq-tooltip-size-padding-vertical) var(--kbq-tooltip-size-padding-horizontal);
     }
@@ -57,6 +75,29 @@ $trigger-margin_without-arrow: 4px;
     &.kbq-tooltip_arrowless {
         @include pop-up.popup-margins(kbq-tooltip, $trigger-margin_without-arrow);
     }
+
+    &.kbq-tooltip_visible {
+        opacity: 1;
+        // Rests at exactly 1: a fractional scale leaves the tooltip permanently resampled, which softens its
+        // text for as long as it is on screen. A transform rather than `none`: it makes the tooltip the
+        // stacking context the arrow's negative `z-index` is drawn in, behind the panel but not behind the page.
+        transform: scale(1);
+        animation: kbq-tooltip-enter 200ms cubic-bezier(0, 0, 0.2, 1);
+
+        @include animation.kbq-animations-off();
+    }
+}
+
+@keyframes kbq-tooltip-enter {
+    from {
+        opacity: 0;
+        transform: scale(0);
+    }
+
+    50% {
+        opacity: 0.5;
+        transform: scale(0.9);
+    }
 }
 
 @include kbq-tooltip-theme();
@@ -74,6 +115,11 @@ $trigger-margin_without-arrow: 4px;
 }
 
 $arrow-offset: calc((#{var(--kbq-tooltip-size-arrow-size)} - 1px) / -2);
-$arrow-padding: calc((18px + $trigger-margin) / 2);
+
+// Rotated by 45deg, the square arrow covers `size * sqrt(2)` of the tooltip edge — ~17px at the default
+// `--kbq-size-m`. The inset is measured from that footprint, not from the square's side, plus a pixel of
+// slack so the arrow never runs into the rounded corner.
+$arrow-footprint: 18px;
+$arrow-padding: calc(($arrow-footprint + $trigger-margin) / 2);
 
 @include pop-up.popup-arrow-positions(kbq-tooltip, $arrow-offset, $arrow-padding);

package/top-bar/top-bar-tokens.scss

@@ -1,13 +1,24 @@
 :where(.kbq-top-bar) {
+    /* LAYER TOKENS */
+    /* The top bar is page chrome: it sits above the page content its shadow spills over and the
+       `kbqOverlayLayer` layer (980), but below every other CDK overlay (1000). */
+    --kbq-top-bar-z-index: 990;
+    /* POSITION TOKENS */
+    /* `sticky` only takes effect once an inset is set — with every inset `auto` the box lays out exactly as
+       `relative`. Set `--kbq-top-bar-inset-block-start: 0` to make the bar stick to the top of its
+       nearest scrolling ancestor. */
     --kbq-top-bar-position: sticky;
-    --kbq-top-bar-background: var(--kbq-background-bg);
+    --kbq-top-bar-inset-block-start: auto;
+    /* SIZE TOKENS */
     --kbq-top-bar-spacer-min-width: 80px;
     --kbq-top-bar-padding-vertical: var(--kbq-size-m);
     --kbq-top-bar-padding-horizontal: var(--kbq-size-xxl);
     --kbq-top-bar-border-radius: 0;
     --kbq-top-bar-container-start-gap: 0;
-    --kbq-top-bar-container-start-basis: 0;
+    --kbq-top-bar-container-start-min-width: 0;
     --kbq-top-bar-container-end-gap: var(--kbq-size-s);
+    /* THEME TOKENS */
+    --kbq-top-bar-background: var(--kbq-background-bg);
     --kbq-top-bar-shadow-bottom: var(--kbq-shadow-overflow-normal-bottom);
     --kbq-top-bar-shadow-transition: ease-out 300ms;
 }