@boostdev/design-system-components 2.15.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -171,6 +171,10 @@
       "types": "./dist/web-components/interaction/bds-dropdown-menu-item.d.ts",
       "import": "./dist/web-components/interaction/bds-dropdown-menu-item.js"
     },
+    "./web-components/interaction/bds-dropdown-menu-group": {
+      "types": "./dist/web-components/interaction/bds-dropdown-menu-group.d.ts",
+      "import": "./dist/web-components/interaction/bds-dropdown-menu-group.js"
+    },
     "./web-components/interaction/bds-popover": {
       "types": "./dist/web-components/interaction/bds-popover.d.ts",
       "import": "./dist/web-components/interaction/bds-popover.js"
@@ -338,7 +342,7 @@
     "changelog:unreleased": "pnpm exec git-cliff --unreleased"
   },
   "devDependencies": {
-    "@boostdev/design-system-foundation": "^2.3.0",
+    "@boostdev/design-system-foundation": "^2.4.0",
     "@boostdev/design-system-react-native": "0.2.0",
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@storybook/addon-docs": "8.6.14",

package/src/components/interaction/DropdownMenu/DropdownMenu.mdx

@@ -5,7 +5,7 @@ import * as Stories from './DropdownMenu.stories';
 
 # DropdownMenu
 
-Floating menu with a list of selectable actions, triggered by a button. Supports disabled items and separators.
+Floating menu with a list of selectable actions, triggered by a button. Supports disabled items, separators, destructive items, shortcut hints and labelled groups.
 
 ## When to use
 - Overflow actions in a toolbar or table row
@@ -26,6 +26,12 @@ Floating menu with a list of selectable actions, triggered by a button. Supports
 ### With disabled item
 <Canvas of={Stories.WithDisabledItem} />
 
+### With groups
+<Canvas of={Stories.WithGroups} />
+
+### With destructive item
+<Canvas of={Stories.WithDestructiveItem} />
+
 ### Aligned end
 <Canvas of={Stories.AlignedEnd} />
 
@@ -45,14 +51,37 @@ Floating menu with a list of selectable actions, triggered by a button. Supports
 <tr><td>`--dropdown_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Menu container corner radius</td></tr>
 <tr><td>`--dropdown_color`</td><td>`var(--bds-color_bg)`</td><td>Menu background colour</td></tr>
 <tr><td>`--dropdown_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Menu text colour</td></tr>
-<tr><td>`--dropdown_shadow`</td><td>`var(--bds-shadow_m)`</td><td>Menu box shadow</td></tr>
+<tr><td>`--dropdown_shadow`</td><td>`var(--bds-shadow_l)`</td><td>Menu box shadow</td></tr>
 <tr><td>`--dropdown_separator-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Separator line colour — the non-text member of the colour set (≥ 3:1)</td></tr>
-<tr><td>`--dropdown_item-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Menu item background on hover</td></tr>
-<tr><td>`--dropdown_item-color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Menu item text colour on hover</td></tr>
+<tr><td>`--dropdown_item-bg--hover`</td><td>`var(--bds-color_primary--subtle)`</td><td>Menu item background on hover and focus</td></tr>
+<tr><td>`--dropdown_item-color--hover`</td><td>`var(--bds-color_on-primary--subtle)`</td><td>Menu item text colour on hover and focus</td></tr>
+<tr><td>`--dropdown_padding`</td><td>`var(--bds-space_xxs)`</td><td>Menu padding on all sides</td></tr>
+<tr><td>`--dropdown_border-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Menu outline colour</td></tr>
+<tr><td>`--dropdown_item-padding`</td><td>`var(--bds-space_xs) var(--bds-space_s)`</td><td>Item padding</td></tr>
+<tr><td>`--dropdown_item-radius`</td><td>`var(--bds-border_radius--xs)`</td><td>Item corner radius</td></tr>
+<tr><td>`--dropdown_item-font-size`</td><td>`var(--bds-font_size--body)`</td><td>Item font size</td></tr>
+<tr><td>`--dropdown_item-opacity--disabled`</td><td>`0.4`</td><td>Disabled item opacity</td></tr>
+<tr><td>`--dropdown_item-color--destructive`</td><td>`var(--bds-color_error_on-bg)`</td><td>Destructive item text colour</td></tr>
+<tr><td>`--dropdown_item-bg--destructive-hover`</td><td>`var(--bds-color_error--subtle)`</td><td>Destructive item background on hover and focus</td></tr>
+<tr><td>`--dropdown_item-color--destructive-hover`</td><td>`var(--bds-color_on-error--subtle)`</td><td>Destructive item text colour on hover and focus</td></tr>
+<tr><td>`--dropdown_group-label-font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Group label font size</td></tr>
+<tr><td>`--dropdown_group-label-font-weight`</td><td>`var(--bds-font_weight--bold)`</td><td>Group label font weight</td></tr>
+<tr><td>`--dropdown_group-label-color`</td><td>`var(--bds-color_on-bg--muted)`</td><td>Group label colour</td></tr>
+<tr><td>`--dropdown_group-label-padding`</td><td>`var(--bds-space_xs) var(--bds-space_s) var(--bds-space_xxs)`</td><td>Group label padding</td></tr>
+<tr><td>`--dropdown_shortcut-color`</td><td>`var(--bds-color_on-bg--muted)`</td><td>Shortcut hint colour</td></tr>
+<tr><td>`--dropdown_shortcut-font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Shortcut hint font size</td></tr>
 </tbody>
 </table>
 
 
+## Item options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `destructive` | boolean | Renders the item in the error colour |
+| `shortcut` | string | Display-only shortcut hint at the inline end; rendered `aria-hidden`, the consumer wires the actual key |
+| `group` | string | Consecutive items with the same `group` render inside a `role="group"` named by a visible label |
+
 ## Accessibility
 
 - Implements ARIA menu pattern: `role="menu"`, `role="menuitem"`
@@ -60,3 +89,5 @@ Floating menu with a list of selectable actions, triggered by a button. Supports
 - Disabled items have `aria-disabled="true"` and are skipped during keyboard navigation
 - Opening the menu focuses the first enabled item (disabled items are skipped as the initial target)
 - Closing the menu via `Escape` or item activation returns focus to the trigger; closing via `Tab` lets focus move naturally to the next element
+- Grouped items sit inside `role="group"` with `aria-labelledby` pointing at the visible group label; the label is not focusable and arrow keys skip it
+- Shortcut hints are `aria-hidden` so they do not become part of the item name

package/src/components/interaction/DropdownMenu/DropdownMenu.module.css

@@ -9,15 +9,15 @@
     inset-block-start: calc(100% + var(--bds-space_xxs));
     z-index: var(--bds-z-index_dropdown);
     min-inline-size: 10rem;
-    padding: var(--bds-space_xxs) 0;
+    padding: var(--dropdown_padding, var(--bds-space_xxs));
     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));
+    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--dropdown_shadow, var(--bds-shadow_l));
     list-style: none;
     margin: 0;
   }
@@ -29,10 +29,29 @@
   .--placement_bottom-start { inset-inline-start: 0; }
   .--placement_bottom-end   { inset-inline-end: 0; }
 
+  .separatorRow {
+    padding-block: var(--bds-space_xxs);
+  }
+
   .separator {
     border: none;
     border-block-start: 1px solid var(--dropdown_separator-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_on-bg))));
-    margin: var(--bds-space_xxs) 0;
+    margin: 0;
+  }
+
+  .group {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .groupLabel {
+    display: block;
+    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)));
   }
 
   .item {
@@ -41,9 +60,10 @@
     align-items: center;
     gap: var(--bds-space_xs);
     inline-size: 100%;
-    padding: var(--bds-space_xs) var(--bds-space_m);
+    padding: var(--dropdown_item-padding, var(--bds-space_xs) var(--bds-space_s));
+    border-radius: var(--dropdown_item-radius, var(--bds-border_radius--xs));
     font-family: var(--bds-font_family--body);
-    font-size: var(--bds-font_size--body);
+    font-size: var(--dropdown_item-font-size, var(--bds-font_size--body));
     color: currentcolor;
     cursor: pointer;
     box-sizing: border-box;
@@ -51,23 +71,51 @@
   }
 
   .item:disabled {
-    opacity: 0.4;
+    opacity: var(--dropdown_item-opacity--disabled, 0.4);
     cursor: not-allowed;
   }
 
   .item:focus-visible {
     outline: var(--bds-outline_default);
     outline-offset: calc(var(--bds-outline_offset) * -1);
-    border-radius: var(--bds-border_radius--xs);
+  }
+
+  .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)));
+  }
+
+  .--destructive {
+    color: var(--dropdown_item-color--destructive, var(--bds-color_error_on-bg));
+  }
+
+  .--destructive: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:not(:disabled):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));
+      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)));
+    }
+
+    .--destructive: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));
     }
   }
 
+  .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));
+  }
+
   .icon {
     display: flex;
     align-items: center;

package/src/components/interaction/DropdownMenu/DropdownMenu.spec.tsx

@@ -1,7 +1,14 @@
-import { render, screen } from '@testing-library/react';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { DropdownMenu } from './DropdownMenu';
 
+const cssSource = readFileSync(
+  resolve(process.cwd(), 'src/components/interaction/DropdownMenu/DropdownMenu.module.css'),
+  'utf8',
+);
+
 const items = [
   { id: 'edit', label: 'Edit', onClick: vi.fn() },
   { id: 'duplicate', label: 'Duplicate', onClick: vi.fn() },
@@ -105,4 +112,110 @@ describe('DropdownMenu', () => {
     await user.click(screen.getByRole('button', { name: 'Actions' }));
     expect(screen.getByRole('menuitem', { name: 'Edit' })).toHaveFocus();
   });
+
+  describe('groups, destructive and shortcut', () => {
+    const grouped = [
+      { id: 'edit', label: 'Edit', group: 'Edit' },
+      { id: 'duplicate', label: 'Duplicate', shortcut: '⌘D', group: 'Edit' },
+      { id: 'delete', label: 'Delete', destructive: true, group: 'Danger' },
+    ];
+
+    it('renders a labelled group for consecutive items with the same group', async () => {
+      const user = userEvent.setup();
+      render(<DropdownMenu trigger={<button type="button">Actions</button>} items={grouped} />);
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      const group = screen.getByRole('group', { name: 'Edit' });
+      expect(within(group).getAllByRole('menuitem')).toHaveLength(2);
+      expect(screen.getByRole('group', { name: 'Danger' })).toBeInTheDocument();
+    });
+
+    it('moves focus from the last item of a group to the first of the next', async () => {
+      const user = userEvent.setup();
+      render(<DropdownMenu trigger={<button type="button">Actions</button>} items={grouped} />);
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      await user.keyboard('{ArrowDown}');
+      expect(screen.getByRole('menuitem', { name: 'Duplicate' })).toHaveFocus();
+      await user.keyboard('{ArrowDown}');
+      expect(screen.getByRole('menuitem', { name: 'Delete' })).toHaveFocus();
+    });
+
+    it('does not render a group for items without a group', async () => {
+      const user = userEvent.setup();
+      render(<DropdownMenu trigger={<button type="button">Actions</button>} items={items} />);
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      expect(screen.queryByRole('group')).not.toBeInTheDocument();
+    });
+
+    it('marks a destructive item with the destructive class', async () => {
+      const user = userEvent.setup();
+      render(<DropdownMenu trigger={<button type="button">Actions</button>} items={grouped} />);
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      expect(screen.getByRole('menuitem', { name: 'Delete' }).className).toMatch(/destructive/);
+      expect(screen.getByRole('menuitem', { name: 'Edit' }).className).not.toMatch(/destructive/);
+    });
+
+    it('renders the shortcut aria-hidden and keeps it out of the item name', async () => {
+      const user = userEvent.setup();
+      render(<DropdownMenu trigger={<button type="button">Actions</button>} items={grouped} />);
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      expect(screen.getByText('⌘D')).toHaveAttribute('aria-hidden', 'true');
+      expect(screen.getByRole('menuitem', { name: 'Duplicate' })).toBeInTheDocument();
+    });
+
+    it('renders a separator before an item with separator set', async () => {
+      const user = userEvent.setup();
+      render(
+        <DropdownMenu
+          trigger={<button type="button">Actions</button>}
+          items={[{ id: 'a', label: 'A' }, { id: 'b', label: 'B', separator: true }]}
+        />
+      );
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      expect(screen.getByRole('separator')).toBeInTheDocument();
+    });
+
+    it('renders the separator of a group\'s first item outside the group', async () => {
+      const user = userEvent.setup();
+      render(
+        <DropdownMenu
+          trigger={<button type="button">Actions</button>}
+          items={[
+            { id: 'a', label: 'A', group: 'One' },
+            { id: 'b', label: 'B', group: 'Two', separator: true },
+            { id: 'c', label: 'C', group: 'Two', separator: true },
+          ]}
+        />
+      );
+      await user.click(screen.getByRole('button', { name: 'Actions' }));
+      const groups = screen.getAllByRole('group');
+      const separators = screen.getAllByRole('separator');
+      expect(separators).toHaveLength(2);
+      expect(groups[1]).not.toContainElement(separators[0]);
+      expect(groups[1]).toContainElement(separators[1]);
+    });
+  });
+
+  describe('stylesheet hooks', () => {
+    it.each([
+      '--dropdown_padding',
+      '--dropdown_border-color',
+      '--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_group-label-font-size',
+      '--dropdown_group-label-font-weight',
+      '--dropdown_group-label-color',
+      '--dropdown_group-label-padding',
+      '--dropdown_shortcut-color',
+      '--dropdown_shortcut-font-size',
+    ])('reads %s through var()', hook => {
+      expect(cssSource).toContain(`var(${hook},`);
+    });
+  });
 });

package/src/components/interaction/DropdownMenu/DropdownMenu.stories.tsx

@@ -66,3 +66,28 @@ export const AlignedEnd: Story = {
     />
   ),
 };
+
+export const WithGroups: Story = {
+  render: () => (
+    <DropdownMenu
+      trigger={<Button variant="outline">Acties ▾</Button>}
+      items={[
+        { id: 'edit', label: 'Bewerken', icon: <span>✎</span>, shortcut: '⌘E', group: 'Bewerken' },
+        { id: 'duplicate', label: 'Dupliceren', shortcut: '⌘D', group: 'Bewerken' },
+        { id: 'delete', label: 'Verwijderen', destructive: true, group: 'Gevaarlijk' },
+      ]}
+    />
+  ),
+};
+
+export const WithDestructiveItem: Story = {
+  render: () => (
+    <DropdownMenu
+      trigger={<Button variant="outline">Beheer ▾</Button>}
+      items={[
+        { id: 'edit', label: 'Bewerken' },
+        { id: 'delete', label: 'Verwijderen', destructive: true, separator: true },
+      ]}
+    />
+  ),
+};

package/src/components/interaction/DropdownMenu/DropdownMenu.tsx

@@ -2,6 +2,7 @@ import {
   HTMLAttributes,
   KeyboardEvent,
   ReactElement,
+  Fragment,
   cloneElement,
   isValidElement,
   useEffect,
@@ -20,8 +21,29 @@ export interface DropdownMenuItem {
   disabled?: boolean;
   icon?: ReactElement;
   separator?: boolean;
+  /** Renders the item in the error colour, for actions that delete or discard. */
+  destructive?: boolean;
+  /** Keyboard shortcut as display text. Decorative (`aria-hidden`); the consumer wires the actual key. */
+  shortcut?: string;
+  /** Consecutive items with the same group render inside a labelled `role="group"`. */
+  group?: string;
 }
 
+interface IndexedItem {
+  item: DropdownMenuItem;
+  index: number;
+}
+
+/** Splits items into runs of consecutive items sharing the same `group`. */
+const toSegments = (items: DropdownMenuItem[]): IndexedItem[][] =>
+  items.reduce<IndexedItem[][]>((segments, item, index) => {
+    const last = segments[segments.length - 1];
+    const startsNewSegment = !last || item.group === undefined || last[0].item.group !== item.group;
+    return startsNewSegment
+      ? [...segments, [{ item, index }]]
+      : [...segments.slice(0, -1), [...last, { item, index }]];
+  }, []);
+
 export interface DropdownMenuProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
   trigger: ReactElement;
   items: DropdownMenuItem[];
@@ -125,23 +147,53 @@ export function DropdownMenu({
           role="menu"
           className={cn(css.menu, css[`--placement_${placement}`])}
         >
-          {items.map((item, index) => (
-            <li key={item.id} role="presentation">
-              {item.separator && <hr className={css.separator} role="separator" />}
-              <button
-                ref={el => { itemRefs.current[index] = el; }}
-                type="button"
-                role="menuitem"
-                disabled={item.disabled}
-                className={css.item}
-                onClick={() => { item.onClick?.(); close(true); }}
-                onKeyDown={e => handleItemKeyDown(e, index)}
-              >
-                {item.icon && <span className={css.icon} aria-hidden="true">{item.icon}</span>}
-                {item.label}
-              </button>
-            </li>
-          ))}
+          {toSegments(items).map(segment => {
+            const { item: first } = segment[0];
+            const groupLabel = first.group;
+            const renderSeparator = () => (
+              <li role="presentation" className={css.separatorRow}>
+                <hr className={css.separator} role="separator" />
+              </li>
+            );
+            /* The first item's separator sits before the group, so the group holds only its label and items. */
+            const leadingSeparator = groupLabel !== undefined && first.separator;
+            const rows = segment.map(({ item, index }, position) => (
+              <Fragment key={item.id}>
+                {item.separator && !(leadingSeparator && position === 0) && renderSeparator()}
+                <li role="presentation">
+                  <button
+                    ref={el => { itemRefs.current[index] = el; }}
+                    type="button"
+                    role="menuitem"
+                    disabled={item.disabled}
+                    className={cn(css.item, item.destructive && css['--destructive'])}
+                    onClick={() => { item.onClick?.(); close(true); }}
+                    onKeyDown={e => handleItemKeyDown(e, index)}
+                  >
+                    {item.icon && <span className={css.icon} aria-hidden="true">{item.icon}</span>}
+                    <span className={css.label}>{item.label}</span>
+                    {item.shortcut && <span className={css.shortcut} aria-hidden="true">{item.shortcut}</span>}
+                  </button>
+                </li>
+              </Fragment>
+            ));
+
+            return groupLabel === undefined ? (
+              rows
+            ) : (
+              <Fragment key={`group-${first.id}`}>
+                {leadingSeparator && renderSeparator()}
+                <li role="presentation">
+                <ul role="group" aria-labelledby={`${menuId}-group-${first.id}`} className={css.group}>
+                  <li role="presentation" id={`${menuId}-group-${first.id}`} className={css.groupLabel}>
+                    {groupLabel}
+                  </li>
+                  {rows}
+                </ul>
+                </li>
+              </Fragment>
+            );
+          })}
         </ul>
       )}
     </div>

package/src/components/interaction/form/Checkbox/Checkbox.module.css

@@ -65,5 +65,6 @@
 
   .checkboxError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 }

package/src/components/interaction/form/Checkbox/Checkbox.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Checkbox } from './Checkbox';
@@ -42,4 +44,9 @@ describe('Checkbox', () => {
     const checkbox = screen.getByLabelText('Accept terms');
     expect(checkbox.id).not.toBe('consumer-supplied-id');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Checkbox/Checkbox.module.css'), 'utf8');
+    expect(css).toMatch(/\.checkboxError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.mdx

@@ -57,3 +57,4 @@ All public override tokens. Set on the CheckboxGroup or any ancestor; they casca
 - `disabled` on the group sets the HTML `disabled` attribute on the `<fieldset>`, which disables all child inputs
 - When `required` is true, the legend shows a visible `*` (hidden from assistive tech via `aria-hidden`) plus a visually-hidden "(required)" span, so the fieldset's accessible name resolves to `"<legend> (required)"` (e.g. `"Contact preferences (required)"`). `aria-required` is intentionally **not** set on the `<fieldset>` — it is not supported ARIA on a `role=group` element and would be ignored by assistive tech
 - Error and hint messages are linked via `aria-describedby`
+- With `error`, the child controls show the error ring (`--bdc-outline_width--error`, `--bdc_color--error`) and the message gets a warning icon. Message hooks (`--formMessage_*`) are listed on FormInput

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.module.css

@@ -42,4 +42,11 @@
     flex-direction: column;
     gap: var(--checkboxGroup_items-gap, var(--bds-space_xs));
   }
+
+  /* Error ring on the controls inside; state rules on the control itself
+     (checked, focus) still win because they have higher specificity. */
+  .groupError input {
+    --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
+  }
 }

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { Checkbox } from '../Checkbox';
 import { CheckboxGroup } from './CheckboxGroup';
@@ -114,4 +116,24 @@ describe('CheckboxGroup', () => {
     );
     expect(screen.getByRole('group')).toBeDisabled();
   });
+
+  it('marks the group with the error class so the controls inside show the error ring', () => {
+    render(
+      <CheckboxGroup legend="Pick" error="Required">
+        <Checkbox label="One" name="one" value="1" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByRole('group', { name: 'Pick' }).className).toContain('groupError');
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/CheckboxGroup/CheckboxGroup.module.css'), 'utf8');
+    expect(css).toMatch(/\.groupError input \{[^}]*--bdc_color: var\(--bdc_color--error\)[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
+
+  it('does not mark the group without an error', () => {
+    render(
+      <CheckboxGroup legend="Pick">
+        <Checkbox label="One" name="one" value="1" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByRole('group', { name: 'Pick' }).className).not.toContain('groupError');
+  });
 });

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.tsx

@@ -28,7 +28,7 @@ export function CheckboxGroup({
   return (
     <fieldset
       {...rest}
-      className={cn(css.group, className)}
+      className={cn(css.group, error && css.groupError, className)}
       aria-describedby={describedBy}
     >
       <legend className={css.legend}>

package/src/components/interaction/form/Combobox/Combobox.module.css

@@ -45,6 +45,7 @@
 
   .inputError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 
   .chevron {

package/src/components/interaction/form/Combobox/Combobox.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Combobox } from './Combobox';
@@ -125,4 +127,9 @@ describe('Combobox', () => {
     expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
     expect(combobox).not.toHaveAttribute('aria-activedescendant');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Combobox/Combobox.module.css'), 'utf8');
+    expect(css).toMatch(/\.inputError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/FormInput/FormInput.mdx

@@ -43,9 +43,18 @@ Text input field with label, optional hint, and error state. The label and input
 <tr><td>`--formInput_border`</td><td>`none`</td><td>Border</td></tr>
 <tr><td>`--formInput_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Corner radius</td></tr>
 <tr><td>`--formInput_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Box shadow</td></tr>
+<tr><td>`--formMessage_font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Font size of the error and hint message (shared by all form controls)</td></tr>
+<tr><td>`--formMessage_gap`</td><td>`var(--bds-space_xxs)`</td><td>Gap between the error icon and the error text</td></tr>
+<tr><td>`--formMessage_icon-size`</td><td>`1.15em`</td><td>Size of the error icon</td></tr>
+<tr><td>`--formMessage_color--error`</td><td>`var(--bds-color_error_on-bg)`</td><td>Error message colour</td></tr>
+<tr><td>`--formMessage_font-weight--error`</td><td>`var(--bds-font_weight--semibold)`</td><td>Error message weight</td></tr>
+<tr><td>`--formMessage_color--hint`</td><td>`inherit`</td><td>Hint colour</td></tr>
+<tr><td>`--formMessage_font-style--hint`</td><td>`italic`</td><td>Hint font style</td></tr>
 </tbody>
 </table>
 
+In the error state the control draws a `--bdc-outline_width--error` (2px) ring in `--bdc_color--error`, and the message gets a warning icon.
+
 `--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.
 
 

package/src/components/interaction/form/FormInput/FormInput.module.css

@@ -42,5 +42,6 @@
 
   .inputError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 }

package/src/components/interaction/form/FormInput/FormInput.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { FormInput } from './FormInput';
@@ -60,4 +62,9 @@ describe('FormInput', () => {
     render(<FormInput label="Email" name="email" ariaLabel="Deprecated label" aria-label="Native label" />);
     expect(screen.getByRole('textbox')).toHaveAccessibleName('Deprecated label');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/FormInput/FormInput.module.css'), 'utf8');
+    expect(css).toMatch(/\.inputError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/NumberInput/NumberInput.module.css

@@ -49,6 +49,7 @@
 
   .inputError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 
   .stepper {