@boostdev/design-system-components 2.7.1 → 2.11.0

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsFieldGroup.stories';
 
 # `<bds-field-group>`
 
-Framework-agnostic FieldGroup custom element. Wraps slotted fields in a `<fieldset>` with a styled `<legend>` and lays them out horizontally (with auto-collapse to vertical via CSS container query) or vertically.
+Framework-agnostic FieldGroup custom element. Wraps slotted fields in a `<fieldset>` with a styled `<legend>` and lays them out horizontally (with auto-collapse to vertical, driven by a `ResizeObserver` — not a CSS container query, see below) or vertically.
 
 Mirrors the React `FieldGroup` component — same token surface, same behavior, same auto-derived collapse threshold.
 
@@ -15,7 +15,7 @@ Mirrors the React `FieldGroup` component — same token surface, same behavior,
 |-----------|--------|---------|-------------|
 | `variant` | `horizontal` \| `vertical` | `horizontal` | Layout direction. |
 | `legend` | string | — | Optional legend text. Falls back to `aria-label` semantics if you set that on the host directly. |
-| `disabled` | boolean | `false` | Forwards to the inner `<fieldset>`; the UA cascades it to descendant form controls (light-DOM children projected through the slot). |
+| `disabled` | boolean | `false` | Forwards to the inner `<fieldset>` AND is propagated to each directly-slotted form control's `disabled` property (see [Notes on shadow DOM](#notes-on-shadow-dom) — the UA's fieldset-disables-descendants behaviour doesn't reach light-DOM children projected through a slot, so the component does it explicitly). |
 
 ## Slots
 
@@ -55,6 +55,7 @@ Same surface as the React component. All public tokens are read with foundation-
 | Variable | Default |
 |----------|---------|
 | `--fieldGroup_legend-color` | `var(--bds-color_on-bg)` |
+| `--fieldGroup_legend-font-family` | `var(--bds-font_family--body)` |
 | `--fieldGroup_legend-font-size` | `var(--bds-font_size--heading-3)` |
 | `--fieldGroup_legend-font-weight` | `var(--bds-font_weight--semibold)` |
 | `--fieldGroup_legend-line-height` | `var(--bds-font_line-height--heading)` |
@@ -62,6 +63,10 @@ Same surface as the React component. All public tokens are read with foundation-
 | `--fieldGroup_legend-gap` | `var(--bds-space_m)` |
 | `--fieldGroup_legend-border-block-end` | `1px solid var(--bds-color_bg--subtle)` |
 
+## How auto-collapse works
+
+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 the per-instance `--fieldGroup_collapse-threshold` can't drive an `@container` rule directly. Instead, the component 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 **host** when the fieldset is narrower. This mirrors the React `FieldGroup` component's mechanism exactly. `ResizeObserver` is required for the collapse to run; it's supported by all current browsers, and in its absence the layout simply stays in its declared variant.
+
 ## Notes on shadow DOM
 
-The component renders its own `<fieldset>` inside the shadow root and projects fields through a `<slot>`. Because slotted elements stay in the host's light DOM, the native `fieldset[disabled]` cascade onto descendants is browser-dependent — modern browsers do propagate disabled to slotted form controls; older ones may not. If you support an older runtime and need a hard guarantee, set `disabled` on each slotted field too.
+The component renders its own `<fieldset>` inside the shadow root and projects fields through a `<slot>`. Slotted elements' actual DOM parent stays the host (not the shadow-root fieldset), so the UA's native `fieldset[disabled]` cascade-to-descendants behaviour — which walks the DOM tree, not the flattened/composed tree — **never reaches them**, in any browser. To compensate, the component explicitly sets `.disabled` on each directly-slotted form control whenever `disabled` changes or new fields are slotted in, and tracks which controls it disabled so re-enabling the group never overrides a control a consumer had individually disabled beforehand. Deeply-nested form controls (e.g. a slotted wrapper `<div>` containing an `<input>`) are not reached — keep form controls as direct children of `<bds-field-group>`.

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

@@ -34,7 +34,7 @@ const meta = {
       description: {
         component:
           'Framework-agnostic FieldGroup. Wraps slotted fields in a `<fieldset>` ' +
-          'and lays them out horizontally with a CSS container query that auto-collapses ' +
+          'and lays them out horizontally with a ResizeObserver-driven auto-collapse ' +
           'to a single column when the host is too narrow to fit a complete row at minimum field width.',
       },
     },

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

@@ -59,7 +59,20 @@ Use `<bds-file-input>` wherever users need to attach one or more files to a form
 
 | Event        | Detail       | Description                             |
 |--------------|--------------|-----------------------------------------|
-| `bds-change` | `FileList`   | Fired when files are selected or dropped |
+| `bds-change` | `FileList`   | Fired when files are selected via the picker or accepted via drag-and-drop |
+
+## CSS Custom Properties
+
+Token names match the React `FileInput` component (`--fileInput_*`) so themes written
+against React apply here unchanged. The previous web-component-only `--file-input_*`
+names still work as deprecated aliases.
+
+| Property                          | Default                                                    | Description                              |
+|------------------------------------|-------------------------------------------------------------|-------------------------------------------|
+| `--fileInput_color`                | `var(--bds-color_on-bg)`                                     | Zone text/icon colour; also drives the `currentcolor` dashed border |
+| `--fileInput_border-color`         | `currentcolor`                                                | Border colour while the zone has focus (`:focus-within`) |
+| `--fileInput_border-color--hover`  | `var(--bds-color_interactive)`                                | Border colour on hover                    |
+| `--fileInput_bg--hover`            | `rgb(from var(--bds-color_interactive) r g b / 4%)`           | Background colour on hover                |
 
 ## Usage in plain HTML
 
@@ -72,8 +85,16 @@ Use `<bds-file-input>` wherever users need to attach one or more files to a form
 
 ## Accessibility
 
-- The drop zone has `role="button"` and `tabindex="0"` so it is keyboard-reachable
-- `aria-label="Upload file"` is set on the zone for screen reader identification
-- `Enter` and `Space` open the native file picker from keyboard focus
-- `disabled` sets `tabindex="-1"` and `pointer-events: none`
+- The drop zone is rendered as a `<label>` associated with the (visually hidden but
+  focusable) shadow file input — the slotted text becomes the input's accessible name,
+  no hardcoded `aria-label` overrides it
+- The shadow input is the only tab stop; the zone itself carries no `role`/`tabindex`
+- `.zone:focus-within` shows a visible focus ring (`--bds-outline_default`) when the
+  shadow input has keyboard focus
+- `Enter` and `Space` open the native file picker via the input's native keyboard handling
+- `disabled` disables the shadow input (removing it from the tab order) and sets
+  `pointer-events: none` on the host
+- Dropped files are filtered against `accept` (extension, `type/*`, or exact MIME type)
+  before being applied — files that don't match are silently discarded, matching the
+  native file picker's behaviour
 - Participates in HTML forms via the Form-Associated Custom Elements API; files are submitted as `FormData` entries

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

@@ -77,6 +77,20 @@ Use `<bds-form-input>` for single-line text fields in forms. It handles label as
 | `bds-input`  | `{ value: string }`     | Fired on every keystroke            |
 | `bds-change` | `{ value: string }`     | Fired when the value is committed   |
 
+## CSS variables
+
+Token names mirror the React `FormInput` component so themes carry over between the two implementations.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--formInput_color_bg` | `var(--bds-color_bg)` | Background colour |
+| `--formInput_color` | `var(--bds-color_on-bg)` | Text colour |
+| `--formInput_border` | `none` | Border (layered on top of the inset focus/error ring) |
+| `--formInput_radius` | `var(--bds-border_radius--full)` | Corner radius |
+| `--formInput_shadow` | `var(--bdc-outline_shadow)` | Box shadow |
+
+`--input_*` (e.g. `--input_border`, `--input_radius`, `--input_shadow`, `--input_color`, `--input_color_bg`) are deprecated aliases for the `--formInput_*` tokens above — they still work but `--formInput_*` is the documented, forward-compatible name. `--formInput_border-color` is a web-component-only legacy override for the inset ring colour (fallback `currentcolor`); prefer `--formInput_border` for adding a visible border.
+
 ## Usage in plain HTML
 
 ```html
@@ -94,5 +108,6 @@ Use `<bds-form-input>` for single-line text fields in forms. It handles label as
 - `required` adds `aria-required="true"` and a visual asterisk
 - `error` sets `aria-invalid="true"` and links the error message via `aria-describedby`
 - `hint` is linked via `aria-describedby` for screen reader announcement
+- When both `error` and `hint` are set, both messages render (matching the React component) so `aria-describedby` never references an id that isn't in the DOM
 - Error messages use `role="alert"` so they are announced immediately
-- The focus ring is applied to the wrapper element, not the inner input
+- The focus ring is applied to the wrapper element, not the inner input, and only appears for keyboard/`:focus-visible` focus — clicking into the field highlights the frame colour without showing the outline ring

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

@@ -24,12 +24,21 @@ Use `<bds-number-input>` for quantity selectors, counters, or any numeric field
 ### Default
 <Canvas of={Stories.Default} />
 
+### With label
+<Canvas of={Stories.WithLabel} />
+
 ### With min and max
 <Canvas of={Stories.WithMinMax} />
 
 ### With custom step (5)
 <Canvas of={Stories.WithStep} />
 
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
@@ -47,6 +56,9 @@ Use `<bds-number-input>` for quantity selectors, counters, or any numeric field
 | `max`      | number  | —           | Maximum allowed value                    |
 | `step`     | number  | `1`         | Increment/decrement step                 |
 | `disabled` | boolean | `false`     | Disables the input and steppers          |
+| `label`    | string  | `""`        | Visible label text, associated with the input via `for`/`id` |
+| `hint`     | string  | —           | Helper text shown below the input when there is no `error` |
+| `error`    | string  | —           | Error message; when set the input enters error state and the message replaces the hint |
 
 ## Events
 
@@ -58,13 +70,33 @@ Use `<bds-number-input>` for quantity selectors, counters, or any numeric field
 ## Usage in plain HTML
 
 ```html
-<bds-number-input name="qty" value="1" min="0" max="99" step="1"></bds-number-input>
+<bds-number-input name="qty" label="Quantity" value="1" min="0" max="99" step="1"></bds-number-input>
 ```
 
 ## Accessibility
 
-- Decrement button has `aria-label="Decrease"` and increment has `aria-label="Increase"`
+- `label` renders a shadow `<label for>` wired to the inner input's `id`, so the field always has an accessible name when a label is provided — leaving `label` unset renders no label element and no accessible name
+- Decrement button has `aria-label="Decrease"` and increment has `aria-label="Increase"`, and both steppers carry `aria-controls` pointing at the input's `id`
+- The input exposes `aria-invalid` (`"true"` when `error` is set) and `aria-describedby`, referencing the rendered error or hint message
 - Stepper buttons are disabled when the value is at `min` or `max`
 - The stepper buttons use `tabindex="-1"` so keyboard users navigate directly to the numeric input
 - `disabled` disables both the input and the stepper buttons
 - Participates in HTML forms via the Form-Associated Custom Elements API
+
+## CSS Custom Properties
+
+| Property                              | Default                              | Description                                    |
+|----------------------------------------|---------------------------------------|-------------------------------------------------|
+| `--numberInput_border`                | `none`                                | Extra CSS `border` on the row frame (on top of the inset bdc border) |
+| `--numberInput_radius`                | `--bds-border_radius--full`          | Corner radius of the row frame and outer stepper corners |
+| `--numberInput_shadow`                | `--bdc-outline_shadow`               | Additional `box-shadow` layered after the bdc inset border |
+| `--numberInput_font-size`             | `--bds-font_size--body`              | Input font size                                |
+| `--numberInput_padding`               | `--bds-space_s`                      | Input padding                                  |
+| `--numberInput_color`                 | `--bds-color_on-bg`                  | Input text color                               |
+| `--numberInput_stepper-padding`       | `--bds-space_xs`                     | Padding of each stepper button (drives its size together with the icon) |
+| `--numberInput_stepper-bg`            | `--bds-color_bg--subtle`             | Stepper background color                       |
+| `--numberInput_stepper-bg--hover`     | `--bds-color_bg--subtle`             | Stepper background color on hover               |
+| `--numberInput_stepper-opacity--hover`| `0.7`                                 | Stepper opacity on hover                        |
+| `--numberInput_stepper-color`         | `--bds-color_interactive`            | Stepper icon color                              |
+
+> **Deprecated:** `--number-input_border-color`, `--number-input_radius`, `--number-input_shadow`, `--number-input_color_bg`, and `--number-input_color` (the original kebab-cased `--number-input_*` names) still work as legacy fallbacks but are superseded by the `--numberInput_*` names above and will be removed in a future major version.

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

@@ -9,6 +9,9 @@ function BdsNumberInput({
   max,
   step,
   disabled,
+  label,
+  hint,
+  error,
 }: {
   name?: string;
   value?: number;
@@ -16,6 +19,9 @@ function BdsNumberInput({
   max?: number;
   step?: number;
   disabled?: boolean;
+  label?: string;
+  hint?: string;
+  error?: string;
 }) {
   return React.createElement('bds-number-input', {
     name,
@@ -24,6 +30,9 @@ function BdsNumberInput({
     max,
     step,
     disabled: disabled || undefined,
+    label,
+    hint,
+    error,
   });
 }
 
@@ -38,6 +47,9 @@ const meta = {
     min: { control: 'number' },
     max: { control: 'number' },
     step: { control: 'number' },
+    label: { control: 'text' },
+    hint: { control: 'text' },
+    error: { control: 'text' },
   },
   decorators: [
     (Story: React.ComponentType) => (
@@ -55,14 +67,26 @@ export const Default: Story = {
   args: { name: 'quantity', value: 0 },
 };
 
+export const WithLabel: Story = {
+  args: { name: 'quantity', label: 'Quantity', value: 1 },
+};
+
 export const WithMinMax: Story = {
-  args: { name: 'quantity', value: 5, min: 0, max: 10 },
+  args: { name: 'quantity', label: 'Quantity', value: 5, min: 0, max: 10 },
 };
 
 export const WithStep: Story = {
-  args: { name: 'quantity', value: 0, step: 5, min: 0, max: 100 },
+  args: { name: 'quantity', label: 'Quantity', value: 0, step: 5, min: 0, max: 100 },
+};
+
+export const WithHint: Story = {
+  args: { name: 'quantity', label: 'Quantity', value: 1, hint: 'Whole numbers only' },
+};
+
+export const WithError: Story = {
+  args: { name: 'quantity', label: 'Quantity', value: 0, min: 1, error: 'Quantity must be at least 1' },
 };
 
 export const Disabled: Story = {
-  args: { name: 'quantity', value: 3, disabled: true },
+  args: { name: 'quantity', label: 'Quantity', value: 3, disabled: true },
 };

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 },
 };