@boostdev/design-system-components 2.8.0 → 2.12.0

package/src/web-components/interaction/bds-tooltip.ts

@@ -16,9 +16,14 @@ export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
  *   (default) — the trigger element (button, icon, etc.)
  *
  * Accessibility:
- *   The `aria-describedby` relationship between trigger and tooltip panel
- *   cannot cross shadow DOM boundaries; screen readers will announce the tooltip
- *   via role="tooltip" proximity when it becomes visible.
+ *   `aria-describedby` id references only resolve within the same tree scope, so a
+ *   slotted (light-DOM) trigger can never reference an id that lives inside this
+ *   element's shadow root. To keep the description reachable, a visually-hidden
+ *   `<span>` holding `content` is appended as a light-DOM child of the host and its
+ *   id is written into `aria-describedby` on the slotted trigger — both elements then
+ *   share the light DOM's tree scope, so the reference resolves in every browser. The
+ *   shadow-DOM tooltip bubble stays `aria-hidden="true"`; it is purely the visual
+ *   presentation, shown on `:hover`/`:focus-within`.
  *
  * @example
  * <bds-tooltip content="More information" placement="bottom">
@@ -27,6 +32,16 @@ export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
  */
 export class BdsTooltip extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: inline-flex;
       align-items: center;
@@ -35,7 +50,7 @@ export class BdsTooltip extends LitElement {
 
     .tooltip {
       position: absolute;
-      z-index: var(--bds-z-index_popover, 200);
+      z-index: var(--bds-z-index_popover);
       padding: var(--bds-space_xxs) var(--bds-space_xs);
       border-radius: var(--tooltip_radius, var(--bds-border_radius--full));
       background-color: var(--tooltip_bg, var(--bds-color_on-bg));
@@ -101,18 +116,98 @@ export class BdsTooltip extends LitElement {
   declare content: string;
   declare placement: TooltipPlacement;
 
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+  /** Visually-hidden light-DOM node holding `content`, referenced by the trigger's aria-describedby. */
+  private _descEl: HTMLSpanElement | null = null;
+
   constructor() {
     super();
     this.content = '';
     this.placement = 'top';
   }
 
+  connectedCallback() {
+    super.connectedCallback();
+    // Deferred: on declarative parsing the trigger may not exist as a child yet
+    // when connectedCallback fires (upgrade happens before children are parsed).
+    Promise.resolve().then(this._syncDescription);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._teardownDescription();
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('content')) {
+      this._syncDescription();
+    }
+  }
+
+  private get _descId(): string {
+    return `bds-tooltip-desc-${this._uid}`;
+  }
+
+  /** Ensures the hidden description node exists (or is torn down) and re-wires the trigger. */
+  private _syncDescription = () => {
+    if (!this.isConnected) return;
+
+    if (!this.content) {
+      this._teardownDescription();
+      return;
+    }
+
+    let desc = this._descEl;
+    if (!desc) {
+      desc = document.createElement('span');
+      desc.id = this._descId;
+      desc.style.cssText =
+        'position:absolute;inline-size:1px;block-size:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;';
+      this.append(desc);
+      this._descEl = desc;
+    }
+
+    desc.textContent = this.content;
+    this._describeTrigger();
+  };
+
+  private _describeTrigger() {
+    const id = this._descId;
+    for (const el of Array.from(this.children)) {
+      if (el === this._descEl) continue;
+      const existing = el.getAttribute('aria-describedby');
+      const ids = existing ? existing.split(/\s+/).filter(Boolean) : [];
+      if (!ids.includes(id)) {
+        el.setAttribute('aria-describedby', [...ids, id].join(' '));
+      }
+    }
+  }
+
+  private _teardownDescription() {
+    const id = this._descId;
+    for (const el of Array.from(this.children)) {
+      if (el === this._descEl) continue;
+      const existing = el.getAttribute('aria-describedby');
+      if (!existing) continue;
+      const ids = existing.split(/\s+/).filter(part => part && part !== id);
+      if (ids.length) {
+        el.setAttribute('aria-describedby', ids.join(' '));
+      } else {
+        el.removeAttribute('aria-describedby');
+      }
+    }
+    this._descEl?.remove();
+    this._descEl = null;
+  }
+
   render() {
     return html`
-      <slot></slot>
+      <slot @slotchange=${this._syncDescription}></slot>
       <span
         class="tooltip --placement_${this.placement}"
         role="tooltip"
+        aria-hidden="true"
       >${this.content}</span>
     `;
   }

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

@@ -30,6 +30,9 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 ### Required
 <Canvas of={Stories.Required} />
 
+### Error
+<Canvas of={Stories.WithError} />
+
 ### Disabled
 <Canvas of={Stories.Disabled} />
 
@@ -49,6 +52,21 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 | `checked`  | boolean | `false` | Whether the checkbox is checked                  |
 | `required` | boolean | `false` | Marks the field as required                      |
 | `disabled` | boolean | `false` | Disables the checkbox                            |
+| `error`    | boolean | `false` | Puts the checkbox in an error state (border colour + `aria-invalid`) |
+
+## CSS Custom Properties
+
+| Property                    | Default                       | Description                                   |
+|------------------------------|--------------------------------|------------------------------------------------|
+| `--checkbox_color`           | `--bds-color_on-bg`            | Border/frame colour (feeds `currentcolor`)     |
+| `--checkbox_border`          | `none`                          | Real CSS `border` (in addition to the bdc inset outline) |
+| `--checkbox_radius`          | `--bdc-outline_radius` (`--bds-border_radius--xs`) | Corner radius            |
+| `--checkbox_shadow`          | `--bdc-outline_shadow`         | Extra box-shadow layered behind the inset border |
+| `--checkbox_color_bg`        | `--bds-color_bg`                | Unchecked background colour                    |
+| `--checkbox_color-active`    | `--bdc-color_active`           | Checked background colour                      |
+| `--checkbox_color-on-active` | `--bdc-color_on-active`        | Checkmark colour                               |
+
+> **Deprecated:** `--checkbox_border-color` is a legacy alias for `--checkbox_color` kept for backwards compatibility — prefer `--checkbox_color`, which matches the React `Checkbox` component's token name.
 
 ## Slots
 
@@ -71,6 +89,7 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 ## Accessibility
 
 - The inner `<input type="checkbox">` is associated with a `<label>` via matching `id`/`for` attributes
-- `required` triggers native browser validation
+- `required` triggers native browser validation; validity is recomputed both when `required` and when `checked` changes, so a required checkbox correctly unblocks form submission once checked
+- `error` sets `aria-invalid="true"` on the inner input and switches the border colour to the error token
 - `disabled` sets `pointer-events: none` and reduces opacity
 - Use `<bds-checkbox-group>` for accessible grouping with `<fieldset>`/`<legend>`

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

@@ -8,6 +8,7 @@ function BdsCheckbox({
   checked,
   required,
   disabled,
+  error,
   children,
 }: {
   name?: string;
@@ -15,6 +16,7 @@ function BdsCheckbox({
   checked?: boolean;
   required?: boolean;
   disabled?: boolean;
+  error?: boolean;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -25,6 +27,7 @@ function BdsCheckbox({
       checked: checked || undefined,
       required: required || undefined,
       disabled: disabled || undefined,
+      error: error || undefined,
     },
     children,
   );
@@ -39,6 +42,7 @@ const meta = {
     checked: { control: 'boolean' },
     required: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsCheckbox>;
 
@@ -61,6 +65,10 @@ export const Required: Story = {
   args: { name: 'option', value: 'yes', required: true, children: 'Required field' },
 };
 
+export const WithError: Story = {
+  args: { name: 'option', value: 'yes', error: true, children: 'Something went wrong' },
+};
+
 export const WithGroup: Story = {
   render: () => (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>

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

@@ -45,7 +45,7 @@ Use `<bds-checkbox-group>` when you have multiple related checkboxes that belong
 | `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                       |
+| `disabled` | boolean | `false` | Disables the fieldset and propagates `disabled` to every slotted `<bds-checkbox>` (a checkbox individually marked `disabled` in markup stays disabled after the group re-enables) |
 
 ## Slots
 
@@ -65,6 +65,7 @@ Use `<bds-checkbox-group>` when you have multiple related checkboxes that belong
 ## Accessibility
 
 - Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers
-- `required` attribute adds a visual asterisk indicator to the legend
-- `disabled` on the group disables all contained checkboxes via the native `<fieldset disabled>` behaviour
+- `required` adds a visible asterisk (`aria-hidden`) plus a visually-hidden "(required)" text alternative in the legend, so requiredness is announced in the group's accessible name. `aria-required` is deliberately **not** set on the fieldset — that attribute is only supported ARIA on the `checkbox`, `combobox`, `gridcell`, `listbox`, `radiogroup`, `spinbutton`, `textbox` and `tree` roles; a bare `<fieldset>` maps to the generic `group` role (there is no ARIA `checkboxgroup` role), so assistive tech would silently ignore it
+- `disabled` on the group sets the shadow `<fieldset disabled>` **and** explicitly propagates the `disabled` attribute to every slotted `<bds-checkbox>` — a shadow-DOM `<fieldset disabled>` has no effect on slotted light-DOM custom elements on its own, so propagation happens in JS (on `disabled` change and on `slotchange`)
+- The fieldset's `aria-describedby` points at the rendered error/hint message id, so screen readers announce it as part of the group's description
 - Error messages use `role="alert"` so they are announced immediately

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

@@ -27,6 +27,12 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 ### With disabled option
 <Canvas of={Stories.WithDisabledOption} />
 
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
 ### Required
 <Canvas of={Stories.Required} />
 
@@ -45,8 +51,34 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 | `value`       | string  | `""`    | Currently selected value                                         |
 | `options`     | string  | `"[]"`  | JSON array of `{ value, label, disabled? }` option objects       |
 | `placeholder` | string  | `""`    | Input placeholder text                                           |
+| `label`       | string  | `""`    | Visible label text, associated to the input via `<label for>`    |
+| `hint`        | string  | —       | Helper text shown below the input                                |
+| `error`       | string  | —       | Error message; when set the input enters error state             |
 | `disabled`    | boolean | `false` | Disables the entire combobox                                     |
 
+## CSS Custom Properties
+
+| Property                               | Default                                              | Description                                                             |
+|------------------------------------------|--------------------------------------------------------|---------------------------------------------------------------------------|
+| `--combobox_border`                    | `none`                                                | Real CSS `border` on the input (in addition to the bdc inset outline)   |
+| `--combobox_radius`                    | `--bdc-outline_radius` (`--bds-border_radius--full`)  | Input corner radius                                                     |
+| `--combobox_shadow`                    | `--bdc-outline_shadow`                                | Extra box-shadow layered behind the input's inset border                |
+| `--combobox_color_bg`                  | `--bds-color_bg`                                      | Input and listbox background colour                                     |
+| `--combobox_color`                     | `--bds-color_on-bg`                                   | Input text colour                                                       |
+| `--combobox_on-color`                  | `--bds-color_on-bg`                                   | Listbox/option text colour                                              |
+| `--combobox_listbox-border`            | `none`                                                | Real CSS `border` on the listbox (in addition to the bdc inset outline) |
+| `--combobox_listbox-radius`            | `--bdc-outline_radius` (`--bds-border_radius--s`)     | Listbox corner radius                                                   |
+| `--combobox_listbox-shadow`            | `--bds-shadow_m`                                      | Listbox elevation shadow                                                |
+| `--combobox_z-index`                   | `--bds-z-index_dropdown`                              | Listbox stacking order                                                  |
+| `--combobox_option-bg--highlighted`    | `--bds-color_bg--subtle`                              | Background of the hovered/keyboard-highlighted/selected option          |
+| `--combobox_option-color--highlighted` | `--bds-color_interactive_on-bg`                       | Text colour of the hovered/keyboard-highlighted/selected option         |
+
+> `--combobox_border-color` is a web-component-only override for the input's inset-border colour (`--bdc_color`, default `currentcolor`); it has no React `Combobox` equivalent. Most consumers should use `--combobox_color` (text colour), which the border also inherits via `currentcolor` unless `--combobox_border-color` is set explicitly.
+
+## Slots
+
+_None._
+
 ## Events
 
 | Event        | Detail                          | Description                          |
@@ -58,6 +90,7 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 ```html
 <bds-combobox
   name="country"
+  label="Country"
   placeholder="Search country…"
   options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
 ></bds-combobox>
@@ -65,7 +98,11 @@ Use `<bds-combobox>` when users need to search and filter a list of options. For
 
 ## Accessibility
 
-- Uses `role="combobox"` on the input with `aria-expanded`, `aria-autocomplete="list"`, and `aria-haspopup="listbox"`
-- Listbox uses `role="listbox"` and each option uses `role="option"` with `aria-selected` and `aria-disabled`
+- `<label>` is associated with the inner input via matching `id`/`for` attributes when `label` is set
+- Uses `role="combobox"` on the input with `aria-expanded`, `aria-autocomplete="list"`, `aria-haspopup="listbox"`, and `autocomplete="off"`
+- `aria-controls` points the input at the listbox; `aria-activedescendant` tracks the keyboard-highlighted option so the current selection is exposed to assistive tech
+- Listbox uses `role="listbox"` and each option uses `role="option"` with `aria-selected` and `aria-disabled`; the "No results" placeholder uses `role="presentation"` so it isn't announced as a selectable option
+- `error` sets `aria-invalid="true"` and links the error message via `aria-describedby`; the error message uses `role="alert"`
+- `hint` is linked via `aria-describedby` for screen reader announcement when there is no error
 - Full keyboard navigation: `ArrowDown`/`ArrowUp` to navigate, `Enter` to select, `Escape` to close
 - Participates in HTML forms via the Form-Associated Custom Elements API

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

@@ -22,12 +22,18 @@ function BdsCombobox({
   value,
   options,
   placeholder,
+  label,
+  hint,
+  error,
   disabled,
 }: {
   name?: string;
   value?: string;
   options?: string;
   placeholder?: string;
+  label?: string;
+  hint?: string;
+  error?: string;
   disabled?: boolean;
 }) {
   return React.createElement('bds-combobox', {
@@ -35,6 +41,9 @@ function BdsCombobox({
     value,
     options,
     placeholder,
+    label,
+    hint,
+    error,
     disabled: disabled || undefined,
   });
 }
@@ -62,6 +71,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     name: 'country',
+    label: 'Country',
     options: COUNTRIES,
     placeholder: 'Search country…',
   },
@@ -70,11 +80,32 @@ export const Default: Story = {
 export const WithDisabledOption: Story = {
   args: {
     name: 'country',
+    label: 'Country',
     options: COUNTRIES_WITH_DISABLED,
     placeholder: 'Search country…',
   },
 };
 
+export const WithHint: Story = {
+  args: {
+    name: 'country',
+    label: 'Country',
+    hint: 'Start typing to filter the list',
+    options: COUNTRIES,
+    placeholder: 'Search country…',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    name: 'country',
+    label: 'Country',
+    error: 'Please select a country',
+    options: COUNTRIES,
+    placeholder: 'Search country…',
+  },
+};
+
 export const Required: Story = {
   args: {
     name: 'country',

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