@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/components/interaction/Toast/Toast.tsx

@@ -2,7 +2,7 @@ import { useState, useEffect, createContext, useContext, ReactNode, useCallback,
 import css from './Toast.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 
-type ToastVariant = 'success' | 'error' | 'info';
+type ToastVariant = 'success' | 'error' | 'info' | 'warning';
 
 interface Toast {
   id: string;
@@ -37,13 +37,15 @@ export function ToastProvider({ children }: { children: ReactNode }) {
   }, []);
 
   // Sync the popover's top-layer visibility with the toast queue.
-  // showPopover() is a no-op when already open (safe to call multiple times).
-  // hidePopover() throws InvalidStateError when already hidden, so catch silently.
+  // Both showPopover() and hidePopover() throw an InvalidStateError when called
+  // in a redundant state (e.g. showPopover() while a 2nd/3rd toast is queued and
+  // the popover is already open, or hidePopover() before any toast has shown) —
+  // catch silently in both directions.
   useEffect(() => {
     const container = containerRef.current;
     if (!container) return;
     if (toasts.length > 0) {
-      container.showPopover?.();
+      try { container.showPopover?.(); } catch { /* already open */ }
     } else {
       try { container.hidePopover?.(); } catch { /* already hidden on initial mount */ }
     }
@@ -65,7 +67,7 @@ export function ToastProvider({ children }: { children: ReactNode }) {
           <ToastItem
             key={toast.id}
             toast={toast}
-            onRemove={() => removeToast(toast.id)}
+            onRemove={removeToast}
           />
         ))}
       </div>
@@ -73,16 +75,20 @@ export function ToastProvider({ children }: { children: ReactNode }) {
   );
 }
 
-function ToastItem({ toast, onRemove }: { toast: Toast; onRemove: () => void }) {
+// `onRemove` is the stable `removeToast` callback (identity never changes across
+// renders) and `toast.id` never changes for a given ToastItem instance, so this
+// effect mounts once per toast and is never re-triggered by sibling toasts
+// joining/leaving the queue — each toast auto-dismisses on its own 5s schedule.
+function ToastItem({ toast, onRemove }: { toast: Toast; onRemove: (id: string) => void }) {
   useEffect(() => {
-    const timer = setTimeout(onRemove, 5000);
+    const timer = setTimeout(() => onRemove(toast.id), 5000);
     return () => clearTimeout(timer);
-  }, [onRemove]);
+  }, [onRemove, toast.id]);
 
   return (
     <div className={cn(css.toast, css[`--variant_${toast.variant}`])} role="status" aria-live="polite" aria-atomic="true">
       <span className={css.message}>{toast.message}</span>
-      <button type="button" className={css.closeButton} onClick={onRemove} aria-label="Dismiss">
+      <button type="button" className={css.closeButton} onClick={() => onRemove(toast.id)} aria-label="Dismiss">
         <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
           <path strokeLinecap="round" strokeLinejoin="round" d="M18 6L6 18M6 6l12 12" />
         </svg>

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

@@ -46,6 +46,9 @@ Binary toggle for opt-in/opt-out choices. Renders a styled native `<input type="
 <tbody>
 <tr><td>`--checkbox_color-active`</td><td>`var(--bdc-color_active)`</td><td>Checked background</td></tr>
 <tr><td>`--checkbox_color-on-active`</td><td>`var(--bdc-color_on-active)`</td><td>Checkmark colour</td></tr>
+<tr><td>`--checkbox_size`</td><td>`calc(var(--bds-space_s) * 2)`</td><td>Checkbox width/height</td></tr>
+<tr><td>`--checkbox_gap`</td><td>`var(--bds-space_m)`</td><td>Gap between the checkbox and its label</td></tr>
+<tr><td>`--checkbox_offset`</td><td>`0.25em`</td><td>Vertical nudge to align the checkbox with the first line of the label</td></tr>
 </tbody>
 </table>
 

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

@@ -1,6 +1,7 @@
 @layer boostdev.component {
   .checkboxGroup {
-    --inputSize: calc(var(--bds-space_s) * 2);
+    --checkbox_size: calc(var(--bds-space_s) * 2);
+    --inputSize:     var(--checkbox_size);
 
     display: flex;
     flex-direction: column;
@@ -9,13 +10,13 @@
   .inputWrapper {
     display: flex;
     align-items: stretch;
-    gap: var(--bds-space_xs);
+    gap: var(--checkbox_gap, var(--bds-space_m));
   }
 
   .checkbox {
-    margin-block-start: 0.25em;
-    inline-size: var(--inputSize);
-    block-size: var(--inputSize);
+    margin-block-start: var(--checkbox_offset, 0.25em);
+    inline-size: var(--checkbox_size);
+    block-size: var(--checkbox_size);
     color: var(--checkbox_color, var(--bds-color_on-bg));
     border: var(--checkbox_border, none);
     --bdc_color: currentcolor;
@@ -27,7 +28,8 @@
     background-color: var(--checkbox_color_bg, var(--bds-color_bg));
     cursor: pointer;
     position: relative;
-    transition: --bdc_color 0.3s ease, background-color 0.3s ease;
+    transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
+      background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
   }
 
   .checkbox:checked {
@@ -56,6 +58,11 @@
     outline-offset: var(--bds-outline_offset);
   }
 
+  .checkbox:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
   .checkboxError {
     --bdc_color: var(--bdc_color--error);
   }

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

@@ -36,4 +36,10 @@ describe('Checkbox', () => {
     render(<Checkbox label="Disabled" name="disabled" disabled />);
     expect(screen.getByRole('checkbox')).toBeDisabled();
   });
+
+  it('keeps label association when a conflicting id prop is passed', () => {
+    render(<Checkbox label="Accept terms" name="terms" id="consumer-supplied-id" />);
+    const checkbox = screen.getByLabelText('Accept terms');
+    expect(checkbox.id).not.toBe('consumer-supplied-id');
+  });
 });

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

@@ -23,13 +23,13 @@ export function Checkbox({ label, name, error, hint, className, ...props }: Chec
     <InputContainer className={cn(css.checkboxGroup, className)}>
       <div className={css.inputWrapper}>
         <input
+          {...props}
           aria-describedby={describedBy}
           aria-invalid={!!error}
           type="checkbox"
           id={id}
           name={name}
           className={cn(css.checkbox, error && css.checkboxError)}
-          {...props}
         />
         <Label id={id} label={label} />
       </div>

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

@@ -36,9 +36,24 @@ Groups multiple `Checkbox` inputs under a shared label. Renders a `<fieldset>` w
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+All public override tokens. Set on the CheckboxGroup or any ancestor; they cascade.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--checkboxGroup_gap` | `var(--bds-space_xs)` | Gap between the legend/items block and, via `--checkboxGroup_items-gap`, between the child checkboxes. |
+| `--checkboxGroup_items-gap` | `var(--bds-space_xs)` | Gap between the child checkboxes. |
+| `--checkboxGroup_legend-color` | `var(--bds-color_on-bg)` | Legend text colour. |
+| `--checkboxGroup_legend-font-family` | `var(--bds-font_family--body)` | Legend font family. |
+| `--checkboxGroup_legend-font-size` | `var(--bds-font_size--body--s)` | Legend font size. |
+| `--checkboxGroup_legend-font-weight` | `var(--bds-font_weight--medium)` | Legend font weight. |
+| `--checkboxGroup_legend-gap` | `var(--bds-space_xs)` | Space below the legend before the items. |
+| `--checkboxGroup_required-color` | `var(--bds-color_error)` | Colour of the visible `*` required marker. |
+
 ## Accessibility
 
 - Wraps checkboxes in a `<fieldset>` with a `<legend>` — screen readers announce the group label before each option
 - `disabled` on the group sets the HTML `disabled` attribute on the `<fieldset>`, which disables all child inputs
-- `aria-required` is set on the `<fieldset>` when `required` is true
+- When `required` is true, the legend shows a visible `*` (hidden from assistive tech via `aria-hidden`) plus a visually-hidden "(required)" span, so the fieldset's accessible name resolves to `"<legend> (required)"` (e.g. `"Contact preferences (required)"`). `aria-required` is intentionally **not** set on the `<fieldset>` — it is not supported ARIA on a `role=group` element and would be ignored by assistive tech
 - Error and hint messages are linked via `aria-describedby`

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

@@ -5,25 +5,41 @@
     margin: 0;
     display: flex;
     flex-direction: column;
-    gap: var(--bds-space_xs);
+    gap: var(--checkboxGroup_gap, var(--bds-space_xs));
   }
 
   .legend {
-    font-family: var(--bds-font_family--body);
-    font-size: var(--bds-font_size--body--s);
-    font-weight: var(--bds-font_weight--medium);
-    color: var(--bds-color_on-bg);
+    font-family: var(--checkboxGroup_legend-font-family, var(--bds-font_family--body));
+    font-size: var(--checkboxGroup_legend-font-size, var(--bds-font_size--body--s));
+    font-weight: var(--checkboxGroup_legend-font-weight, var(--bds-font_weight--medium));
+    color: var(--checkboxGroup_legend-color, var(--bds-color_on-bg));
     padding: 0;
-    margin-block-end: var(--bds-space_xs);
+    margin-block-end: var(--checkboxGroup_legend-gap, var(--bds-space_xs));
   }
 
   .required {
-    color: var(--bds-color_error);
+    color: var(--checkboxGroup_required-color, var(--bds-color_error));
+  }
+
+  /* Visually hidden but still exposed to assistive tech — carries the
+     "required" state into the fieldset's accessible name, since the
+     visible asterisk above is aria-hidden and `aria-required` is not
+     supported ARIA on a fieldset (role=group). */
+  .requiredLabel {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
   }
 
   .items {
     display: flex;
     flex-direction: column;
-    gap: var(--bds-space_xs);
+    gap: var(--checkboxGroup_items-gap, var(--bds-space_xs));
   }
 }

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

@@ -66,16 +66,46 @@ describe('CheckboxGroup', () => {
     expect(fieldset.getAttribute('aria-describedby')).toContain(hintMsg.id);
   });
 
-  it('marks fieldset as required when required prop is set', () => {
+  it('does not set the unsupported aria-required attribute on the fieldset', () => {
+    render(
+      <CheckboxGroup legend="Required" required>
+        <Checkbox label="Option" name="opt" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByRole('group')).not.toHaveAttribute('aria-required');
+  });
+
+  it('shows a visible required marker when required prop is set', () => {
     render(
       <CheckboxGroup legend="Required" required>
         <Checkbox label="Option" name="opt" />
       </CheckboxGroup>
     );
-    expect(screen.getByRole('group')).toHaveAttribute('aria-required', 'true');
     expect(screen.getByText('*')).toBeInTheDocument();
   });
 
+  it('conveys required state to assistive tech via the accessible group name', () => {
+    render(
+      <CheckboxGroup legend="Contact preferences" required>
+        <Checkbox label="Option" name="opt" />
+      </CheckboxGroup>
+    );
+    expect(
+      screen.getByRole('group', { name: 'Contact preferences (required)' })
+    ).toBeInTheDocument();
+  });
+
+  it('omits the required marker and accessible required text when required is not set', () => {
+    render(
+      <CheckboxGroup legend="Optional preferences">
+        <Checkbox label="Option" name="opt" />
+      </CheckboxGroup>
+    );
+    expect(screen.queryByText('*')).not.toBeInTheDocument();
+    expect(screen.queryByText('(required)')).not.toBeInTheDocument();
+    expect(screen.getByRole('group', { name: 'Optional preferences' })).toBeInTheDocument();
+  });
+
   it('disables the fieldset when disabled prop is set', () => {
     render(
       <CheckboxGroup legend="Disabled" disabled>

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

@@ -29,12 +29,24 @@ export function CheckboxGroup({
     <fieldset
       {...rest}
       className={cn(css.group, className)}
-      aria-required={required || undefined}
       aria-describedby={describedBy}
     >
       <legend className={css.legend}>
         {legend}
-        {required && <span className={css.required} aria-hidden="true"> *</span>}
+        {required && (
+          <>
+            {/* Visible-only marker — aria-hidden because `aria-required` is not
+                supported ARIA on a fieldset/role=group, so requiredness must be
+                conveyed through the legend's accessible text instead (below). The
+                literal `{' '}` text node sits directly in the legend (not nested
+                inside a span) so it survives accessible-name computation — a
+                leading space nested inside an element gets trimmed away when
+                that element's own text alternative is computed. */}
+            <span className={css.required} aria-hidden="true"> *</span>
+            {' '}
+            <span className={css.requiredLabel}>(required)</span>
+          </>
+        )}
       </legend>
       <div className={css.items}>{children}</div>
       <Message inputId={id} type="error" message={error} />

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

@@ -42,10 +42,16 @@ Searchable select with type-ahead filtering. Combines a text input with a dropdo
 <tr><td>`--combobox_border`</td><td>`none`</td><td>Input border</td></tr>
 <tr><td>`--combobox_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Input corner radius</td></tr>
 <tr><td>`--combobox_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Input box shadow</td></tr>
-<tr><td>`--combobox_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Dropdown list text colour</td></tr>
+<tr><td>`--combobox_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Dropdown list and option text colour</td></tr>
+<tr><td>`--combobox_listbox-bg`</td><td>`var(--combobox_color_bg)`</td><td>Dropdown list background colour</td></tr>
 <tr><td>`--combobox_listbox-border`</td><td>`none`</td><td>Dropdown list border</td></tr>
 <tr><td>`--combobox_listbox-radius`</td><td>`var(--bdc-outline_radius)`</td><td>Dropdown list corner radius</td></tr>
 <tr><td>`--combobox_listbox-shadow`</td><td>`var(--bds-shadow_m)`</td><td>Dropdown list box shadow</td></tr>
+<tr><td>`--combobox_listbox-max-block-size`</td><td>`15rem`</td><td>Dropdown list maximum height</td></tr>
+<tr><td>`--combobox_listbox-padding-block`</td><td>`var(--bds-space_xxs)`</td><td>Dropdown list block padding</td></tr>
+<tr><td>`--combobox_option-padding-block`</td><td>`var(--bds-space_xs)`</td><td>Option block padding</td></tr>
+<tr><td>`--combobox_option-padding-inline`</td><td>`var(--bds-space_m)`</td><td>Option inline padding</td></tr>
+<tr><td>`--combobox_option-font-size`</td><td>`var(--bds-font_size--body)`</td><td>Option font size</td></tr>
 <tr><td>`--combobox_option-bg--highlighted`</td><td>`var(--bds-color_bg--subtle)`</td><td>Highlighted option background</td></tr>
 <tr><td>`--combobox_option-color--highlighted`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Highlighted option text colour</td></tr>
 </tbody>
@@ -55,6 +61,7 @@ Searchable select with type-ahead filtering. Combines a text input with a dropdo
 ## Accessibility
 
 - Input uses `role="combobox"` with `aria-autocomplete="list"` and `aria-controls`
-- Listbox uses `role="listbox"` with `role="option"` items
-- `aria-activedescendant` tracks keyboard-highlighted option
-- `Escape` closes the dropdown; `Enter` selects the active option
+- Listbox uses `role="listbox"` with `role="option"` items, and gets an accessible name via `aria-label` derived from the `label` prop when it is a string
+- `aria-activedescendant` tracks the keyboard-highlighted option and is only set while the listbox is open
+- `ArrowDown`/`ArrowUp` open the closed listbox on first press, then move the highlight to the next/previous enabled option (disabled options are skipped)
+- `Escape` closes the dropdown; `Enter` selects the highlighted option (a no-op on a disabled option)

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

@@ -66,17 +66,17 @@
     inset-block-start: calc(100% + var(--bds-space_xxs));
     inset-inline: 0;
     z-index: var(--bds-z-index_dropdown);
-    max-block-size: 15rem;
+    max-block-size: var(--combobox_listbox-max-block-size, 15rem);
     overflow-block: auto;
     list-style: none;
     margin: 0;
-    padding: var(--bds-space_xxs) 0;
+    padding: var(--combobox_listbox-padding-block, var(--bds-space_xxs)) 0;
     border: var(--combobox_listbox-border, none);
     --bdc_color: currentcolor;
     --bdc-outline_radius: var(--bds-border_radius--s);
 
     border-radius: var(--combobox_listbox-radius, var(--bdc-outline_radius));
-    background-color: var(--combobox_color, var(--bds-color_bg));
+    background-color: var(--combobox_listbox-bg, var(--combobox_color_bg, var(--bds-color_bg)));
     color: var(--combobox_on-color, var(--bds-color_on-bg));
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--combobox_listbox-shadow, var(--bds-shadow_m));
   }
@@ -84,9 +84,9 @@
   .option {
     display: flex;
     align-items: center;
-    padding: var(--bds-space_xs) var(--bds-space_m);
-    font-size: var(--bds-font_size--body);
-    color: var(--combobox_color, var(--bds-color_on-bg));
+    padding: var(--combobox_option-padding-block, var(--bds-space_xs)) var(--combobox_option-padding-inline, var(--bds-space_m));
+    font-size: var(--combobox_option-font-size, var(--bds-font_size--body));
+    color: var(--combobox_on-color, var(--bds-color_on-bg));
     cursor: pointer;
     transition: var(--bds-animation_transition);
   }

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

@@ -78,4 +78,51 @@ describe('Combobox', () => {
     render(<Combobox label="Country" name="country" options={options} error="Required" />);
     expect(screen.getByRole('combobox')).toHaveAttribute('aria-invalid', 'true');
   });
+
+  it('gives the listbox an accessible name from the label', async () => {
+    const user = userEvent.setup();
+    render(<Combobox label="Country" name="country" options={options} />);
+    await user.click(screen.getByRole('combobox'));
+    expect(screen.getByRole('listbox')).toHaveAccessibleName('Country');
+  });
+
+  it('opens the closed listbox on ArrowUp without setting aria-activedescendant', async () => {
+    const user = userEvent.setup();
+    render(<Combobox label="Country" name="country" options={options} />);
+    const combobox = screen.getByRole('combobox');
+    await user.click(combobox);
+    await user.keyboard('{Escape}');
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+    await user.keyboard('{ArrowUp}');
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(combobox).not.toHaveAttribute('aria-activedescendant');
+  });
+
+  it('does not select a disabled option on Enter when it is the only filtered result', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<Combobox label="Country" name="country" options={options} onChange={onChange} />);
+    await user.type(screen.getByRole('combobox'), 'France');
+    expect(screen.getByRole('option', { name: 'France' })).toBeInTheDocument();
+    await user.keyboard('{ArrowDown}');
+    await user.keyboard('{Enter}');
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('clears aria-activedescendant when the listbox closes via an outside click', async () => {
+    const user = userEvent.setup();
+    render(
+      <div>
+        <Combobox label="Country" name="country" options={options} />
+        <button type="button">Outside</button>
+      </div>
+    );
+    const combobox = screen.getByRole('combobox');
+    await user.click(combobox);
+    await user.keyboard('{ArrowDown}');
+    expect(combobox).toHaveAttribute('aria-activedescendant');
+    await user.click(screen.getByRole('button', { name: 'Outside' }));
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(combobox).not.toHaveAttribute('aria-activedescendant');
+  });
 });

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

@@ -102,18 +102,22 @@ export function Combobox({
     if (e.key === 'ArrowDown') {
       e.preventDefault();
       if (!isOpen) { setIsOpen(true); return; }
+      if (enabledIndexes.length === 0) { setHighlightedIndex(-1); return; }
       const pos = enabledIndexes.indexOf(highlightedIndex);
-      setHighlightedIndex(enabledIndexes[(pos + 1) % enabledIndexes.length] ?? 0);
+      setHighlightedIndex(enabledIndexes[(pos + 1) % enabledIndexes.length]);
     } else if (e.key === 'ArrowUp') {
       e.preventDefault();
+      if (!isOpen) { setIsOpen(true); return; }
+      if (enabledIndexes.length === 0) { setHighlightedIndex(-1); return; }
       const pos = enabledIndexes.indexOf(highlightedIndex);
       setHighlightedIndex(
-        enabledIndexes[(pos - 1 + enabledIndexes.length) % enabledIndexes.length] ?? 0
+        enabledIndexes[(pos - 1 + enabledIndexes.length) % enabledIndexes.length]
       );
     } else if (e.key === 'Enter') {
       e.preventDefault();
-      if (highlightedIndex >= 0 && filtered[highlightedIndex]) {
-        selectOption(filtered[highlightedIndex]);
+      const option = filtered[highlightedIndex];
+      if (highlightedIndex >= 0 && option && !option.disabled) {
+        selectOption(option);
       }
     } else if (e.key === 'Escape') {
       setIsOpen(false);
@@ -137,7 +141,7 @@ export function Combobox({
           aria-haspopup="listbox"
           aria-autocomplete="list"
           aria-controls={listboxId}
-          aria-activedescendant={highlightedIndex >= 0 ? getOptionId(highlightedIndex) : undefined}
+          aria-activedescendant={isOpen && highlightedIndex >= 0 ? getOptionId(highlightedIndex) : undefined}
           aria-invalid={!!error}
           aria-describedby={describedBy}
           autoComplete="off"
@@ -158,6 +162,7 @@ export function Combobox({
           <ul
             id={listboxId}
             role="listbox"
+            aria-label={typeof label === 'string' ? label : undefined}
             className={css.listbox}
           >
             {filtered.map((option, index) => (

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

@@ -5,7 +5,7 @@ import * as Stories from './FieldGroup.stories';
 
 # FieldGroup
 
-Semantically groups related form fields under a single `<fieldset>` and lays them out either horizontally (with a CSS container query that collapses to a vertical stack when the FieldGroup itself is too narrow) or vertically.
+Semantically groups related form fields under a single `<fieldset>` and lays them out either horizontally (collapsing to a vertical stack when the FieldGroup itself is too narrow) or vertically.
 
 Use this any time multiple fields belong to the same conceptual section — contact details, address, search filters, registration step — and you want them grouped for screen readers AND visually arranged on a single row when there's room.
 
@@ -23,13 +23,13 @@ Use this any time multiple fields belong to the same conceptual section — cont
 
 ## Variants
 
-- **`horizontal`** (default) — fields flow into a row; each claims at least `--fieldGroup_min-field-width`. When the FieldGroup's own inline-size drops below the **auto-derived** threshold (`N × min-field-width + (N − 1) × gap`, where `N` is the actual number of children), the layout collapses to a single column via a CSS container query. A 2-field group collapses earlier than a 5-field group; you don't have to tune anything per call site.
+- **`horizontal`** (default) — fields flow into a row; each claims at least `--fieldGroup_min-field-width`. When the FieldGroup's own inline-size drops below the **auto-derived** threshold (`N × min-field-width + (N − 1) × gap`, where `N` is the actual number of children), the layout collapses to a single column. A 2-field group collapses earlier than a 5-field group; you don't have to tune anything per call site.
 - **`vertical`** — fields always stack one per row.
 
 <Canvas of={Stories.Horizontal} />
 <Canvas of={Stories.Vertical} />
 
-### Container query in action
+### Auto-collapse in action
 
 The collapse-to-vertical threshold measures the **FieldGroup itself**, not the viewport. The FieldGroup below sits inside a 20 rem wrapper, so the same horizontal variant collapses cleanly to a single column even though the page is wide.
 
@@ -77,6 +77,7 @@ All public override tokens. Set on the FieldGroup or any ancestor; they cascade.
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `--fieldGroup_legend-color` | `var(--bds-color_on-bg)` | Legend text colour. |
+| `--fieldGroup_legend-font-family` | `var(--bds-font_family--body)` | Legend font family. |
 | `--fieldGroup_legend-font-size` | `var(--bds-font_size--heading-3)` | Legend font size. |
 | `--fieldGroup_legend-font-weight` | `var(--bds-font_weight--semibold)` | Legend font weight. |
 | `--fieldGroup_legend-line-height` | `var(--bds-font_line-height--heading)` | Legend line height. |
@@ -88,13 +89,13 @@ All public override tokens. Set on the FieldGroup or any ancestor; they cascade.
 
 - Renders as `<fieldset>` so assistive tech announces the legend before each field, and the native `disabled` attribute cascades to all descendants.
 - When `legend` is omitted, you must provide `aria-label` or `aria-labelledby` on the FieldGroup so the group still has an accessible name.
-- The container query is a layout-only change — DOM order stays in source order, so the tab/reading order is unaffected by the horizontal-to-vertical switch.
+- The auto-collapse is a layout-only change — DOM order stays in source order, so the tab/reading order is unaffected by the horizontal-to-vertical switch.
 
 ## How the responsive layout works
 
 The horizontal variant uses `display: flex; flex-flow: row wrap;` with each child claiming at least `--fieldGroup_min-field-width`. This handles natural wrapping across multiple rows.
 
-Layered on top, a CSS [`@container`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container) query forces a clean single-column layout when the FieldGroup itself is narrower than the **auto-derived** collapse threshold:
+Layered on top, FieldGroup forces a clean single-column layout when the FieldGroup itself is narrower than an **auto-derived** collapse threshold:
 
 ```css
 --fieldGroup_collapse-threshold:
@@ -103,11 +104,9 @@ Layered on top, a CSS [`@container`](https://developer.mozilla.org/en-US/docs/We
     + (var(--fieldGroup_field-count) - 1) * var(--fieldGroup_gap)
   );
 
-@container field-group (max-inline-size: var(--fieldGroup_collapse-threshold)) {
-  .fieldGroup.--variant_horizontal .fields { flex-direction: column; }
-}
+.fieldGroup.--variant_horizontal[data-collapsed='true'] .fields { flex-direction: column; }
 ```
 
-`--fieldGroup_field-count` is set by the React component as an inline `style` custom property derived from `Children.count(children)`, so the threshold scales with the actual content. A 2-field group collapses around `2 × 12rem + 1 × gap`; a 5-field group collapses around `5 × 12rem + 4 × gap`. No magic numbers per call site.
+`--fieldGroup_field-count` is set by the React component as an inline `style` custom property derived from the actual rendered children, so the threshold scales with the actual content. A 2-field group collapses around `2 × 12rem + 1 × gap`; a 5-field group collapses around `5 × 12rem + 4 × gap`. No magic numbers per call site.
 
-Because the query is bound to the FieldGroup's own inline-size (via `container-type: inline-size`), the same FieldGroup behaves correctly whether you place it in a sidebar, a modal, a 2-up grid cell, or a full-width page — with zero media-query wiring at the call site.
+CSS [`@container`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container) query *conditions* can't reference custom properties (`var()` inside a container-query feature value is invalid CSS), so this per-instance threshold can't drive an `@container` rule directly. Instead, FieldGroup renders a hidden probe element whose own inline-size resolves `--fieldGroup_collapse-threshold` as a normal property value, and a `ResizeObserver` compares the probe's resolved pixel width against the fieldset's own width, toggling `data-collapsed="true"` on the fieldset when the fieldset is narrower. This keeps the same effect as a container query — bound to the FieldGroup's own inline-size, not the viewport — so the same FieldGroup behaves correctly whether you place it in a sidebar, a modal, a 2-up grid cell, or a full-width page, with zero media-query wiring at the call site. `ResizeObserver` is required for this collapse to run; it's supported by all current browsers, and in its absence (or during SSR) the layout simply stays in its declared variant.