@boostdev/design-system-components 2.15.0 → 2.16.0

package/src/web-components/interaction/bds-dropdown-menu.spec.ts

@@ -1,6 +1,13 @@
 import { fixture, cleanup } from '../test/helpers';
 import { BdsDropdownMenu } from './bds-dropdown-menu';
 import { BdsDropdownMenuItem } from './bds-dropdown-menu-item';
+import { BdsDropdownMenuGroup } from './bds-dropdown-menu-group';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const itemSource = readFileSync(resolve(process.cwd(), 'src/web-components/interaction/bds-dropdown-menu-item.ts'), 'utf8');
+const groupSource = readFileSync(resolve(process.cwd(), 'src/web-components/interaction/bds-dropdown-menu-group.ts'), 'utf8');
+const menuSource = readFileSync(resolve(process.cwd(), 'src/web-components/interaction/bds-dropdown-menu.ts'), 'utf8');
 
 describe('bds-dropdown-menu', () => {
   it('is registered as a custom element', () => {
@@ -163,3 +170,131 @@ describe('bds-dropdown-menu-item', () => {
     cleanup(el);
   });
 });
+
+describe('bds-dropdown-menu-item colour', () => {
+  it('inherits the colour from the menu panel so --dropdown_on-color applies', () => {
+    expect(String(BdsDropdownMenuItem.styles)).toMatch(/\.item \{[^}]*color:\s*inherit/);
+    expect(String(BdsDropdownMenuItem.styles)).not.toMatch(/\.item \{[^}]*color:\s*var\(--bds-color_on-bg\)/);
+    expect(itemSource).toContain(':host([destructive]) .item {');
+  });
+});
+
+describe('bds-dropdown-menu-item shortcut, icon and destructive', () => {
+  it('renders the shortcut aria-hidden and reflects the attribute', async () => {
+    const el = await fixture('<bds-dropdown-menu-item value="edit" shortcut="⌘E">Edit</bds-dropdown-menu-item>') as BdsDropdownMenuItem;
+    const shortcut = el.shadowRoot!.querySelector('.shortcut')!;
+    expect(shortcut.textContent).toBe('⌘E');
+    expect(shortcut.getAttribute('aria-hidden')).toBe('true');
+    expect(el.getAttribute('shortcut')).toBe('⌘E');
+    cleanup(el);
+  });
+
+  it('omits the shortcut element when no shortcut is set', async () => {
+    const el = await fixture('<bds-dropdown-menu-item value="edit">Edit</bds-dropdown-menu-item>');
+    expect(el.shadowRoot!.querySelector('.shortcut')).toBeNull();
+    cleanup(el);
+  });
+
+  it('offers an icon slot before the label, hidden until filled', async () => {
+    const el = await fixture('<bds-dropdown-menu-item value="edit">Edit</bds-dropdown-menu-item>') as BdsDropdownMenuItem;
+    const icon = el.shadowRoot!.querySelector('.icon')!;
+    expect(icon.querySelector('slot[name="icon"]')).toBeTruthy();
+    expect(icon.hasAttribute('hidden')).toBe(true);
+    expect(icon.compareDocumentPosition(el.shadowRoot!.querySelector('.label')!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    cleanup(el);
+  });
+
+  it('reflects the destructive attribute', async () => {
+    const el = await fixture('<bds-dropdown-menu-item value="delete" destructive>Delete</bds-dropdown-menu-item>') as BdsDropdownMenuItem;
+    expect(el.destructive).toBe(true);
+    expect(el.hasAttribute('destructive')).toBe(true);
+    cleanup(el);
+  });
+
+  it.each([
+    '--dropdown_item-padding',
+    '--dropdown_item-radius',
+    '--dropdown_item-font-size',
+    '--dropdown_item-bg--hover',
+    '--dropdown_item-color--hover',
+    '--dropdown_item-opacity--disabled',
+    '--dropdown_item-color--destructive',
+    '--dropdown_item-bg--destructive-hover',
+    '--dropdown_item-color--destructive-hover',
+    '--dropdown_shortcut-color',
+    '--dropdown_shortcut-font-size',
+  ])('reads %s through var() in the item stylesheet', hook => {
+    expect(itemSource).toContain(`var(${hook},`);
+  });
+});
+
+describe('bds-dropdown-menu-group', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-dropdown-menu-group')).toBe(BdsDropdownMenuGroup);
+  });
+
+  it('renders a role="group" named by its visible label', async () => {
+    const el = await fixture('<bds-dropdown-menu-group label="Edit"></bds-dropdown-menu-group>') as BdsDropdownMenuGroup;
+    const group = el.shadowRoot!.querySelector('[role="group"]')!;
+    const labelId = group.getAttribute('aria-labelledby')!;
+    const label = el.shadowRoot!.getElementById(labelId)!;
+    expect(label.textContent?.trim()).toBe('Edit');
+    cleanup(el);
+  });
+
+  it('renders no label element and no aria-labelledby without a label', async () => {
+    const el = await fixture('<bds-dropdown-menu-group></bds-dropdown-menu-group>') as BdsDropdownMenuGroup;
+    const group = el.shadowRoot!.querySelector('[role="group"]')!;
+    expect(group.hasAttribute('aria-labelledby')).toBe(false);
+    expect(el.shadowRoot!.querySelector('.label')).toBeNull();
+    cleanup(el);
+  });
+
+  it('updates the label when the attribute changes', async () => {
+    const el = await fixture('<bds-dropdown-menu-group label="Edit"></bds-dropdown-menu-group>') as BdsDropdownMenuGroup;
+    el.setAttribute('label', 'Danger');
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelector('.label')!.textContent?.trim()).toBe('Danger');
+    cleanup(el);
+  });
+
+  it.each([
+    '--dropdown_group-label-font-size',
+    '--dropdown_group-label-font-weight',
+    '--dropdown_group-label-color',
+    '--dropdown_group-label-padding',
+  ])('reads %s through var() in the group stylesheet', hook => {
+    expect(groupSource).toContain(`var(${hook},`);
+  });
+
+  it('moves focus from the last item of one group to the first of the next', async () => {
+    const el = await fixture(`
+      <bds-dropdown-menu>
+        <button slot="trigger" type="button">Options</button>
+        <bds-dropdown-menu-group label="Edit">
+          <bds-dropdown-menu-item value="a">A</bds-dropdown-menu-item>
+          <bds-dropdown-menu-item value="b">B</bds-dropdown-menu-item>
+        </bds-dropdown-menu-group>
+        <bds-dropdown-menu-group label="Danger">
+          <bds-dropdown-menu-item value="c" destructive>C</bds-dropdown-menu-item>
+        </bds-dropdown-menu-group>
+      </bds-dropdown-menu>
+    `) as BdsDropdownMenu;
+    const items = [...el.querySelectorAll('bds-dropdown-menu-item')] as BdsDropdownMenuItem[];
+    await Promise.all(items.map(item => item.updateComplete));
+    el._open();
+    await el.updateComplete;
+    const buttons = items.map(item => item.shadowRoot!.querySelector<HTMLButtonElement>('button')!);
+    const spy = vi.spyOn(buttons[2], 'focus');
+    buttons[1].focus();
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+    expect(spy).toHaveBeenCalled();
+    cleanup(el);
+  });
+});
+
+describe('bds-dropdown-menu panel hooks', () => {
+  it.each(['--dropdown_padding', '--dropdown_border-color'])('reads %s through var()', hook => {
+    expect(menuSource).toContain(`var(${hook},`);
+  });
+});

package/src/web-components/interaction/bds-dropdown-menu.ts

@@ -19,7 +19,8 @@ export type DropdownMenuPlacement = 'bottom-start' | 'bottom-end' | 'top-start'
  *
  * Slots:
  *   trigger   — the activating element (button or similar)
- *   (default) — `<bds-dropdown-menu-item>` elements
+ *   (default) — `<bds-dropdown-menu-item>` elements, optionally wrapped in
+ *               `<bds-dropdown-menu-group label="...">`
  *
  * Events:
  *   bds-open  — fired when the menu opens
@@ -55,15 +56,15 @@ export class BdsDropdownMenu extends LitElement {
       inset-inline-start: 0;
       min-inline-size: 10rem;
       border: var(--dropdown_border, none);
-      --bdc_color: currentcolor;
+      --bdc_color: var(--dropdown_border-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_on-bg))));
       --bdc-outline_radius: var(--bds-border_radius--s);
 
       border-radius: var(--dropdown_radius, var(--bdc-outline_radius));
       background-color: var(--dropdown_color, var(--bds-color_bg--strong, var(--bds-color_bg)));
       color: var(--dropdown_on-color, var(--bds-color_on-bg));
       box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color),
-        var(--dropdown_shadow, var(--bds-shadow_m));
-      padding: var(--bds-space_xxs);
+        var(--dropdown_shadow, var(--bds-shadow_l));
+      padding: var(--dropdown_padding, var(--bds-space_xxs));
       z-index: var(--bds-z-index_dropdown);
       display: none;
       flex-direction: column;

package/src/web-components/interaction/bds-tab.spec.ts

@@ -14,6 +14,22 @@ describe('bds-tab', () => {
     cleanup(el);
   });
 
+  it('copies the slotted label into data-label to reserve the bold width', async () => {
+    const el = await fixture('<bds-tab>Overview</bds-tab>') as BdsTab;
+    const slot = el.shadowRoot!.querySelector('slot')!;
+    slot.dispatchEvent(new Event('slotchange'));
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelector('.label')!.getAttribute('data-label')).toBe('Overview');
+    cleanup(el);
+  });
+
+  it('styles a hidden ::after at the active weight', () => {
+    const css = BdsTab.styles.toString();
+    expect(css).toMatch(/\.label::after\s*\{[^}]*content:\s*attr\(data-label\)/);
+    expect(css).toMatch(/\.label::after\s*\{[^}]*font-weight:\s*var\(--tab_font-weight,\s*var\(--tab_font-weight--active,\s*var\(--bds-font_weight--bold\)\)\)/);
+    expect(css).toMatch(/\.label::after\s*\{[^}]*visibility:\s*hidden/);
+  });
+
   it('is not selected by default', async () => {
     const el = await fixture('<bds-tab>Label</bds-tab>') as BdsTab;
     expect(el.selected).toBe(false);
@@ -72,10 +88,10 @@ describe('bds-tab', () => {
   it('lets the public --tab_color/--tab_border-color tokens win over selected/hover-state defaults', () => {
     const cssText = BdsTab.styles.cssText;
     expect(cssText).toMatch(
-      /\.tab\s*{[^}]*color:\s*var\(--tab_color,\s*var\(--tab_color--state,\s*var\(--bds-color_on-bg\)\)\)/,
+      /\.tab\s*{[^}]*color:\s*var\(--tab_color,\s*var\(--tab_color--state,\s*var\(--tab_color--inactive,\s*var\(--bds-color_on-bg--muted,\s*var\(--bds-color_on-bg\)\)\)\)\)/,
     );
     expect(cssText).toMatch(
-      /\.tab\s*{[^}]*border-block-end:\s*2px solid var\(--tab_border-color,\s*var\(--tab_border-color--state,\s*transparent\)\)/,
+      /\.tab\s*{[^}]*border-block-end:\s*var\(--tab_indicator-width,\s*3px\) solid var\(--tab_border-color,\s*var\(--tab_border-color--state,\s*transparent\)\)/,
     );
   });
 
@@ -93,4 +109,20 @@ describe('bds-tab', () => {
       /--tab_color--state:\s*var\(--tab_color--hover,/,
     );
   });
+
+  it('styles the resting tab muted and medium, the selected tab strong and bold, and hover in the full text colour', () => {
+    const cssText = BdsTab.styles.cssText;
+    expect(cssText).toMatch(
+      /\.tab\s*{[^}]*font-weight:\s*var\(--tab_font-weight,\s*var\(--tab_font-weight--state,\s*var\(--tab_font-weight--inactive,\s*var\(--bds-font_weight--medium\)\)\)\)/,
+    );
+    expect(cssText).toMatch(
+      /:host\(\[selected\]\)\s*\.tab\s*{[^}]*--tab_color--state:\s*var\(--tab_color--active,\s*var\(--bds-color_on-bg\)\)/,
+    );
+    expect(cssText).toMatch(
+      /:host\(\[selected\]\)\s*\.tab\s*{[^}]*--tab_font-weight--state:\s*var\(--tab_font-weight--active,\s*var\(--bds-font_weight--bold\)\)/,
+    );
+    expect(cssText).toMatch(
+      /--tab_color--state:\s*var\(--tab_color--hover,\s*var\(--bds-color_on-bg\)\)/,
+    );
+  });
 });

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

@@ -38,14 +38,14 @@ export class BdsTab extends LitElement {
       padding: var(--bds-space_s) var(--bds-space_m);
       font-family: var(--bds-font_family--body);
       font-size: var(--bds-font_size--body);
-      font-weight: var(--bds-font_weight--semibold);
+      font-weight: var(--tab_font-weight, var(--tab_font-weight--state, var(--tab_font-weight--inactive, var(--bds-font_weight--medium))));
 
       /* Layered cascade: public overrides (--tab_color, --tab_border-color) win over
          per-state defaults. Active/hover write to the inner --tab_*--state slot —
          mirrors the React Tabs.module.css pattern so a consumer's --tab_color
          override is never shadowed by the selected/hover rules below. */
-      color:            var(--tab_color, var(--tab_color--state, var(--bds-color_on-bg)));
-      border-block-end: 2px solid var(--tab_border-color, var(--tab_border-color--state, transparent));
+      color:            var(--tab_color, var(--tab_color--state, var(--tab_color--inactive, var(--bds-color_on-bg--muted, var(--bds-color_on-bg)))));
+      border-block-end: var(--tab_indicator-width, 3px) solid var(--tab_border-color, var(--tab_border-color--state, transparent));
       margin-block-end: -1px;
       cursor: pointer;
       transition: var(--bds-animation_transition);
@@ -53,10 +53,27 @@ export class BdsTab extends LitElement {
     }
 
     :host([selected]) .tab {
-      --tab_color--state:        var(--tab_color--active, var(--bds-color_interactive_on-bg));
+      --tab_color--state:        var(--tab_color--active, var(--bds-color_on-bg));
+      --tab_font-weight--state:  var(--tab_font-weight--active, var(--bds-font_weight--bold));
       --tab_border-color--state: var(--tab_border-color--active, var(--bds-color_interactive));
     }
 
+    /* Reserves the width of the bold label so selecting a tab does not shift the row.
+       The hidden ::after repeats the label at the active weight in the same grid cell. */
+    .label {
+      display: inline-grid;
+    }
+
+    .label::after {
+      content: attr(data-label);
+      grid-area: 1 / 1;
+      font-weight: var(--tab_font-weight, var(--tab_font-weight--active, var(--bds-font_weight--bold)));
+      visibility: hidden;
+      pointer-events: none;
+      block-size: 0;
+      overflow: hidden;
+    }
+
     .tab:disabled {
       opacity: 0.4;
       cursor: not-allowed;
@@ -70,7 +87,7 @@ export class BdsTab extends LitElement {
 
     @media (hover: hover) and (pointer: fine) {
       .tab:not(:disabled, [aria-selected='true']):hover {
-        --tab_color--state: var(--tab_color--hover, var(--bds-color_interactive_on-bg));
+        --tab_color--state: var(--tab_color--hover, var(--bds-color_on-bg));
       }
     }
   `;
@@ -78,15 +95,18 @@ export class BdsTab extends LitElement {
   static properties = {
     selected: { type: Boolean, reflect: true },
     disabled: { type: Boolean, reflect: true },
+    _label: { state: true },
   };
 
   declare selected: boolean;
   declare disabled: boolean;
+  declare private _label: string;
 
   constructor() {
     super();
     this.selected = false;
     this.disabled = false;
+    this._label = '';
   }
 
   /** Called by `bds-tabs` to focus the inner button for keyboard navigation. */
@@ -94,6 +114,11 @@ export class BdsTab extends LitElement {
     this.shadowRoot?.querySelector<HTMLButtonElement>('button')?.focus();
   }
 
+  private _handleSlotChange(e: Event) {
+    const slot = e.target as HTMLSlotElement;
+    this._label = slot.assignedNodes({ flatten: true }).map((n) => n.textContent ?? '').join('').trim();
+  }
+
   private _handleClick() {
     if (this.disabled) return;
     this.dispatchEvent(new CustomEvent('bds-tab-select', { bubbles: true, composed: true }));
@@ -110,7 +135,7 @@ export class BdsTab extends LitElement {
         ?disabled=${this.disabled}
         @click=${this._handleClick}
       >
-        <slot></slot>
+        <span class="label" data-label=${this._label}><slot @slotchange=${this._handleSlotChange}></slot></span>
       </button>
     `;
   }

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

@@ -117,4 +117,20 @@ describe('bds-tooltip', () => {
     expect(cssText).toMatch(/z-index:\s*var\(--bds-z-index_popover\);/);
     expect(cssText).not.toContain('200');
   });
+
+  it('sizes the tooltip to its text up to a max width and lets it wrap', () => {
+    const cssText = BdsTooltip.styles.cssText;
+    expect(cssText).toMatch(/inline-size:\s*max-content;/);
+    expect(cssText).toMatch(/max-inline-size:\s*var\(--tooltip_max-inline-size,\s*20rem\);/);
+    expect(cssText).toMatch(/white-space:\s*normal;/);
+    expect(cssText).not.toContain('nowrap;\n      pointer-events');
+  });
+
+  it('exposes the radius, padding, font-size and offset hooks with their defaults', () => {
+    const cssText = BdsTooltip.styles.cssText;
+    expect(cssText).toContain('var(--tooltip_radius, var(--bds-border_radius--xs))');
+    expect(cssText).toContain('var(--tooltip_padding, var(--bds-space_xxs) var(--bds-space_s))');
+    expect(cssText).toContain('var(--tooltip_font-size, var(--bds-font_size--body--s))');
+    expect(cssText).toContain('var(--tooltip_offset, var(--bds-space_xs))');
+  });
 });

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

@@ -51,13 +51,15 @@ export class BdsTooltip extends LitElement {
     .tooltip {
       position: absolute;
       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));
+      padding: var(--tooltip_padding, var(--bds-space_xxs) var(--bds-space_s));
+      border-radius: var(--tooltip_radius, var(--bds-border_radius--xs));
       background-color: var(--tooltip_bg, var(--bds-color_on-bg));
       color: var(--tooltip_text, var(--bds-color_bg));
-      font-size: var(--bds-font_size--body--s);
+      font-size: var(--tooltip_font-size, var(--bds-font_size--body--s));
       line-height: var(--bds-font_line-height--body);
-      white-space: nowrap;
+      inline-size: max-content;
+      max-inline-size: var(--tooltip_max-inline-size, 20rem);
+      white-space: normal;
       pointer-events: none;
 
       /* Hidden by default */
@@ -75,28 +77,28 @@ export class BdsTooltip extends LitElement {
 
     /* Placement: top (default) */
     .tooltip.--placement_top {
-      inset-block-end: calc(100% + var(--bds-space_xs));
+      inset-block-end: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
       inset-inline-start: 50%;
       transform: translateX(-50%);
     }
 
     /* Placement: bottom */
     .tooltip.--placement_bottom {
-      inset-block-start: calc(100% + var(--bds-space_xs));
+      inset-block-start: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
       inset-inline-start: 50%;
       transform: translateX(-50%);
     }
 
     /* Placement: left */
     .tooltip.--placement_left {
-      inset-inline-end: calc(100% + var(--bds-space_xs));
+      inset-inline-end: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
       inset-block-start: 50%;
       transform: translateY(-50%);
     }
 
     /* Placement: right */
     .tooltip.--placement_right {
-      inset-inline-start: calc(100% + var(--bds-space_xs));
+      inset-inline-start: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
       inset-block-start: 50%;
       transform: translateY(-50%);
     }

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsCheckbox.stories';
 
 Form-associated checkbox custom element. Participates in HTML forms via the Form-Associated Custom Elements API — native browser validation (required, etc.) works without any wrapper.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -86,6 +86,10 @@ Use `<bds-checkbox>` whenever you need a single boolean toggle that participates
 <bds-checkbox name="agree" value="yes" required>I agree to the terms</bds-checkbox>
 ```
 
+## Error state
+
+With `error`, the checkbox ring widens to `--bdc-outline_width--error` (2px) in `--bdc_color--error`. Message hooks (`--formMessage_*`: font-size, gap, icon-size, color--error, font-weight--error, color--hint, font-style--hint) are listed on `<bds-form-input>`.
+
 ## Accessibility
 
 - The inner `<input type="checkbox">` is associated with a `<label>` via matching `id`/`for` attributes

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

@@ -36,7 +36,7 @@ function BdsCheckbox({
 const meta = {
   title: 'Web Components/Form/Checkbox',
   component: BdsCheckbox,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     checked: { control: 'boolean' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsCheckboxGroup.stories';
 
 Groups related checkboxes with a shared label, hint, and error message. Renders a `<fieldset>` with a `<legend>` for accessible grouping.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -62,6 +62,10 @@ Use `<bds-checkbox-group>` when you have multiple related checkboxes that belong
 </bds-checkbox-group>
 ```
 
+## Error state
+
+With `error`, the message gets a warning icon and the slotted `<bds-checkbox>` elements get `error` too, so they show the error ring (`--bdc-outline_width--error`, `--bdc_color--error`). A checkbox marked `error` in markup keeps it when the group error clears. Message hooks (`--formMessage_*`: font-size, gap, icon-size, color--error, font-weight--error, color--hint, font-style--hint) are listed on `<bds-form-input>`.
+
 ## Accessibility
 
 - Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers

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

@@ -33,7 +33,7 @@ function BdsCheckboxGroup({
 const meta = {
   title: 'Web Components/Form/CheckboxGroup',
   component: BdsCheckboxGroup,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     required: { control: 'boolean' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsCombobox.stories';
 
 Form-associated autocomplete combobox. Renders a text input with a filterable dropdown. Keyboard navigation: `ArrowDown`/`ArrowUp` to move focus, `Enter` to select, `Escape` to close.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -96,6 +96,10 @@ _None._
 ></bds-combobox>
 ```
 
+## Error state
+
+With `error`, the message gets a warning icon and the field ring widens to `--bdc-outline_width--error` (2px). Message hooks (`--formMessage_*`: font-size, gap, icon-size, color--error, font-weight--error, color--hint, font-style--hint) are listed on `<bds-form-input>`.
+
 ## Accessibility
 
 - `<label>` is associated with the inner input via matching `id`/`for` attributes when `label` is set

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

@@ -51,7 +51,7 @@ function BdsCombobox({
 const meta = {
   title: 'Web Components/Form/Combobox',
   component: BdsCombobox,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     disabled: { control: 'boolean' },

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

@@ -27,7 +27,7 @@ function BdsFieldGroup({
 const meta = {
   title: 'Web Components/Form/FieldGroup',
   component: BdsFieldGroup,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: {
     layout: 'padded',
     docs: {

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsFileInput.stories';
 
 Form-associated file upload zone with drag-and-drop support. Renders a styled drop zone that opens the native file picker on click or keyboard activation.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

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

@@ -30,7 +30,7 @@ function BdsFileInput({
 const meta = {
   title: 'Web Components/Form/FileInput',
   component: BdsFileInput,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     multiple: { control: 'boolean' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsFormInput.stories';
 
 Form-associated text input with label, hint, error, and prefix/suffix slot support. Participates in HTML forms via the Form-Associated Custom Elements API.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -88,6 +88,13 @@ Token names mirror the React `FormInput` component so themes carry over between
 | `--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 |
+| `--formMessage_font-size` | `var(--bds-font_size--body--s)` | Font size of the error and hint message (shared by all form controls) |
+| `--formMessage_gap` | `var(--bds-space_xxs)` | Gap between the error icon and the error text |
+| `--formMessage_icon-size` | `1.15em` | Size of the error icon |
+| `--formMessage_color--error` | `var(--bds-color_error_on-bg)` | Error message colour |
+| `--formMessage_font-weight--error` | `var(--bds-font_weight--semibold)` | Error message weight |
+| `--formMessage_color--hint` | `inherit` | Hint colour |
+| `--formMessage_font-style--hint` | `italic` | Hint font style |
 
 `--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.
 

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

@@ -55,7 +55,7 @@ function BdsFormInput({
 const meta = {
   title: 'Web Components/Form/FormInput',
   component: BdsFormInput,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     type: {

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsNumberInput.stories';
 
 Form-associated number input with increment and decrement stepper buttons. Hides the browser's native spinners and provides styled stepper controls instead.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -73,6 +73,10 @@ Use `<bds-number-input>` for quantity selectors, counters, or any numeric field
 <bds-number-input name="qty" label="Quantity" value="1" min="0" max="99" step="1"></bds-number-input>
 ```
 
+## Error state
+
+With `error`, the message gets a warning icon and the field ring widens to `--bdc-outline_width--error` (2px). Message hooks (`--formMessage_*`: font-size, gap, icon-size, color--error, font-weight--error, color--hint, font-style--hint) are listed on `<bds-form-input>`.
+
 ## Accessibility
 
 - `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

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

@@ -39,7 +39,7 @@ function BdsNumberInput({
 const meta = {
   title: 'Web Components/Form/NumberInput',
   component: BdsNumberInput,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     disabled: { control: 'boolean' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsRadio.stories';
 
 Form-associated radio button custom element. Use multiple `<bds-radio>` elements with the same `name` to form a mutually exclusive group. For a labelled group with error/hint support, use `<bds-radio-group>`.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -89,6 +89,10 @@ Use `<bds-radio>` for single-choice selection from a set of options. Always grou
 <bds-radio name="size" value="l">Large</bds-radio>
 ```
 
+## Error state
+
+With `error`, the radio ring widens to `--bdc-outline_width--error` (2px) in `--bdc_color--error`. Message hooks (`--formMessage_*`: font-size, gap, icon-size, color--error, font-weight--error, color--hint, font-style--hint) are listed on `<bds-form-input>`.
+
 ## Accessibility
 
 - The inner `<input type="radio">` is associated with a `<label>` via matching `id`/`for` attributes

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

@@ -39,7 +39,7 @@ function BdsRadio({
 const meta = {
   title: 'Web Components/Form/Radio',
   component: BdsRadio,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     checked: { control: 'boolean' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsRadioGroup.stories';
 
 Groups related radio buttons with a shared label and name. Renders a `<fieldset>` with a `<legend>`, and propagates the `name` attribute to all slotted `<bds-radio>` children so they form a mutually exclusive set.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -68,6 +68,10 @@ The legend uses `var(--bds-font_weight--medium)` (matching the React `RadioGroup
 </bds-radio-group>
 ```
 
+## Error state
+
+With `error`, the message gets a warning icon and the slotted `<bds-radio>` elements get `error` too, so they show the error ring (`--bdc-outline_width--error`, `--bdc_color--error`). A radio marked `error` in markup keeps it when the group error clears. Message hooks (`--formMessage_*`: font-size, gap, icon-size, color--error, font-weight--error, color--hint, font-style--hint) are listed on `<bds-form-input>`.
+
 ## Accessibility
 
 - Renders a `<fieldset>` with a `<legend>`, which is announced as a group by screen readers

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

@@ -36,7 +36,7 @@ function BdsRadioGroup({
 const meta = {
   title: 'Web Components/Form/RadioGroup',
   component: BdsRadioGroup,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     required: { control: 'boolean' },