@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/components/ui/SkipLink/SkipLink.mdx

@@ -25,8 +25,27 @@ The link is visually hidden until focused. Press **Tab** on the preview below to
 
 ## 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
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--skip-link_z-index`</td><td>`var(--bds-z-index_xl)`</td><td>Stacking order. Defaults to the "critical overlay" tier so the focused link paints above sticky headers/navigation.</td></tr>
+<tr><td>`--skip-link_inset`</td><td>`var(--bds-space_s)`</td><td>Distance from the block-start and inline-start edges of the viewport when focused.</td></tr>
+<tr><td>`--skip-link_padding`</td><td>`var(--bds-space_xs) var(--bds-space_m)`</td><td>Inner padding of the link.</td></tr>
+<tr><td>`--skip-link_font-size`</td><td>`var(--bds-font_size--body)`</td><td>Link text size.</td></tr>
+<tr><td>`--skip-link_radius`</td><td>`var(--bds-border_radius--s)`</td><td>Corner radius.</td></tr>
+<tr><td>`--skip-link_border`</td><td>`none`</td><td>Border shorthand, in addition to the focus-colour inset frame.</td></tr>
+<tr><td>`--skip-link_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Extra shadow layered after the inset frame border (bdc formula's shadow slot).</td></tr>
+</tbody>
+</table>
+
 ## Accessibility
 
 - Renders as a standard `<a>` — no special ARIA needed

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

@@ -1,21 +1,22 @@
 @layer boostdev.component {
   .skipLink {
     position: absolute;
-    inset-block-start: var(--bds-space_s);
-    inset-inline-start: var(--bds-space_s);
-    z-index: var(--z_overlay);
-    padding: var(--bds-space_xs) var(--bds-space_m);
+    inset-block-start: var(--skip-link_inset, var(--bds-space_s));
+    inset-inline-start: var(--skip-link_inset, var(--bds-space_s));
+    z-index: var(--skip-link_z-index, var(--bds-z-index_xl));
+    padding: var(--skip-link_padding, var(--bds-space_xs) var(--bds-space_m));
     background-color: var(--bds-color_bg);
     color: var(--bds-color_on-bg);
-    font-size: var(--bds-font_size--body);
+    font-size: var(--skip-link_font-size, var(--bds-font_size--body));
     font-weight: var(--bds-font_weight--semibold);
-    border-radius: var(--bds-border_radius--s);
+    border-radius: var(--skip-link_radius, var(--bds-border_radius--s));
     text-decoration: none;
 
     --bdc_color: var(--color_focus, var(--bds-color_interactive));
 
     border: var(--skip-link_border, none);
-    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
+    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color),
+      var(--skip-link_shadow, var(--bdc-outline_shadow));
     transform: translateY(-200%);
     transition: transform var(--bds-animation_transition-duration) var(--bds-animation_easing);
   }

package/src/components/ui/SkipLink/SkipLink.spec.tsx

@@ -1,6 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { SkipLink } from './SkipLink';
 
+const cssSource = readFileSync(
+  resolve(process.cwd(), 'src/components/ui/SkipLink/SkipLink.module.css'),
+  'utf8',
+);
+
 describe('SkipLink', () => {
   it('renders a link with default text', () => {
     render(<SkipLink />);
@@ -21,4 +28,25 @@ describe('SkipLink', () => {
     render(<SkipLink href="#content" />);
     expect(screen.getByRole('link')).toHaveAttribute('href', '#content');
   });
+
+  it('resolves z-index from a real token with a fallback so the focused link rises above sticky headers', () => {
+    // jsdom has no layout engine, so the winning stacking context can't be
+    // asserted via computed style; pin the contract in the CSS source
+    // instead (same approach as NotificationBanner.spec.tsx). Previously
+    // this referenced the undefined --z_overlay token, which resolves to
+    // `auto` and defeats the skip link's entire purpose.
+    const ruleMatch = cssSource.match(/\.skipLink\s*{[^}]*}/);
+    expect(ruleMatch).not.toBeNull();
+    const rule = ruleMatch?.[0] ?? '';
+
+    expect(rule).not.toMatch(/--z_overlay/);
+    expect(rule).toMatch(/z-index:\s*var\(--skip-link_z-index,\s*var\(--bds-z-index_xl\)\)/);
+  });
+
+  it('layers a shadow slot after the bdc inset frame border', () => {
+    const ruleMatch = cssSource.match(/\.skipLink\s*{[^}]*}/);
+    const rule = ruleMatch?.[0] ?? '';
+
+    expect(rule).toMatch(/var\(--skip-link_shadow,\s*var\(--bdc-outline_shadow\)\)/);
+  });
 });

package/src/components/ui/Table/Table.mdx

@@ -28,6 +28,8 @@ Data table with optional sortable columns and caption.
 
 ## 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
@@ -40,15 +42,27 @@ Data table with optional sortable columns and caption.
 <tbody>
 <tr><td>`--table_border`</td><td>`none`</td><td>Container border</td></tr>
 <tr><td>`--table_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Container corner radius</td></tr>
+<tr><td>`--table_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Container frame shadow (appended to the inset border box-shadow)</td></tr>
+<tr><td>`--table_cell-padding`</td><td>`var(--bds-space_s) var(--bds-space_m)`</td><td>Padding shared by the caption, header cells and body cells</td></tr>
+<tr><td>`--table_font-size`</td><td>`var(--bds-font_size--body)`</td><td>Body cell font size</td></tr>
+<tr><td>`--table_header-font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Header cell / sort button font size</td></tr>
 <tr><td>`--table_sortBtn-color--hover`</td><td>`var(--bds-color_on-bg)`</td><td>Sort button text colour on hover</td></tr>
 <tr><td>`--table_row-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Table row background on hover</td></tr>
 </tbody>
 </table>
 
 
+## Notes
+
+- `rowKey?: (row: Row, index: number) => string` — derives a stable React key per row. Defaults to the row index when omitted; use this when your row objects may be structurally identical or non-serializable.
+- `TableColumn.sortLabel?: string` — accessible label used for a sortable column's sort button. Provide this when `header` is not a plain string (e.g. an icon or custom `ReactNode`) so the sort button gets a meaningful accessible name instead of falling back to its visible content.
+- `Table` extends `HTMLAttributes<HTMLDivElement>` and spreads unrecognised props onto the scrollable wrapper `<div>` (e.g. `data-testid`, `aria-label`).
+
 ## Accessibility
 
 - Wraps in `<table>` with `<thead>` and `<tbody>`
 - Column headers use `<th scope="col">`
 - Sortable columns set `aria-sort="ascending"` / `"descending"` / `"none"`
 - `caption` renders as `<caption>` — the accessible name of the table
+- The horizontally scrollable wrapper is keyboard focusable (`tabIndex={0}`, overridable via a `tabIndex` prop) and, whenever it has an accessible name — from `caption`, or a consumer-supplied `aria-label`/`aria-labelledby` — exposes `role="region"` labelled accordingly, so keyboard users can scroll it and screen reader users can identify it
+- Sort button accessible names use `col.sortLabel` when provided, otherwise `col.header` when it is a plain string; for non-string headers the button falls back to its visible text content instead of stringifying the `ReactNode`

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

@@ -7,20 +7,25 @@
     --bdc-outline_radius: var(--bds-border_radius--s);
 
     border-radius: var(--table_radius, var(--bdc-outline_radius));
-    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
+    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--table_shadow, var(--bdc-outline_shadow));
+  }
+
+  .wrapper:focus-visible {
+    outline: var(--bds-outline_default);
+    outline-offset: calc(var(--bds-outline_offset) * -1);
   }
 
   .table {
     inline-size: 100%;
     border-collapse: collapse;
-    font-size: var(--bds-font_size--body);
+    font-size: var(--table_font-size, var(--bds-font_size--body));
     font-family: var(--bds-font_family--body);
   }
 
   .caption {
     caption-side: top;
     text-align: start;
-    padding: var(--bds-space_s) var(--bds-space_m);
+    padding: var(--table_cell-padding, var(--bds-space_s) var(--bds-space_m));
     font-weight: var(--bds-font_weight--semibold);
     color: var(--bds-color_on-bg);
   }
@@ -30,10 +35,10 @@
   }
 
   .th {
-    padding: var(--bds-space_s) var(--bds-space_m);
+    padding: var(--table_cell-padding, var(--bds-space_s) var(--bds-space_m));
     text-align: start;
     font-weight: var(--bds-font_weight--semibold);
-    font-size: var(--bds-font_size--body--s);
+    font-size: var(--table_header-font-size, var(--bds-font_size--body--s));
     color: var(--bds-color_on-bg--subtle);
     white-space: nowrap;
     border-block-end: 1px solid var(--bds-color_bg--subtle);
@@ -48,12 +53,12 @@
     display: flex;
     align-items: center;
     gap: var(--bds-space_xxs);
-    padding: var(--bds-space_s) var(--bds-space_m);
+    padding: var(--table_cell-padding, var(--bds-space_s) var(--bds-space_m));
     inline-size: 100%;
     cursor: pointer;
     color: var(--bds-color_on-bg--subtle);
     font-weight: var(--bds-font_weight--semibold);
-    font-size: var(--bds-font_size--body--s);
+    font-size: var(--table_header-font-size, var(--bds-font_size--body--s));
     transition: var(--bds-animation_transition);
     box-sizing: border-box;
   }
@@ -102,7 +107,7 @@
   }
 
   .td {
-    padding: var(--bds-space_s) var(--bds-space_m);
+    padding: var(--table_cell-padding, var(--bds-space_s) var(--bds-space_m));
     color: var(--bds-color_on-bg);
     vertical-align: middle;
   }

package/src/components/ui/Table/Table.spec.tsx

@@ -66,4 +66,60 @@ describe('Table', () => {
     render(<Table columns={columns} rows={rows} sortKey="role" sortDirection="asc" onSort={() => {}} />);
     expect(screen.getByRole('columnheader', { name: /Role/i })).toHaveAttribute('aria-sort', 'ascending');
   });
+
+  it('does not stringify a ReactNode header into the sort button aria-label', () => {
+    const nodeColumns = [
+      ...columns,
+      { key: 'extra', header: <span>Extra</span>, sortable: true },
+    ];
+    render(<Table columns={nodeColumns} rows={rows} onSort={() => {}} />);
+    const extraButton = screen.getByRole('button', { name: 'Extra' });
+    expect(extraButton.hasAttribute('aria-label')).toBe(false);
+  });
+
+  it('uses sortLabel for the sort button aria-label when provided', () => {
+    const nodeColumns = [
+      ...columns,
+      { key: 'extra', header: <span>Extra</span>, sortable: true, sortLabel: 'Extra column' },
+    ];
+    render(<Table columns={nodeColumns} rows={rows} onSort={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Sort by Extra column' })).toBeInTheDocument();
+  });
+
+  it('does not warn about duplicate keys when row objects are structurally identical', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const duplicateRows = [rows[0], { ...rows[0] }];
+    render(<Table columns={columns} rows={duplicateRows} />);
+    const keyWarnings = consoleErrorSpy.mock.calls.filter(call => String(call[0]).includes('same key'));
+    expect(keyWarnings).toHaveLength(0);
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('uses rowKey to derive the row key when provided', () => {
+    const rowKey = vi.fn((row: Record<string, unknown>) => String(row.name));
+    render(<Table columns={columns} rows={rows} rowKey={rowKey} />);
+    expect(rowKey).toHaveBeenCalledWith(rows[0], 0);
+    expect(rowKey).toHaveBeenCalledWith(rows[1], 1);
+  });
+
+  it('forwards additional HTML attributes to the scrollable wrapper', () => {
+    render(<Table columns={columns} rows={rows} data-testid="my-table" />);
+    expect(screen.getByTestId('my-table')).toBeInTheDocument();
+  });
+
+  it('exposes the scroll wrapper as a focusable labelled region when a caption is set', () => {
+    render(<Table columns={columns} rows={rows} caption="Team members" />);
+    const region = screen.getByRole('region', { name: 'Team members' });
+    expect(region).toHaveAttribute('tabindex', '0');
+  });
+
+  it('does not expose an unlabelled region role when there is no caption or aria-label', () => {
+    render(<Table columns={columns} rows={rows} />);
+    expect(screen.queryByRole('region')).not.toBeInTheDocument();
+  });
+
+  it('respects a consumer-supplied aria-label over the generated caption label', () => {
+    render(<Table columns={columns} rows={rows} caption="Team members" aria-label="Custom label" />);
+    expect(screen.getByRole('region', { name: 'Custom label' })).toBeInTheDocument();
+  });
 });

package/src/components/ui/Table/Table.tsx

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { HTMLAttributes, ReactNode, useId } from 'react';
 import css from './Table.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
@@ -7,16 +7,29 @@ export interface TableColumn<Row> {
   key: string;
   header: ReactNode;
   sortable?: boolean;
+  /**
+   * Accessible label for the sort button, used instead of stringifying `header`.
+   * Required for a reliable accessible name when `header` is not plain text
+   * (e.g. an icon or custom ReactNode) — otherwise the button falls back to
+   * its visible text content.
+   */
+  sortLabel?: string;
   render?: (row: Row) => ReactNode;
 }
 
-interface TableProps<Row extends Record<string, unknown>> extends WithClassName {
+interface TableProps<Row extends Record<string, unknown>>
+  extends WithClassName,
+    HTMLAttributes<HTMLDivElement> {
   columns: TableColumn<Row>[];
   rows: Row[];
   caption?: string;
   sortKey?: string;
   sortDirection?: 'asc' | 'desc';
   onSort?: (key: string, direction: 'asc' | 'desc') => void;
+  /**
+   * Derives a stable React key per row. Defaults to the row index when omitted.
+   */
+  rowKey?: (row: Row, index: number) => string;
 }
 
 export function Table<Row extends Record<string, unknown>>({
@@ -26,8 +39,15 @@ export function Table<Row extends Record<string, unknown>>({
   sortKey,
   sortDirection,
   onSort,
+  rowKey,
   className,
+  ...rest
 }: Readonly<TableProps<Row>>) {
+  const generatedId = useId();
+  const captionId = caption ? `${generatedId}-caption` : undefined;
+  const hasCustomLabel = 'aria-label' in rest || 'aria-labelledby' in rest;
+  const hasAccessibleName = Boolean(caption) || hasCustomLabel;
+
   const handleSort = (key: string) => {
     if (!onSort) return;
     const nextDirection = sortKey === key && sortDirection === 'asc' ? 'desc' : 'asc';
@@ -39,10 +59,28 @@ export function Table<Row extends Record<string, unknown>>({
     return sortDirection === 'asc' ? 'ascending' : 'descending';
   };
 
+  const getSortAriaLabel = (col: TableColumn<Row>): string | undefined => {
+    const label = col.sortLabel ?? (typeof col.header === 'string' ? col.header : undefined);
+    if (!label) return undefined;
+    const stateSuffix =
+      sortKey === col.key ? `, currently ${sortDirection === 'asc' ? 'ascending' : 'descending'}` : '';
+    return `Sort by ${label}${stateSuffix}`;
+  };
+
   return (
-    <div className={cn(css.wrapper, className)}>
+    <div
+      {...rest}
+      className={cn(css.wrapper, className)}
+      tabIndex={rest.tabIndex ?? 0}
+      role={hasAccessibleName ? 'region' : undefined}
+      aria-labelledby={hasCustomLabel ? rest['aria-labelledby'] : captionId}
+    >
       <table className={css.table}>
-        {caption && <caption className={css.caption}>{caption}</caption>}
+        {caption && (
+          <caption id={captionId} className={css.caption}>
+            {caption}
+          </caption>
+        )}
         <thead className={css.thead}>
           <tr>
             {columns.map(col => (
@@ -57,7 +95,7 @@ export function Table<Row extends Record<string, unknown>>({
                     type="button"
                     className={css.sortButton}
                     onClick={() => handleSort(col.key)}
-                    aria-label={`Sort by ${String(col.header)}${sortKey === col.key ? `, currently ${sortDirection === 'asc' ? 'ascending' : 'descending'}` : ''}`}
+                    aria-label={getSortAriaLabel(col)}
                   >
                     {col.header}
                     <svg
@@ -84,7 +122,7 @@ export function Table<Row extends Record<string, unknown>>({
         </thead>
         <tbody className={css.tbody}>
           {rows.map((row, rowIndex) => (
-            <tr key={JSON.stringify(row) || rowIndex} className={css.tr}>
+            <tr key={rowKey?.(row, rowIndex) ?? rowIndex} className={css.tr}>
               {columns.map(col => (
                 <td key={col.key} className={css.td}>
                   {col.render ? col.render(row) : String(row[col.key] ?? '')}

package/src/components/ui/Tabs/Tabs.mdx

@@ -31,6 +31,8 @@ Organises content into discrete panels accessible via a horizontal tab list.
 
 ## 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
@@ -64,9 +66,23 @@ The override surface is **layered**. Setting `--tab_color` / `--tab_border-color
 
 Defaults: hover/active text resolves to `--bds-color_interactive_on-bg`; active border to `--bds-color_interactive`.
 
+### Spacing tokens
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--tab_padding`</td><td>`var(--bds-space_s) var(--bds-space_m)`</td><td>Padding of each tab button.</td></tr>
+<tr><td>`--tabs_gap`</td><td>`var(--bds-space_xxs)`</td><td>Gap between tab buttons in the tablist.</td></tr>
+<tr><td>`--tabs_panel-padding`</td><td>`var(--bds-space_m)`</td><td>Block-start padding of the active panel.</td></tr>
+</tbody>
+</table>
 
 ## Accessibility
 
 - Implements ARIA tabs pattern: `role="tablist"`, `role="tab"`, `role="tabpanel"`
 - Arrow keys navigate between tabs; `Enter`/`Space` activate
 - Active tab uses `aria-selected="true"`; panel linked via `aria-labelledby`
+- Tab panels are focusable (`tabIndex={0}`) so keyboard users can move from the active tab into its panel content
+- The initially active tab always resolves to an enabled tab: `defaultTab` is honoured only when it points to a non-disabled tab, otherwise the first enabled tab is used — a disabled first tab (or an invalid `defaultTab`) never leaves the tablist keyboard-unreachable

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

@@ -7,14 +7,14 @@
   .tabList {
     display: flex;
     border-block-end: 1px solid var(--bds-color_bg--subtle);
-    gap: var(--bds-space_xxs);
+    gap: var(--tabs_gap, var(--bds-space_xxs));
   }
 
   .tab {
     all: unset;
     display: inline-flex;
     align-items: center;
-    padding: var(--bds-space_s) var(--bds-space_m);
+    padding: var(--tab_padding, var(--bds-space_s) var(--bds-space_m));
     font-family: var(--bds-font_family--body);
     font-size: var(--bds-font_size--body);
     font-weight: var(--bds-font_weight--semibold);
@@ -51,7 +51,7 @@
   }
 
   .panel {
-    padding-block-start: var(--bds-space_m);
+    padding-block-start: var(--tabs_panel-padding, var(--bds-space_m));
   }
 
   .panel:focus-visible {

package/src/components/ui/Tabs/Tabs.spec.tsx

@@ -88,4 +88,24 @@ describe('Tabs', () => {
     const panelId = firstTab.getAttribute('aria-controls');
     expect(document.getElementById(panelId!)).toBeInTheDocument();
   });
+
+  it('activates the first enabled tab when the first tab is disabled and no defaultTab is given', () => {
+    const tabsWithDisabledFirst = [
+      { id: 'tab1', label: 'First', content: <p>First panel</p>, disabled: true },
+      { id: 'tab2', label: 'Second', content: <p>Second panel</p> },
+    ];
+    render(<Tabs tabs={tabsWithDisabledFirst} />);
+    expect(screen.getByRole('tab', { name: 'Second' })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('tab', { name: 'Second' })).toHaveAttribute('tabindex', '0');
+  });
+
+  it('falls back to the first enabled tab when defaultTab points to a disabled tab', () => {
+    render(<Tabs tabs={tabs} defaultTab="tab3" />);
+    expect(screen.getByRole('tab', { name: 'First' })).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('makes the active tab panel focusable', () => {
+    render(<Tabs tabs={tabs} />);
+    expect(screen.getByText('First panel').closest('[role="tabpanel"]')).toHaveAttribute('tabindex', '0');
+  });
 });

package/src/components/ui/Tabs/Tabs.tsx

@@ -17,7 +17,10 @@ interface TabsProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
 
 export function Tabs({ tabs, defaultTab, className, ...rest }: Readonly<TabsProps>) {
   const baseId = useId();
-  const [activeTab, setActiveTab] = useState(defaultTab ?? tabs[0]?.id);
+  const [activeTab, setActiveTab] = useState(() => {
+    const initialTab = tabs.find(tab => tab.id === defaultTab && !tab.disabled) ?? tabs.find(tab => !tab.disabled);
+    return initialTab?.id;
+  });
   const tabRefs = useRef<(HTMLButtonElement | null)[]>([]);
 
   const enabledIndexes = tabs
@@ -88,6 +91,7 @@ export function Tabs({ tabs, defaultTab, className, ...rest }: Readonly<TabsProp
             role="tabpanel"
             aria-labelledby={tabId}
             hidden={!isActive}
+            tabIndex={0}
             className={css.panel}
           >
             {tab.content}

package/src/components/ui/Tooltip/Tooltip.mdx

@@ -34,6 +34,8 @@ Short contextual label that appears on hover or focus. Use to supplement icon bu
 
 ## 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
@@ -46,6 +48,11 @@ Short contextual label that appears on hover or focus. Use to supplement icon bu
 <tbody>
 <tr><td>`--tooltip_bg`</td><td>`var(--bds-color_on-bg)`</td><td>Tooltip background colour</td></tr>
 <tr><td>`--tooltip_text`</td><td>`var(--bds-color_bg)`</td><td>Tooltip text colour</td></tr>
+<tr><td>`--tooltip_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Tooltip corner radius</td></tr>
+<tr><td>`--tooltip_padding`</td><td>`var(--bds-space_xxs) var(--bds-space_xs)`</td><td>Tooltip padding</td></tr>
+<tr><td>`--tooltip_font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Tooltip text size</td></tr>
+<tr><td>`--tooltip_offset`</td><td>`var(--bds-space_xs)`</td><td>Gap between the trigger and the tooltip. Set to `0` to close the gap so the pointer can travel from the trigger onto the tooltip without a dead zone.</td></tr>
+<tr><td>`--tooltip_max-inline-size`</td><td>`20rem`</td><td>Maximum inline size before content wraps</td></tr>
 </tbody>
 </table>
 
@@ -54,4 +61,6 @@ Short contextual label that appears on hover or focus. Use to supplement icon bu
 
 - Tooltip content is linked via `aria-describedby` on the trigger element
 - Shown on both `:hover` and `:focus` to be keyboard accessible
+- Dismissible with the <kbd>Escape</kbd> key while the tooltip is visible (WCAG 1.4.13)
+- Hoverable — moving the pointer from the trigger onto the tooltip itself keeps it open instead of dismissing it
 - Does not contain interactive content (use `Popover` for that)

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

@@ -6,16 +6,27 @@
   }
 
   .tooltip {
+    /* The `hidden` attribute (toggled by React state) is what makes the
+       tooltip's visibility genuinely testable and accessible - it removes
+       the element from the accessibility tree natively, matching the
+       convention used by Accordion/Tabs panels. Browsers default
+       `[hidden]` to `display: none`, which would skip the opacity
+       transition below, so it's overridden back to a normal display here;
+       showing/hiding stays driven entirely by visibility/opacity via the
+       --visible class. */
+    display: block;
     position: absolute;
     z-index: var(--bds-z-index_popover);
-    padding: var(--bds-space_xxs) var(--bds-space_xs);
+    padding: var(--tooltip_padding, var(--bds-space_xxs) var(--bds-space_xs));
     border-radius: var(--tooltip_radius, var(--bds-border_radius--full));
     background-color: var(--tooltip_bg, var(--bds-color_on-bg));
     color: var(--tooltip_text, var(--bds-color_bg));
-    font-size: var(--bds-font_size--body--s);
+    font-size: var(--tooltip_font-size, var(--bds-font_size--body--s));
     line-height: var(--bds-font_line-height--body);
-    white-space: nowrap;
+    max-inline-size: var(--tooltip_max-inline-size, 20rem);
+    white-space: normal;
     pointer-events: none;
+    --tooltip_dir: 1;
 
     /* Hidden by default */
     visibility: hidden;
@@ -23,37 +34,46 @@
     transition: opacity var(--bds-animation_transition-duration) var(--bds-animation_easing);
   }
 
-  /* Show on hover and keyboard focus */
-  .wrapper:hover .tooltip,
-  .wrapper:focus-within .tooltip {
+  [dir='rtl'] .tooltip,
+  .tooltip[dir='rtl'] {
+    --tooltip_dir: -1;
+  }
+
+  /* Shown when the component's isVisible state is true (hover, focus, or
+     keyboard-triggered) — driven by React state rather than pure CSS :hover
+     so an Escape keypress can dismiss it (WCAG 1.4.13) even while the
+     pointer is still over the trigger. pointer-events is enabled only while
+     visible so the tooltip content itself is hoverable. */
+  .--visible {
     visibility: visible;
     opacity: 1;
+    pointer-events: auto;
   }
 
   /* Placement: top (default) */
   .--placement_top {
-    inset-block-end: calc(100% + var(--bds-space_xs));
+    inset-block-end: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
     inset-inline-start: 50%;
-    transform: translateX(-50%);
+    transform: translateX(calc(-50% * var(--tooltip_dir, 1)));
   }
 
   /* Placement: bottom */
   .--placement_bottom {
-    inset-block-start: calc(100% + var(--bds-space_xs));
+    inset-block-start: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
     inset-inline-start: 50%;
-    transform: translateX(-50%);
+    transform: translateX(calc(-50% * var(--tooltip_dir, 1)));
   }
 
   /* Placement: left */
   .--placement_left {
-    inset-inline-end: calc(100% + var(--bds-space_xs));
+    inset-inline-end: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
     inset-block-start: 50%;
     transform: translateY(-50%);
   }
 
   /* Placement: right */
   .--placement_right {
-    inset-inline-start: calc(100% + var(--bds-space_xs));
+    inset-inline-start: calc(100% + var(--tooltip_offset, var(--bds-space_xs)));
     inset-block-start: 50%;
     transform: translateY(-50%);
   }

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

@@ -43,4 +43,60 @@ describe('Tooltip', () => {
     await user.tab();
     expect(screen.getByRole('tooltip')).toBeVisible();
   });
+
+  it('shows and hides the tooltip on hover', async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip content="Hover text">
+        <button type="button">Hover target</button>
+      </Tooltip>
+    );
+    const trigger = screen.getByRole('button', { name: 'Hover target' });
+    const tooltip = screen.getByRole('tooltip', { hidden: true });
+    expect(tooltip).not.toBeVisible();
+
+    await user.hover(trigger);
+    expect(tooltip).toBeVisible();
+
+    await user.unhover(trigger);
+    expect(tooltip).not.toBeVisible();
+  });
+
+  it('dismisses the tooltip when Escape is pressed while visible', async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip content="Focused">
+        <button type="button">Focus me</button>
+      </Tooltip>
+    );
+    await user.tab();
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toBeVisible();
+
+    await user.keyboard('{Escape}');
+    expect(tooltip).not.toBeVisible();
+  });
+
+  it('keeps the tooltip visible when the pointer moves onto the tooltip content, and hides it once the pointer leaves', async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip content="Hover text">
+        <button type="button">Hover target</button>
+      </Tooltip>
+    );
+    const trigger = screen.getByRole('button', { name: 'Hover target' });
+    const tooltip = screen.getByRole('tooltip', { hidden: true });
+
+    await user.hover(trigger);
+    expect(tooltip).toBeVisible();
+
+    // Moving the pointer onto the (now interactive) tooltip content must not
+    // dismiss it - this is only possible once pointer-events is enabled on
+    // the visible tooltip.
+    await user.hover(tooltip);
+    expect(tooltip).toBeVisible();
+
+    await user.unhover(tooltip);
+    expect(tooltip).not.toBeVisible();
+  });
 });