@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/components/ui/Tooltip/Tooltip.tsx

@@ -1,4 +1,13 @@
-import { HTMLAttributes, ReactElement, ReactNode, cloneElement, isValidElement, useId, useState } from 'react';
+import {
+  HTMLAttributes,
+  KeyboardEvent,
+  ReactElement,
+  ReactNode,
+  cloneElement,
+  isValidElement,
+  useId,
+  useState,
+} from 'react';
 import css from './Tooltip.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
@@ -19,6 +28,15 @@ export function Tooltip({
   const tooltipId = useId();
   const [isVisible, setIsVisible] = useState(false);
 
+  const show = () => setIsVisible(true);
+  const hide = () => setIsVisible(false);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement>) => {
+    if (event.key === 'Escape' && isVisible) {
+      hide();
+    }
+  };
+
   const trigger = isValidElement(children)
     ? cloneElement(children as ReactElement<Record<string, unknown>>, {
         'aria-describedby': tooltipId,
@@ -29,17 +47,18 @@ export function Tooltip({
     <span
       {...rest}
       className={cn(css.wrapper, className)}
-      onMouseEnter={() => setIsVisible(true)}
-      onMouseLeave={() => setIsVisible(false)}
-      onFocus={() => setIsVisible(true)}
-      onBlur={() => setIsVisible(false)}
+      onMouseEnter={show}
+      onMouseLeave={hide}
+      onFocus={show}
+      onBlur={hide}
+      onKeyDown={handleKeyDown}
     >
       {trigger}
       <span
         id={tooltipId}
         role="tooltip"
-        aria-hidden={!isVisible}
-        className={cn(css.tooltip, css[`--placement_${placement}`])}
+        hidden={!isVisible}
+        className={cn(css.tooltip, css[`--placement_${placement}`], isVisible && css['--visible'])}
       >
         {content}
       </span>

package/src/components/ui/Typography/Typography.mdx

@@ -33,6 +33,8 @@ Renders a text element with a design-system variant. Decouples visual style from
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -44,6 +46,11 @@ Renders a text element with a design-system variant. Decouples visual style from
 </thead>
 <tbody>
 <tr><td>`--typography_color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour override</td></tr>
+<tr><td>`--typography_font-size--h1`</td><td>`var(--bds-font_size--heading-1)`</td><td>Font size override for the `h1` variant</td></tr>
+<tr><td>`--typography_font-size--h2`</td><td>`var(--bds-font_size--heading-2)`</td><td>Font size override for the `h2` variant</td></tr>
+<tr><td>`--typography_font-size--h3`</td><td>`var(--bds-font_size--heading-3)`</td><td>Font size override for the `h3` variant</td></tr>
+<tr><td>`--typography_font-size--body`</td><td>`var(--bds-font_size--body)`</td><td>Font size override for the `body` variant</td></tr>
+<tr><td>`--typography_font-size--body_s`</td><td>`var(--bds-font_size--body--s)`</td><td>Font size override for the `body_s` variant</td></tr>
 </tbody>
 </table>
 

package/src/components/ui/Typography/Typography.module.css

@@ -7,32 +7,32 @@
 
   .--h1 {
     font-family: var(--bds-font_family--heading);
-    font-size: var(--bds-font_size--heading-1);
+    font-size: var(--typography_font-size--h1, var(--bds-font_size--heading-1));
     font-weight: var(--bds-font_weight--bold);
     line-height: var(--bds-font_line-height--heading);
   }
 
   .--h2 {
     font-family: var(--bds-font_family--heading);
-    font-size: var(--bds-font_size--heading-2);
+    font-size: var(--typography_font-size--h2, var(--bds-font_size--heading-2));
     font-weight: var(--bds-font_weight--semibold);
     line-height: var(--bds-font_line-height--heading);
   }
 
   .--h3 {
     font-family: var(--bds-font_family--heading);
-    font-size: var(--bds-font_size--heading-3);
+    font-size: var(--typography_font-size--h3, var(--bds-font_size--heading-3));
     font-weight: var(--bds-font_weight--semibold);
     line-height: var(--bds-font_line-height--heading);
   }
 
   .--body {
-    font-size: var(--bds-font_size--body);
+    font-size: var(--typography_font-size--body, var(--bds-font_size--body));
     line-height: var(--bds-font_line-height--body);
   }
 
   .--body_s {
-    font-size: var(--bds-font_size--body--s);
+    font-size: var(--typography_font-size--body_s, var(--bds-font_size--body--s));
     line-height: var(--bds-font_line-height--body);
   }
 }

package/src/index.ts

@@ -10,7 +10,7 @@ export { Breadcrumb } from './components/ui/Breadcrumb';
 export type { BreadcrumbItem } from './components/ui/Breadcrumb';
 export { Collapsible } from './components/ui/Collapsible';
 export type { CollapsibleProps } from './components/ui/Collapsible';
-export { Calendar } from './components/ui/Calendar';
+export { Calendar, CalendarRange } from './components/ui/Calendar';
 export { Carousel } from './components/ui/Carousel';
 export { DescriptionList } from './components/ui/DescriptionList';
 export type { DescriptionItem } from './components/ui/DescriptionList';
@@ -34,13 +34,17 @@ export { Typography } from './components/ui/Typography';
 export { Button } from './components/interaction/Button';
 export type { ButtonProps } from './components/interaction/Button';
 export { Command } from './components/interaction/Command';
-export type { CommandItem } from './components/interaction/Command';
+export type { CommandItem, CommandProps } from './components/interaction/Command';
 export { Dialog } from './components/interaction/Dialog';
+export type { DialogProps } from './components/interaction/Dialog';
 export { Drawer } from './components/interaction/Drawer';
+export type { DrawerProps } from './components/interaction/Drawer';
 export { DropdownMenu } from './components/interaction/DropdownMenu';
-export type { DropdownMenuItem } from './components/interaction/DropdownMenu';
+export type { DropdownMenuItem, DropdownMenuProps } from './components/interaction/DropdownMenu';
 export { Popover } from './components/interaction/Popover';
+export type { PopoverProps } from './components/interaction/Popover';
 export { Rating } from './components/interaction/Rating';
+export type { RatingProps } from './components/interaction/Rating';
 export { ToastProvider, useToast } from './components/interaction/Toast';
 
 // Form

package/src/stories/DesignSystem/Borders.mdx

@@ -56,7 +56,7 @@ Components use `outline` rather than `border` for their decorative edge. The rea
     <TokenRow token="--bdc-outline_width"  type="<length>"             defaultValue="1px"          description="Border width" />
     <TokenRow token="--bdc-outline_offset" type="<length>"             defaultValue="-1px"         description="Negative = inset (border-like); positive = outer halo" />
     <TokenRow token="--bdc-outline_radius" type="<length-percentage>"  defaultValue="0"            description="Border radius, synced with the element's own radius" />
-    <TokenRow token="--bdc-outline_shadow" type="*"                    defaultValue="none"         description="Box shadow — opt-in accent, e.g. focus glow" />
+    <TokenRow token="--bdc-outline_shadow" type="*"                    defaultValue="0 0 0 0 transparent" description="Box shadow — opt-in accent, e.g. focus glow (transparent, not `none` — invalid in a comma-separated box-shadow list)" />
   </tbody>
 </table>
 
@@ -82,22 +82,24 @@ Components use `outline` rather than `border` for their decorative edge. The rea
 
 ## Component pattern
 
-Every component that renders a bordered element follows this CSS pattern:
+Every component that renders a bordered element follows this CSS pattern. The frame itself is drawn
+with an **inset `box-shadow`** (not `outline` or `border`) so it has zero layout impact while still
+letting `--bdc_color` animate smoothly via the registered `@property`. `outline` is reserved
+exclusively for the `:focus-visible` ring:
 
 ```css
 .element {
   /* Suppress any browser default border — consumer can re-enable
      via the --component_border custom property if needed. */
-  border: none;
+  border: var(--component_border, none);
 
   /* bdc defaults */
   --bdc_color: currentcolor;
 
-  /* Rendered border (zero layout impact) */
-  outline: var(--bdc-outline_width) solid var(--bdc_color);
-  outline-offset: var(--bdc-outline_offset);
-  border-radius: var(--bdc-outline_radius);
-  box-shadow: var(--bdc-outline_shadow);
+  /* Rendered border (inset box-shadow — zero layout impact) */
+  border-radius: var(--component_radius, var(--bdc-outline_radius));
+  box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color),
+              var(--component_shadow, var(--bdc-outline_shadow));
 
   /* Smooth colour transitions via registered @property */
   transition: --bdc_color 150ms ease-out;
@@ -107,13 +109,16 @@ Every component that renders a bordered element follows this CSS pattern:
 .element:focus              { --bdc_color: var(--bdc_color--focus); }
 .element[aria-invalid="true"] { --bdc_color: var(--bdc_color--error); }
 
-/* Keyboard accessibility ring — replaces outline on focus-visible */
+/* Keyboard accessibility ring — outline is used here only, replacing
+   the inset box-shadow visually on focus-visible */
 .element:focus-visible {
   outline: var(--bds-outline_default);
   outline-offset: var(--bds-outline_offset);
 }
 ```
 
+See `src/components/ui/Accordion/Accordion.module.css` for a shipped example of this pattern.
+
 ---
 
 ## Consumer overrides

package/src/stories/DesignSystem/Colors.mdx

@@ -119,62 +119,64 @@ These are the tokens you should use in component CSS. They adapt automatically t
 
 ## Base palette
 
-These `--bds-BASE__color--*` tokens are the primitive values. **Do not use them directly** in component CSS — always use semantic tokens so themes work correctly.
+The primitive palette, defined in the foundation's DTCG source (`tokens/color/base.dtcg.json`).
+Each swatch shows its DTCG path (`color.<hue>.<step>`) and value. In component CSS, always use
+the semantic tokens above so themes work correctly — the palette is reference documentation.
 
 ### Grey
 
 <SwatchRow>
-  <Swatch label="grey-100" token="--bds-BASE__color--grey--100" bg="var(--bds-BASE__color--grey--100)" />
-  <Swatch label="grey-200" token="--bds-BASE__color--grey--200" bg="var(--bds-BASE__color--grey--200)" />
-  <Swatch label="grey-300" token="--bds-BASE__color--grey--300" bg="var(--bds-BASE__color--grey--300)" />
-  <Swatch label="grey-400" token="--bds-BASE__color--grey--400" bg="var(--bds-BASE__color--grey--400)" />
-  <Swatch label="grey-500" token="--bds-BASE__color--grey" bg="var(--bds-BASE__color--grey)" text="white" />
-  <Swatch label="grey-600" token="--bds-BASE__color--grey--600" bg="var(--bds-BASE__color--grey--600)" text="white" />
-  <Swatch label="grey-700" token="--bds-BASE__color--grey--700" bg="var(--bds-BASE__color--grey--700)" text="white" />
-  <Swatch label="grey-800" token="--bds-BASE__color--grey--800" bg="var(--bds-BASE__color--grey--800)" text="white" />
-  <Swatch label="grey-900" token="--bds-BASE__color--grey--900" bg="var(--bds-BASE__color--grey--900)" text="white" />
+  <Swatch label="grey-100" token="color.grey.100" bg="#f3f4f6" />
+  <Swatch label="grey-200" token="color.grey.200" bg="#e5e7eb" />
+  <Swatch label="grey-300" token="color.grey.300" bg="#d1d5dc" />
+  <Swatch label="grey-400" token="color.grey.400" bg="#99a1af" />
+  <Swatch label="grey-500" token="color.grey" bg="#6a7282" text="white" />
+  <Swatch label="grey-600" token="color.grey.600" bg="#4a5565" text="white" />
+  <Swatch label="grey-700" token="color.grey.700" bg="#364153" text="white" />
+  <Swatch label="grey-800" token="color.grey.800" bg="#1e2939" text="white" />
+  <Swatch label="grey-900" token="color.grey.900" bg="#101828" text="white" />
 </SwatchRow>
 
 ### Green
 
 <SwatchRow>
-  <Swatch label="green-100" token="--bds-BASE__color--green--100" bg="var(--bds-BASE__color--green--100)" />
-  <Swatch label="green-200" token="--bds-BASE__color--green--200" bg="var(--bds-BASE__color--green--200)" />
-  <Swatch label="green-300" token="--bds-BASE__color--green--300" bg="var(--bds-BASE__color--green--300)" />
-  <Swatch label="green-400" token="--bds-BASE__color--green--400" bg="var(--bds-BASE__color--green--400)" />
-  <Swatch label="green-500" token="--bds-BASE__color--green" bg="var(--bds-BASE__color--green)" />
-  <Swatch label="green-600" token="--bds-BASE__color--green--600" bg="var(--bds-BASE__color--green--600)" />
-  <Swatch label="green-700" token="--bds-BASE__color--green--700" bg="var(--bds-BASE__color--green--700)" text="white" />
-  <Swatch label="green-800" token="--bds-BASE__color--green--800" bg="var(--bds-BASE__color--green--800)" text="white" />
-  <Swatch label="green-900" token="--bds-BASE__color--green--900" bg="var(--bds-BASE__color--green--900)" text="white" />
+  <Swatch label="green-100" token="color.green.100" bg="#dcfce7" />
+  <Swatch label="green-200" token="color.green.200" bg="#b9f8cf" />
+  <Swatch label="green-300" token="color.green.300" bg="#7bf1a8" />
+  <Swatch label="green-400" token="color.green.400" bg="#05df72" />
+  <Swatch label="green-500" token="color.green" bg="#00c950" />
+  <Swatch label="green-600" token="color.green.600" bg="#00a63e" />
+  <Swatch label="green-700" token="color.green.700" bg="#008236" text="white" />
+  <Swatch label="green-800" token="color.green.800" bg="#016630" text="white" />
+  <Swatch label="green-900" token="color.green.900" bg="#0d542b" text="white" />
 </SwatchRow>
 
 ### Blue
 
 <SwatchRow>
-  <Swatch label="blue-100" token="--bds-BASE__color--blue--100" bg="var(--bds-BASE__color--blue--100)" />
-  <Swatch label="blue-200" token="--bds-BASE__color--blue--200" bg="var(--bds-BASE__color--blue--200)" />
-  <Swatch label="blue-300" token="--bds-BASE__color--blue--300" bg="var(--bds-BASE__color--blue--300)" />
-  <Swatch label="blue-400" token="--bds-BASE__color--blue--400" bg="var(--bds-BASE__color--blue--400)" />
-  <Swatch label="blue-500" token="--bds-BASE__color--blue" bg="var(--bds-BASE__color--blue)" text="white" />
-  <Swatch label="blue-600" token="--bds-BASE__color--blue--600" bg="var(--bds-BASE__color--blue--600)" text="white" />
-  <Swatch label="blue-700" token="--bds-BASE__color--blue--700" bg="var(--bds-BASE__color--blue--700)" text="white" />
-  <Swatch label="blue-800" token="--bds-BASE__color--blue--800" bg="var(--bds-BASE__color--blue--800)" text="white" />
-  <Swatch label="blue-900" token="--bds-BASE__color--blue--900" bg="var(--bds-BASE__color--blue--900)" text="white" />
+  <Swatch label="blue-100" token="color.blue.100" bg="#dbeafe" />
+  <Swatch label="blue-200" token="color.blue.200" bg="#bedbff" />
+  <Swatch label="blue-300" token="color.blue.300" bg="#8ec5ff" />
+  <Swatch label="blue-400" token="color.blue.400" bg="#51a2ff" />
+  <Swatch label="blue-500" token="color.blue" bg="#2b7fff" text="white" />
+  <Swatch label="blue-600" token="color.blue.600" bg="#155dfc" text="white" />
+  <Swatch label="blue-700" token="color.blue.700" bg="#1447e6" text="white" />
+  <Swatch label="blue-800" token="color.blue.800" bg="#193cb8" text="white" />
+  <Swatch label="blue-900" token="color.blue.900" bg="#1c398e" text="white" />
 </SwatchRow>
 
 ### Orange
 
 <SwatchRow>
-  <Swatch label="orange-100" token="--bds-BASE__color--orange--100" bg="var(--bds-BASE__color--orange--100)" />
-  <Swatch label="orange-200" token="--bds-BASE__color--orange--200" bg="var(--bds-BASE__color--orange--200)" />
-  <Swatch label="orange-300" token="--bds-BASE__color--orange--300" bg="var(--bds-BASE__color--orange--300)" />
-  <Swatch label="orange-400" token="--bds-BASE__color--orange--400" bg="var(--bds-BASE__color--orange--400)" />
-  <Swatch label="orange-500" token="--bds-BASE__color--orange" bg="var(--bds-BASE__color--orange)" />
-  <Swatch label="orange-600" token="--bds-BASE__color--orange--600" bg="var(--bds-BASE__color--orange--600)" text="white" />
-  <Swatch label="orange-700" token="--bds-BASE__color--orange--700" bg="var(--bds-BASE__color--orange--700)" text="white" />
-  <Swatch label="orange-800" token="--bds-BASE__color--orange--800" bg="var(--bds-BASE__color--orange--800)" text="white" />
-  <Swatch label="orange-900" token="--bds-BASE__color--orange--900" bg="var(--bds-BASE__color--orange--900)" text="white" />
+  <Swatch label="orange-100" token="color.orange.100" bg="#ffedd4" />
+  <Swatch label="orange-200" token="color.orange.200" bg="#ffd6a7" />
+  <Swatch label="orange-300" token="color.orange.300" bg="#ffb86a" />
+  <Swatch label="orange-400" token="color.orange.400" bg="#ff8904" />
+  <Swatch label="orange-500" token="color.orange" bg="#ff6900" />
+  <Swatch label="orange-600" token="color.orange.600" bg="#f54900" text="white" />
+  <Swatch label="orange-700" token="color.orange.700" bg="#ca3500" text="white" />
+  <Swatch label="orange-800" token="color.orange.800" bg="#9f2d00" text="white" />
+  <Swatch label="orange-900" token="color.orange.900" bg="#7e2a0c" text="white" />
 </SwatchRow>
 
 ---
@@ -186,10 +188,10 @@ Override `--bds-color_green` and `--bds-color_interactive` to change the primary
 ```css
 @layer boostdev.tokens.override {
   :root {
-    --bds-color_green:           var(--bds-BASE__color--blue);
-    --bds-color_on-green:         var(--bds-BASE__color--white);
-    --bds-color_interactive:     var(--bds-BASE__color--blue);
-    --bds-color_on-interactive: var(--bds-BASE__color--white);
+    --bds-color_green:           var(--bds-color_blue);
+    --bds-color_on-green:        var(--bds-color_white);
+    --bds-color_interactive:     var(--bds-color_blue);
+    --bds-color_on-interactive:  var(--bds-color_white);
   }
 }
 ```

package/src/stories/DesignSystem/Overview.mdx

@@ -91,8 +91,8 @@ Override any token in your own layer to retheme:
 
 @layer boostdev.tokens.override {
   :root {
-    --bds-cta:    var(--bds-BASE__color--blue);
-    --bds-color_on-green: var(--bds-BASE__color--white);
+    --bds-cta:    var(--bds-color_blue);
+    --bds-color_on-green: var(--bds-color_white);
   }
 }
 ```
@@ -106,5 +106,6 @@ Override any token in your own layer to retheme:
 - `bds-` prefix = all foundation tokens
 - `_` separates group from name
 - `--` separates name from scale variant
-- `BASE__` prefix = primitive palette (never use directly in component CSS)
+- Primitive palette values live in the foundation's DTCG source (`tokens/**/*.dtcg.json`)
+  and are inlined into the semantic tokens at build time
 - All semantic tokens are prefixed with `bds-` (e.g. `--bds-bg`, `--bds-interactive`)

package/src/stories/Introduction.mdx

@@ -94,11 +94,11 @@ import logo from '../static/logo.svg';
     ```css
     @layer boostdev.tokens.override {
         :root {
-            --bds-cta:         var(--bds-BASE__color--orange);
-            --bds-on-cta:      var(--bds-BASE__color--white);
-            --bds-interactive: var(--bds-BASE__color--orange);
-            --bds-active:      var(--bds-BASE__color--orange);
-            --bds-on-active:   var(--bds-BASE__color--white);
+            --bds-cta:         var(--bds-color_orange);
+            --bds-on-cta:      var(--bds-color_white);
+            --bds-interactive: var(--bds-color_orange);
+            --bds-active:      var(--bds-color_orange);
+            --bds-on-active:   var(--bds-color_white);
         }
     }
     ```

package/src/web-components/globals.ts

@@ -44,9 +44,16 @@ const bdcCss = `
       --bdc_color--focus: var(--bds-color_interactive);
       --bdc_color--error: var(--bds-color_error);
 
+      /* 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-outline_width:  1px;
       --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;
     }
   }

package/src/web-components/index.ts

@@ -63,6 +63,7 @@ export { BdsGrid } from './layout/bds-grid';
 export { BdsGridItem } from './layout/bds-grid-item';
 
 // Phase 8 — complete parity with React library
+export { BdsButtonContainer } from './ui/bds-button-container';
 export { BdsButtonGroup } from './ui/bds-button-group';
 export { BdsTable } from './ui/bds-table';
 export { BdsPagination } from './ui/bds-pagination';
@@ -73,5 +74,6 @@ export type { FieldGroupVariant as BdsFieldGroupVariant } from './interaction/fo
 export { BdsFormInput } from './interaction/form/bds-form-input';
 export { BdsCarousel } from './ui/bds-carousel';
 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';

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

@@ -73,7 +73,16 @@ Or in HTML without a bundler:
 
 | Event | Bubbles | Description |
 |-------|---------|-------------|
-| `bds-accordion-item-toggle` | Yes | Fired by `<bds-accordion-item>` when the trigger is clicked; the parent accordion handles state |
+| `bds-accordion-item-toggle` | Yes | Fired by `<bds-accordion-item>` when the trigger is clicked; the closest ancestor `<bds-accordion>` handles state. Nested accordions each own only their own items — a `<bds-accordion>` never reacts to a toggle event whose item belongs to a nested accordion, and stops the event from bubbling to any accordion further up the tree once it is handled. |
+
+## CSS Custom Properties — `<bds-accordion>`
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--accordion_border` | `none` | Container border |
+| `--accordion_radius` | `var(--bdc-outline_radius)` | Container corner radius |
+| `--accordion_shadow` | `var(--bdc-outline_shadow)` | Container box-shadow tail (layered after the frame border) |
+| `--accordion_trigger-bg--hover` | `var(--bds-color_bg--subtle)` | Trigger button background on hover |
 
 ## Usage in plain HTML
 

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

@@ -56,7 +56,7 @@ Slot an SVG (or any element) into `icon-start` or `icon-end`:
 
 ### Icon-only (1:1 aspect ratio)
 
-Set the `is-icon-only` attribute to render a square button with equal `var(--bds-space_xs)` padding on both axes. Composable with any `variant`. Always pair with `aria-label` — there's no visible label text for assistive tech to read.
+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.
 
 <Canvas of={Stories.IconOnly} />
 <Canvas of={Stories.IconOnlyOutline} />
@@ -88,9 +88,9 @@ Set the `is-icon-only` attribute to render a square button with equal `var(--bds
 | `href` | string | — | Renders as `<a>` when set |
 | `target` | string | — | Forwarded to `<a>` when `href` is set |
 | `rel` | string | — | Forwarded to `<a>` when `href` is set |
-| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type. `submit`/`reset` act on the nearest light-DOM `<form>` the element participates in (via `ElementInternals` — see [Form participation](#form-participation)) |
 | `has-pulse` | boolean | `false` | Adds animated ring for CTA emphasis |
-| `is-icon-only` | boolean | `false` | 1:1 aspect ratio with equal `xs` padding on both axes. Requires `aria-label`. |
+| `is-icon-only` | boolean | `false` | 1:1 aspect ratio with equal `xxs` padding on both axes. Requires `aria-label`. |
 | `aria-label` | string | — | Accessible label (required for icon-only buttons) |
 
 ## Slots
@@ -108,6 +108,17 @@ 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` |
 
+## Form participation
+
+`<bds-button>` is form-associated via the Form-Associated Custom Elements API (`ElementInternals`). When placed inside a light-DOM `<form>` — directly or via `<slot>` — `type="submit"` calls the form's `requestSubmit()` and `type="reset"` calls its `reset()`. This works even though the button itself renders in shadow DOM, where a plain `<button type="submit">` would have no form to act on.
+
+```html
+<form>
+  <bds-button type="submit">Save</bds-button>
+  <bds-button type="reset" variant="outline">Cancel</bds-button>
+</form>
+```
+
 ## Invoker Commands API
 
 `<bds-button>` can control a `<bds-popover>` declaratively using `commandfor` and `command`:
@@ -135,4 +146,4 @@ Set the `is-icon-only` attribute to render a square button with equal `var(--bds
 - Always provide a label via slot content or `aria-label` (required for icon-only buttons)
 - `disabled` sets `aria-disabled="true"` and prevents click events
 - When rendered as `<a>`, `href` must point to a valid destination
-- `has-pulse` animation respects `prefers-reduced-motion`
+- `has-pulse` and the hover icon animation both respect `prefers-reduced-motion`

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

@@ -130,7 +130,7 @@ const meta: Meta<BdsButtonStoryArgs> = {
     },
     isIconOnly: {
       control: 'boolean',
-      description: 'Forces 1:1 aspect ratio with minimal xs padding. Composable with any `variant`. Requires `aria-label`.',
+      description: 'Forces 1:1 aspect ratio with minimal xxs padding. Composable with any `variant`. Requires `aria-label`.',
       table: { defaultValue: { summary: 'false' } },
     },
     hasPulse: {

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

@@ -31,7 +31,7 @@ Or in HTML without a bundler:
 
 ## When not to use
 
-- When multiple related sections need to be coordinated (open one, close others) — use `<bds-accordion>` instead
+- Multiple interrelated sections with complex state — use `<bds-accordion>` instead
 - For navigation menus — use a dedicated nav component
 
 ## Examples
@@ -54,7 +54,7 @@ Or in HTML without a bundler:
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `open` | boolean | `false` | Whether the panel is currently expanded |
-| `name` | string | `""` | Groups collapsibles so only one in a group is open at a time (native `<details name>` behaviour) |
+| `name` | string | `""` | Groups collapsibles so only one in a group is open at a time. Each `<bds-collapsible>` renders its own `<details>` in its own shadow root, so this is implemented by the component itself (querying same-`name` elements in `document` and closing them) rather than relying on the native `<details name>` behaviour, which is scoped per tree and can't see across shadow boundaries. |
 
 ## Slots
 
@@ -100,7 +100,7 @@ Or in HTML without a bundler:
 |----------|---------|-------------|
 | `--collapsible_bg` | `var(--bds-color_bg)` | Summary (header) background colour |
 | `--collapsible_bg--hover` | `var(--bds-color_bg--subtle)` | Summary background on hover |
-| `--collapsible_content-bg` | `var(--bds-color_bg)` | Content panel background colour |
+| `--collapsible_content-bg` | `transparent` | Content panel background colour |
 | `--collapsible_color` | `var(--bds-color_on-bg)` | Summary text colour |
 | `--collapsible_on-color` | `var(--bds-color_on-bg)` | Content text colour |
 | `--collapsible_border-color` | `var(--bds-color_bg--subtle)` | Border colour |

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsDialog.stories';
 
 # <bds-dialog>
 
-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.
+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.
 
@@ -55,6 +55,7 @@ Or in HTML without a bundler:
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `open` | boolean | `false` | Controlled open state — syncs to native `showModal()` / `close()` |
+| `aria-label` | string | — | Accessible name, forwarded to the inner shadow `<dialog>` |
 
 ## Slots
 
@@ -71,17 +72,19 @@ Or in HTML without a bundler:
 
 ## Invoker Commands API
 
-Open or close the dialog declaratively using the Invoker Commands API:
+Open or close the dialog declaratively using the Invoker Commands API. `<bds-dialog>` is a custom element (not a native `<dialog>`), so it only reacts to **custom** command values — these must be prefixed with `--` per the Invoker Commands spec:
 
 ```html
-<button commandfor="my-dialog" command="show-modal">Open</button>
-<button commandfor="my-dialog" command="close">Close</button>
+<button commandfor="my-dialog" command="--show-modal">Open</button>
+<button commandfor="my-dialog" command="--close">Close</button>
 
 <bds-dialog id="my-dialog">
   <p>Dialog content</p>
 </bds-dialog>
 ```
 
+The unprefixed `show-modal` / `close` command values are still accepted by the element's internal handler for compatibility with polyfilled or programmatic dispatch, but native browsers will not fire a `command` event for them on a custom-element target — always use `--show-modal` / `--close` in markup.
+
 The Invoker Commands API is a native browser feature. For browsers that do not support it yet, use the `open` attribute or JavaScript.
 
 ## Usage in plain HTML
@@ -102,9 +105,11 @@ The Invoker Commands API is a native browser feature. For browsers that do not s
 ## Accessibility
 
 - Renders a native `<dialog>` element with `aria-modal="true"`
-- Focus is trapped inside the dialog while open (Tab / Shift+Tab cycle)
+- Set `aria-label` on `<bds-dialog>` to give the dialog an accessible name — it is forwarded to the inner shadow `<dialog>`
+- Focus is trapped inside the dialog while open (Tab / Shift+Tab cycle), including focus that lands on the shadow-internal close button
 - Escape key closes the dialog
 - Clicking the backdrop closes the dialog
 - Focus returns to the triggering element on close
-- A visually positioned close button is provided with `aria-label="Close dialog"`
-- `document.body.overflow` is set to `hidden` while the dialog is open to prevent background scroll
+- A visually positioned close button is provided with `aria-label="Close dialog"` and a 44×44px hit area (WCAG 2.5.5), with a visible `:focus-visible` outline
+- `document.body.overflow` is set to `hidden` while the dialog is open to prevent background scroll, and is released automatically if the dialog is removed from the DOM while still open
+- Content taller than the dialog's `90svh` cap scrolls internally instead of overflowing the box

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

@@ -138,7 +138,7 @@ export const InvokerCommands: Story = {
       <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
         {React.createElement(
           'button',
-          { commandFor: dialogId, command: 'show-modal', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+          { commandFor: dialogId, command: '--show-modal', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
           'Open with Invoker Command',
         )}
         {React.createElement(
@@ -148,7 +148,7 @@ export const InvokerCommands: Story = {
             'div',
             { style: { minWidth: '260px' } },
             React.createElement('h2', { style: { margin: '0 0 0.5rem' } }, 'Invoker Commands'),
-            React.createElement('p', { style: { margin: 0 } }, 'This dialog was opened using the Invoker Commands API (commandfor + command="show-modal").'),
+            React.createElement('p', { style: { margin: 0 } }, 'This dialog was opened using the Invoker Commands API (commandfor + command="--show-modal").'),
           ),
         )}
       </div>

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

@@ -58,6 +58,7 @@ Or in HTML without a bundler:
 |-----------|------|---------|-------------|
 | `open` | boolean | `false` | Controlled open state |
 | `side` | `"left" \| "right"` | `"right"` | Which side the panel slides in from |
+| `aria-label` | string | — | Overrides the default accessible name (which is otherwise the `title` slot content, via `aria-labelledby`) |
 
 ## Slots
 
@@ -75,14 +76,15 @@ Or in HTML without a bundler:
 
 ## Invoker Commands API
 
-Open or close the drawer declaratively using the Invoker Commands API:
+Open or close the drawer declaratively using the Invoker Commands API. `<bds-drawer>` is a custom element, not a native `<dialog>`, so the browser only dispatches the `command` event for **custom** (`--`-prefixed) command values — the built-in `show-modal`/`close` values never fire on it:
 
 ```html
-<button commandfor="my-drawer" command="show-modal">Open</button>
+<button commandfor="my-drawer" command="--show-modal">Open</button>
 <bds-drawer id="my-drawer" side="right">
   <span slot="title">Settings</span>
   <p>Drawer content</p>
 </bds-drawer>
+<button commandfor="my-drawer" command="--close">Close</button>
 ```
 
 ## Usage in plain HTML
@@ -99,10 +101,11 @@ Open or close the drawer declaratively using the Invoker Commands API:
 ## Accessibility
 
 - Renders a native `<dialog>` element with `aria-modal="true"`
-- Focus is trapped inside the drawer while open (Tab / Shift+Tab cycle)
+- Accessible name: the `title` slot content is wired via `aria-labelledby` by default; set a host `aria-label` attribute to override it
+- Focus is trapped inside the drawer while open (Tab / Shift+Tab cycle), including slotted content
 - Escape key closes the drawer
-- Clicking the backdrop closes the drawer
+- Clicking the backdrop closes the drawer (detected via `event.target === dialog`, so keyboard-activated synthetic clicks on inner controls never trigger a false close)
 - Focus returns to the triggering element on close
-- A close button is provided with `aria-label="Close drawer"`
-- `document.body.overflow` is set to `hidden` while the drawer is open
+- A close button is provided with `aria-label="Close drawer"` and a 44&times;44px hit area
+- `document.body.overflow` is set to `hidden` while the drawer is open, and restored on close or if the element is disconnected while still open
 - Slide-in animation respects `prefers-reduced-motion`