@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/web-components/interaction/bds-tab.ts

@@ -17,6 +17,16 @@ import { LitElement, css, html } from 'lit';
  */
 export class BdsTab extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: inline-flex;
     }
@@ -29,8 +39,13 @@ export class BdsTab extends LitElement {
       font-family: var(--bds-font_family--body);
       font-size: var(--bds-font_size--body);
       font-weight: var(--bds-font_weight--semibold);
-      color: var(--tab_color, var(--bds-color_on-bg));
-      border-block-end: 2px solid var(--tab_border-color, transparent);
+
+      /* Layered cascade: public overrides (--tab_color, --tab_border-color) win over
+         per-state defaults. Active/hover write to the inner --tab_*--state slot —
+         mirrors the React Tabs.module.css pattern so a consumer's --tab_color
+         override is never shadowed by the selected/hover rules below. */
+      color:            var(--tab_color, var(--tab_color--state, var(--bds-color_on-bg)));
+      border-block-end: 2px solid var(--tab_border-color, var(--tab_border-color--state, transparent));
       margin-block-end: -1px;
       cursor: pointer;
       transition: var(--bds-animation_transition);
@@ -38,8 +53,8 @@ export class BdsTab extends LitElement {
     }
 
     :host([selected]) .tab {
-      --tab_color:        var(--bds-color_interactive_on-bg);
-      --tab_border-color: var(--bds-color_interactive);
+      --tab_color--state:        var(--tab_color--active, var(--bds-color_interactive_on-bg));
+      --tab_border-color--state: var(--tab_border-color--active, var(--bds-color_interactive));
     }
 
     .tab:disabled {
@@ -55,7 +70,7 @@ export class BdsTab extends LitElement {
 
     @media (hover: hover) and (pointer: fine) {
       .tab:not(:disabled, [aria-selected='true']):hover {
-        --tab_color: var(--bds-color_interactive_on-bg);
+        --tab_color--state: var(--tab_color--hover, var(--bds-color_interactive_on-bg));
       }
     }
   `;

package/src/web-components/interaction/bds-tabs.spec.ts

@@ -36,6 +36,23 @@ describe('bds-tabs', () => {
     cleanup(el);
   });
 
+  it('does not select a disabled first tab — activates the first enabled tab instead', async () => {
+    const el = await fixture(`
+      <bds-tabs>
+        <bds-tab slot="tab" disabled>Tab 1</bds-tab>
+        <bds-tab slot="tab">Tab 2</bds-tab>
+        <bds-tab-panel slot="panel">Panel 1</bds-tab-panel>
+        <bds-tab-panel slot="panel">Panel 2</bds-tab-panel>
+      </bds-tabs>
+    `);
+    // Wait for deferred _applyState
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    expect(tabs[0].selected).toBe(false);
+    expect(tabs[1].selected).toBe(true);
+    cleanup(el);
+  });
+
   it('first panel is visible, others are hidden by default', async () => {
     const el = await fixture(html);
     await Promise.resolve();
@@ -77,9 +94,10 @@ describe('bds-tabs', () => {
   it('ArrowRight moves to next enabled tab', async () => {
     const el = await fixture(html);
     await Promise.resolve();
-    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
-    await Promise.resolve();
     const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    // Real usage: the keydown originates from the focused (currently active) tab.
+    tabs[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    await Promise.resolve();
     expect(tabs[1].selected).toBe(true);
     cleanup(el);
   });
@@ -89,7 +107,7 @@ describe('bds-tabs', () => {
     await Promise.resolve();
     const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
     tabs[2].disabled = true; // ensure disabled is set (Lit property may not reflect from HTML attribute in jsdom)
-    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }));
+    tabs[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }));
     // disabled tab is skipped; enabled tabs are 0 and 1 → wraps to last enabled (index 1)
     expect(tabs[1].selected).toBe(true);
     cleanup(el);
@@ -102,7 +120,7 @@ describe('bds-tabs', () => {
     await Promise.all(tabs.map(t => t.updateComplete));
     // Navigate to tab 1 first
     tabs[1].dispatchEvent(new CustomEvent('bds-tab-select', { bubbles: true, composed: true }));
-    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
+    tabs[1].dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
     expect(tabs[0].selected).toBe(true);
     cleanup(el);
   });
@@ -112,9 +130,78 @@ describe('bds-tabs', () => {
     await Promise.resolve();
     const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
     tabs[2].disabled = true; // ensure disabled is set
-    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
+    tabs[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
     // Last enabled tab is index 1 (tab 3 is disabled)
     expect(tabs[1].selected).toBe(true);
     cleanup(el);
   });
+
+  it('does not hijack Arrow/Home/End keys typed outside a <bds-tab> (e.g. host-level dispatch)', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    // Dispatched directly on the <bds-tabs> host — not on a <bds-tab> — must be ignored.
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    await Promise.resolve();
+    expect(tabs[0].selected).toBe(true);
+    expect(tabs[1].selected).toBe(false);
+    cleanup(el);
+  });
+
+  it('does not hijack ArrowLeft pressed inside a tab-panel input (caret movement stays with the input)', async () => {
+    const el = await fixture(`
+      <bds-tabs>
+        <bds-tab slot="tab">Tab 1</bds-tab>
+        <bds-tab slot="tab">Tab 2</bds-tab>
+        <bds-tab-panel slot="panel"><input type="text" /></bds-tab-panel>
+        <bds-tab-panel slot="panel">Panel 2</bds-tab-panel>
+      </bds-tabs>
+    `);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    const input = el.querySelector('input')!;
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }));
+    await Promise.resolve();
+    expect(tabs[0].selected).toBe(true);
+    expect(tabs[1].selected).toBe(false);
+    cleanup(el);
+  });
+
+  it('wires role/id/aria-controls on tabs and role/id/aria-labelledby on panels', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    const panels = [...el.querySelectorAll<BdsTabPanel>('bds-tab-panel')];
+
+    tabs.forEach((tab, i) => {
+      expect(tab.getAttribute('role')).toBe('tab');
+      expect(tab.id).toBeTruthy();
+      expect(tab.getAttribute('aria-controls')).toBe(panels[i].id);
+    });
+
+    panels.forEach((panel, i) => {
+      expect(panel.getAttribute('role')).toBe('tabpanel');
+      expect(panel.id).toBeTruthy();
+      expect(panel.getAttribute('aria-labelledby')).toBe(tabs[i].id);
+    });
+
+    cleanup(el);
+  });
+
+  it('preserves a consumer-supplied id instead of overwriting it', async () => {
+    const el = await fixture(`
+      <bds-tabs>
+        <bds-tab slot="tab" id="custom-tab-id">Tab 1</bds-tab>
+        <bds-tab-panel slot="panel" id="custom-panel-id">Panel 1</bds-tab-panel>
+      </bds-tabs>
+    `);
+    await Promise.resolve();
+    const tab = el.querySelector<BdsTab>('bds-tab')!;
+    const panel = el.querySelector<BdsTabPanel>('bds-tab-panel')!;
+    expect(tab.id).toBe('custom-tab-id');
+    expect(panel.id).toBe('custom-panel-id');
+    expect(tab.getAttribute('aria-controls')).toBe('custom-panel-id');
+    expect(panel.getAttribute('aria-labelledby')).toBe('custom-tab-id');
+    cleanup(el);
+  });
 });

package/src/web-components/interaction/bds-tabs.ts

@@ -26,6 +26,16 @@ import type { BdsTabPanel } from './bds-tab-panel';
  */
 export class BdsTabs extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: flex;
       flex-direction: column;
@@ -40,6 +50,7 @@ export class BdsTabs extends LitElement {
 
   private _activeIndex = 0;
   private _mo: MutationObserver | null = null;
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
 
   connectedCallback() {
     super.connectedCallback();
@@ -70,7 +81,10 @@ export class BdsTabs extends LitElement {
   private get _enabledIndexes(): number[] {
     return this._tabs
       .map((tab, i) => ({ tab, i }))
-      .filter(({ tab }) => !tab.disabled)
+      // Check the attribute too: on first render the reflected `disabled`
+      // property may not be set yet when _applyState runs, but the authored
+      // `disabled` attribute is already present.
+      .filter(({ tab }) => !tab.disabled && !tab.hasAttribute('disabled'))
       .map(({ i }) => i);
   }
 
@@ -83,8 +97,28 @@ export class BdsTabs extends LitElement {
       this._activeIndex = Math.max(0, tabs.length - 1);
     }
 
+    // A disabled tab must never be the active one. If the current active index
+    // is not an enabled tab (e.g. the default index-0 tab is <bds-tab disabled>),
+    // move selection to the first enabled tab — matching the React Tabs behaviour.
+    if (this._enabledIndexes.length && !this._enabledIndexes.includes(this._activeIndex)) {
+      this._activeIndex = this._enabledIndexes[0];
+    }
+
+    // Assign role/id/aria-* on the light-DOM host elements (not the shadow-internal
+    // button/slot) — <bds-tab> and <bds-tab-panel> share the light-DOM tree with
+    // <bds-tabs>, so id-based aria-controls/aria-labelledby references resolve.
+    // Shadow-internal ids would not be valid IDREF targets from outside their root.
     tabs.forEach((tab, i) => {
+      const panel = panels[i];
       tab.selected = (i === this._activeIndex);
+      tab.setAttribute('role', 'tab');
+      if (!tab.id) tab.id = `bds-tabs-${this._uid}-tab-${i}`;
+      if (panel) {
+        if (!panel.id) panel.id = `bds-tabs-${this._uid}-panel-${i}`;
+        tab.setAttribute('aria-controls', panel.id);
+        panel.setAttribute('role', 'tabpanel');
+        panel.setAttribute('aria-labelledby', tab.id);
+      }
     });
 
     panels.forEach((panel, i) => {
@@ -106,6 +140,13 @@ export class BdsTabs extends LitElement {
   };
 
   private _handleKeydown = (e: KeyboardEvent) => {
+    // Only handle Arrow/Home/End when the key originates from a <bds-tab> (i.e. a
+    // tab button has focus). Without this guard the host-level listener hijacked
+    // these keys anywhere in the light DOM, including tab-panel content such as
+    // text inputs, sliders, or carousels.
+    const origin = e.target as Element | null;
+    if (!origin?.closest('bds-tab')) return;
+
     const enabled = this._enabledIndexes;
     if (!enabled.length) return;
 

package/src/web-components/interaction/bds-toast-provider.spec.ts

@@ -119,4 +119,47 @@ describe('bds-toast-provider', () => {
     expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(2);
     cleanup(el);
   });
+
+  it('updated() does not throw when showPopover() reports an already-open popover (regression)', async () => {
+    // jsdom does not implement the Popover API, so showPopover/hidePopover are
+    // undefined on real elements in tests — mock them to reproduce the real-browser
+    // InvalidStateError that fires when showPopover() is called on an already-open
+    // popover (e.g. a 2nd/3rd toast joining the queue while the popover is showing).
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('First', 'info');
+    await el.updateComplete;
+    const container = el.shadowRoot!.querySelector('[popover="manual"]') as HTMLElement & {
+      showPopover?: () => void;
+    };
+    container.showPopover = vi.fn(() => {
+      throw new DOMException('Invalid state', 'InvalidStateError');
+    });
+    expect(() => (el as unknown as { updated: () => void }).updated()).not.toThrow();
+    expect(container.showPopover).toHaveBeenCalledTimes(1);
+    cleanup(el);
+  });
+
+  it('variant rules write --toast_color--variant, not the public --toast_color hook (cascade parity)', () => {
+    const cssText = BdsToastProvider.styles.cssText;
+    // Variants must only set the inner slot so a consumer-set --toast_color still
+    // wins the cascade (element-level declarations otherwise beat inherited values).
+    expect(cssText).toMatch(/\.toast\.--variant_error\s*{[^}]*--toast_color--variant:\s*var\(--toast_color--error, var\(--bds-color_error\)\)/);
+    expect(cssText).not.toMatch(/\.toast\.--variant_error\s*{[^}]*--toast_color:\s*var\(--bds-color_error\)/);
+    expect(cssText).toMatch(/background-color:\s*var\(--toast_color,\s*var\(--toast_color--variant,\s*var\(--bds-color_bg\)\)\);/);
+  });
+
+  it('close button expands its hit area to >=44px via the ::after pseudo-element (touch target)', () => {
+    const cssText = BdsToastProvider.styles.cssText;
+    expect(cssText).toMatch(/\.close::after\s*{[^}]*inset:\s*-0\.75rem;/);
+  });
+
+  it('container/toast/close use logical properties, not physical ones', () => {
+    const cssText = BdsToastProvider.styles.cssText;
+    expect(cssText).toMatch(/inset-block-end:\s*var\(--bds-space_xl,\s*2rem\);/);
+    expect(cssText).toMatch(/inset-inline-end:\s*var\(--bds-space_xl,\s*2rem\);/);
+    expect(cssText).not.toMatch(/\n\s*bottom:/);
+    expect(cssText).not.toMatch(/\n\s*right:/);
+    expect(cssText).not.toMatch(/\bwidth:\s*1\.25rem/);
+    expect(cssText).not.toMatch(/\bheight:\s*1\.25rem/);
+  });
 });

package/src/web-components/interaction/bds-toast-provider.ts

@@ -38,6 +38,16 @@ interface ToastEntry {
  */
 export class BdsToastProvider extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: contents;
     }
@@ -46,8 +56,8 @@ export class BdsToastProvider extends LitElement {
       /* Reset UA popover defaults */
       position: fixed;
       inset: unset;
-      bottom: var(--bds-space_xl, 2rem);
-      right: var(--bds-space_xl, 2rem);
+      inset-block-end: var(--bds-space_xl, 2rem);
+      inset-inline-end: var(--bds-space_xl, 2rem);
       display: flex;
       flex-direction: column;
       gap: var(--bds-space_m, 1rem);
@@ -58,34 +68,36 @@ export class BdsToastProvider extends LitElement {
 
     .toast {
       padding: var(--bds-space_m) var(--bds-space_l);
-      background-color: var(--toast_color, var(--bds-color_bg));
-      color: var(--toast_on-color, var(--bds-color_on-bg));
-      border-radius: var(--bds-border_radius--s);
-      box-shadow: var(--bds-shadow_s);
+      /* Layered cascade: public overrides (--toast_color, --toast_on-color) win
+         over per-variant defaults. Variants write to the inner --toast_*--variant slot. */
+      background-color: var(--toast_color, var(--toast_color--variant, var(--bds-color_bg)));
+      color: var(--toast_on-color, var(--toast_on-color--variant, var(--bds-color_on-bg)));
+      border-radius: var(--toast_radius, var(--bds-border_radius--s));
+      box-shadow: var(--toast_shadow, var(--bds-shadow_s));
       display: flex;
       align-items: center;
       gap: var(--bds-space_m);
-      min-width: 300px;
+      min-inline-size: min(300px, calc(100svw - 2 * var(--bds-space_xl)));
     }
 
     .toast.--variant_success {
-      --toast_color:    var(--bds-color_success);
-      --toast_on-color: var(--bds-color_on-success);
+      --toast_color--variant:    var(--toast_color--success, var(--bds-color_success));
+      --toast_on-color--variant: var(--toast_on-color--success, var(--bds-color_on-success));
     }
 
     .toast.--variant_warning {
-      --toast_color:    var(--bds-color_warning);
-      --toast_on-color: var(--bds-color_on-warning);
+      --toast_color--variant:    var(--toast_color--warning, var(--bds-color_warning));
+      --toast_on-color--variant: var(--toast_on-color--warning, var(--bds-color_on-warning));
     }
 
     .toast.--variant_info {
-      --toast_color:    var(--bds-color_bg--subtle);
-      --toast_on-color: var(--bds-color_on-bg--subtle);
+      --toast_color--variant:    var(--toast_color--info, var(--bds-color_bg--subtle));
+      --toast_on-color--variant: var(--toast_on-color--info, var(--bds-color_on-bg--subtle));
     }
 
     .toast.--variant_error {
-      --toast_color:    var(--bds-color_error);
-      --toast_on-color: var(--bds-color_on-error);
+      --toast_color--variant:    var(--toast_color--error, var(--bds-color_error));
+      --toast_on-color--variant: var(--toast_on-color--error, var(--bds-color_on-error));
     }
 
     .message {
@@ -93,22 +105,35 @@ export class BdsToastProvider extends LitElement {
     }
 
     .close {
+      position: relative;
       display: flex;
       align-items: center;
       justify-content: center;
       flex-shrink: 0;
-      width: 1.25rem;
-      height: 1.25rem;
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
       padding: 0;
       background: none;
       border: none;
       cursor: pointer;
-      color: var(--toast_on-color);
+      color: currentcolor;
+    }
+
+    /* Expands the hit area to >=44px (WCAG 2.5.5) without growing the visible icon. */
+    .close::after {
+      content: '';
+      position: absolute;
+      inset: -0.75rem;
+    }
+
+    .close:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
     }
 
     .close svg {
-      width: 1rem;
-      height: 1rem;
+      inline-size: 1rem;
+      block-size: 1rem;
     }
   `;
 
@@ -135,6 +160,10 @@ export class BdsToastProvider extends LitElement {
 
   // Sync the popover's top-layer visibility with the toast queue —
   // mirrors Toast.tsx's useEffect([toasts.length]).
+  // Both showPopover() and hidePopover() throw an InvalidStateError when called
+  // in a redundant state (e.g. showPopover() while a 2nd/3rd toast is queued and
+  // the popover is already open, or hidePopover() before any toast has shown) —
+  // catch silently in both directions.
   updated() {
     const container = this.shadowRoot?.querySelector<HTMLElement & {
       showPopover?: () => void;
@@ -142,7 +171,7 @@ export class BdsToastProvider extends LitElement {
     }>('[popover]');
     if (!container) return;
     if (this._toasts.length > 0) {
-      container.showPopover?.();
+      try { container.showPopover?.(); } catch { /* already open */ }
     } else {
       try { container.hidePopover?.(); } catch { /* already hidden on initial mount */ }
     }

package/src/web-components/interaction/bds-tooltip.spec.ts

@@ -46,4 +46,75 @@ describe('bds-tooltip', () => {
     expect(el.querySelector('button')!.textContent).toBe('Help');
     cleanup(el);
   });
+
+  it('associates the trigger with the tooltip content via aria-describedby', async () => {
+    const el = await fixture('<bds-tooltip content="Helpful text"><button type="button">?</button></bds-tooltip>');
+    // Wait for the deferred connectedCallback wiring (Promise.resolve().then(...)).
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const trigger = el.querySelector('button')!;
+    const describedById = trigger.getAttribute('aria-describedby');
+    expect(describedById).toBeTruthy();
+
+    const descEl = el.querySelector(`#${describedById}`);
+    expect(descEl).not.toBeNull();
+    expect(descEl!.textContent).toBe('Helpful text');
+    // The description node must live in the light DOM (same tree scope as the
+    // trigger) — aria-describedby cannot reference an id inside the shadow root.
+    expect(descEl!.getRootNode()).toBe(document);
+    cleanup(el);
+  });
+
+  it('keeps a consumer-provided aria-describedby alongside the generated one', async () => {
+    const el = await fixture(
+      '<bds-tooltip content="Tip"><button type="button" aria-describedby="external-hint">?</button></bds-tooltip>',
+    );
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const trigger = el.querySelector('button')!;
+    const ids = trigger.getAttribute('aria-describedby')!.split(/\s+/);
+    expect(ids).toContain('external-hint');
+    expect(ids.length).toBe(2);
+    cleanup(el);
+  });
+
+  it('updates the hidden description text when content changes', async () => {
+    const el = await fixture('<bds-tooltip content="First"><button type="button">?</button></bds-tooltip>') as BdsTooltip;
+    await Promise.resolve();
+    await Promise.resolve();
+
+    el.content = 'Second';
+    await el.updateComplete;
+
+    const trigger = el.querySelector('button')!;
+    const describedById = trigger.getAttribute('aria-describedby')!;
+    const descEl = el.querySelector(`#${describedById}`);
+    expect(descEl!.textContent).toBe('Second');
+    cleanup(el);
+  });
+
+  it('does not add aria-describedby when content is empty', async () => {
+    const el = await fixture('<bds-tooltip><button type="button">?</button></bds-tooltip>');
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const trigger = el.querySelector('button')!;
+    expect(trigger.hasAttribute('aria-describedby')).toBe(false);
+    cleanup(el);
+  });
+
+  it('hides the shadow-DOM tooltip bubble from assistive technology', async () => {
+    const el = await fixture('<bds-tooltip content="Helpful text"><button type="button">?</button></bds-tooltip>');
+    const tooltip = el.shadowRoot!.querySelector('[role="tooltip"]')!;
+    expect(tooltip.getAttribute('aria-hidden')).toBe('true');
+    cleanup(el);
+  });
+
+  it('does not hardcode a z-index fallback (token parity with React Tooltip)', () => {
+    const cssText = BdsTooltip.styles.cssText;
+    expect(cssText).toMatch(/z-index:\s*var\(--bds-z-index_popover\);/);
+    expect(cssText).not.toContain('200');
+  });
 });

package/src/web-components/interaction/bds-tooltip.ts

@@ -16,9 +16,14 @@ export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
  *   (default) — the trigger element (button, icon, etc.)
  *
  * Accessibility:
- *   The `aria-describedby` relationship between trigger and tooltip panel
- *   cannot cross shadow DOM boundaries; screen readers will announce the tooltip
- *   via role="tooltip" proximity when it becomes visible.
+ *   `aria-describedby` id references only resolve within the same tree scope, so a
+ *   slotted (light-DOM) trigger can never reference an id that lives inside this
+ *   element's shadow root. To keep the description reachable, a visually-hidden
+ *   `<span>` holding `content` is appended as a light-DOM child of the host and its
+ *   id is written into `aria-describedby` on the slotted trigger — both elements then
+ *   share the light DOM's tree scope, so the reference resolves in every browser. The
+ *   shadow-DOM tooltip bubble stays `aria-hidden="true"`; it is purely the visual
+ *   presentation, shown on `:hover`/`:focus-within`.
  *
  * @example
  * <bds-tooltip content="More information" placement="bottom">
@@ -27,6 +32,16 @@ export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
  */
 export class BdsTooltip extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: inline-flex;
       align-items: center;
@@ -35,7 +50,7 @@ export class BdsTooltip extends LitElement {
 
     .tooltip {
       position: absolute;
-      z-index: var(--bds-z-index_popover, 200);
+      z-index: var(--bds-z-index_popover);
       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));
@@ -101,18 +116,98 @@ export class BdsTooltip extends LitElement {
   declare content: string;
   declare placement: TooltipPlacement;
 
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+  /** Visually-hidden light-DOM node holding `content`, referenced by the trigger's aria-describedby. */
+  private _descEl: HTMLSpanElement | null = null;
+
   constructor() {
     super();
     this.content = '';
     this.placement = 'top';
   }
 
+  connectedCallback() {
+    super.connectedCallback();
+    // Deferred: on declarative parsing the trigger may not exist as a child yet
+    // when connectedCallback fires (upgrade happens before children are parsed).
+    Promise.resolve().then(this._syncDescription);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._teardownDescription();
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('content')) {
+      this._syncDescription();
+    }
+  }
+
+  private get _descId(): string {
+    return `bds-tooltip-desc-${this._uid}`;
+  }
+
+  /** Ensures the hidden description node exists (or is torn down) and re-wires the trigger. */
+  private _syncDescription = () => {
+    if (!this.isConnected) return;
+
+    if (!this.content) {
+      this._teardownDescription();
+      return;
+    }
+
+    let desc = this._descEl;
+    if (!desc) {
+      desc = document.createElement('span');
+      desc.id = this._descId;
+      desc.style.cssText =
+        'position:absolute;inline-size:1px;block-size:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;';
+      this.append(desc);
+      this._descEl = desc;
+    }
+
+    desc.textContent = this.content;
+    this._describeTrigger();
+  };
+
+  private _describeTrigger() {
+    const id = this._descId;
+    for (const el of Array.from(this.children)) {
+      if (el === this._descEl) continue;
+      const existing = el.getAttribute('aria-describedby');
+      const ids = existing ? existing.split(/\s+/).filter(Boolean) : [];
+      if (!ids.includes(id)) {
+        el.setAttribute('aria-describedby', [...ids, id].join(' '));
+      }
+    }
+  }
+
+  private _teardownDescription() {
+    const id = this._descId;
+    for (const el of Array.from(this.children)) {
+      if (el === this._descEl) continue;
+      const existing = el.getAttribute('aria-describedby');
+      if (!existing) continue;
+      const ids = existing.split(/\s+/).filter(part => part && part !== id);
+      if (ids.length) {
+        el.setAttribute('aria-describedby', ids.join(' '));
+      } else {
+        el.removeAttribute('aria-describedby');
+      }
+    }
+    this._descEl?.remove();
+    this._descEl = null;
+  }
+
   render() {
     return html`
-      <slot></slot>
+      <slot @slotchange=${this._syncDescription}></slot>
       <span
         class="tooltip --placement_${this.placement}"
         role="tooltip"
+        aria-hidden="true"
       >${this.content}</span>
     `;
   }