@boostdev/design-system-components 2.8.0 → 2.11.0

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

@@ -6,18 +6,20 @@
     flex-direction: column;
   }
 
+  /* --input_* below are deprecated aliases for --formInput_*, kept working for one major. */
   .input {
-    font-family: var(--bds-font_family--body);
-    font-size: var(--bds-font_size--body);
-    padding: var(--bds-space_s);
-    border: var(--input_border, none);
+    font-family: var(--formInput_font-family, var(--bds-font_family--body));
+    font-size: var(--formInput_font-size, var(--bds-font_size--body));
+    padding: var(--formInput_padding, var(--bds-space_s));
+    border: var(--formInput_border, var(--input_border, none));
     --bdc_color: currentcolor;
     --bdc-outline_radius: var(--bds-border_radius--full);
 
-    border-radius: var(--input_radius, var(--bdc-outline_radius));
-    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--input_shadow, var(--bdc-outline_shadow));
-    color: var(--input_color, var(--bds-color_on-bg));
-    background-color: var(--input_color_bg, var(--bds-color_bg));
+    border-radius: var(--formInput_radius, var(--input_radius, var(--bdc-outline_radius)));
+    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color),
+                var(--formInput_shadow, var(--input_shadow, var(--bdc-outline_shadow)));
+    color: var(--formInput_color, var(--input_color, var(--bds-color_on-bg)));
+    background-color: var(--formInput_color_bg, var(--input_color_bg, var(--bds-color_bg)));
     transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
                 background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
   }
@@ -31,6 +33,13 @@
     outline-offset: var(--bds-outline_offset);
   }
 
+  /* Disabled — also matches when an ancestor <fieldset disabled> (e.g. a
+     disabled FieldGroup) propagates the disabled state to this input. */
+  .input:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+
   .inputError {
     --bdc_color: var(--bdc_color--error);
   }

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

@@ -40,4 +40,24 @@ describe('FormInput', () => {
     render(<FormInput label="Name" name="name" disabled />);
     expect(screen.getByRole('textbox')).toBeDisabled();
   });
+
+  it('keeps the input associated with its label when a consumer id prop is passed', () => {
+    render(<FormInput label="Email" name="email" id="consumer-id" />);
+    expect(screen.getByLabelText('Email')).toBeInTheDocument();
+  });
+
+  it('applies aria-label from the deprecated ariaLabel prop', () => {
+    render(<FormInput label="Email" name="email" ariaLabel="Email address" />);
+    expect(screen.getByRole('textbox')).toHaveAccessibleName('Email address');
+  });
+
+  it('applies aria-label passed as a native attribute', () => {
+    render(<FormInput label="Email" name="email" aria-label="Email address" />);
+    expect(screen.getByRole('textbox')).toHaveAccessibleName('Email address');
+  });
+
+  it('prefers the deprecated ariaLabel prop over a native aria-label when both are passed', () => {
+    render(<FormInput label="Email" name="email" ariaLabel="Deprecated label" aria-label="Native label" />);
+    expect(screen.getByRole('textbox')).toHaveAccessibleName('Deprecated label');
+  });
 });

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

@@ -10,6 +10,10 @@ interface FormInputProps extends WithClassName, Omit<InputHTMLAttributes<HTMLInp
   label: ReactNode;
   name: string;
   type?: Exclude<HTMLInputTypeAttribute, 'checkbox' | 'radio' | 'file'>;
+  /**
+   * @deprecated Use the native `aria-label` attribute instead. Kept working for backwards
+   * compatibility; will be removed in a later major.
+   */
   ariaLabel?: string;
   error?: string;
   hint?: string;
@@ -23,6 +27,7 @@ export function FormInput({
   hint,
   className,
   required,
+  'aria-label': nativeAriaLabel,
   ...props
 }: FormInputProps) {
   const id = name + useId();
@@ -34,15 +39,15 @@ export function FormInput({
     <InputContainer className={cn(css.formGroup, className)}>
       <Label id={id} label={label} />
       <input
+        {...props}
         aria-invalid={!!error}
         aria-describedby={describedBy}
-        aria-label={ariaLabel}
+        aria-label={ariaLabel ?? nativeAriaLabel}
         aria-required={required || undefined}
         id={id}
         name={name}
         required={required}
         className={cn(css.input, error && css.inputError)}
-        {...props}
       />
       <Message inputId={id} type="error" message={error} />
       <Message inputId={id} type="hint" message={hint} />

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

@@ -47,6 +47,9 @@ Numeric text input with increment/decrement stepper buttons. Enforces `min`, `ma
 <tr><td>`--numberInput_stepper-bg`</td><td>`var(--bds-color_bg--subtle)`</td><td>Stepper button background</td></tr>
 <tr><td>`--numberInput_stepper-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Stepper button background on hover</td></tr>
 <tr><td>`--numberInput_stepper-opacity--hover`</td><td>`0.7`</td><td>Stepper button opacity on hover</td></tr>
+<tr><td>`--numberInput_padding`</td><td>`var(--bds-space_s)`</td><td>Input padding</td></tr>
+<tr><td>`--numberInput_font-size`</td><td>`var(--bds-font_size--body)`</td><td>Input font size</td></tr>
+<tr><td>`--numberInput_stepper-padding`</td><td>`var(--bds-space_xs)`</td><td>Stepper button padding</td></tr>
 </tbody>
 </table>
 
@@ -54,5 +57,6 @@ Numeric text input with increment/decrement stepper buttons. Enforces `min`, `ma
 ## Accessibility
 
 - Renders `<input type="number">` — browser-native spinner support
-- Stepper buttons have `aria-label="Increment"` / `"Decrement"`
+- Stepper buttons have `aria-label="Increase"` / `"Decrease"` by default; override the wording (e.g. for localization) with the `increaseLabel` / `decreaseLabel` props
 - Label linked via `id`/`htmlFor`
+- Clearing the field or typing an intermediate value (e.g. a leading `-` while entering a negative number) is preserved rather than being coerced to `0`; `onChange` only fires once a full number has been parsed

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

@@ -33,9 +33,9 @@
     border: none;
     outline: none;
     font-family: var(--bds-font_family--body);
-    font-size: var(--bds-font_size--body);
+    font-size: var(--numberInput_font-size, var(--bds-font_size--body));
     text-align: center;
-    padding: var(--bds-space_s);
+    padding: var(--numberInput_padding, var(--bds-space_s));
     background: transparent;
     color: var(--numberInput_color, var(--bds-color_on-bg));
     min-inline-size: 0;
@@ -56,8 +56,8 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    padding: var(--bds-space_xs);
-    margin: 1px;
+    padding: var(--numberInput_stepper-padding, var(--bds-space_xs));
+    margin: var(--bdc-outline_width);
     background-color: var(--numberInput_stepper-bg, var(--bds-color_bg--subtle));
     color: var(--numberInput_color, var(--bds-color_on-bg));
     cursor: pointer;
@@ -66,8 +66,8 @@
   }
 
   .stepper svg {
-    width: 1rem;
-    height: 1rem;
+    inline-size: 1rem;
+    block-size: 1rem;
     color: var(--numberInput_stepper-color, var(--bds-color_interactive));
   }
 

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

@@ -1,7 +1,23 @@
+import { useState } from 'react';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { NumberInput } from './NumberInput';
 
+function ControlledHarness({ initial, onChange }: { initial: number; onChange?: (value: number) => void }) {
+  const [value, setValue] = useState(initial);
+  return (
+    <NumberInput
+      label="Qty"
+      name="qty"
+      value={value}
+      onChange={next => {
+        setValue(next);
+        onChange?.(next);
+      }}
+    />
+  );
+}
+
 describe('NumberInput', () => {
   it('renders a number input with label', () => {
     render(<NumberInput label="Quantity" name="qty" />);
@@ -46,4 +62,39 @@ describe('NumberInput', () => {
     expect(screen.getByRole('button', { name: 'Increase' })).toBeDisabled();
     expect(screen.getByRole('button', { name: 'Decrease' })).toBeDisabled();
   });
+
+  it('supports custom stepper labels via increaseLabel/decreaseLabel', () => {
+    render(<NumberInput label="Qty" name="qty" increaseLabel="Verhogen" decreaseLabel="Verlagen" />);
+    expect(screen.getByRole('button', { name: 'Verhogen' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Verlagen' })).toBeInTheDocument();
+  });
+
+  it('allows clearing a controlled value instead of forcing it back to 0', async () => {
+    const onChange = vi.fn();
+    render(<ControlledHarness initial={5} onChange={onChange} />);
+    const input = screen.getByRole('spinbutton');
+    await userEvent.clear(input);
+    expect(input).toHaveValue(null);
+    expect(onChange).not.toHaveBeenCalledWith(0);
+  });
+
+  it('allows typing a negative number into a controlled field', async () => {
+    const onChange = vi.fn();
+    render(<ControlledHarness initial={5} onChange={onChange} />);
+    const input = screen.getByRole('spinbutton');
+    await userEvent.clear(input);
+    await userEvent.type(input, '-5');
+    expect(input).toHaveValue(-5);
+    expect(onChange).toHaveBeenCalledWith(-5);
+    expect(onChange).not.toHaveBeenCalledWith(0);
+  });
+
+  it('allows clearing an uncontrolled value instead of forcing it back to 0', async () => {
+    const onChange = vi.fn();
+    render(<NumberInput label="Qty" name="qty" defaultValue={5} onChange={onChange} />);
+    const input = screen.getByRole('spinbutton');
+    await userEvent.clear(input);
+    expect(input).toHaveValue(null);
+    expect(onChange).not.toHaveBeenCalledWith(0);
+  });
 });

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

@@ -1,4 +1,4 @@
-import {HTMLAttributes, useId, useRef, useState} from 'react';
+import {HTMLAttributes, useEffect, useId, useRef, useState} from 'react';
 import css from './NumberInput.module.css';
 import {Label} from '../atoms/Label';
 import {Message} from '../atoms/Message';
@@ -18,6 +18,10 @@ interface NumberInputProps extends WithClassName, Omit<HTMLAttributes<HTMLDivEle
   error?: string;
   hint?: string;
   onChange?: (value: number) => void;
+  /** Accessible label for the decrement (−) stepper button. Defaults to `'Decrease'`. */
+  decreaseLabel?: string;
+  /** Accessible label for the increment (+) stepper button. Defaults to `'Increase'`. */
+  increaseLabel?: string;
 }
 
 export function NumberInput({
@@ -33,6 +37,8 @@ export function NumberInput({
   hint,
   onChange,
   className,
+  decreaseLabel = 'Decrease',
+  increaseLabel = 'Increase',
   ...rest
 }: Readonly<NumberInputProps>) {
   const uid = name + useId();
@@ -45,6 +51,18 @@ export function NumberInput({
   const [internalValue, setInternalValue] = useState(defaultValue ?? 0);
   const currentValue = isControlled ? value! : internalValue;
 
+  // Controlled mode renders the input from a local text draft instead of the raw
+  // numeric `value` prop directly, so the field can be cleared and intermediate
+  // input (an empty string while retyping) doesn't get coerced back to a number
+  // on every keystroke. The draft re-syncs whenever an external `value` change
+  // doesn't already match what's currently drafted (e.g. a consumer-side reset).
+  const [controlledDraft, setControlledDraft] = useState(() => (isControlled ? String(value) : ''));
+
+  useEffect(() => {
+    if (!isControlled) return;
+    setControlledDraft(prev => (parseFloat(prev) === value ? prev : String(value)));
+  }, [isControlled, value]);
+
   const clamp = (v: number): number => {
     const withMin = min !== undefined ? Math.max(min, v) : v;
     return max !== undefined ? Math.min(max, withMin) : withMin;
@@ -58,6 +76,8 @@ export function NumberInput({
         inputRef.current.value = String(next);
         inputRef.current.dispatchEvent(new Event('input', { bubbles: true }));
       }
+    } else {
+      setControlledDraft(String(next));
     }
     onChange?.(next);
   };
@@ -69,7 +89,7 @@ export function NumberInput({
         <button
           type="button"
           className={css.stepper}
-          aria-label="Decrease"
+          aria-label={decreaseLabel}
           aria-controls={uid}
           disabled={disabled || (min !== undefined && currentValue <= min)}
           onClick={() => adjust(-step)}
@@ -84,7 +104,7 @@ export function NumberInput({
           id={uid}
           type="number"
           name={name}
-          {...(isControlled ? { value } : { defaultValue })}
+          {...(isControlled ? { value: controlledDraft } : { defaultValue })}
           min={min}
           max={max}
           step={step}
@@ -93,16 +113,24 @@ export function NumberInput({
           aria-describedby={describedBy}
           className={cn(css.input, error ? css.inputError : undefined)}
           onChange={e => {
-            const v = parseFloat(e.target.value);
-            const safe = isNaN(v) ? 0 : v;
-            if (!isControlled) setInternalValue(safe);
-            onChange?.(safe);
+            // `validity.badInput` is true while the user is mid-typing text the
+            // browser can't parse yet (e.g. a lone '-' or a trailing '.'). Leave
+            // the field's own editing buffer untouched instead of forcing it back
+            // to the last committed value on every keystroke.
+            if (e.target.validity.badInput) return;
+            const raw = e.target.value;
+            if (isControlled) setControlledDraft(raw);
+            if (raw === '') return; // field genuinely cleared - don't coerce to 0
+            const parsed = parseFloat(raw);
+            if (Number.isNaN(parsed)) return;
+            if (!isControlled) setInternalValue(parsed);
+            onChange?.(parsed);
           }}
         />
         <button
           type="button"
           className={css.stepper}
-          aria-label="Increase"
+          aria-label={increaseLabel}
           aria-controls={uid}
           disabled={disabled || (max !== undefined && currentValue >= max)}
           onClick={() => adjust(step)}

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

@@ -47,8 +47,14 @@ Single-select option within a group. Renders a styled native `<input type="radio
 </thead>
 <tbody>
 <tr><td>`--radio_color-active`</td><td>`var(--bdc-color_active)`</td><td>Selected fill and border colour</td></tr>
-<tr><td>`--radio_color-on-active`</td><td>`var(--bdc-color_on-active)`</td><td>Inner dot colour</td></tr>
+<tr><td>`--radio_color_bg`</td><td>`var(--bds-color_bg)`</td><td>Inner dot colour (the cut-out centre of the selected fill) and unselected background</td></tr>
 <tr><td>`--radio_description-color`</td><td>`var(--bds-color_on-bg--subtle)`</td><td>Description text colour</td></tr>
+<tr><td>`--radio_size`</td><td>`calc(var(--bds-space_s) * 2)`</td><td>Input diameter</td></tr>
+<tr><td>`--radio_offset`</td><td>`0.2em`</td><td>Optical vertical alignment offset between the input and the label baseline</td></tr>
+<tr><td>`--radio_radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Input border radius</td></tr>
+<tr><td>`--radio_color`</td><td>`var(--bds-color_on-bg)`</td><td>Border colour (unselected)</td></tr>
+<tr><td>`--radio_border`</td><td>`none`</td><td>Additional border shorthand</td></tr>
+<tr><td>`--radio_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Additional bdc shadow-tail slot</td></tr>
 </tbody>
 </table>
 
@@ -58,3 +64,4 @@ Single-select option within a group. Renders a styled native `<input type="radio
 - Native `<input type="radio">` — group semantics via shared `name`
 - Wrap groups in `<fieldset>` with a `<legend>` for a group label
 - Arrow keys move between radios in the same group
+- `description`, `hint` and `error` text are all associated with the input via `aria-describedby`

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

@@ -1,7 +1,7 @@
 @layer boostdev.component {
   .radioGroup {
-    --inputSize:     calc(var(--bds-space_s) * 2);
-    --labelPosition: calc(var(--inputSize) + var(--bds-space_m));
+    --radio_size: calc(var(--bds-space_s) * 2);
+    --inputSize:  var(--radio_size);
 
     display: flex;
     flex-direction: column;
@@ -28,13 +28,13 @@
 
   .radio {
     flex-shrink: 0;
-    margin-block-start: 0.2em;
-    inline-size: var(--inputSize);
-    block-size: var(--inputSize);
+    margin-block-start: var(--radio_offset, 0.2em);
+    inline-size: var(--radio_size);
+    block-size: var(--radio_size);
     color: var(--radio_color, var(--bds-color_on-bg));
     border: var(--radio_border, none);
     --bdc_color: currentcolor;
-    --bdc-outline_radius: 50%;
+    --bdc-outline_radius: var(--bds-border_radius--circle);
 
     border-radius: var(--radio_radius, var(--bdc-outline_radius));
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--radio_shadow, var(--bdc-outline_shadow));
@@ -42,7 +42,8 @@
     background-color: var(--radio_color_bg, var(--bds-color_bg));
     cursor: pointer;
     position: relative;
-    transition: --bdc_color 0.2s ease, background-color 0.2s ease;
+    transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
+      background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
   }
 
   .radio:checked {
@@ -63,6 +64,18 @@
     outline-offset: var(--bds-outline_offset);
   }
 
+  /* Disabled — also matches when an ancestor <fieldset disabled> (e.g. a
+     disabled RadioGroup/FieldGroup) propagates the disabled state. */
+  .radio:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+
+  .radio:disabled ~ .textWrapper {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
   .radioError {
     --bdc_color: var(--bdc_color--error);
   }

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

@@ -35,4 +35,19 @@ describe('Radio', () => {
     render(<Radio label="Disabled" name="disabled" value="x" disabled />);
     expect(screen.getByRole('radio')).toBeDisabled();
   });
+
+  it('associates the description with the input via aria-describedby', () => {
+    render(<Radio label="Option" name="opt" value="x" description="More info about this option" />);
+    const radio = screen.getByRole('radio');
+    const describedBy = radio.getAttribute('aria-describedby');
+    expect(describedBy).toBeTruthy();
+    const description = screen.getByText('More info about this option');
+    expect(describedBy).toContain(description.id);
+  });
+
+  it('keeps the label associated with the input when a consumer id is passed', () => {
+    render(<Radio label="Option" name="opt" value="x" id="custom-radio-id" />);
+    const radio = screen.getByLabelText('Option');
+    expect(radio).toHaveAttribute('id', 'custom-radio-id');
+  });
 });

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

@@ -14,11 +14,13 @@ interface RadioProps extends WithClassName, Omit<InputHTMLAttributes<HTMLInputEl
   hint?: string;
 }
 
-export function Radio({ label, name, description, error, hint, className, ...props }: RadioProps) {
-  const id = name + useId();
+export function Radio({ label, name, description, error, hint, className, id: consumerId, ...props }: RadioProps) {
+  const id = consumerId ?? name + useId();
+  const descriptionId = id + 'description';
   const hintId = id + 'hint';
   const errorId = id + 'error';
-  const describedBy = [error && errorId, hint && hintId].filter(Boolean).join(' ') || undefined;
+  const describedBy =
+    [description && descriptionId, error && errorId, hint && hintId].filter(Boolean).join(' ') || undefined;
 
   return (
     <InputContainer className={cn(css.radioGroup, className)}>
@@ -34,7 +36,11 @@ export function Radio({ label, name, description, error, hint, className, ...pro
         />
         <div className={css.textWrapper}>
           <Label id={id} label={label} />
-          {description && <span className={css.description}>{description}</span>}
+          {description && (
+            <span id={descriptionId} className={css.description}>
+              {description}
+            </span>
+          )}
         </div>
       </div>
       <Message inputId={id} type="error" message={error} />

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

@@ -36,10 +36,25 @@ Groups multiple `Radio` inputs under a shared label. Renders a `<fieldset>` with
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+All public override tokens. Set on the RadioGroup or any ancestor; they cascade.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--radioGroup_gap` | `var(--bds-space_xs)` | Gap between the legend/items block and, via `--radioGroup_items-gap`, between the child radios. |
+| `--radioGroup_items-gap` | `var(--bds-space_xs)` | Gap between the child radios. |
+| `--radioGroup_legend-color` | `var(--bds-color_on-bg)` | Legend text colour. |
+| `--radioGroup_legend-font-family` | `var(--bds-font_family--body)` | Legend font family. |
+| `--radioGroup_legend-font-size` | `var(--bds-font_size--body--s)` | Legend font size. |
+| `--radioGroup_legend-font-weight` | `var(--bds-font_weight--medium)` | Legend font weight. |
+| `--radioGroup_legend-gap` | `var(--bds-space_xs)` | Space below the legend before the items. |
+| `--radioGroup_required-color` | `var(--bds-color_error)` | Colour of the visible `*` required marker. |
+
 ## Accessibility
 
 - Wraps radio buttons 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. `"Preferred contact (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`
 - Arrow keys move between options within the group; `Tab` moves focus out of the group

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

@@ -5,25 +5,41 @@
     margin: 0;
     display: flex;
     flex-direction: column;
-    gap: var(--bds-space_xs);
+    gap: var(--radioGroup_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(--radioGroup_legend-font-family, var(--bds-font_family--body));
+    font-size: var(--radioGroup_legend-font-size, var(--bds-font_size--body--s));
+    font-weight: var(--radioGroup_legend-font-weight, var(--bds-font_weight--medium));
+    color: var(--radioGroup_legend-color, var(--bds-color_on-bg));
     padding: 0;
-    margin-block-end: var(--bds-space_xs);
+    margin-block-end: var(--radioGroup_legend-gap, var(--bds-space_xs));
   }
 
   .required {
-    color: var(--bds-color_error);
+    color: var(--radioGroup_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(--radioGroup_items-gap, var(--bds-space_xs));
   }
 }

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

@@ -54,16 +54,46 @@ describe('RadioGroup', () => {
     expect(fieldset.getAttribute('aria-describedby')).toContain(errorMsg.id);
   });
 
-  it('marks fieldset as required when required prop is set', () => {
+  it('does not set the unsupported aria-required attribute on the fieldset', () => {
+    render(
+      <RadioGroup legend="Required" required>
+        <Radio label="Option" name="opt" value="opt" />
+      </RadioGroup>
+    );
+    expect(screen.getByRole('group')).not.toHaveAttribute('aria-required');
+  });
+
+  it('shows a visible required marker when required prop is set', () => {
     render(
       <RadioGroup legend="Required" required>
         <Radio label="Option" name="opt" value="opt" />
       </RadioGroup>
     );
-    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(
+      <RadioGroup legend="Preferred contact" required>
+        <Radio label="Option" name="opt" value="opt" />
+      </RadioGroup>
+    );
+    expect(
+      screen.getByRole('group', { name: 'Preferred contact (required)' })
+    ).toBeInTheDocument();
+  });
+
+  it('omits the required marker and accessible required text when required is not set', () => {
+    render(
+      <RadioGroup legend="Optional contact">
+        <Radio label="Option" name="opt" value="opt" />
+      </RadioGroup>
+    );
+    expect(screen.queryByText('*')).not.toBeInTheDocument();
+    expect(screen.queryByText('(required)')).not.toBeInTheDocument();
+    expect(screen.getByRole('group', { name: 'Optional contact' })).toBeInTheDocument();
+  });
+
   it('disables the fieldset when disabled prop is set', () => {
     render(
       <RadioGroup legend="Disabled" disabled>

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

@@ -29,12 +29,24 @@ export function RadioGroup({
     <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/SegmentedControl/SegmentedControl.mdx

@@ -97,18 +97,24 @@ When `selectedIndex` is omitted, the component auto-detects the active item from
 | `--control_track-bg` | `var(--bds-color_bg--subtle)` | Track background colour (both variants) |
 | `--control_item-bg` | `transparent` | Inactive item background (outline variant) |
 | `--control_item-bg--active` | `var(--bds-color_bg)` | Active item background (outline variant) |
-| `--control_radius` | `var(--bds-border_radius--m)` | Border radius of the outer track |
+| `--control_radius` | `var(--bds-border_radius--full)` | Border radius of the outer track |
+| `--control_track-pad` | `var(--bds-space_xxs)` | Inset gap between the track edge and the thumb/indicator |
 | `--control_thumb-bg` | `var(--bds-color_interactive)` | Filled thumb colour (filled variant) |
-| `--control_thumb-radius` | `var(--bds-border_radius--s)` | Border radius of the thumb, indicator, and item focus ring |
+| `--control_thumb-radius` | `var(--bds-border_radius--full)` | Border radius of the thumb, indicator, and item focus ring |
+| `--control_thumb-shadow` | `var(--bds-shadow_s)` | Filled thumb box-shadow (filled variant) |
+| `--control_item-padding` | `var(--bds-space_xs) var(--bds-space_m)` | Item padding (medium size) |
 | `--control_label-color` | `var(--bds-color_on-bg--subtle)` | Inactive item text colour |
 | `--control_label-color--active` | `var(--bds-color_on-interactive)` (filled) / `var(--bds-color_interactive)` (outline) | Active item text colour |
 | `--control_label-color--hover` | `var(--bds-color_on-bg)` | Hovered inactive item text colour |
 | `--control_indicator-color` | `var(--bds-color_interactive)` | Outline indicator border colour (outline variant) |
+| `--control_indicator-width` | `2px` | Outline indicator border width (outline variant) |
 
 ## Accessibility
 
 - The container renders as `role="group"`. Provide `aria-label` when the context doesn't supply a visible label.
 - Each child is responsible for its own semantics: buttons use `aria-pressed`, links use `aria-current="page"`.
+- When `selectedIndex` drives the active item and the child hasn't already set `aria-current`/`aria-pressed`/`aria-selected` itself, the component injects `aria-pressed={true}` (buttons) or `aria-current="page"` (links) onto the active child automatically.
+- When neither `selectedIndex` nor an ARIA-marked child is present, no item is treated as active — the sliding thumb/indicator stay hidden instead of defaulting to the first item.
+- `disabled` (on the control, or on an individual child via its own `disabled`/`aria-disabled` prop) is enforced, not just styled: the item receives `aria-disabled="true"`; `<button>` children also get the native `disabled` attribute (removing them from the tab order and blocking activation); non-button children (e.g. links) get `tabIndex={-1}` and their click is prevented.
 - The sliding thumb and indicator are `aria-hidden` — they are purely decorative.
-- The active item is communicated via the child's own ARIA attribute, not via the container.
 - Respects `prefers-reduced-motion` — the sliding animation is disabled when the user has opted out.