@boostdev/design-system-components 2.15.0 → 2.16.0

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

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsToastProvider.stories';
 
 Framework-agnostic toast notification provider. Wrap your page content in `<bds-toast-provider>` to enable toast notifications that render in the browser top layer (above fixed/sticky elements). Auto-dismisses after 5 seconds.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

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

@@ -37,7 +37,7 @@ function ToastDemo() {
 const meta = {
   title: 'Web Components/Interaction/ToastProvider',
   component: ToastDemo,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
 } satisfies Meta<typeof ToastDemo>;
 

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsTooltip.stories';
 
 Framework-agnostic Tooltip custom element. Displays a small informational label on hover and keyboard focus using CSS-only visibility — no JavaScript positioning required.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -52,6 +52,9 @@ Or in HTML without a bundler:
 ### Right placement
 <Canvas of={Stories.Right} />
 
+### Long text
+<Canvas of={Stories.LongText} />
+
 ### All placements
 <Canvas of={Stories.AllPlacements} />
 
@@ -74,10 +77,15 @@ Or in HTML without a bundler:
 
 ## CSS Custom Properties
 
-| Property | Description |
-|----------|-------------|
-| `--tooltip_bg` | Tooltip background colour (default: `var(--bds-color_on-bg)`) |
-| `--tooltip_text` | Tooltip text colour (default: `var(--bds-color_bg)`) |
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--tooltip_bg` | `var(--bds-color_on-bg)` | Tooltip background colour |
+| `--tooltip_text` | `var(--bds-color_bg)` | Tooltip text colour |
+| `--tooltip_radius` | `var(--bds-border_radius--xs)` | Tooltip corner radius |
+| `--tooltip_padding` | `var(--bds-space_xxs) var(--bds-space_s)` | Tooltip padding |
+| `--tooltip_font-size` | `var(--bds-font_size--body--s)` | Tooltip text size |
+| `--tooltip_offset` | `var(--bds-space_xs)` | Gap between the trigger and the tooltip |
+| `--tooltip_max-inline-size` | `20rem` | Maximum inline size before content wraps. The tooltip is as wide as its text (`max-content`) up to this value |
 
 ## Usage in plain HTML
 

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

@@ -16,14 +16,14 @@ function BdsTooltip({
   return React.createElement(
     'bds-tooltip',
     { content, placement },
-    children ?? React.createElement('button', { type: 'button' }, 'Hover me'),
+    children ?? React.createElement('bds-button', null, 'Hover me'),
   );
 }
 
 const meta = {
   title: 'Web Components/UI/Tooltip',
   component: BdsTooltip,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     content: { control: 'text' },
@@ -44,11 +44,7 @@ export const OnButton: Story = {
     React.createElement(
       'bds-tooltip',
       { content: args.content, placement: args.placement },
-      React.createElement(
-        'button',
-        { type: 'button', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
-        'Save',
-      ),
+      React.createElement('bds-button', null, 'Save'),
     ),
 };
 
@@ -64,6 +60,14 @@ export const Right: Story = {
   args: { content: 'Appears to the right', placement: 'right' },
 };
 
+export const LongText: Story = {
+  args: {
+    content:
+      'Longer explanation that wraps onto a second line once it reaches the maximum width of the tooltip.',
+    placement: 'bottom',
+  },
+};
+
 export const AllPlacements: Story = {
   render: () => (
     <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '4rem', padding: '3rem' }}>
@@ -74,11 +78,7 @@ export const AllPlacements: Story = {
           React.createElement(
             'bds-tooltip',
             { content: `Placement: ${placement}`, placement },
-            React.createElement(
-              'button',
-              { type: 'button', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
-              placement,
-            ),
+            React.createElement('bds-button', null, placement),
           ),
         ),
       )}

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

@@ -0,0 +1,72 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+/**
+ * `<bds-dropdown-menu-group>` — a labelled group of `<bds-dropdown-menu-item>`
+ * elements inside a `<bds-dropdown-menu>`.
+ *
+ * The shadow root renders a `role="group"` element named by the visible label
+ * (`aria-labelledby` inside the same shadow root). The label is not focusable;
+ * keyboard navigation in the menu only visits the items.
+ *
+ * Attributes:
+ *   label — visible group label, also the accessible name of the group
+ *
+ * Slots:
+ *   (default) — `<bds-dropdown-menu-item>` elements
+ *
+ * @example
+ * <bds-dropdown-menu-group label="Edit">
+ *   <bds-dropdown-menu-item value="edit">Edit</bds-dropdown-menu-item>
+ * </bds-dropdown-menu-group>
+ */
+export class BdsDropdownMenuGroup extends LitElement {
+  static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it here. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
+    :host {
+      display: block;
+    }
+
+    .label {
+      padding: var(--dropdown_group-label-padding, var(--bds-space_xs) var(--bds-space_s) var(--bds-space_xxs));
+      font-family: var(--bds-font_family--body);
+      font-size: var(--dropdown_group-label-font-size, var(--bds-font_size--body--s));
+      font-weight: var(--dropdown_group-label-font-weight, var(--bds-font_weight--bold));
+      color: var(--dropdown_group-label-color, var(--bds-color_on-bg--muted, var(--bds-color_on-bg)));
+    }
+  `;
+
+  static properties = {
+    label: { type: String, reflect: true },
+  };
+
+  declare label: string;
+
+  constructor() {
+    super();
+    this.label = '';
+  }
+
+  render() {
+    return html`
+      <div role="group" aria-labelledby=${this.label ? 'label' : nothing}>
+        ${this.label ? html`<div id="label" class="label">${this.label}</div>` : nothing}
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-dropdown-menu-group', BdsDropdownMenuGroup);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-dropdown-menu-group': BdsDropdownMenuGroup;
+  }
+}

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

@@ -1,4 +1,4 @@
-import { LitElement, css, html } from 'lit';
+import { LitElement, css, html, nothing } from 'lit';
 
 /**
  * `<bds-dropdown-menu-item>` — a single item inside a `<bds-dropdown-menu>`.
@@ -6,9 +6,12 @@ import { LitElement, css, html } from 'lit';
  * Attributes:
  *   value       — value associated with this item
  *   disabled    — disables this item
- *   destructive — renders the item in a destructive (red) style
+ *   destructive — renders the item in a destructive (error colour) style
+ *   shortcut    — keyboard shortcut as display text (decorative, `aria-hidden`);
+ *                 the consumer wires the actual key
  *
  * Slots:
+ *   icon      — optional icon shown before the label (decorative)
  *   (default) — item label text
  *
  * Events:
@@ -34,7 +37,7 @@ export class BdsDropdownMenuItem extends LitElement {
     }
 
     :host([disabled]) {
-      opacity: 0.5;
+      opacity: var(--dropdown_item-opacity--disabled, 0.4);
       pointer-events: none;
     }
 
@@ -43,36 +46,67 @@ export class BdsDropdownMenuItem extends LitElement {
       align-items: center;
       gap: var(--bds-space_xs);
       inline-size: 100%;
-      padding: var(--bds-space_xs) var(--bds-space_s);
-      font-size: var(--bds-font_size--body);
+      padding: var(--dropdown_item-padding, var(--bds-space_xs) var(--bds-space_s));
+      font-size: var(--dropdown_item-font-size, var(--bds-font_size--body));
       font-family: var(--bds-font_family--body);
-      color: var(--bds-color_on-bg);
+      color: inherit;
       background: none;
       border: none;
       text-align: start;
       cursor: pointer;
-      border-radius: var(--bds-border_radius--xs);
+      border-radius: var(--dropdown_item-radius, var(--bds-border_radius--xs));
       transition: var(--bds-animation_transition);
     }
 
     :host([destructive]) .item {
-      color: var(--bds-color_error);
+      color: var(--dropdown_item-color--destructive, var(--bds-color_error_on-bg));
+    }
+
+    .item:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: calc(var(--bds-outline_offset) * -1);
+    }
+
+    .item:not(:disabled):focus-visible {
+      background-color: var(--dropdown_item-bg--hover, var(--bds-color_primary--subtle, var(--bds-color_blue--subtle)));
+      color: var(--dropdown_item-color--hover, var(--bds-color_on-primary--subtle, var(--bds-color_on-blue--subtle)));
+    }
+
+    :host([destructive]) .item:not(:disabled):focus-visible {
+      background-color: var(--dropdown_item-bg--destructive-hover, var(--bds-color_error--subtle));
+      color: var(--dropdown_item-color--destructive-hover, var(--bds-color_on-error--subtle));
     }
 
     @media (hover: hover) and (pointer: fine) {
-      .item:hover {
-        background-color: var(--dropdown_item-bg--hover, var(--bds-color_bg--subtle));
-        color: var(--dropdown_item-color--hover, var(--bds-color_interactive_on-bg));
+      .item:not(:disabled):hover {
+        background-color: var(--dropdown_item-bg--hover, var(--bds-color_primary--subtle, var(--bds-color_blue--subtle)));
+        color: var(--dropdown_item-color--hover, var(--bds-color_on-primary--subtle, var(--bds-color_on-blue--subtle)));
       }
 
-      :host([destructive]) .item:hover {
-        background-color: color-mix(in srgb, var(--bds-color_error) 10%, transparent);
+      :host([destructive]) .item:not(:disabled):hover {
+        background-color: var(--dropdown_item-bg--destructive-hover, var(--bds-color_error--subtle));
+        color: var(--dropdown_item-color--destructive-hover, var(--bds-color_on-error--subtle));
       }
     }
 
-    .item:focus-visible {
-      outline: var(--bds-outline_default);
-      outline-offset: var(--bds-outline_offset);
+    .icon[hidden] {
+      display: none;
+    }
+
+    .icon {
+      display: flex;
+      align-items: center;
+      flex-shrink: 0;
+    }
+
+    .label {
+      flex: 1;
+    }
+
+    .shortcut {
+      flex-shrink: 0;
+      color: var(--dropdown_shortcut-color, var(--bds-color_on-bg--muted, var(--bds-color_on-bg)));
+      font-size: var(--dropdown_shortcut-font-size, var(--bds-font_size--body--s));
     }
   `;
 
@@ -80,17 +114,27 @@ export class BdsDropdownMenuItem extends LitElement {
     value:       { type: String, reflect: true },
     disabled:    { type: Boolean, reflect: true },
     destructive: { type: Boolean, reflect: true },
+    shortcut:    { type: String, reflect: true },
+    _hasIcon:    { state: true },
   };
 
   declare value: string;
   declare disabled: boolean;
   declare destructive: boolean;
+  declare shortcut: string;
+  declare _hasIcon: boolean;
 
   constructor() {
     super();
     this.value = '';
     this.disabled = false;
     this.destructive = false;
+    this.shortcut = '';
+    this._hasIcon = false;
+  }
+
+  private _onIconSlotChange(e: Event) {
+    this._hasIcon = (e.target as HTMLSlotElement).assignedNodes().length > 0;
   }
 
   private _handleClick() {
@@ -120,7 +164,11 @@ export class BdsDropdownMenuItem extends LitElement {
         @click=${this._handleClick}
         @keydown=${this._handleKeydown}
       >
-        <slot></slot>
+        <span class="icon" aria-hidden="true" ?hidden=${!this._hasIcon}>
+          <slot name="icon" @slotchange=${this._onIconSlotChange}></slot>
+        </span>
+        <span class="label"><slot></slot></span>
+        ${this.shortcut ? html`<span class="shortcut" aria-hidden="true">${this.shortcut}</span>` : nothing}
       </button>
     `;
   }