@boostdev/design-system-components 2.14.1 → 2.16.0

package/src/css/bdc.css

@@ -9,6 +9,8 @@
  *  --bdc-outline_*     — tokens that directly map to CSS outline sub-properties
  *
  * @property declarations must be top-level (not inside @layer).
+ * The :root defaults live in boostdev.tokens.semantic so a consumer can override them in
+ * boostdev.tokens.override. --bdc-outline_width inherits so a :root value reaches components.
  * --bdc_color uses inherits: false so each element owns its own colour instance,
  * enabling per-element transition: --bdc_color for focus/error state animations.
  * ─────────────────────────────────────────────────────────────────────────────── */
@@ -22,7 +24,7 @@
 
 @property --bdc-outline_width {
   syntax: '<length>';
-  inherits: false;
+  inherits: true;
   initial-value: 1px;
 }
 
@@ -46,7 +48,7 @@
   initial-value: 0 0 0 0 transparent;
 }
 
-@layer boostdev.component {
+@layer boostdev.tokens.semantic {
   :root {
     /* border: none by default — outline provides the visual edge */
     --bdc-outline_border: none;
@@ -66,6 +68,7 @@
 
     /* Outline geometry */
     --bdc-outline_width:  1px;
+    --bdc-outline_width--error: 2px;
     --bdc-outline_offset: -1px; /* available for consumer use; bdc borders now use inset box-shadow */
     --bdc-outline_radius: var(--bds-border_radius--xs);
     --bdc-outline_radius--l: 1.5em;

package/src/css/bdc.spec.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const read = (path: string): string => readFileSync(resolve(__dirname, path), 'utf8');
+
+const sources = {
+  'bdc.css': read('./bdc.css'),
+  'globals.ts': read('../web-components/globals.ts'),
+} as const;
+
+/** Returns the text between the braces of `@layer boostdev.tokens.semantic { ... }`. */
+const semanticLayerBody = (source: string): string | undefined => {
+  const start = source.indexOf('@layer boostdev.tokens.semantic');
+  if (start === -1) return undefined;
+  const open = source.indexOf('{', start);
+  const body = [...source.slice(open)].reduce<{ depth: number; end: number }>(
+    (acc, ch, i) => {
+      if (acc.end !== -1) return acc;
+      const depth = acc.depth + (ch === '{' ? 1 : ch === '}' ? -1 : 0);
+      return { depth, end: depth === 0 ? i : -1 };
+    },
+    { depth: 0, end: -1 },
+  );
+  return source.slice(open + 1, open + body.end);
+};
+
+const rootDeclarations = (source: string): string[] =>
+  [...(semanticLayerBody(source) ?? '').matchAll(/^\s*(--[\w-]+)\s*:/gm)].map((m) => m[1] ?? '');
+
+describe.each(Object.entries(sources))('%s', (_name, source) => {
+  it('puts the :root defaults in boostdev.tokens.semantic', () => {
+    const body = semanticLayerBody(source);
+    expect(body).toBeDefined();
+    expect(body).toContain(':root');
+    expect(body).toContain('--bdc-color_active:');
+    expect(body).toContain('--bdc_color--error:');
+  });
+
+  it('does not put the :root defaults in boostdev.component', () => {
+    expect(source).not.toContain('@layer boostdev.component');
+  });
+
+  it('registers --bdc-outline_width as inheriting', () => {
+    expect(source).toMatch(/@property --bdc-outline_width\s*\{[^}]*inherits:\s*true/);
+  });
+
+  it('keeps the per-element tokens non-inheriting', () => {
+    ['--bdc_color', '--bdc-outline_offset', '--bdc-outline_radius', '--bdc-outline_shadow'].forEach((token) => {
+      expect(source).toMatch(new RegExp(`@property ${token}\\s*\\{[^}]*inherits:\\s*false`));
+    });
+  });
+
+  it('declares the error outline width', () => {
+    expect(source).toContain('--bdc-outline_width--error: 2px;');
+  });
+});
+
+describe('bdc.css and globals.ts', () => {
+  it('declare the same set of :root custom properties', () => {
+    expect([...rootDeclarations(sources['globals.ts'])].sort()).toEqual(
+      [...rootDeclarations(sources['bdc.css'])].sort(),
+    );
+  });
+});

package/src/stories/DesignSystem/Borders.mdx

@@ -123,23 +123,31 @@ See `src/components/ui/Accordion/Accordion.module.css` for a shipped example of
 
 ## Consumer overrides
 
-Override a component's border colour for a specific context by reassigning `--bdc_color`:
+The `:root` defaults of the `bdc` tokens (`--bdc_color--focus`, `--bdc_color--error`, `--bdc-color_active*`, `--bdc-color_on-active*`, `--bdc-outline_width`, `--bdc-outline_width--error`, `--bds-outline_default`, `--bds-outline_offset`) live in `@layer boostdev.tokens.semantic`, so they can be set in `@layer boostdev.tokens.override`:
 
 ```css
-/* Scoped to a single component instance */
-.my-context .my-input {
-  --bdc_color: var(--bds-color_warning);
-}
-
-/* Override globally via the token layer */
 @layer boostdev.tokens.override {
   :root {
-    --bdc_color: var(--bds-color_green);
+    --bdc-color_active: var(--bds-color_green);
+    --bdc_color--focus: var(--bds-color_green);
+    --bdc-outline_width: 2px;
   }
 }
 ```
 
-To change width or radius independently:
+The `bdc` defaults now share the `boostdev.tokens.semantic` layer with the foundation, so load the component stylesheet after the foundation stylesheet for the solid focus ring to win (the documented import order already does this). `--bdc-outline_radius` is registered with `inherits: false` and set by each component itself, so it cannot be set on `:root`.
+
+`--bdc-outline_width` is registered with `inherits: true`, so a value on `:root` or on a wrapper reaches the components inside it.
+
+`--bdc_color` is per element by design (`inherits: false`): every component owns its own instance so its state colour can transition. Do not set it on `:root`; that has no effect. Change a component's rest border colour through the component's own hook instead:
+
+```css
+.my-menu {
+  --dropdown_border-color: var(--bds-color_warning);
+}
+```
+
+To change width or radius for one element:
 
 ```css
 .my-card {

package/src/web-components/globals.ts

@@ -14,7 +14,7 @@ const bdcCss = `
 
   @property --bdc-outline_width {
     syntax: '<length>';
-    inherits: false;
+    inherits: true;
     initial-value: 1px;
   }
 
@@ -36,7 +36,7 @@ const bdcCss = `
     initial-value: 0 0 0 0 transparent;
   }
 
-  @layer boostdev.component {
+  @layer boostdev.tokens.semantic {
     :root {
       --bdc-outline_border: none;
 
@@ -47,14 +47,20 @@ const bdcCss = `
       /* Active / selected state colours — override these to theme all filled form controls globally */
       --bdc-color_active:          var(--bds-color_interactive);
       --bdc-color_on-active:       var(--bds-color_on-interactive);
-      --bdc-color_active--subtle:  var(--bds-color_blue--subtle);
-      --bdc-color_active--strong:  var(--bds-color_interactive_on-bg);
+      --bdc-color_active--subtle:    var(--bds-color_blue--subtle);
+      --bdc-color_on-active--subtle: var(--bds-color_on-blue--subtle);
+      --bdc-color_active--strong:    var(--bds-color_interactive_on-bg);
+      --bdc-color_on-active--strong: var(--bds-color_on-blue--strong);
 
       --bdc-outline_width:  1px;
+      --bdc-outline_width--error: 2px;
       --bdc-outline_offset: -1px; /* available for consumer use; bdc borders now use inset box-shadow */
       --bdc-outline_radius: var(--bds-border_radius--xs);
       --bdc-outline_radius--l: 1.5em;
       --bdc-outline_shadow: 0 0 0 0 transparent;
+
+      --bds-outline_default: 2px solid var(--bds-color_interactive);
+      --bds-outline_offset:  2px;
     }
   }
 `;

package/src/web-components/index.ts

@@ -77,3 +77,4 @@ export { BdsCalendar } from './ui/bds-calendar';
 export { BdsCalendarRange } from './ui/bds-calendar-range';
 export { BdsDropdownMenu } from './interaction/bds-dropdown-menu';
 export { BdsDropdownMenuItem } from './interaction/bds-dropdown-menu-item';
+export { BdsDropdownMenuGroup } from './interaction/bds-dropdown-menu-group';

package/src/web-components/interaction/BdsAccordion.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsAccordion.stories';
 
 Framework-agnostic Accordion custom element. Coordinates open/closed state across `<bds-accordion-item>` children; by default only one item is open at a time.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/interaction/BdsAccordion.stories.tsx

@@ -61,7 +61,7 @@ function BdsAccordionStory({
 const meta = {
   title: 'Web Components/UI/Accordion',
   component: BdsAccordionStory,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     allowMultiple: { control: 'boolean' },

package/src/web-components/interaction/BdsButton.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsButton.stories';
 
 Framework-agnostic button custom element. Renders as `<button>` or `<a>` depending on whether `href` is set. Matches the React `Button` component in variants, sizes, and theming.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -54,6 +54,13 @@ Slot an SVG (or any element) into `icon-start` or `icon-end`:
 <Canvas of={Stories.WithIconStart} />
 <Canvas of={Stories.WithIconEnd} />
 
+### Icon offset across sizes
+
+The gap between an icon and the button edge (`--button_icon-offset`) is half the size's inline padding by default, so it scales automatically with `size` and with the responsive space tokens at wider viewports. Set `--button_icon-offset` on the host or an ancestor to override it — it inherits across the shadow boundary.
+
+<Canvas of={Stories.IconOffsetMatrix} />
+<Canvas of={Stories.IconOffsetOverride} />
+
 ### Icon-only (1:1 aspect ratio)
 
 Set the `is-icon-only` attribute to render a square button with equal `var(--bds-space_xxs)` padding on both axes. Composable with any `variant`. Always pair with `aria-label` — there's no visible label text for assistive tech to read.
@@ -107,6 +114,7 @@ Set the `is-icon-only` attribute to render a square button with equal `var(--bds
 |----------|-------------|
 | `--button_color` | Identity colour — fills the default variant, outlines the outline variant |
 | `--button_on-color` | Text/icon colour on the button surface. Pair with `--button_color` |
+| `--button_icon-offset` | How far the icon slots pull into the padding (optical correction). Defaults to half the inline padding for the current `size`, so it scales with `size` and the responsive space tokens. Inherits across the shadow boundary — set it on the host or an ancestor. |
 
 ## Form participation
 

package/src/web-components/interaction/BdsButton.stories.tsx

@@ -101,7 +101,7 @@ type BdsButtonStoryArgs = Omit<BdsButtonProps, 'iconStart' | 'iconEnd'> & {
 const meta: Meta<BdsButtonStoryArgs> = {
   title: 'Web Components/Interaction/Button',
   component: BdsButton,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     variant: {
@@ -210,3 +210,44 @@ export const AllIconOnly: Story = {
     </div>
   ),
 };
+
+/**
+ * Every size × icon position × variant combination, mirroring the React
+ * `IconOffsetMatrix` story. The icon-to-edge offset (`--button_icon-offset`,
+ * defaulting to half the size's inline padding) is set inside the shadow DOM,
+ * so this also confirms React and the web component stay pixel-identical.
+ */
+export const IconOffsetMatrix: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {(['small', 'medium', 'large'] as const).map(s => (
+        <div key={s} style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+          {(['default', 'outline'] as const).flatMap(v => [
+            <BdsButton key={`${v}-${s}-start`} variant={v} size={s} iconStart={CheckIcon}>
+              {v} {s} start
+            </BdsButton>,
+            <BdsButton key={`${v}-${s}-end`} variant={v} size={s} iconEnd={ArrowRightEnd}>
+              {v} {s} end
+            </BdsButton>,
+          ])}
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * `--button_icon-offset` set on a plain wrapper `<div>` (light DOM, an
+ * ancestor of the `<bds-button>` host) inherits across the shadow boundary
+ * and overrides the default half-padding calculation inside the shadow tree —
+ * confirming the token is a real public override point for the web component.
+ */
+export const IconOffsetOverride: Story = {
+  render: () => (
+    <div style={{ '--button_icon-offset': '4px' } as React.CSSProperties}>
+      <BdsButton size="large" iconStart={CheckIcon}>
+        Fixed 4px offset
+      </BdsButton>
+    </div>
+  ),
+};

package/src/web-components/interaction/BdsCollapsible.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsCollapsible.stories';
 
 Framework-agnostic Collapsible custom element. Wraps a native `<details>`/`<summary>` pair for built-in toggle behaviour with design-system styling and a `bds-toggle` event.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/interaction/BdsCollapsible.stories.tsx

@@ -25,7 +25,7 @@ function BdsCollapsible({
 const meta = {
   title: 'Web Components/UI/Collapsible',
   component: BdsCollapsible,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     open: { control: 'boolean' },

package/src/web-components/interaction/BdsDialog.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsDialog.stories';
 
 Framework-agnostic Dialog custom element. Wraps a native `<dialog>` element with `showModal()` / `close()` lifecycle, backdrop-click to dismiss, Escape key handling, Tab focus trapping, and the Invoker Commands API (custom commands).
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/interaction/BdsDialog.stories.tsx

@@ -53,7 +53,7 @@ function BdsDialog({
 const meta = {
   title: 'Web Components/Interaction/Dialog',
   component: BdsDialog,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     triggerLabel: { control: 'text' },

package/src/web-components/interaction/BdsDrawer.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsDrawer.stories';
 
 Framework-agnostic Drawer (slide-in panel) custom element. Same modal infrastructure as `<bds-dialog>` but positioned as a side panel that slides in from either side of the viewport.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/interaction/BdsDrawer.stories.tsx

@@ -54,7 +54,7 @@ function BdsDrawer({
 const meta = {
   title: 'Web Components/Interaction/Drawer',
   component: BdsDrawer,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     side: { control: 'select', options: ['left', 'right'] },

package/src/web-components/interaction/BdsDropdownMenu.mdx

@@ -5,9 +5,9 @@ import * as Stories from './BdsDropdownMenu.stories';
 
 # <bds-dropdown-menu>
 
-Framework-agnostic Dropdown Menu custom element. A trigger-anchored menu panel with keyboard navigation, light-dismiss, and support for disabled and destructive items.
+Framework-agnostic Dropdown Menu custom element. A trigger-anchored menu panel with keyboard navigation, light-dismiss, and support for disabled and destructive items, shortcut hints and labelled groups.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -45,6 +45,9 @@ Or in HTML without a bundler:
 ### With disabled item
 <Canvas of={Stories.WithDisabledItem} />
 
+### With groups
+<Canvas of={Stories.WithGroups} />
+
 ### All placements
 <Canvas of={Stories.AllPlacements} />
 
@@ -57,17 +60,37 @@ Or in HTML without a bundler:
 | Property | Default | Description |
 |----------|---------|-------------|
 | `--dropdown_border` | `none` | Real CSS `border` on the panel (in addition to the bdc inset outline) |
+| `--dropdown_padding` | `--bds-space_xxs` | Panel padding on all sides |
+| `--dropdown_border-color` | `--bds-color_on-bg--as-surface` | Panel outline colour (the bdc inset outline) |
 | `--dropdown_radius` | `--bdc-outline_radius` (`--bds-border_radius--s`) | Panel corner radius |
 | `--dropdown_color` | `--bds-color_bg` | Panel background colour |
 | `--dropdown_on-color` | `--bds-color_on-bg` | Panel text colour |
-| `--dropdown_shadow` | `--bds-shadow_m` | Panel elevation shadow, layered behind the inset border |
+| `--dropdown_shadow` | `--bds-shadow_l` | Panel elevation shadow, layered behind the inset border |
 
 ## CSS Custom Properties — `<bds-dropdown-menu-item>`
 
 | Property | Default | Description |
 |----------|---------|-------------|
-| `--dropdown_item-bg--hover` | `--bds-color_bg--subtle` | Item background colour on hover |
-| `--dropdown_item-color--hover` | `--bds-color_interactive_on-bg` | Item text colour on hover |
+| `--dropdown_item-padding` | `--bds-space_xs --bds-space_s` | Item padding |
+| `--dropdown_item-radius` | `--bds-border_radius--xs` | Item corner radius |
+| `--dropdown_item-font-size` | `--bds-font_size--body` | Item font size |
+| `--dropdown_item-bg--hover` | `--bds-color_primary--subtle` | Item background on hover and keyboard focus |
+| `--dropdown_item-color--hover` | `--bds-color_on-primary--subtle` | Item text colour on hover and keyboard focus |
+| `--dropdown_item-opacity--disabled` | `0.4` | Opacity of a disabled item |
+| `--dropdown_item-color--destructive` | `--bds-color_error_on-bg` | Destructive item text colour |
+| `--dropdown_item-bg--destructive-hover` | `--bds-color_error--subtle` | Destructive item background on hover and focus |
+| `--dropdown_item-color--destructive-hover` | `--bds-color_on-error--subtle` | Destructive item text colour on hover and focus |
+| `--dropdown_shortcut-color` | `--bds-color_on-bg--muted` | Shortcut hint colour |
+| `--dropdown_shortcut-font-size` | `--bds-font_size--body--s` | Shortcut hint font size |
+
+## CSS Custom Properties — `<bds-dropdown-menu-group>`
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--dropdown_group-label-font-size` | `--bds-font_size--body--s` | Group label font size |
+| `--dropdown_group-label-font-weight` | `--bds-font_weight--bold` | Group label font weight |
+| `--dropdown_group-label-color` | `--bds-color_on-bg--muted` | Group label colour |
+| `--dropdown_group-label-padding` | `--bds-space_xs --bds-space_s --bds-space_xxs` | Group label padding |
 
 ## Attributes — `<bds-dropdown-menu>`
 
@@ -83,20 +106,34 @@ Or in HTML without a bundler:
 | `value` | string | `""` | Value emitted in `bds-select` event detail |
 | `disabled` | boolean | `false` | Prevents interaction; item is excluded from keyboard navigation |
 | `destructive` | boolean | `false` | Renders the item in a destructive (error colour) style |
+| `shortcut` | string | `""` | Shortcut as display text at the inline end; `aria-hidden`, the consumer wires the actual key |
+
+## Attributes — `<bds-dropdown-menu-group>`
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `label` | string | `""` | Visible group label and accessible name of the group |
 
 ## Slots — `<bds-dropdown-menu>`
 
 | Slot | Description |
 |------|-------------|
 | `trigger` | The activating element (typically a `<button>`) |
-| `(default)` | `<bds-dropdown-menu-item>` elements |
+| `(default)` | `<bds-dropdown-menu-item>` or `<bds-dropdown-menu-group>` elements |
 
 ## Slots — `<bds-dropdown-menu-item>`
 
 | Slot | Description |
 |------|-------------|
+| `icon` | Optional decorative icon before the label |
 | `(default)` | Item label text |
 
+## Slots — `<bds-dropdown-menu-group>`
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | `<bds-dropdown-menu-item>` elements |
+
 ## Events
 
 | Event | Fired by | Bubbles | Detail | Description |
@@ -116,6 +153,23 @@ Or in HTML without a bundler:
 </bds-dropdown-menu>
 ```
 
+## Usage with groups
+
+```html
+<bds-dropdown-menu>
+  <bds-button slot="trigger" variant="outline">Acties</bds-button>
+  <bds-dropdown-menu-group label="Bewerken">
+    <bds-dropdown-menu-item value="edit" shortcut="⌘E">
+      <span slot="icon">✎</span>Bewerken
+    </bds-dropdown-menu-item>
+    <bds-dropdown-menu-item value="duplicate">Dupliceren</bds-dropdown-menu-item>
+  </bds-dropdown-menu-group>
+  <bds-dropdown-menu-group label="Gevaarlijk">
+    <bds-dropdown-menu-item value="delete" destructive>Verwijderen</bds-dropdown-menu-item>
+  </bds-dropdown-menu-group>
+</bds-dropdown-menu>
+```
+
 ## Accessibility
 
 - The slotted trigger receives `aria-haspopup="menu"`, `aria-controls` (pointing at the panel's id), and `aria-expanded` kept in sync with open/close state
@@ -125,3 +179,5 @@ Or in HTML without a bundler:
 - Disabled items are excluded from keyboard navigation
 - Focus returns to the trigger element on close
 - The panel is an absolutely-positioned shadow-DOM element (not the native Popover API), so it can be clipped by an ancestor's `overflow` or stacking context
+- `<bds-dropdown-menu-group>` renders a `role="group"` in its shadow root named by its visible label (`aria-labelledby` within the same shadow root); the label is not focusable and keyboard navigation skips it
+- The item `shortcut` is `aria-hidden`; the consumer wires the actual key

package/src/web-components/interaction/BdsDropdownMenu.stories.tsx

@@ -16,7 +16,7 @@ function BdsDropdownMenu({
   return React.createElement(
     'bds-dropdown-menu',
     { placement },
-    React.createElement('button', { slot: 'trigger', type: 'button' }, triggerLabel),
+    React.createElement('bds-button', { slot: 'trigger', variant: 'outline' }, triggerLabel),
     children ?? [
       React.createElement('bds-dropdown-menu-item', { key: 'edit', value: 'edit' }, 'Edit'),
       React.createElement('bds-dropdown-menu-item', { key: 'duplicate', value: 'duplicate' }, 'Duplicate'),
@@ -28,7 +28,7 @@ function BdsDropdownMenu({
 const meta = {
   title: 'Web Components/Interaction/DropdownMenu',
   component: BdsDropdownMenu,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     placement: {
@@ -51,10 +51,10 @@ export const WithDestructiveItem: Story = {
     React.createElement(
       'bds-dropdown-menu',
       { placement: 'bottom-start' },
-      React.createElement('button', { slot: 'trigger', type: 'button' }, 'Manage'),
+      React.createElement('bds-button', { slot: 'trigger', variant: 'outline' }, 'Manage'),
       React.createElement('bds-dropdown-menu-item', { value: 'edit' }, 'Edit'),
       React.createElement('bds-dropdown-menu-item', { value: 'duplicate' }, 'Duplicate'),
-      React.createElement('bds-dropdown-menu-item', { value: 'delete', destructive: '' }, 'Delete'),
+      React.createElement('bds-dropdown-menu-item', { value: 'delete', destructive: true }, 'Delete'),
     ),
 };
 
@@ -63,13 +63,38 @@ export const WithDisabledItem: Story = {
     React.createElement(
       'bds-dropdown-menu',
       { placement: 'bottom-start' },
-      React.createElement('button', { slot: 'trigger', type: 'button' }, 'Actions'),
+      React.createElement('bds-button', { slot: 'trigger', variant: 'outline' }, 'Actions'),
       React.createElement('bds-dropdown-menu-item', { value: 'view' }, 'View'),
-      React.createElement('bds-dropdown-menu-item', { value: 'export', disabled: '' }, 'Export (unavailable)'),
+      React.createElement('bds-dropdown-menu-item', { value: 'export', disabled: true }, 'Export (unavailable)'),
       React.createElement('bds-dropdown-menu-item', { value: 'share' }, 'Share'),
     ),
 };
 
+export const WithGroups: Story = {
+  render: () =>
+    React.createElement(
+      'bds-dropdown-menu',
+      { placement: 'bottom-start' },
+      React.createElement('bds-button', { slot: 'trigger', variant: 'outline' }, 'Acties'),
+      React.createElement(
+        'bds-dropdown-menu-group',
+        { label: 'Bewerken' },
+        React.createElement(
+          'bds-dropdown-menu-item',
+          { value: 'edit', shortcut: '⌘E' },
+          React.createElement('span', { slot: 'icon' }, '✎'),
+          'Bewerken',
+        ),
+        React.createElement('bds-dropdown-menu-item', { value: 'duplicate', shortcut: '⌘D' }, 'Dupliceren'),
+      ),
+      React.createElement(
+        'bds-dropdown-menu-group',
+        { label: 'Gevaarlijk' },
+        React.createElement('bds-dropdown-menu-item', { value: 'delete', destructive: true }, 'Verwijderen'),
+      ),
+    ),
+};
+
 export const AllPlacements: Story = {
   render: () => (
     <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '6rem', padding: '5rem' }}>
@@ -80,7 +105,7 @@ export const AllPlacements: Story = {
           React.createElement(
             'bds-dropdown-menu',
             { placement: p },
-            React.createElement('button', { slot: 'trigger', type: 'button' }, p),
+            React.createElement('bds-button', { slot: 'trigger', variant: 'outline' }, p),
             React.createElement('bds-dropdown-menu-item', { value: 'a' }, 'Item A'),
             React.createElement('bds-dropdown-menu-item', { value: 'b' }, 'Item B'),
           ),

package/src/web-components/interaction/BdsPopover.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsPopover.stories';
 
 Framework-agnostic popover custom element. A non-modal floating panel anchored to a trigger element. Uses CSS Anchor Positioning for automatic repositioning when near viewport edges.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/interaction/BdsPopover.stories.tsx

@@ -24,7 +24,7 @@ function BdsPopover({
 const meta = {
   title: 'Web Components/Interaction/Popover',
   component: BdsPopover,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     placement: { control: 'select', options: ['bottom', 'top', 'left', 'right'] },

package/src/web-components/interaction/BdsSkipLink.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsSkipLink.stories';
 
 Framework-agnostic Skip Navigation Link custom element. Visually hidden until focused, allowing keyboard users to jump directly to the main content area and bypass repeated navigation.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/interaction/BdsSkipLink.stories.tsx

@@ -20,7 +20,7 @@ function BdsSkipLink({
 const meta = {
   title: 'Web Components/UI/SkipLink',
   component: BdsSkipLink,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     href: { control: 'text' },

package/src/web-components/interaction/BdsTabs.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsTabs.stories';
 
 Framework-agnostic Tabs custom element. Coordinates `<bds-tab>` and `<bds-tab-panel>` children by DOM order, with full keyboard navigation.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -102,6 +102,11 @@ across every state; set `--tab_color--active` to theme only the selected tab.
 | `--tab_color--active` | Text colour override for the selected tab |
 | `--tab_border-color--active` | Bottom-border colour override for the selected tab |
 | `--tab_color--hover` | Text colour override on hover (unselected, enabled tabs) |
+| `--tab_color--inactive` | Text colour override for unselected tabs (default: `--bds-color_on-bg--muted`) |
+| `--tab_font-weight` | Tab font weight override (all states) |
+| `--tab_font-weight--inactive` | Font weight override for unselected tabs (default: `--bds-font_weight--medium`) |
+| `--tab_font-weight--active` | Font weight override for the selected tab (default: `--bds-font_weight--bold`) |
+| `--tab_indicator-width` | Thickness of the bottom indicator line (default: `3px`) |
 
 ## Usage in plain HTML
 
@@ -125,6 +130,10 @@ Tabs and panels are matched by DOM order (first tab → first panel, etc.):
 </bds-tabs>
 ```
 
+## Layout stability
+
+The slotted label is mirrored into a `data-label` attribute on an inner wrapper, and a hidden `::after` repeats it at the active weight (`--tab_font-weight--active`). The tab keeps its bold width, so selecting a tab does not shift the row. The copy is invisible and not read by screen readers.
+
 ## Accessibility
 
 - The tab list container has `role="tablist"`

package/src/web-components/interaction/BdsTabs.stories.tsx

@@ -29,7 +29,7 @@ function BdsTabs({
 const meta = {
   title: 'Web Components/UI/Tabs',
   component: BdsTabs,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
 } satisfies Meta<typeof BdsTabs>;