@koobiq/components 20.4.2 → 21.0.0

package/accordion/accordion-trigger.scss

@@ -1,3 +1,5 @@
+@use '../core/styles/common/animation';
+
 .kbq-accordion-trigger {
     display: flex;
     flex-direction: row;
@@ -12,9 +14,7 @@
 
         transition: transform 300ms ease-out;
 
-        @media (prefers-reduced-motion: reduce) {
-            transition: none;
-        }
+        @include animation.kbq-animations-off();
     }
 
     & .kbq-accordion-trigger__badge,
@@ -23,13 +23,6 @@
         margin-right: var(--kbq-size-s);
     }
 
-    // @deprecated Actions nested inside the trigger are focusable elements inside a `role="button"`.
-    // Put them in a `.kbq-accordion-header__actions` sibling of the trigger instead.
-    & .kbq-accordion-trigger__action {
-        padding: var(--kbq-size-xxs) var(--kbq-size-xxs) var(--kbq-size-3xs);
-        margin-bottom: calc(-1 * #{var(--kbq-size-3xs)});
-    }
-
     &.kbq-accordion-trigger_fill {
         padding: var(--kbq-accordion-size-item-header-variant-fill-padding);
 

package/accordion/accordion.scss

@@ -1,3 +1,4 @@
+@use '../core/styles/common/animation';
 @use './accordion-theme' as *;
 
 .kbq-accordion {
@@ -55,18 +56,15 @@
     &[data-state='open'] {
         transition: height 300ms ease-out;
         height: var(--kbq-accordion-content-height, auto);
+
+        @include animation.kbq-animations-off();
     }
 
     &[data-state='closed'] {
         transition: height 300ms ease-out;
         height: 0;
-    }
 
-    @media (prefers-reduced-motion: reduce) {
-        &[data-state='open'],
-        &[data-state='closed'] {
-            transition: none;
-        }
+        @include animation.kbq-animations-off();
     }
 }
 

package/actions-panel/actions-panel-container.scss

@@ -1,16 +1,42 @@
+@use '../core/styles/common/animation';
+@use '../core/styles/common/squircle' as *;
+
+$easing: cubic-bezier(0.4, 0, 0.2, 1);
+
+// Points the disabled tokens of a button style at its enabled ones, so the disabled state keeps the enabled colors.
+@mixin kbq-actions-panel-disabled-tokens($base) {
+    --kbq-#{$base}-states-disabled-background: var(--kbq-#{$base}-background);
+    --kbq-#{$base}-states-disabled-border: var(--kbq-#{$base}-border);
+    --kbq-#{$base}-states-disabled-foreground: var(--kbq-#{$base}-foreground);
+    --kbq-#{$base}-states-disabled-left-icon: var(--kbq-#{$base}-left-icon);
+    --kbq-#{$base}-states-disabled-right-icon: var(--kbq-#{$base}-right-icon);
+}
+
 .kbq-actions-panel-container {
     background: var(--kbq-actions-panel-background-color);
     color: var(--kbq-actions-panel-text-color);
     box-shadow: var(--kbq-actions-panel-box-shadow);
     height: var(--kbq-actions-panel-height);
     padding: var(--kbq-actions-panel-padding);
-    border-radius: var(--kbq-actions-panel-border-radius);
+    @include kbq-squircle(var(--kbq-actions-panel-border-radius));
     display: flex;
     flex-grow: 1;
     align-items: center;
     overflow: hidden;
     box-sizing: border-box;
 
+    transform: translateY(100%);
+    transition: transform 150ms $easing;
+
+    @include animation.kbq-animations-off();
+
+    &.kbq-actions-panel-container_visible {
+        transform: none;
+        animation: kbq-actions-panel-enter 125ms $easing;
+
+        @include animation.kbq-animations-off();
+    }
+
     .kbq-actions-panel-container__content {
         display: flex;
         align-items: center;
@@ -28,9 +54,27 @@
     .kbq-button-icon {
         --kbq-button-filled-contrast-fade-off-background: transparent;
         --kbq-button-filled-contrast-fade-on-background: transparent;
+
+        // The disabled tokens of contrast buttons are grey tints made for light surfaces, and they are almost invisible
+        // on this dark panel. Those buttons keep their enabled colors and only fade out. Other colors keep their states.
+        &.kbq-disabled.kbq-contrast,
+        &.kbq-disabled.kbq-contrast-fade {
+            @include kbq-actions-panel-disabled-tokens(button-filled-contrast-fade-off);
+            @include kbq-actions-panel-disabled-tokens(button-filled-contrast-fade-on);
+            @include kbq-actions-panel-disabled-tokens(button-outline-contrast-fade-on);
+            @include kbq-actions-panel-disabled-tokens(button-transparent-contrast-fade-on);
+
+            opacity: var(--kbq-opacity-disabled);
+        }
     }
 }
 
 .kbq-actions-panel-overlay {
     margin: var(--kbq-actions-panel-margin);
 }
+
+@keyframes kbq-actions-panel-enter {
+    from {
+        transform: translateY(100%);
+    }
+}

package/alert/alert.component.scss

@@ -1,6 +1,7 @@
 @use '../core/styles/common/tokens' as *;
 
 @use './alert-theme' as *;
+@use '../core/styles/common/squircle' as *;
 
 .kbq-alert {
     display: flex;
@@ -26,7 +27,7 @@
 }
 
 .kbq-alert.kbq-alert_normal {
-    border-radius: var(--kbq-alert-size-normal-container-border-radius);
+    @include kbq-squircle(var(--kbq-alert-size-normal-container-border-radius));
 
     padding: var(--kbq-alert-size-normal-container-padding-top) var(--kbq-alert-size-normal-container-padding-right)
         var(--kbq-alert-size-normal-container-padding-bottom) var(--kbq-alert-size-normal-container-padding-left);
@@ -79,7 +80,7 @@
 }
 
 .kbq-alert.kbq-alert_compact {
-    border-radius: var(--kbq-alert-size-compact-container-border-radius);
+    @include kbq-squircle(var(--kbq-alert-size-compact-container-border-radius));
 
     padding: var(--kbq-alert-size-compact-container-padding-top) var(--kbq-alert-size-compact-container-padding-right)
         var(--kbq-alert-size-compact-container-padding-bottom) var(--kbq-alert-size-compact-container-padding-left);

package/app-switcher/_app-switcher-theme.scss

@@ -27,8 +27,4 @@
     .kbq-app-switcher-group-header__badge {
         @include kbq-typography-level-to-styles-css-variables(typography, text-compact-medium);
     }
-
-    .kbq-app-switch-tree-option__text {
-        @include kbq-typography-level-to-styles-css-variables(typography, text-normal-medium);
-    }
 }

package/app-switcher/app-switcher-dropdown-app.scss

@@ -1,14 +1,15 @@
 @use '../core/styles/common';
 @use '../core/styles/common/tokens';
+@use '../core/styles/common/squircle' as *;
 
 .kbq-app-switcher-dropdown-app {
     display: flex;
     flex-direction: row;
 
     width: 100%;
-    min-height: 50px;
+    min-height: var(--kbq-app-switcher-size-dropdown-app-height-min, 50px);
 
-    border-radius: var(--kbq-size-xs);
+    @include kbq-squircle(var(--kbq-size-xs));
     // transparent border to keep the box model aligned with the other list rows (matches kbq-list-item-base)
     border: var(--kbq-size-3xs) solid transparent;
 

package/app-switcher/app-switcher-dropdown-site.scss

@@ -1,5 +1,6 @@
 @use '../core/styles/common';
 @use '../core/styles/common/tokens';
+@use '../core/styles/common/squircle' as *;
 
 .kbq-app-switcher-dropdown-site {
     display: flex;
@@ -12,7 +13,7 @@
 
     text-decoration: none;
 
-    border-radius: var(--kbq-size-xs);
+    @include kbq-squircle(var(--kbq-size-xs));
 
     @include common.user-select(none);
     @include common.kbq-list-item-base();

package/app-switcher/{kbq-app-switcher-list-item.scss → app-switcher-list-item.scss}

@@ -1,5 +1,6 @@
 @use '../core/styles/common';
 @use '../core/styles/common/tokens';
+@use '../core/styles/common/squircle' as *;
 
 .kbq-app-switcher-list-item {
     position: relative;
@@ -8,9 +9,9 @@
     flex-direction: row;
 
     max-width: 100%;
-    min-height: 38px;
+    min-height: var(--kbq-app-switcher-size-list-item-height-min, 38px);
 
-    border-radius: var(--kbq-size-s);
+    @include kbq-squircle(var(--kbq-size-s));
 
     padding: var(--kbq-size-xxs) var(--kbq-size-m) var(--kbq-size-xs) var(--kbq-size-m);
 
@@ -43,7 +44,7 @@
 
         &:has(+ :not(.kbq-app-switcher-site_nested)),
         &:last-child {
-            border-bottom-left-radius: var(--kbq-size-s);
+            @include kbq-squircle(var(--kbq-size-s), border-bottom-left-radius);
 
             &:after {
                 top: 0;
@@ -72,7 +73,7 @@
     width: var(--kbq-size-xxl);
     height: var(--kbq-size-xxl);
 
-    border-radius: var(--kbq-size-xxs);
+    @include kbq-squircle(var(--kbq-size-xxs));
 
     & .kbq-icon {
         transform: rotate(0deg);
@@ -85,6 +86,19 @@
     }
 }
 
+// The toggle is revealed by hover or keyboard focus (see the theme mixin below). A pointer-less device
+// produces neither while browsing the list, so keep the affordance visible there instead of hiding the only
+// way to expand a group.
+@media (hover: none) {
+    .kbq-app-switcher-list-item__toggle {
+        display: flex;
+    }
+
+    .kbq-app-switcher-list-item:has(.kbq-app-switcher-list-item__toggle) .kbq-app-switcher-list-item__icon {
+        visibility: hidden;
+    }
+}
+
 .kbq-app-switcher-list-item__icon {
     padding-top: var(--kbq-size-s);
     padding-right: var(--kbq-size-m);

package/app-switcher/app-switcher-tokens.scss

@@ -0,0 +1,15 @@
+/**
+ * Sizes specific to the app-switcher, exposed as override points instead of literals scattered across the
+ * component styles.
+ *
+ * Declared on both selectors because the site flyouts render in their own CDK overlay (panel class
+ * `.kbq-app-switcher-sites`) and therefore inherit nothing from `.kbq-app-switcher`. Every consumer still
+ * passes the current value as the `var()` fallback, so the styles hold up even outside these containers.
+ */
+.kbq-app-switcher,
+.kbq-app-switcher-sites {
+    --kbq-app-switcher-size-container-width: 320px;
+    --kbq-app-switcher-size-empty-search-result-height: 96px;
+    --kbq-app-switcher-size-list-item-height-min: 38px;
+    --kbq-app-switcher-size-dropdown-app-height-min: 50px;
+}

package/app-switcher/app-switcher.scss

@@ -1,4 +1,5 @@
 @use './app-switcher-theme' as *;
+@use '../core/styles/common/squircle' as *;
 
 .kbq-app-switcher {
     position: relative;
@@ -9,14 +10,16 @@
     margin-top: var(--kbq-size-xxs);
     margin-bottom: var(--kbq-size-xxs);
 
-    width: 320px;
+    width: var(--kbq-app-switcher-size-container-width, 320px);
 
-    border-radius: var(--kbq-size-xs);
+    @include kbq-squircle(var(--kbq-size-xs));
 
     box-shadow: var(--kbq-shadow-popup);
 
     box-sizing: border-box;
 
+    // Keeps the panel above adjacent content when the component is rendered inline (as the docs and e2e
+    // fixtures do) rather than inside a CDK overlay, which stacks on its own.
     z-index: 1;
 }
 
@@ -25,7 +28,7 @@
 }
 
 .kbq-app-switcher__search-result {
-    max-width: 320px;
+    max-width: var(--kbq-app-switcher-size-container-width, 320px);
 
     min-height: 0;
 
@@ -37,7 +40,14 @@
     justify-content: center;
     align-items: center;
 
-    height: 96px;
+    height: var(--kbq-app-switcher-size-empty-search-result-height, 96px);
+}
+
+// The element is an always-mounted `role="status"` live region (see app-switcher.html); it only takes up
+// space while it actually holds the message. Comments - the anchors Angular leaves behind for `@if` - do not
+// affect `:empty`, and `preserveWhitespaces: false` keeps whitespace-only text nodes out of the template.
+.kbq-app-switcher__empty-search-result:empty {
+    display: none;
 }
 
 .kbq-app-switcher__app-container {

package/autocomplete/autocomplete.scss

@@ -2,6 +2,7 @@
 @use '../core/styles/common/select';
 
 @use './autocomplete-theme' as *;
+@use '../core/styles/common/squircle' as *;
 
 .kbq-autocomplete-panel {
     visibility: hidden;
@@ -17,7 +18,7 @@
     // See `%kbq-select-panel` — same soft cap, same token.
     max-width: var(--kbq-panel-size-width-max, 640px);
 
-    border-radius: var(--kbq-autocomplete-size-panel-border-radius, var(--kbq-size-border-radius));
+    @include kbq-squircle(var(--kbq-autocomplete-size-panel-border-radius, var(--kbq-size-border-radius)));
     max-height: var(--kbq-autocomplete-size-panel-max-height);
 
     .kbq-autocomplete-panel__content {
@@ -44,12 +45,12 @@
     .kbq-option {
         @include select.item-active-area(var(--kbq-size-3xs));
     }
+}
 
-    // We need to offset horizontal dividers by their height, because
-    // they throw off the keyboard navigation inside the panel.
-    .kbq-divider-horizontal {
-        margin-top: -1px;
-    }
+// Layout, typography and the transparent text around the hint are set inline by `kbqCreateTextMirror`, since they
+// follow the field; only the look of the hint itself lives here.
+.kbq-autocomplete-inline-hint__hint {
+    color: var(--kbq-form-field-default-placeholder);
 }
 
 @include kbq-autocomplete-theme();

package/badge/badge.component.scss

@@ -1,3 +1,4 @@
+@use '../core/styles/common/squircle' as *;
 @use '../core/styles/common/tokens' as *;
 
 @use './badge-theme' as *;
@@ -19,10 +20,8 @@
     padding-right: var(--kbq-badge-size-normal-horizontal-padding);
     padding-left: var(--kbq-badge-size-normal-horizontal-padding);
 
-    border: {
-        width: var(--kbq-badge-size-normal-border-width);
-        radius: var(--kbq-badge-size-normal-border-radius);
-    }
+    border-width: var(--kbq-badge-size-normal-border-width);
+    @include kbq-squircle(var(--kbq-badge-size-normal-border-radius));
 
     & .kbq-badge-caption {
         padding-left: var(--kbq-badge-size-normal-content-padding);
@@ -43,10 +42,8 @@
         padding-right: var(--kbq-badge-size-compact-horizontal-padding);
         padding-left: var(--kbq-badge-size-compact-horizontal-padding);
 
-        border: {
-            width: var(--kbq-badge-size-compact-border-width);
-            radius: var(--kbq-badge-size-compact-border-radius);
-        }
+        border-width: var(--kbq-badge-size-compact-border-width);
+        @include kbq-squircle(var(--kbq-badge-size-compact-border-radius));
 
         & .kbq-badge-caption {
             padding-left: var(--kbq-badge-size-compact-content-padding);

package/breadcrumbs/breadcrumbs.scss

@@ -19,19 +19,41 @@
         padding: 1px;
     }
 
+    // `display: contents` would keep the list's items as the host's direct flex children, but it also
+    // drops the element's box — and with it, in several browser/AT stacks, the `role="list"` semantics
+    // the wrapper exists to carry. Giving it the same flex properties as the host keeps both template
+    // branches laid out identically without relying on a box-less element to expose its role.
+    .kbq-breadcrumbs__list {
+        display: flex;
+        align-items: center;
+        gap: var(--kbq-breadcrumbs-gap);
+    }
+
     .kbq-breadcrumb-item__container {
         display: inline-flex;
         align-items: center;
     }
 
+    // On both wrappers rather than on the host. `.kbq-overflow-items` alone left the offset inert in
+    // the `wrap` and `none` modes, which render `.kbq-breadcrumbs__list` instead; the host itself
+    // cannot carry it, because a negative margin on a flex item is subtracted from the space the
+    // flex algorithm hands it, so the trail stops being squeezed and `KbqOverflowItems` — which
+    // measures its own box — concludes that every item fits and collapses nothing.
     &.kbq-breadcrumbs_first-item-negative-margin {
-        .kbq-overflow-items {
+        .kbq-overflow-items,
+        .kbq-breadcrumbs__list {
             margin-left: var(--kbq-breadcrumb-item-negative-margin);
         }
     }
 
     &.kbq-breadcrumbs_wrap {
         flex-wrap: wrap;
+
+        // The host only ever lays out a single flex child (`.kbq-breadcrumbs__list` or the overflow
+        // wrapper), so the wrapping itself has to happen one level down, on the list's own items.
+        .kbq-breadcrumbs__list {
+            flex-wrap: wrap;
+        }
     }
 
     &.kbq-breadcrumbs_compact {
@@ -171,15 +193,8 @@
         }
     }
 
-    .kbq-breadcrumb_current {
-        .kbq-button,
-        .kbq-button-icon {
-            &.kbq-button_transparent.kbq-contrast {
-                --kbq-button-transparent-contrast-fade-on-foreground: var(--kbq-foreground-contrast);
-            }
-        }
-
-        color: var(--kbq-foreground-contrast);
+    .kbq-breadcrumb__separator {
+        color: var(--kbq-icon-contrast-fade);
     }
 }
 

package/button/_button-base.scss

@@ -2,6 +2,7 @@
 @use '../core/styles/common/list';
 
 @use '../core/styles/common/tokens' as *;
+@use '../core/styles/common/squircle' as *;
 
 %kbq-button-base {
     @include button.kbq-button-reset();
@@ -27,7 +28,7 @@
     vertical-align: baseline;
 
     border: var(--kbq-button-size-border-width) solid transparent;
-    border-radius: var(--kbq-button-size-border-radius);
+    @include kbq-squircle(var(--kbq-button-size-border-radius));
 
     &::-moz-focus-inner {
         border: 0;
@@ -55,25 +56,47 @@
     & .kbq-button-text {
         @include list.kbq-truncate-line();
 
-        display: flex;
-        align-items: center;
+        // must stay a block container: `text-overflow: ellipsis` is not painted on a flex box
+        display: inline-block;
 
         min-width: 0;
+
+        // legacy `<i kbq-icon> Text` markup projects the icon into the default slot as a direct
+        // child, so it lands here. `vertical-align: middle` aligns it to the x-height, not the line
+        // box centre, which leaves it ~1px low — only a flex context centres it exactly. Truncation
+        // is unavailable in that case; use `kbqButtonPrefix`/`kbqButtonSuffix` to get centred icons
+        // AND an ellipsis. Scoped to a direct child so an icon nested deeper in the label (e.g. inside
+        // a projected badge) doesn't also fall back to flex and lose its ellipsis.
+        &:has(> .kbq-icon) {
+            display: flex;
+            align-items: center;
+        }
+    }
+
+    // A label with no text has nothing to truncate, and non-text content is only centred exactly by
+    // a flex context. `:has()` cannot decide this on its own: it would have to tell an icon-only
+    // label from a text label containing an icon, and selectors cannot see text nodes — so the class
+    // is computed by `KbqButtonCssStyler`. Covers content nested in a consumer's own wrapper element,
+    // which no descendant-based selector could match without breaking truncation elsewhere.
+    &.kbq-button_no-label .kbq-button-text {
+        display: flex;
+        align-items: center;
     }
 
+    /* Logical properties so the leading/trailing icon gap mirrors under `dir="rtl"`. */
     & .kbq-icon_left {
-        margin-right: var(--kbq-button-size-content-padding);
+        margin-inline-end: var(--kbq-button-size-content-padding);
     }
 
     & .kbq-icon_right {
-        margin-left: var(--kbq-button-size-content-padding);
+        margin-inline-start: var(--kbq-button-size-content-padding);
     }
 
     & .kbq-button-prefix {
-        margin-right: var(--kbq-button-size-content-padding);
+        margin-inline-end: var(--kbq-button-size-content-padding);
     }
 
     & .kbq-button-suffix {
-        margin-left: var(--kbq-button-size-content-padding);
+        margin-inline-start: var(--kbq-button-size-content-padding);
     }
 }

package/button/_button-theme.scss

@@ -50,7 +50,19 @@
     .kbq-button-icon {
         -webkit-font-smoothing: antialiased;
 
+        // Every style opens with an unqualified rule carrying its default color, so a button always
+        // renders: `kbq-button-reset()` sets neither `background` nor `color`, so a style that
+        // matched no branch at all fell through to the user-agent button appearance. The design
+        // system pairs each style with only a subset of the colors, and the styles do not share a
+        // default — `transparent` paints no fill, so its neutral color is `contrast`, not
+        // `contrast-fade`. Being one class less specific than every color branch below, and than
+        // any container theme restyling a nested button (e.g. `kbq-button-toggle`), the unqualified
+        // rule only takes effect where nothing else matches. The branches that repeat it are kept
+        // for the same reason: dropping them would lower the specificity those container themes
+        // currently compete with. Same shape as `_icon-theme.scss`.
         &.kbq-button_filled {
+            @include kbq-button-type(filled, contrast-fade-on);
+
             &.kbq-contrast {
                 @include kbq-button-type(filled, contrast-fade-off);
             }
@@ -61,6 +73,8 @@
         }
 
         &.kbq-button_outline {
+            @include kbq-button-type(outline, contrast-fade-on);
+
             &.kbq-theme-fade {
                 @include kbq-button-type(outline, theme-fade-on);
             }
@@ -71,6 +85,8 @@
         }
 
         &.kbq-button_transparent {
+            @include kbq-button-type(transparent, contrast-fade-on);
+
             &.kbq-theme {
                 @include kbq-button-type(transparent, theme-fade-on);
             }

package/button/button-group.scss

@@ -17,6 +17,13 @@
         }
     }
 
+    // Filled buttons paint their background under the transparent border the mixins above rely on,
+    // so in a uniformly filled contrast group the junction between buttons disappears. Clipping the
+    // background to the padding box keeps that border visible as a divider. Each selector reads as
+    // "the group has no direct child that is *not* a filled contrast[-fade] button", i.e. every
+    // child matches.
+    // @TODO tech debt (#DS-4847): replace the DOM introspection with a modifier class once the
+    // per-button color/style state is signal-based and can be observed by `KbqButtonGroupRoot`.
     &:not(:has(> :not(.kbq-contrast-fade.kbq-button_filled))),
     &:not(:has(> :not(.kbq-contrast.kbq-button_filled))) {
         :is(.kbq-button, .kbq-button-icon) {

package/button/button-tokens.scss

@@ -6,8 +6,6 @@
     --kbq-button-size-horizontal-padding: var(--kbq-size-m);
     --kbq-button-size-content-padding: var(--kbq-size-xs);
     --kbq-button-icon-size-horizontal-padding: var(--kbq-size-s);
-    --kbq-button-icon-size-vertical-padding: var(--kbq-size-s);
-    --kbq-button-icon-size-content-padding: var(--kbq-size-xxs);
     /* THEME TOKENS */
     --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-contrast);
     --kbq-button-filled-contrast-fade-off-border: transparent;

package/button/button.scss

@@ -1,12 +1,23 @@
-@use '../core/styles/common/animation';
-
 @use 'button-base' as *;
 @use '../core/styles/common/tokens' as *;
 
 @use './button-theme' as *;
 
+// The `.kbq-progress` loading state used by this component is emitted globally by `kbq-core()`.
+// `.kbq-button-icon_left` / `.kbq-button-icon_right` are set by `KbqButtonCssStyler` and styled by
+// `dropdown.scss` — they have no rules here on purpose.
+
+// hug the content by default, but never grow past the container: `white-space: nowrap` makes the
+// label's min-content contribution its full width, so without this the button would overflow instead
+// of letting `.kbq-button-text` truncate. Deliberately not on `.kbq-button-icon`: an icon button has
+// no label to truncate, so clamping it would only shrink `.kbq-button-text` and clip the icon.
+%kbq-button-clamped-to-container {
+    max-width: 100%;
+}
+
 .kbq-button {
     @extend %kbq-button-base;
+    @extend %kbq-button-clamped-to-container;
 
     // base padding - border-width
     padding-left: kbq-difference-series-css-variables([button-size-horizontal-padding, button-size-border-width]);
@@ -15,6 +26,7 @@
 
 .kbq-light-button {
     @extend %kbq-button-base;
+    @extend %kbq-button-clamped-to-container;
 }
 
 .kbq-button-icon {
@@ -22,6 +34,26 @@
 
     padding-left: kbq-difference-series-css-variables([button-icon-size-horizontal-padding, button-size-border-width]);
     padding-right: kbq-difference-series-css-variables([button-icon-size-horizontal-padding, button-size-border-width]);
+
+    // an icon button has no label for the slots to space themselves from, so a marker directive on
+    // a lone icon must not push it off centre. Must stay logical to match the base rules: a physical
+    // `margin-right: 0` would leave the base `margin-inline-end` standing under `dir="rtl"`.
+    & .kbq-icon_left,
+    & .kbq-button-prefix {
+        margin-inline-end: 0;
+    }
+
+    & .kbq-icon_right,
+    & .kbq-button-suffix {
+        margin-inline-start: 0;
+    }
+
+    // a pair of icons is spaced by a single gap rather than by two facing margins. Uses the size
+    // scale directly: the icon-button content-padding token was removed as dead in 21.0.0 and the
+    // migration guide tells consumers their override of it is gone, so it must not come back.
+    &.kbq-button-icon_left.kbq-button-icon_right .kbq-icon_left {
+        margin-inline-end: var(--kbq-size-xxs);
+    }
 }
 
 @include kbq-button-theme();

package/button-toggle/_button-toggle-theme.scss

@@ -1,8 +1,13 @@
 @use '../core/styles/common/tokens' as *;
 
 @mixin kbq-button-toggle-state($state-name) {
-    & > .kbq-button,
-    & > .kbq-icon-button {
+    // The style class is named on purpose. The inner button is a transparent `KbqButton`, so
+    // `kbq-button-theme()` also styles it, at the same specificity a bare `> .kbq-button` would
+    // have — which stylesheet wins would then come down to the order the two are injected in.
+    // (`.kbq-button-icon` rather than `.kbq-icon-button`: the former is what `KbqButtonCssStyler`
+    // sets on an icon-only button, the latter is the unrelated `KbqIconButton` host class.)
+    & > .kbq-button.kbq-button_transparent,
+    & > .kbq-button-icon.kbq-button_transparent {
         background: var(--kbq-button-toggle-item-#{$state-name}-background);
 
         color: var(--kbq-button-toggle-item-#{$state-name}-text);