@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/components/interaction/form/Switch/Switch.module.css

@@ -1,10 +1,5 @@
 @layer boostdev.component {
   .switchGroup {
-    --switch_thumb-size:   1.25em;
-    --switch_track-pad:    var(--bds-space_xxxs);
-    --switch_track-height: calc(var(--switch_thumb-size) + var(--switch_track-pad) * 2);
-    --switch_track-width:  calc(var(--switch_thumb-size) * 2 + var(--switch_track-pad) * 2);
-
     color: var(--switch_color, var(--bds-color_on-bg));
     display: flex;
     flex-direction: column;
@@ -25,8 +20,8 @@
     display: inline-flex;
     align-items: center;
     flex-shrink: 0;
-    inline-size: var(--switch_track-width);
-    block-size: var(--switch_track-height);
+    inline-size: calc(var(--switch_thumb-size, 1.25em) * 2 + var(--switch_track-pad, var(--bds-space_xxxs)) * 2);
+    block-size: calc(var(--switch_thumb-size, 1.25em) + var(--switch_track-pad, var(--bds-space_xxxs)) * 2);
   }
 
   /* Real input — invisible overlay to capture pointer/keyboard events */
@@ -50,11 +45,11 @@
   .track {
     display: inline-flex;
     align-items: center;
-    inline-size: var(--switch_track-width);
-    block-size: var(--switch_track-height);
+    inline-size: calc(var(--switch_thumb-size, 1.25em) * 2 + var(--switch_track-pad, var(--bds-space_xxxs)) * 2);
+    block-size: calc(var(--switch_thumb-size, 1.25em) + var(--switch_track-pad, var(--bds-space_xxxs)) * 2);
     border-radius: var(--switch_track-radius, var(--bds-border_radius--full));
     background-color: var(--switch_track-bg, var(--bds-color_grey--subtle));
-    padding-inline: var(--switch_track-pad);
+    padding-inline: var(--switch_track-pad, var(--bds-space_xxxs));
     pointer-events: none;
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--switch_shadow, var(--bdc-outline_shadow));
     transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
@@ -67,8 +62,8 @@
   /* Thumb */
   .thumb {
     display: block;
-    inline-size: var(--switch_thumb-size);
-    block-size: var(--switch_thumb-size);
+    inline-size: var(--switch_thumb-size, 1.25em);
+    block-size: var(--switch_thumb-size, 1.25em);
     border-radius: var(--switch_thumb-radius, var(--bds-border_radius--circle));
     background-color: var(--switch_thumb-bg, var(--bds-color_interactive));
     box-shadow: var(--bds-shadow_s);
@@ -90,7 +85,11 @@
 
   .switch:checked + .track .thumb {
     background-color: var(--switch_thumb-bg--active, var(--bds-color_interactive));
-    transform: translateX(var(--switch_thumb-size));
+    transform: translateX(var(--switch_thumb-size, 1.25em));
+  }
+
+  [dir='rtl'] .switch:checked + .track .thumb {
+    transform: translateX(calc(var(--switch_thumb-size, 1.25em) * -1));
   }
 
   /* Focus visible on the visual track */

package/src/components/interaction/form/Switch/Switch.spec.tsx

@@ -68,4 +68,24 @@ describe('Switch', () => {
     render(<Switch label="Toggle" name="size-l" size="large" />);
     expect(screen.getByRole('switch').closest('.switchGroup')).toHaveClass('--size_large');
   });
+
+  it('sets aria-invalid when an error is present', () => {
+    render(<Switch label="Accept" name="accept" error="Required" />);
+    expect(screen.getByRole('switch')).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('does not set aria-invalid when there is no error', () => {
+    render(<Switch label="Accept" name="accept" />);
+    expect(screen.getByRole('switch')).toHaveAttribute('aria-invalid', 'false');
+  });
+
+  it('keeps the label associated with the input when a consumer id is passed', () => {
+    render(<Switch label="Toggle" name="toggle" id="custom-switch-id" />);
+    expect(screen.getByLabelText('Toggle')).toBeInTheDocument();
+  });
+
+  it('keeps role="switch" even when a consumer role is passed', () => {
+    render(<Switch label="Toggle" name="toggle" role="checkbox" />);
+    expect(screen.getByRole('switch')).toBeInTheDocument();
+  });
 });

package/src/components/interaction/form/Switch/Switch.tsx

@@ -36,13 +36,14 @@ export function Switch({
         {prefix && <span>{prefix}</span>}
         <div className={css.trackWrapper}>
           <input
+            {...props}
             type="checkbox"
             role="switch"
             id={id}
             name={name}
             aria-describedby={describedBy}
+            aria-invalid={!!error}
             className={cn(css.switch, error ? css.switchError : undefined)}
-            {...props}
           />
           <span className={css.track} aria-hidden="true">
             <span className={css.thumb} />

package/src/components/interaction/form/Textarea/Textarea.mdx

@@ -47,6 +47,11 @@ Multi-line text input with label, hint, and error support.
 <tr><td>`--textarea_border`</td><td>`none`</td><td>Border</td></tr>
 <tr><td>`--textarea_radius`</td><td>`var(--bdc-outline_radius--l)` (1.5em)</td><td>Corner radius</td></tr>
 <tr><td>`--textarea_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Box shadow</td></tr>
+<tr><td>`--textarea_padding`</td><td>`var(--bds-space_s)`</td><td>Inner padding</td></tr>
+<tr><td>`--textarea_font-family`</td><td>`var(--bds-font_family--body)`</td><td>Font family</td></tr>
+<tr><td>`--textarea_font-size`</td><td>`var(--bds-font_size--body)`</td><td>Font size</td></tr>
+<tr><td>`--textarea_line-height`</td><td>`var(--bds-font_line-height--body)`</td><td>Line height</td></tr>
+<tr><td>`--textarea_min-block-size`</td><td>`calc(var(--bds-space_m) * 5)`</td><td>Minimum height</td></tr>
 </tbody>
 </table>
 

package/src/components/interaction/form/Textarea/Textarea.module.css

@@ -5,10 +5,10 @@
   }
 
   .textarea {
-    font-family: var(--bds-font_family--body);
-    font-size: var(--bds-font_size--body);
-    line-height: var(--bds-font_line-height--body);
-    padding: var(--bds-space_s);
+    font-family: var(--textarea_font-family, var(--bds-font_family--body));
+    font-size: var(--textarea_font-size, var(--bds-font_size--body));
+    line-height: var(--textarea_line-height, var(--bds-font_line-height--body));
+    padding: var(--textarea_padding, var(--bds-space_s));
     border: var(--textarea_border, none);
     --bdc_color: currentcolor;
     --bdc-outline_radius: var(--bdc-outline_radius--l);
@@ -18,7 +18,7 @@
     background-color: var(--textarea_color_bg, var(--bds-color_bg));
     color: var(--textarea_color, var(--bds-color_on-bg));
     resize: vertical;
-    min-block-size: calc(var(--bds-space_m) * 5);
+    min-block-size: var(--textarea_min-block-size, calc(var(--bds-space_m) * 5));
     transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
                 background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
   }

package/src/components/interaction/form/Textarea/Textarea.spec.tsx

@@ -50,4 +50,17 @@ describe('Textarea', () => {
     render(<Textarea label="Message" name="message" rows={6} />);
     expect(screen.getByRole('textbox')).toHaveAttribute('rows', '6');
   });
+
+  it('keeps the label and message wired to a consumer-provided id', () => {
+    render(
+      <Textarea label="Message" name="message" id="custom-id" hint="Max 500 characters" error="Required" />
+    );
+    const textarea = screen.getByLabelText('Message');
+    expect(textarea).toHaveAttribute('id', 'custom-id');
+    const describedBy = textarea.getAttribute('aria-describedby');
+    expect(describedBy).toBeTruthy();
+    describedBy
+      ?.split(' ')
+      .forEach((describedById) => expect(describedById.startsWith('custom-id')).toBe(true));
+  });
 });

package/src/components/interaction/form/Textarea/Textarea.tsx

@@ -20,9 +20,11 @@ export function Textarea({
   hint,
   className,
   required,
+  id: idProp,
   ...props
 }: Readonly<TextareaProps>) {
-  const id = name + useId();
+  const generatedId = useId();
+  const id = idProp ?? name + generatedId;
   const hintId = id + 'hint';
   const errorId = id + 'error';
   const describedBy = [error && errorId, hint && hintId].filter(Boolean).join(' ') || undefined;

package/src/components/interaction/form/atoms/Message.module.css

@@ -2,7 +2,7 @@
   .error,
   .hint {
     font-size: var(--bds-font_size--body--s);
-    margin-inline-start: var(--labelPosition);
+    margin-inline-start: var(--labelPosition, 0);
   }
 
   .error {

package/src/components/interaction/form/atoms/Message.spec.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react';
+import { Message } from './Message';
+
+describe('Message', () => {
+  it('renders nothing when message is undefined', () => {
+    const { container } = render(<Message inputId="field-1" type="hint" message={undefined} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders the message text', () => {
+    render(<Message inputId="field-1" type="hint" message="At least 8 characters." />);
+    expect(screen.getByText('At least 8 characters.')).toBeInTheDocument();
+  });
+
+  it('exposes an error message via role=alert so it is announced to assistive tech', () => {
+    render(<Message inputId="field-1" type="error" message="This field is required." />);
+    expect(screen.getByRole('alert')).toHaveTextContent('This field is required.');
+  });
+
+  it('does not expose a hint message as an alert', () => {
+    render(<Message inputId="field-1" type="hint" message="Optional hint." />);
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+
+  it('sets the message id to inputId concatenated with type', () => {
+    render(<Message inputId="field-1" type="error" message="Required" />);
+    expect(screen.getByRole('alert')).toHaveAttribute('id', 'field-1error');
+  });
+});

package/src/components/interaction/form/atoms/Message.tsx

@@ -12,7 +12,7 @@ export const Message = ({ message, type, inputId, className }: MessageProps) =>
   if (!message) return null;
 
   return (
-    <p id={inputId + type} className={cn(css[type], className)}>
+    <p id={inputId + type} role={type === 'error' ? 'alert' : undefined} className={cn(css[type], className)}>
       {message}
     </p>
   );

package/src/components/layout/ButtonGroup/ButtonGroup.mdx

@@ -45,6 +45,17 @@ Layout wrapper that arranges `Button` children according to a contextual variant
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--buttonGroup_gap`</td><td>`var(--bds-space_l)`</td><td>Gap between buttons.</td></tr>
+</tbody>
+</table>
+
 ## Accessibility
 
 - Renders as `<div role="group">` — no additional ARIA needed for the wrapper

package/src/components/layout/ButtonGroup/ButtonGroup.module.css

@@ -10,7 +10,7 @@
     position: relative;
     display: flex;
     flex-direction: column-reverse;
-    gap: var(--bds-space_l);
+    gap: var(--buttonGroup_gap, var(--bds-space_l));
     align-items: center;
   }
 
@@ -51,10 +51,6 @@
         justify-content: flex-start;
         align-items: center;
       }
-
-      .buttonGroup.--variant_grid .container {
-        justify-content: center;
-      }
     }
   }
 }

package/src/components/layout/ButtonGroup/ButtonGroup.stories.tsx

@@ -20,6 +20,20 @@ const TwoButtons = () => (
   </>
 );
 
+const ThreeButtons = () => (
+  <>
+    <Button variant="outline">Back</Button>
+    <Button variant="outline">Save draft</Button>
+    <Button variant="default">Publish</Button>
+  </>
+);
+
+/** Two actions — the common Cancel / Confirm row. */
+export const TwoButtonsExample: Story = { render: () => <ButtonContainer variant="modal"><TwoButtons /></ButtonContainer> };
+
+/** Three actions. */
+export const ThreeButtonsExample: Story = { render: () => <ButtonContainer variant="content"><ThreeButtons /></ButtonContainer> };
+
 export const Default: Story = { render: () => <ButtonContainer><TwoButtons /></ButtonContainer> };
 export const Flow: Story = { render: () => <ButtonContainer variant="flow"><TwoButtons /></ButtonContainer> };
 export const Card: Story = { render: () => <ButtonContainer variant="card"><TwoButtons /></ButtonContainer> };

package/src/components/layout/Card/Card.mdx

@@ -54,6 +54,9 @@ Contained surface for grouping related content. Three visual variants provide di
 <tr><td>`--card_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Card text colour.</td></tr>
 <tr><td>`--card_padding`</td><td>varies by `padding` prop</td><td>Card padding (overrides the prop default).</td></tr>
 <tr><td>`--card_border`</td><td>`none`</td><td>Border (outlined variant).</td></tr>
+<tr><td>`--card_radius`</td><td>`var(--bds-border_radius--m)`</td><td>Card corner radius.</td></tr>
+<tr><td>`--card_transition`</td><td>`var(--bds-animation_transition)`</td><td>Transition applied to colour/shadow/transform changes.</td></tr>
+<tr><td>`--card_shadow--active`</td><td>`var(--bds-shadow_s)`</td><td>Box-shadow while a clickable card is pressed (`:active`).</td></tr>
 </tbody>
 </table>
 
@@ -76,6 +79,8 @@ Plus `--card_shadow--clickable-hover` (`var(--bds-shadow_xl)`) for hover on any
 ## Accessibility
 
 - Static card renders as `<div>` — no interactive role
-- Clickable card renders as `<button>` — keyboard and screen reader accessible
+- Clickable card renders as `<button>` — keyboard and screen reader accessible, with browser UA button styling (font, alignment, border, width) reset to match a non-interactive card
+- Focus-visible ring on a clickable card uses `--bds-outline_default` / `--bds-outline_offset` (the same focus treatment as every other interactive component)
+- The hover lift and colour/shadow transitions respect `prefers-reduced-motion` — both are disabled when the user has opted out
 - When using `as="a"`, provide a valid `href`; when using a router `Link`, ensure it forwards `className` and `children`
 - Ensure clickable cards have a meaningful accessible name (via visible text content)

package/src/components/layout/Card/Card.module.css

@@ -2,11 +2,21 @@
   .card {
     background-color: var(--card_color, var(--bds-color_bg));
     color: var(--card_on-color, var(--bds-color_on-bg));
-    border-radius: var(--bds-border_radius--m);
-    transition: all 0.3s ease;
+    border-radius: var(--card_radius, var(--bds-border_radius--m));
+    transition: var(--card_transition, var(--bds-animation_transition));
     position: relative;
   }
 
+  /* Clickable cards render as <button> — normalize UA button styles so it
+     looks and lays out identically to a non-interactive card. */
+  .card:is(button) {
+    border: none;
+    font: inherit;
+    text-align: inherit;
+    display: block;
+    inline-size: 100%;
+  }
+
   /* Resting shadows — consumers can override per-variant via
      --card_shadow--default / --card_shadow--elevated / --card_shadow--outlined. */
   .card.--default {
@@ -61,13 +71,13 @@
   }
 
   .card.--clickable:focus-visible {
-    outline: 2px solid var(--color_focus, currentcolor);
-    outline-offset: 2px;
+    outline: var(--bds-outline_default);
+    outline-offset: var(--bds-outline_offset);
   }
 
   .card.--clickable:active {
     transform: translateY(0);
-    box-shadow: var(--bds-shadow_s);
+    box-shadow: var(--card_shadow--active, var(--bds-shadow_s));
   }
 
   @media (hover: hover) and (pointer: fine) {
@@ -88,4 +98,15 @@
       box-shadow: var(--card_shadow--outlined-hover, var(--bds-shadow_s));
     }
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    .card {
+      transition: none;
+    }
+
+    .card.--clickable:hover,
+    .card.--clickable:active {
+      transform: none;
+    }
+  }
 }

package/src/components/layout/Card/Card.spec.tsx

@@ -18,6 +18,13 @@ describe('Card', () => {
     expect(screen.getByRole('button')).toBeInTheDocument();
   });
 
+  it('keeps the card class on the button so UA button styles are normalized', () => {
+    render(<Card onClick={() => {}}>Clickable</Card>);
+    // The `.card:is(button)` rule (font/text-align/display/border reset) only
+    // applies if the rendered <button> still carries the base `card` class.
+    expect(screen.getByRole('button')).toHaveClass('card');
+  });
+
   it('calls onClick when clicked', async () => {
     const user = userEvent.setup();
     const onClick = vi.fn();

package/src/components/layout/Card/Card.tsx

@@ -3,14 +3,15 @@ import css from './Card.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
 
-type CardOwnProps = WithClassName & {
+type CardOwnProps<C extends ElementType> = WithClassName & {
   variant?: 'default' | 'elevated' | 'outlined';
   padding?: 'none' | 'small' | 'medium' | 'large' | 'extra-large';
   textAlign?: 'start' | 'center' | 'end';
-  as?: ElementType;
+  as?: C;
 };
 
-type CardProps<C extends ElementType = 'div'> = CardOwnProps & Omit<ComponentPropsWithoutRef<C>, keyof CardOwnProps>;
+type CardProps<C extends ElementType = 'div'> = CardOwnProps<C> &
+  Omit<ComponentPropsWithoutRef<C>, keyof CardOwnProps<C>>;
 
 export function Card<C extends ElementType = 'div'>({
   children,

package/src/components/layout/Grid/Grid.spec.tsx

@@ -402,6 +402,50 @@ describe('applyMasonryLayout', () => {
       expect(a.style.gridColumn).toBe('var(--bds-grid_span-100)');
     });
 
+    it('accounts for a row wrap when an explicit-span item does not fit the remaining columns', () => {
+      // Regression: the demotion cursor advanced by `col + consumed` even when
+      // `consumed` overflowed the remaining row space. CSS Grid's `dense`
+      // auto-placement actually wraps a too-wide explicit item to the start of
+      // the next row, so the cursor must jump to `consumed`, not `col + consumed`.
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const a = makeAutoItem(50);
+      const explicit = makeItem(50);
+      explicit.style.gridColumn = 'span 3';
+      const b = makeAutoItem(50);
+      container.append(a, explicit, b);
+      // 'half' in a 4-col grid → 2 cols (fraction fallback).
+      applyMasonryLayout(container, [a, explicit, b], { preferredColumnSpan: 'half' });
+      expect(a.style.gridColumn).toBe('span 2'); // cols 0-1, cursor -> 2
+      expect(explicit.style.gridColumn).toBe('span 3'); // doesn't fit remaining 2 cols -> wraps, cursor -> 3
+      expect(b.style.gridColumn).toBe('span 1'); // only 1 col remains in the wrapped row -> demoted
+    });
+
+    it('refreshes the restore snapshot when something else rewrites the item inline gridColumn between runs', () => {
+      // Regression: GridItem's `columnSpan="auto"` re-renders (e.g. once an
+      // image's aspect ratio resolves) overwrite the inline `gridColumn` the
+      // polyfill previously wrote. The polyfill only snapshotted the ORIGINAL
+      // value once, so it never picked up React's fresh value — unsetting
+      // `masonryPreferredColumnSpan` later restored the stale pre-resolve span.
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const a = makeAutoItem(50);
+      a.style.gridColumn = 'span var(--bds-grid_columns-25)'; // placeholder before media resolves
+      container.append(a);
+
+      applyMasonryLayout(container, [a], { preferredColumnSpan: 'half' });
+      expect(a.style.gridColumn).toBe('span 2');
+
+      // Simulate React re-rendering GridItem after the image resolves, which
+      // overwrites the inline style the polyfill wrote.
+      a.style.gridColumn = 'span var(--bds-grid_columns-50)';
+      applyMasonryLayout(container, [a], { preferredColumnSpan: 'half' });
+      expect(a.style.gridColumn).toBe('span 2'); // preferred span still wins while set
+
+      applyMasonryLayout(container, [a]); // preferredColumnSpan dropped
+      expect(a.style.gridColumn).toBe('span var(--bds-grid_columns-50)'); // restores the fresh value, not the stale placeholder
+    });
+
     it('clearMasonryLayout restores gridColumn on data-column-span-auto items', () => {
       const container = makeContainer(10);
       container.style.gridTemplateColumns = '100px 100px 100px 100px';

package/src/components/layout/Grid/Grid.tsx

@@ -34,7 +34,7 @@ export function getGridContext(): Context<GridContextValue> {
   return _GridContext;
 }
 
-type GridOwnProps = WithClassName & {
+type GridOwnProps<C extends ElementType> = WithClassName & {
   variant?: GridVariant;
   columns?: number;
   isCentered?: boolean;
@@ -68,11 +68,11 @@ type GridOwnProps = WithClassName & {
    * you've confirmed the auto-tuner is wrong for your case.
    */
   masonryRowUnitPx?: number;
-  as?: ElementType;
+  as?: C;
 };
 
-type GridProps<C extends ElementType = 'div'> = GridOwnProps &
-  Omit<ComponentPropsWithoutRef<C>, keyof GridOwnProps>;
+type GridProps<C extends ElementType = 'div'> = GridOwnProps<C> &
+  Omit<ComponentPropsWithoutRef<C>, keyof GridOwnProps<C>>;
 
 export function Grid<C extends ElementType = 'div'>({
   children,
@@ -113,7 +113,7 @@ export function Grid<C extends ElementType = 'div'>({
   const ctx = useMemo<GridContextValue>(() => ({ autoSpanMedia }), [autoSpanMedia]);
 
   return (
-    <Component ref={ref} {...rest} className={classNames} style={composedStyle}>
+    <Component ref={ref as never} {...rest} className={classNames} style={composedStyle}>
       <GridContext.Provider value={ctx}>{children}</GridContext.Provider>
     </Component>
   );

package/src/components/layout/Grid/GridItem.tsx

@@ -3,7 +3,6 @@ import {
   ComponentPropsWithoutRef,
   CSSProperties,
   useContext,
-  useLayoutEffect,
   useRef,
   useState,
 } from 'react';
@@ -18,6 +17,7 @@ import {
   readMediaAspect,
   type AutoSpanResult,
 } from './autoSpan';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
 
 export type GridItemSpanValue =
   | 'full'
@@ -53,16 +53,16 @@ function resolveSpan(value: Exclude<GridItemSpanValue, 'auto'>): string {
   return SPAN_VAR[value];
 }
 
-type GridItemOwnProps = WithClassName & {
+type GridItemOwnProps<C extends ElementType> = WithClassName & {
   columnSpan?: GridItemSpanValue;
   rowSpan?: number;
   startColumn?: number;
   endColumn?: number;
-  as?: ElementType;
+  as?: C;
 };
 
-type GridItemProps<C extends ElementType = 'div'> = GridItemOwnProps &
-  Omit<ComponentPropsWithoutRef<C>, keyof GridItemOwnProps>;
+type GridItemProps<C extends ElementType = 'div'> = GridItemOwnProps<C> &
+  Omit<ComponentPropsWithoutRef<C>, keyof GridItemOwnProps<C>>;
 
 export function GridItem<C extends ElementType = 'div'>({
   children,
@@ -82,7 +82,7 @@ export function GridItem<C extends ElementType = 'div'>({
   const ref = useRef<HTMLElement | null>(null);
   const [autoSpan, setAutoSpan] = useState<AutoSpanResult>('one-quarter');
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (effectiveSpan !== 'auto') return;
     const el = ref.current;
     if (!el) return;

package/src/components/layout/Grid/masonry.ts

@@ -1,5 +1,6 @@
-import { RefObject, useLayoutEffect } from 'react';
+import { RefObject } from 'react';
 import type { GridItemSpanValue } from './GridItem';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
 
 type NamedSpan = Exclude<GridItemSpanValue, 'auto' | number>;
 
@@ -114,6 +115,17 @@ export type MasonryOptions = {
 // items pinned to their polyfill-assigned span.
 const ORIGINAL_COL_ATTR = 'data-bds-masonry-original-column';
 
+// Data attribute caching the last `gridColumn` value the polyfill itself wrote
+// for a preferred-span item. Used to detect drift: React re-renders a
+// `data-column-span-auto` GridItem whenever its own computed span changes
+// (e.g. `columnSpan="auto"` resolving after an image's aspect ratio loads),
+// overwriting the inline `gridColumn` the polyfill previously set. Without
+// this check, ORIGINAL_COL_ATTR would stay pinned to whatever value existed
+// the very first time the polyfill ran (often a placeholder), so removing
+// `masonryPreferredColumnSpan`/`isMasonry` later would restore that stale
+// value instead of the item's real current span.
+const LAST_COL_ATTR = 'data-bds-masonry-col';
+
 // Data attribute caching the last applied row-span. Used to short-circuit no-op
 // re-runs: when every child's newly-measured span matches the cached value, the
 // polyfill skips all writes. This prevents `grid-auto-flow: dense` from
@@ -190,17 +202,30 @@ export function applyMasonryLayout(
       let col = 0;
       for (const child of children) {
         if (child.hasAttribute('data-column-span-auto')) {
-          if (!child.hasAttribute(ORIGINAL_COL_ATTR)) {
-            child.setAttribute(ORIGINAL_COL_ATTR, child.style.gridColumn);
+          const currentInline = child.style.gridColumn;
+          const lastWritten = child.getAttribute(LAST_COL_ATTR);
+          // Refresh the snapshot on first sight, or when something other than
+          // the polyfill (i.e. React re-rendering the item) has since changed
+          // the inline value — otherwise we'd restore a stale span later.
+          if (!child.hasAttribute(ORIGINAL_COL_ATTR) || currentInline !== lastWritten) {
+            child.setAttribute(ORIGINAL_COL_ATTR, currentInline);
           }
           const remaining = totalCols - col;
           const span = Math.max(1, Math.min(preferredCols, remaining));
           child.style.gridColumn = `span ${span}`;
+          child.setAttribute(LAST_COL_ATTR, child.style.gridColumn);
           col = (col + span) % totalCols;
         } else {
           // Item has an explicit span — consume its columns for the demotion budget.
           const consumed = Math.min(totalCols, readExplicitSpan(child, totalCols));
-          col = (col + consumed) % totalCols;
+          // A span that doesn't fit the remaining row wraps to a fresh row in
+          // the browser's auto-placement algorithm (dense packing places it at
+          // the start of the next row, not at `col + consumed`).
+          if (consumed > totalCols - col) {
+            col = consumed % totalCols;
+          } else {
+            col = (col + consumed) % totalCols;
+          }
         }
       }
     }
@@ -340,6 +365,7 @@ function restoreOriginalColumn(el: HTMLElement): void {
   if (!el.hasAttribute(ORIGINAL_COL_ATTR)) return;
   el.style.gridColumn = el.getAttribute(ORIGINAL_COL_ATTR) ?? '';
   el.removeAttribute(ORIGINAL_COL_ATTR);
+  el.removeAttribute(LAST_COL_ATTR);
 }
 
 /**
@@ -353,7 +379,7 @@ export function useMasonry(
   options: MasonryOptions = {},
 ): void {
   const { preferredColumnSpan, rowUnitPx } = options;
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const container = ref.current;
     if (!container || !enabled) return;
     if (supportsNativeMasonry()) return;

package/src/components/layout/Grid/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,11 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+/**
+ * `useLayoutEffect` that falls back to `useEffect` when there is no DOM
+ * (SSR / RSC). React 18 logs a warning ("useLayoutEffect does nothing on
+ * the server") whenever `useLayoutEffect` runs during a non-browser render —
+ * this avoids that warning while preserving the synchronous-before-paint
+ * timing `GridItem` and the masonry polyfill both depend on in the browser.
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;

package/src/components/layout/IconWrapper/IconWrapper.mdx

@@ -28,11 +28,17 @@ Circular container that sizes to its own `font-size`. Use to give an SVG icon a
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--icon-wrapper-color`</td><td>`var(--bds-color_bg)`</td><td>Background colour</td></tr>
-<tr><td>`--bds-on-icon-wrapper-color`</td><td>`var(--bds-color_on-bg)`</td><td>Icon colour</td></tr>
+<tr><td>`--icon-wrapper_color`</td><td>`var(--bds-color_bg)`</td><td>Background colour</td></tr>
+<tr><td>`--icon-wrapper_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Icon colour (text/fill)</td></tr>
+<tr><td>`--icon-wrapper_radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Corner radius</td></tr>
+<tr><td>`--icon-wrapper_size`</td><td>`3em`</td><td>Font size — drives the icon's `1em`-based glyph size</td></tr>
+<tr><td>`--icon-wrapper_margin-block-start`</td><td>`var(--bds-space_l)`</td><td>Space above the wrapper</td></tr>
+<tr><td>`--icon-wrapper_margin-block-end`</td><td>`var(--bds-space_m)`</td><td>Space below the wrapper</td></tr>
 </tbody>
 </table>
 
+> `--icon-wrapper-color` and `--icon-wrapper-radius` (hyphen-delimited) are deprecated aliases for `--icon-wrapper_color` and `--icon-wrapper_radius` — still supported, but new code should use the underscore-delimited names.
+
 
 ## Accessibility