@boostdev/design-system-components 2.14.0 → 2.15.0

package/src/components/interaction/Button/Button.mdx

@@ -55,6 +55,12 @@ Pass any `ReactNode` to `iconStart` or `iconEnd`. Icons inherit the button's `cu
 <Canvas of={Stories.WithIconEnd} />
 <Canvas of={Stories.WithBothIcons} />
 
+### Icon offset across sizes
+
+The gap between an icon and the button edge (`--button_icon-offset`) is half the size's inline padding by default, so it scales automatically with `size` and with the responsive space tokens at wider viewports.
+
+<Canvas of={Stories.IconOffsetMatrix} />
+
 ### Icon-only (1:1 aspect ratio)
 
 Set `isIconOnly` to render a square button with equal `xs` padding on both axes — composable with any `variant`. The icon sits centred; the button's height (from `size`) determines both width and height. Always pair with `aria-label` — there's no visible text for assistive tech to read.
@@ -143,6 +149,7 @@ Every public token below can be set on the button or any ancestor — the consum
 <tr><td>`--button_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Button border radius.</td></tr>
 <tr><td>`--button_height`</td><td>`3em` (medium)</td><td>Button height. Also drives the width when `isIconOnly` is set.</td></tr>
 <tr><td>`--button_font-size`</td><td>`inherit` (medium)</td><td>Button font size.</td></tr>
+<tr><td>`--button_icon-offset`</td><td>Half of the inline padding for the current size</td><td>How far `iconStart`/`iconEnd` pull into the padding (optical correction). Scales with `size` and with the responsive space tokens by default — override to pin a fixed offset instead.</td></tr>
 </tbody>
 </table>
 

package/src/components/interaction/Button/Button.module.css

@@ -33,7 +33,9 @@
     all: unset;
     position: relative;
     font: inherit;
-    padding-inline: var(--bds-space_l);
+    --button_padding-inline--size: var(--bds-space_l);
+
+    padding-inline: var(--button_padding-inline--size);
     display: inline-flex;
     gap: var(--bds-space_xs);
     border-radius: var(--button_radius, var(--bds-border_radius--full));
@@ -82,20 +84,17 @@
   .button.--size_small {
     --button_height:    2.25em;
     --button_font-size: var(--bds-font_size--body--s);
-
-    padding-inline: var(--bds-space_m);
+    --button_padding-inline--size: var(--bds-space_m);
   }
 
   .button.--size_medium {
     --button_height: 3em;
-
-    padding-inline: var(--bds-space_l);
+    --button_padding-inline--size: var(--bds-space_l);
   }
 
   .button.--size_large {
     --button_font-size: var(--bds-font_size--heading-3);
-
-    padding-inline: var(--bds-space_xl);
+    --button_padding-inline--size: var(--bds-space_xl);
   }
 
   .button.--hasPulse {
@@ -133,17 +132,26 @@
     flex-shrink: 0;
   }
 
+  /* Icon offset — pulls the icon into the padding so the optical gap between
+     icon and edge matches the gap between label and edge. Defaults to half
+     the size's inline padding (--button_padding-inline--size, set above per
+     --size_*), so it scales automatically with size and with the responsive
+     space tokens (space_l/space_xl grow at wider viewports). --button_icon-offset
+     is the public override; like the identity tokens above it is intentionally
+     read only as a var() fallback here, never declared on .button, so an
+     ancestor-set value inherits through instead of being shadowed by a
+     same-element declaration. */
   .iconStart {
     display: flex;
     align-items: center;
-    margin-inline-start: calc(var(--bds-space_s) * -1);
+    margin-inline-start: calc(var(--button_icon-offset, calc(var(--button_padding-inline--size) / 2)) * -1);
     transition: var(--bds-animation_transition);
   }
 
   .iconEnd {
     display: flex;
     align-items: center;
-    margin-inline-end: calc(var(--bds-space_s) * -1);
+    margin-inline-end: calc(var(--button_icon-offset, calc(var(--button_padding-inline--size) / 2)) * -1);
     transition: var(--bds-animation_transition);
   }
 

package/src/components/interaction/Button/Button.stories.tsx

@@ -158,3 +158,31 @@ export const AllIconOnly: Story = {
     </div>
   ),
 };
+
+/**
+ * Every size × icon position × variant combination in one grid, so the
+ * icon-to-edge offset (which now scales with the size's inline padding —
+ * see `--button_icon-offset` in the CSS variables docs) can be eyeballed
+ * and measured across viewports. Each button's label states its own
+ * variant/size/position so a verification script can find the right
+ * `.iconStart`/`.iconEnd` span via the button's accessible name and read
+ * `getComputedStyle(span).marginInlineStart` / `marginInlineEnd`.
+ */
+export const IconOffsetMatrix: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {(['small', 'medium', 'large'] as const).map(s => (
+        <div key={s} style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+          {(['default', 'outline'] as const).flatMap(v => [
+            <Button key={`${v}-${s}-start`} variant={v} size={s} iconStart={CheckIcon}>
+              {v} {s} start
+            </Button>,
+            <Button key={`${v}-${s}-end`} variant={v} size={s} iconEnd={CheckIcon}>
+              {v} {s} end
+            </Button>,
+          ])}
+        </div>
+      ))}
+    </div>
+  ),
+};

package/src/stories/DesignSystem/TokenSets.mdx

@@ -149,8 +149,28 @@ something else:
 </Split>
 
 The requirement follows from **what** you place, not from **who** places it. That saves another
-decision at the call site — which is why `Separator`, the `DropdownMenu` divider and the `Drawer`
-header rule all take `--as-surface` rather than a hand-rolled opacity over the text colour.
+decision at the call site — which is why every rule this library draws takes `--as-surface`:
+`Separator`, the `DropdownMenu` divider, the `Drawer` header rule, the line between `Accordion`
+items, the rail under the `Tabs` tablist, and the `Table`'s header underline and row rules. None of
+them softens a text colour with a hand-rolled opacity, and none picks a shade at the call site.
+
+### Both ways of getting it wrong
+
+Without a name for the non-text member, the two colours nearest to hand are the text colour and the
+ground colour — and both are wrong, in opposite directions. This library shipped one of each:
+
+| | On a 1px rule against `bg` | |
+|---|---|---|
+| `--bds-color_on-bg` (text) | 21:1 light, 16:1 dark | far too loud — reads as a hard edge |
+| `--bds-color_bg--subtle` (ground) | 1.1:1 light, 1.7:1 dark | far too faint — separates nothing |
+| `--bds-color_on-bg--as-surface` | 4.8:1 light, 6.8:1 dark | over the 3:1 band, under the text colour |
+
+The first is the tempting mistake, because the text colour is right there in the set and obviously
+visible. The second is the tidy-looking mistake, because a ground colour feels appropriately quiet.
+They come from the same gap: no third member, so the choice falls to whoever writes the line.
+
+Both directions are checked in CI, not by review. A hairline may not be painted with an
+`--bds-color_on-*` token, and it may not be painted with a `--bds-color_bg*` token either.
 
 `--as-surface` exists on the base rung of `bg`, `primary`, `secondary` and `accent-1..3`. It is a
 partner of the content side, so it is named `on-<x>--as-surface` and never on the surface side.

package/src/web-components/interaction/BdsButton.mdx

@@ -54,6 +54,13 @@ Slot an SVG (or any element) into `icon-start` or `icon-end`:
 <Canvas of={Stories.WithIconStart} />
 <Canvas of={Stories.WithIconEnd} />
 
+### Icon offset across sizes
+
+The gap between an icon and the button edge (`--button_icon-offset`) is half the size's inline padding by default, so it scales automatically with `size` and with the responsive space tokens at wider viewports. Set `--button_icon-offset` on the host or an ancestor to override it — it inherits across the shadow boundary.
+
+<Canvas of={Stories.IconOffsetMatrix} />
+<Canvas of={Stories.IconOffsetOverride} />
+
 ### Icon-only (1:1 aspect ratio)
 
 Set the `is-icon-only` attribute to render a square button with equal `var(--bds-space_xxs)` padding on both axes. Composable with any `variant`. Always pair with `aria-label` — there's no visible label text for assistive tech to read.
@@ -107,6 +114,7 @@ Set the `is-icon-only` attribute to render a square button with equal `var(--bds
 |----------|-------------|
 | `--button_color` | Identity colour — fills the default variant, outlines the outline variant |
 | `--button_on-color` | Text/icon colour on the button surface. Pair with `--button_color` |
+| `--button_icon-offset` | How far the icon slots pull into the padding (optical correction). Defaults to half the inline padding for the current `size`, so it scales with `size` and the responsive space tokens. Inherits across the shadow boundary — set it on the host or an ancestor. |
 
 ## Form participation
 

package/src/web-components/interaction/BdsButton.stories.tsx

@@ -210,3 +210,44 @@ export const AllIconOnly: Story = {
     </div>
   ),
 };
+
+/**
+ * Every size × icon position × variant combination, mirroring the React
+ * `IconOffsetMatrix` story. The icon-to-edge offset (`--button_icon-offset`,
+ * defaulting to half the size's inline padding) is set inside the shadow DOM,
+ * so this also confirms React and the web component stay pixel-identical.
+ */
+export const IconOffsetMatrix: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {(['small', 'medium', 'large'] as const).map(s => (
+        <div key={s} style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+          {(['default', 'outline'] as const).flatMap(v => [
+            <BdsButton key={`${v}-${s}-start`} variant={v} size={s} iconStart={CheckIcon}>
+              {v} {s} start
+            </BdsButton>,
+            <BdsButton key={`${v}-${s}-end`} variant={v} size={s} iconEnd={ArrowRightEnd}>
+              {v} {s} end
+            </BdsButton>,
+          ])}
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * `--button_icon-offset` set on a plain wrapper `<div>` (light DOM, an
+ * ancestor of the `<bds-button>` host) inherits across the shadow boundary
+ * and overrides the default half-padding calculation inside the shadow tree —
+ * confirming the token is a real public override point for the web component.
+ */
+export const IconOffsetOverride: Story = {
+  render: () => (
+    <div style={{ '--button_icon-offset': '4px' } as React.CSSProperties}>
+      <BdsButton size="large" iconStart={CheckIcon}>
+        Fixed 4px offset
+      </BdsButton>
+    </div>
+  ),
+};

package/src/web-components/interaction/bds-button.ts

@@ -70,7 +70,9 @@ export class BdsButton extends LitElement {
       all: unset;
       position: relative;
       font: inherit;
-      padding-inline: var(--bds-space_l);
+      --button_padding-inline--size: var(--bds-space_l);
+
+      padding-inline: var(--button_padding-inline--size);
       display: inline-flex;
       gap: var(--bds-space_xs);
       border-radius: var(--button_radius, var(--bds-border_radius--full));
@@ -120,17 +122,17 @@ export class BdsButton extends LitElement {
     .button.small {
       --button_height:    2.25em;
       --button_font-size: var(--bds-font_size--body--s);
-      padding-inline: var(--bds-space_m);
+      --button_padding-inline--size: var(--bds-space_m);
     }
 
     .button.medium {
       --button_height: 3em;
-      padding-inline: var(--bds-space_l);
+      --button_padding-inline--size: var(--bds-space_l);
     }
 
     .button.large {
       --button_font-size: var(--bds-font_size--heading-3);
-      padding-inline: var(--bds-space_xl);
+      --button_padding-inline--size: var(--bds-space_xl);
     }
 
     /* Pulse */
@@ -173,15 +175,23 @@ export class BdsButton extends LitElement {
       align-items: center;
     }
 
+    /* Icon offset — pulls the icon into the padding so the optical gap between
+       icon and edge matches the gap between label and edge. Defaults to half
+       the size's inline padding (--button_padding-inline--size, set above per
+       size), so it scales automatically with size and with the responsive
+       space tokens. --button_icon-offset is the public override; it is read
+       only as a var() fallback here, never declared on .button, so a value
+       set on the host or an ancestor inherits through the shadow boundary
+       instead of being shadowed by a same-element declaration. */
     .icon-start.has-content {
       display: flex;
-      margin-inline-start: calc(var(--bds-space_s) * -1);
+      margin-inline-start: calc(var(--button_icon-offset, calc(var(--button_padding-inline--size) / 2)) * -1);
       transition: var(--bds-animation_transition);
     }
 
     .icon-end.has-content {
       display: flex;
-      margin-inline-end: calc(var(--bds-space_s) * -1);
+      margin-inline-end: calc(var(--button_icon-offset, calc(var(--button_padding-inline--size) / 2)) * -1);
       transition: var(--bds-animation_transition);
     }