@boostdev/design-system-components 2.8.0 → 2.12.0

package/src/web-components/interaction/form/BdsRadio.mdx

@@ -30,19 +30,30 @@ Use `<bds-radio>` for single-choice selection from a set of options. Always grou
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
+### With description
+<Canvas of={Stories.WithDescription} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Group (mutually exclusive selection)
+<Canvas of={Stories.Group} />
+
 ## Props
 
 <ArgTypes of={Stories} />
 
 ## Attributes
 
-| Attribute  | Type    | Default | Description                                      |
-|------------|---------|---------|--------------------------------------------------|
-| `name`     | string  | `""`    | Form field name (groups radio buttons)           |
-| `value`    | string  | `""`    | Value submitted when this option is selected     |
-| `checked`  | boolean | `false` | Whether this option is selected                  |
-| `required` | boolean | `false` | Marks the field as required                      |
-| `disabled` | boolean | `false` | Disables this radio option                       |
+| Attribute     | Type    | Default | Description                                                    |
+|---------------|---------|---------|------------------------------------------------------------------|
+| `name`        | string  | `""`    | Form field name — radios sharing a `name` form a mutually exclusive group |
+| `value`       | string  | `""`    | Value submitted when this option is selected                   |
+| `checked`     | boolean | `false` | Whether this option is selected                                |
+| `required`    | boolean | `false` | Marks the field as required                                    |
+| `disabled`    | boolean | `false` | Disables this radio option                                     |
+| `error`       | boolean | `false` | Error visual state; sets `aria-invalid="true"` on the input    |
+| `description` | string  | —       | Supporting text rendered below the label, wired via `aria-describedby` |
 
 ## Slots
 
@@ -52,9 +63,23 @@ Use `<bds-radio>` for single-choice selection from a set of options. Always grou
 
 ## Events
 
-| Event    | Detail | Description                                    |
-|----------|--------|------------------------------------------------|
-| `change` | —      | Native change event forwarded from the inner `<input>` |
+| Event        | Detail                              | Description                                                        |
+|--------------|--------------------------------------|---------------------------------------------------------------------|
+| `bds-change` | `{ value: string, checked: true }`  | Fired when this radio becomes checked via user interaction (click or arrow-key navigation). Composed — crosses the shadow boundary, unlike the native `change` event. |
+
+## Overridable CSS custom properties
+
+| Token                       | Default                          | Description                                    |
+|------------------------------|-----------------------------------|-------------------------------------------------|
+| `--radio_color`              | `--bds-color_on-bg` (via `--radio_border-color`, deprecated) | Border/text colour driving the `currentcolor` frame |
+| `--radio_border`             | `none`                            | Border shorthand around the frame              |
+| `--radio_radius`             | `--bds-border_radius--circle`    | Corner radius                                   |
+| `--radio_shadow`             | `--bdc-outline_shadow`           | Extra box-shadow layered with the inset border  |
+| `--radio_color_bg`           | `--bds-color_bg`                 | Background colour                               |
+| `--radio_color-active`       | `--bdc-color_active`             | Colour of the inner dot / border when checked   |
+| `--radio_description-color`  | `--bds-color_on-bg--subtle`      | Colour of the `description` text                |
+
+> `--radio_border-color` is a **deprecated alias** for `--radio_color` — it still works but new code should use `--radio_color`.
 
 ## Usage in plain HTML
 
@@ -67,6 +92,8 @@ Use `<bds-radio>` for single-choice selection from a set of options. Always grou
 ## Accessibility
 
 - The inner `<input type="radio">` is associated with a `<label>` via matching `id`/`for` attributes
-- Radios with the same `name` form a mutually exclusive group for keyboard navigation
+- Radios sharing a `name` form a real mutually exclusive group: checking one unchecks the others (searched within the same document/shadow root), and `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight` move selection between them
+- Roving `tabindex`: only the checked radio (or the first radio if none is checked) is a tab stop within its group, matching native `<input type="radio">` keyboard semantics
+- `error` sets `aria-invalid="true"` on the inner input; `description` is wired via `aria-describedby`
 - Use `<bds-radio-group>` to wrap related radios in a `<fieldset>`/`<legend>` for proper screen reader announcements
-- Participates in HTML forms via the Form-Associated Custom Elements API
+- Participates in HTML forms via the Form-Associated Custom Elements API; `formResetCallback` restores the radio's initial `checked` state on form reset

package/src/web-components/interaction/form/BdsRadio.stories.tsx

@@ -8,6 +8,8 @@ function BdsRadio({
   checked,
   required,
   disabled,
+  error,
+  description,
   children,
 }: {
   name?: string;
@@ -15,6 +17,8 @@ function BdsRadio({
   checked?: boolean;
   required?: boolean;
   disabled?: boolean;
+  error?: boolean;
+  description?: string;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -25,6 +29,8 @@ function BdsRadio({
       checked: checked || undefined,
       required: required || undefined,
       disabled: disabled || undefined,
+      error: error || undefined,
+      description,
     },
     children,
   );
@@ -39,6 +45,8 @@ const meta = {
     checked: { control: 'boolean' },
     required: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'boolean' },
+    description: { control: 'text' },
   },
 } satisfies Meta<typeof BdsRadio>;
 
@@ -56,3 +64,21 @@ export const Checked: Story = {
 export const Disabled: Story = {
   args: { name: 'size', value: 'm', disabled: true, children: 'Medium (disabled)' },
 };
+
+export const WithDescription: Story = {
+  args: { name: 'size', value: 'm', description: 'Fits most people', children: 'Medium' },
+};
+
+export const WithError: Story = {
+  args: { name: 'size', value: 'm', error: true, children: 'Medium' },
+};
+
+export const Group: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+      {React.createElement('bds-radio', { name: 'group-size', value: 's' }, 'Small')}
+      {React.createElement('bds-radio', { name: 'group-size', value: 'm', checked: true }, 'Medium')}
+      {React.createElement('bds-radio', { name: 'group-size', value: 'l' }, 'Large')}
+    </div>
+  ),
+};

package/src/web-components/interaction/form/BdsRadioGroup.mdx

@@ -45,8 +45,8 @@ Use `<bds-radio-group>` whenever you have a set of mutually exclusive options. T
 | `name`     | string  | `""`    | Shared name propagated to all slotted `<bds-radio>` elements      |
 | `error`    | string  | —       | Error message shown below items; takes priority over `hint`       |
 | `hint`     | string  | —       | Helper text shown below items                                     |
-| `required` | boolean | `false` | Shows a required indicator on the legend                          |
-| `disabled` | boolean | `false` | Disables the entire fieldset                                      |
+| `required` | boolean | `false` | Shows a required indicator on the legend and sets `aria-required` on the fieldset |
+| `disabled` | boolean | `false` | Disables the fieldset **and** propagates `disabled` to every slotted `<bds-radio>` |
 
 ## Slots
 
@@ -54,6 +54,10 @@ Use `<bds-radio-group>` whenever you have a set of mutually exclusive options. T
 |-------------|---------------------------|
 | `(default)` | `<bds-radio>` elements    |
 
+## Overridable CSS custom properties
+
+The legend uses `var(--bds-font_weight--medium)` (matching the React `RadioGroup`). `bds-radio-group` has no component-local override tokens of its own — style slotted `<bds-radio>` elements directly via their own tokens.
+
 ## Usage in plain HTML
 
 ```html
@@ -68,6 +72,7 @@ Use `<bds-radio-group>` whenever you have a set of mutually exclusive options. T
 
 - Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers
 - The `name` attribute is automatically propagated to all slotted `<bds-radio>` elements
-- `required` adds a visual asterisk to the legend
-- `disabled` on the group disables all contained radios via the native `<fieldset disabled>` behaviour
+- `required` adds a visual asterisk to the legend and sets `aria-required="true"` on the fieldset
+- `disabled` on the group disables the native `<fieldset>` **and** is explicitly propagated (attribute set/removed) to every slotted `<bds-radio>` — a shadow-DOM `<fieldset disabled>` alone has no effect on slotted light-DOM content, so this propagation is required for the group's `disabled` state to actually disable its radios. A `<bds-radio>` that was already individually marked `disabled` in markup stays disabled if the group is later re-enabled.
+- `aria-describedby` on the fieldset references the error/hint message id so assistive technology announces it alongside the group
 - Error messages use `role="alert"` so they are announced immediately

package/src/web-components/interaction/form/BdsSegmentedControl.mdx

@@ -52,9 +52,10 @@ Use `<bds-segmented-control>` for mutually exclusive view or mode toggles where
 
 ## Events
 
-| Event    | Detail | Description                                              |
-|----------|--------|----------------------------------------------------------|
-| `change` | —      | Fired when a new segment is selected (radio mode only)   |
+| Event        | Detail          | Description                                                          |
+|--------------|-----------------|-----------------------------------------------------------------------|
+| `bds-change` | `{ value }`     | Fired when a new segment is selected (radio mode only)                |
+| `change`     | —               | **Deprecated** alias for `bds-change`, kept for backward compatibility |
 
 ## Usage in plain HTML
 
@@ -76,19 +77,44 @@ Use `<bds-segmented-control>` for mutually exclusive view or mode toggles where
 
 ## CSS Custom Properties
 
+Token names match the React `SegmentedControl` component (`--control_*`) so themes
+written against React apply here unchanged. The previous web-component-only
+`--segmented_*` names still work as deprecated aliases.
+
 | Property | Default | Description |
 |----------|---------|-------------|
-| `--segmented_color_bg` | `var(--bds-color_bg--subtle)` | Track background colour (both variants) |
-| `--segmented_item-bg` | `transparent` | Inactive item background (outline variant) |
-| `--segmented_item-bg--active` | `var(--bds-color_bg)` | Active item background (outline variant) |
-| `--segmented_thumb-color` | `var(--bds-color_interactive)` | Filled thumb colour (filled variant) |
-| `--segmented_color` | `var(--bds-color_on-bg)` | Item text colour |
-| `--segmented_color--active` | `var(--bds-color_on-interactive)` (filled) / `var(--bds-color_interactive)` (outline) | Active item text colour |
+| `--control_track-pad` | `var(--bds-space_xxs)` | Padding between the track edge and the items/thumb |
+| `--control_track-bg` | `var(--bds-color_bg--subtle)` | Track background colour (both variants) |
+| `--control_radius` | `var(--bds-border_radius--full)` | Track (outer) border radius — pill by default |
+| `--control_thumb-radius` | `var(--bds-border_radius--full)` | Thumb, indicator, and item border radius |
+| `--control_thumb-bg` | `var(--bds-color_interactive)` | Filled thumb colour (filled variant) |
+| `--control_thumb-shadow` | `var(--bds-shadow_s)` | Filled thumb box-shadow (filled variant) |
+| `--control_indicator-width` | `2px` | Inset border width of the sliding indicator (outline variant) |
+| `--control_indicator-color` | `var(--bds-color_interactive)` | Inset border colour of the sliding indicator (outline variant) |
+| `--control_item-bg` | `transparent` | Inactive item background (outline variant) |
+| `--control_item-bg--active` | `var(--bds-color_bg)` | Active item background (outline variant) |
+| `--control_label-color` | `var(--bds-color_on-bg)` | 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)` | Inactive, non-disabled item text colour on hover (fine pointers only) |
+
+<details>
+<summary>Deprecated aliases</summary>
+
+| Old property | Maps to |
+|--------------|---------|
+| `--segmented_color_bg` | `--control_track-bg` |
+| `--segmented_item-bg` | `--control_item-bg` |
+| `--segmented_item-bg--active` | `--control_item-bg--active` |
+| `--segmented_thumb-color` | `--control_thumb-bg` |
+| `--segmented_color` | `--control_label-color` |
+| `--segmented_color--active` | `--control_label-color--active` |
+
+</details>
 
 ## Accessibility
 
-- In radio mode, each option renders as a visually hidden `<input type="radio">` inside a `<label>`, so keyboard users can navigate with arrow keys
-- In link mode, options render as `<a>` elements with `aria-current="page"` on the active item
+- In radio mode, each option renders as a visually hidden `<input type="radio">` inside a `<label>`, so keyboard users can navigate with arrow keys; the visible `<label>` shows a focus ring when its radio has keyboard (`:focus-visible`) focus
+- In link mode, options render as `<a>` elements with `aria-current="page"` on the active item and get the focus ring directly
 - Disabled options have `aria-disabled="true"` and remove the `href` from link mode items
 - `disabled` on the host element disables all options
 - The sliding thumb and indicator use `aria-hidden="true"` so they are not announced by screen readers

package/src/web-components/interaction/form/BdsSelect.mdx

@@ -27,6 +27,15 @@ Use `<bds-select>` for pick-from-list dropdowns where users cannot type to searc
 ### With placeholder
 <Canvas of={Stories.WithPlaceholder} />
 
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ### Required
 <Canvas of={Stories.Required} />
 
@@ -48,20 +57,26 @@ Use `<bds-select>` for pick-from-list dropdowns where users cannot type to searc
 | `value`       | string  | `""`    | Currently selected value                                       |
 | `options`     | string  | `"[]"`  | JSON array of `{ value, label, disabled? }` option objects     |
 | `placeholder` | string  | `""`    | Placeholder option label (disabled, empty value)               |
+| `label`       | string  | `""`    | Visible label text (rendered as a shadow `<label for>`)        |
+| `hint`        | string  | —       | Helper text shown below the select                             |
+| `error`       | string  | —       | Error message; when set the select enters error state          |
 | `required`    | boolean | `false` | Marks the field as required                                    |
 | `disabled`    | boolean | `false` | Disables the select                                            |
 
+When `label` is omitted, set `aria-label` on the host element (`<bds-select aria-label="Country">`) and it is forwarded to the inner `<select>` so the control still has an accessible name.
+
 ## Events
 
-| Event    | Detail | Description                                           |
-|----------|--------|-------------------------------------------------------|
-| `change` | —      | Native change event forwarded from the inner `<select>` |
+| Event        | Detail               | Description                            |
+|--------------|----------------------|-----------------------------------------|
+| `bds-change` | `{ value: string }`  | Fired when the selected value changes   |
 
 ## Usage in plain HTML
 
 ```html
 <bds-select
   name="country"
+  label="Country"
   placeholder="Choose a country…"
   options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
 ></bds-select>
@@ -70,7 +85,10 @@ Use `<bds-select>` for pick-from-list dropdowns where users cannot type to searc
 ## Accessibility
 
 - Wraps a native `<select>` which has full browser and assistive technology support
+- `label` renders a shadow `<label for>` associated with the inner `<select>` via matching `id`/`for`; if omitted, a host `aria-label` is forwarded to the select instead
+- `error` sets `aria-invalid="true"` and links the error message via `aria-describedby`; the message uses `role="alert"` so it is announced immediately
+- `hint` is linked via `aria-describedby` for screen reader announcement
 - The custom chevron icon is `aria-hidden="true"` to avoid duplicate announcements
-- `required` uses the native `<select required>` attribute for browser validation
+- `required` uses the native `<select required>` attribute for browser validation and sets `aria-required="true"`
 - `disabled` uses the native `<select disabled>` attribute
 - Participates in HTML forms via the Form-Associated Custom Elements API

package/src/web-components/interaction/form/BdsSelect.stories.tsx

@@ -22,6 +22,9 @@ function BdsSelect({
   value,
   options,
   placeholder,
+  label,
+  hint,
+  error,
   required,
   disabled,
 }: {
@@ -29,6 +32,9 @@ function BdsSelect({
   value?: string;
   options?: string;
   placeholder?: string;
+  label?: string;
+  hint?: string;
+  error?: string;
   required?: boolean;
   disabled?: boolean;
 }) {
@@ -37,6 +43,9 @@ function BdsSelect({
     value,
     options,
     placeholder,
+    label,
+    hint,
+    error,
     required: required || undefined,
     disabled: disabled || undefined,
   });
@@ -71,6 +80,30 @@ export const WithPlaceholder: Story = {
   args: { name: 'country', options: COUNTRIES, placeholder: 'Choose a country…' },
 };
 
+export const WithLabel: Story = {
+  args: { name: 'country', options: COUNTRIES, label: 'Country', placeholder: 'Choose a country…' },
+};
+
+export const WithHint: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES,
+    label: 'Country',
+    placeholder: 'Choose a country…',
+    hint: 'Used to calculate shipping costs',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    name: 'country',
+    options: COUNTRIES,
+    label: 'Country',
+    placeholder: 'Choose a country…',
+    error: 'Please select a country',
+  },
+};
+
 export const Required: Story = {
   args: { name: 'country', options: COUNTRIES, placeholder: 'Choose a country…', required: true },
 };

package/src/web-components/interaction/form/BdsSlider.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsSlider.stories';
 
 # <bds-slider>
 
-Form-associated range slider. Wraps a native `<input type="range">` with a styled fill track driven by the `--slider_fill` CSS custom property.
+Form-associated range slider. Wraps a native `<input type="range">` with a styled fill track driven by the `--slider_fill` CSS custom property, plus label/hint/error wiring matching the other form web components.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -30,6 +30,12 @@ Use `<bds-slider>` for continuous or stepped numeric ranges — volume controls,
 ### With custom min/max (1–5)
 <Canvas of={Stories.WithMinMax} />
 
+### With label and value
+<Canvas of={Stories.WithLabel} />
+
+### Error state
+<Canvas of={Stories.WithError} />
+
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
@@ -39,39 +45,50 @@ Use `<bds-slider>` for continuous or stepped numeric ranges — volume controls,
 
 ## Attributes
 
-| Attribute  | Type    | Default | Description                              |
-|------------|---------|---------|------------------------------------------|
-| `name`     | string  | `""`    | Form field name                          |
-| `value`    | number  | `0`     | Current value                            |
-| `min`      | number  | `0`     | Minimum value                            |
-| `max`      | number  | `100`   | Maximum value                            |
-| `step`     | number  | `1`     | Step increment                           |
-| `disabled` | boolean | `false` | Disables the slider                      |
+| Attribute    | Type    | Default | Description                                          |
+|--------------|---------|---------|-------------------------------------------------------|
+| `name`       | string  | `""`    | Form field name                                        |
+| `value`      | number  | `0`     | Current value                                          |
+| `min`        | number  | `0`     | Minimum value                                          |
+| `max`        | number  | `100`   | Maximum value                                          |
+| `step`       | number  | `1`     | Step increment                                         |
+| `label`      | string  | `""`    | Visible label text, associated with the input via `for`/`id` |
+| `hint`       | string  | —       | Helper text shown below the slider                     |
+| `error`      | string  | —       | Error message; when set the slider enters error state and the input gets `aria-invalid="true"` |
+| `show-value` | boolean | `false` | Shows the current value next to the label               |
+| `disabled`   | boolean | `false` | Disables the slider                                     |
 
 ## Events
 
-| Event    | Detail | Description                          |
-|----------|--------|--------------------------------------|
-| `input`  | —      | Fired continuously as the user drags |
-| `change` | —      | Fired when the user releases         |
+| Event        | Detail            | Description                                                                                             |
+|--------------|-------------------|-----------------------------------------------------------------------------------------------------------|
+| `input`      | —                 | Native event, fired continuously as the user drags                                                        |
+| `bds-change` | `{ value: number }` | Fired when the user releases. Re-dispatched from the host as a composed event so it reliably crosses the shadow boundary — the native `change` event does not. |
 
 ## CSS Custom Properties
 
-| Property                | Description                             |
-|-------------------------|-----------------------------------------|
-| `--slider_fill-color`   | Fill track colour (defaults to `--bds-color_interactive`) |
-| `--slider_track-color`  | Unfilled track colour (defaults to `--bds-color_bg--subtle`) |
-| `--slider_thumb-color`  | Thumb colour (defaults to `--bds-color_interactive`) |
+| Property                 | Description                                          | Default                          |
+|---------------------------|-------------------------------------------------------|-----------------------------------|
+| `--slider_color`          | Track `color` (used as a fallback text/context colour) | `--bds-color_on-bg`               |
+| `--slider_color-active`   | Fill track + thumb colour                              | `--bdc-color_active`              |
+| `--slider_color--error`   | Fill track + thumb colour when `error` is set          | `--bds-color_error`               |
+| `--slider_track-bg`       | Unfilled track colour                                  | `--bds-color_bg--subtle`          |
+| `--slider_track-height`   | Track thickness                                        | `--bds-space_xxs`                 |
+| `--slider_track-radius`   | Track corner radius                                    | `--bds-border_radius--full`       |
+| `--slider_thumb-size`     | Thumb diameter                                         | `calc(--bds-space_s * 2)`         |
+| `--slider_thumb-radius`   | Thumb corner radius                                    | `--bds-border_radius--circle`     |
 
 ## Usage in plain HTML
 
 ```html
-<bds-slider name="volume" value="50" min="0" max="100" step="5"></bds-slider>
+<bds-slider name="volume" label="Volume" value="50" min="0" max="100" step="5" show-value></bds-slider>
 ```
 
 ## Accessibility
 
 - Wraps a native `<input type="range">` which has full browser and assistive technology support
+- `label` renders a shadow `<label for>` bound to the input — set it so the slider has an accessible name
+- `hint`/`error` text is wired to the input via `aria-describedby`; `error` also sets `aria-invalid="true"`
 - Arrow keys adjust the value by `step`
 - `disabled` prevents interaction and reduces opacity
 - Participates in HTML forms via the Form-Associated Custom Elements API

package/src/web-components/interaction/form/BdsSlider.stories.tsx

@@ -8,6 +8,10 @@ function BdsSlider({
   min,
   max,
   step,
+  label,
+  hint,
+  error,
+  showValue,
   disabled,
 }: {
   name?: string;
@@ -15,6 +19,10 @@ function BdsSlider({
   min?: number;
   max?: number;
   step?: number;
+  label?: string;
+  hint?: string;
+  error?: string;
+  showValue?: boolean;
   disabled?: boolean;
 }) {
   return React.createElement('bds-slider', {
@@ -23,6 +31,10 @@ function BdsSlider({
     min,
     max,
     step,
+    label,
+    hint,
+    error,
+    'show-value': showValue || undefined,
     disabled: disabled || undefined,
   });
 }
@@ -37,6 +49,10 @@ const meta = {
     min: { control: 'number' },
     max: { control: 'number' },
     step: { control: 'number' },
+    label: { control: 'text' },
+    hint: { control: 'text' },
+    error: { control: 'text' },
+    showValue: { control: 'boolean' },
     disabled: { control: 'boolean' },
   },
   decorators: [
@@ -63,6 +79,14 @@ export const WithMinMax: Story = {
   args: { name: 'rating', value: 3, min: 1, max: 5 },
 };
 
+export const WithLabel: Story = {
+  args: { name: 'volume', label: 'Volume', value: 50, showValue: true, hint: 'Adjust the playback volume' },
+};
+
+export const WithError: Story = {
+  args: { name: 'volume', label: 'Volume', value: 90, error: 'Value exceeds the recommended maximum' },
+};
+
 export const Disabled: Story = {
   args: { name: 'volume', value: 40, disabled: true },
 };

package/src/web-components/interaction/form/BdsSwitch.mdx

@@ -30,19 +30,27 @@ Use `<bds-switch>` for binary on/off settings where the change takes immediate e
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
+### Small size
+<Canvas of={Stories.Small} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ## Props
 
 <ArgTypes of={Stories} />
 
 ## Attributes
 
-| Attribute  | Type    | Default | Description                                      |
-|------------|---------|---------|--------------------------------------------------|
-| `name`     | string  | `""`    | Form field name                                  |
-| `value`    | string  | `"on"`  | Value submitted when the switch is on            |
-| `checked`  | boolean | `false` | Whether the switch is on                         |
-| `required` | boolean | `false` | Marks the field as required                      |
-| `disabled` | boolean | `false` | Disables the switch                              |
+| Attribute  | Type    | Default    | Description                                                |
+|------------|---------|------------|--------------------------------------------------------------|
+| `name`     | string  | `""`       | Form field name                                             |
+| `value`    | string  | `"on"`     | Value submitted when the switch is on                       |
+| `checked`  | boolean | `false`    | Whether the switch is on                                    |
+| `required` | boolean | `false`    | Marks the field as required                                 |
+| `disabled` | boolean | `false`    | Disables the switch                                         |
+| `error`    | string  | —          | Error message; when set the track shows the error colour and the input reports `aria-invalid="true"` |
+| `size`     | string  | `"medium"` | Track/thumb size: `small`, `medium`, `large`                |
 
 ## Slots
 
@@ -52,21 +60,40 @@ Use `<bds-switch>` for binary on/off settings where the change takes immediate e
 
 ## Events
 
-| Event    | Detail | Description                                    |
-|----------|--------|------------------------------------------------|
-| `change` | —      | Fired when the switch state changes            |
+| Event        | Detail                 | Description                                                                                                  |
+|--------------|------------------------|----------------------------------------------------------------------------------------------------------------|
+| `bds-change` | `{ checked: boolean }` | Composed event fired when the switch is toggled; crosses the shadow boundary so it can be listened for on the host element |
 
 ## Usage in plain HTML
 
 ```html
 <bds-switch name="notifications" value="enabled">Enable notifications</bds-switch>
 <bds-switch name="darkMode" value="on" checked>Dark mode</bds-switch>
+<bds-switch name="compact" size="small">Compact mode</bds-switch>
+<bds-switch name="terms" required error="You must accept the terms">Accept terms</bds-switch>
 ```
 
+## CSS custom properties
+
+| Property                       | Default                                | Description                               |
+|----------------------------------|-------------------------------------------|---------------------------------------------|
+| `--switch_color`               | `var(--bds-color_on-bg)`               | Label text colour                         |
+| `--switch_thumb-size`          | `1.25em` (`1em` small / `1.5em` large) | Thumb diameter — also drives track sizing |
+| `--switch_track-pad`           | `var(--bds-space_xxxs)`                | Padding between track edge and thumb      |
+| `--switch_track-radius`        | `var(--bds-border_radius--full)`       | Track corner radius                       |
+| `--switch_track-bg`            | `var(--bds-color_grey--subtle)`        | Track background when off                 |
+| `--switch_track-bg--active`    | `var(--bdc-color_active--subtle)`      | Track background when on                  |
+| `--switch_thumb-bg`            | `var(--bds-color_interactive)`         | Thumb (and track border) colour when off  |
+| `--switch_thumb-bg--active`    | `var(--bds-color_interactive)`         | Thumb colour when on                      |
+| `--switch_thumb-radius`        | `var(--bds-border_radius--circle)`     | Thumb corner radius                       |
+| `--switch_border-color--error` | `var(--bds-color_error)`               | Track border colour when `error` is set   |
+| `--switch_shadow`              | `var(--bdc-outline_shadow)`            | Track box-shadow tail                     |
+
 ## Accessibility
 
 - Uses `role="switch"` on the inner `<input type="checkbox">` for correct screen reader announcement
 - The inner `<input>` is associated with a `<label>` via matching `id`/`for` attributes
 - The visual track and thumb are inside the `<label>` — clicking the label or the track both toggle the switch
 - `disabled` sets `pointer-events: none` and reduces opacity
-- Participates in HTML forms via the Form-Associated Custom Elements API
+- `error` sets `aria-invalid="true"` on the inner input
+- Participates in HTML forms via the Form-Associated Custom Elements API; `formResetCallback` restores the switch's initial `checked` state on form reset

package/src/web-components/interaction/form/BdsSwitch.stories.tsx

@@ -8,6 +8,8 @@ function BdsSwitch({
   checked,
   required,
   disabled,
+  error,
+  size,
   children,
 }: {
   name?: string;
@@ -15,6 +17,8 @@ function BdsSwitch({
   checked?: boolean;
   required?: boolean;
   disabled?: boolean;
+  error?: string;
+  size?: 'small' | 'medium' | 'large';
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -25,6 +29,8 @@ function BdsSwitch({
       checked: checked || undefined,
       required: required || undefined,
       disabled: disabled || undefined,
+      error,
+      size,
     },
     children,
   );
@@ -39,6 +45,8 @@ const meta = {
     checked: { control: 'boolean' },
     required: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'text' },
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
   },
 } satisfies Meta<typeof BdsSwitch>;
 
@@ -56,3 +64,11 @@ export const Checked: Story = {
 export const Disabled: Story = {
   args: { name: 'notifications', value: 'enabled', disabled: true, children: 'Notifications (disabled)' },
 };
+
+export const Small: Story = {
+  args: { name: 'compact', value: 'enabled', size: 'small', children: 'Compact mode' },
+};
+
+export const WithError: Story = {
+  args: { name: 'terms', value: 'accepted', required: true, error: 'You must accept the terms', children: 'Accept terms' },
+};