@boostdev/design-system-components 2.5.1 → 2.7.0

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

@@ -35,20 +35,35 @@ Organises content into discrete panels accessible via a horizontal tab list.
 
 ## CSS variables
 
+The override surface is **layered**. Setting `--tab_color` / `--tab_border-color` on the tablist (or any ancestor) wins in every state — resting, hover, and active. Setting per-state tokens targets only that one state.
+
+### Public override tokens (win over per-state defaults)
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--tab_color`</td><td>`var(--bds-color_on-bg)`</td><td>Default tab text colour</td></tr>
-<tr><td>`--tab_border-color`</td><td>`transparent`</td><td>Default tab bottom border colour</td></tr>
-<tr><td>`--tab_color--active`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Active tab text colour</td></tr>
-<tr><td>`--tab_border-color--active`</td><td>`var(--bds-color_interactive)`</td><td>Active tab bottom border colour</td></tr>
-<tr><td>`--tab_color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Tab text colour on hover</td></tr>
+<tr><td>`--tab_color`</td><td>per state</td><td>Tab text colour. Set to theme every state at once.</td></tr>
+<tr><td>`--tab_border-color`</td><td>per state</td><td>Tab block-end border colour.</td></tr>
+</tbody>
+</table>
+
+### Per-state overrides
+
+<table>
+<thead>
+<tr><th>State</th><th>Text</th><th>Border</th></tr>
+</thead>
+<tbody>
+<tr><td>resting</td><td>(`var(--bds-color_on-bg)`)</td><td>(`transparent`)</td></tr>
+<tr><td>hover</td><td>`--tab_color--hover`</td><td>—</td></tr>
+<tr><td>active</td><td>`--tab_color--active`</td><td>`--tab_border-color--active`</td></tr>
 </tbody>
 </table>
 
+Defaults: hover/active text resolves to `--bds-color_interactive_on-bg`; active border to `--bds-color_interactive`.
+
 
 ## Accessibility
 

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

@@ -18,16 +18,19 @@
     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. */
+    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);
   }
 
   .tab.--active {
-    --tab_color:        var(--tab_color--active, var(--bds-color_interactive_on-bg));
-    --tab_border-color: var(--tab_border-color--active, 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 {
@@ -43,7 +46,7 @@
 
   @media (hover: hover) and (pointer: fine) {
     .tab:not(:disabled, .--active):hover {
-      --tab_color: var(--tab_color--hover, var(--bds-color_interactive_on-bg));
+      --tab_color--state: var(--tab_color--hover, var(--bds-color_interactive_on-bg));
     }
   }
 

package/src/index.ts

@@ -48,6 +48,8 @@ export { Checkbox } from './components/interaction/form/Checkbox';
 export { CheckboxGroup } from './components/interaction/form/CheckboxGroup';
 export type { CheckboxGroupProps } from './components/interaction/form/CheckboxGroup';
 export { Combobox } from './components/interaction/form/Combobox';
+export { FieldGroup } from './components/interaction/form/FieldGroup';
+export type { FieldGroupProps, FieldGroupVariant } from './components/interaction/form/FieldGroup';
 export type { ComboboxOption } from './components/interaction/form/Combobox';
 export { FileInput } from './components/interaction/form/FileInput';
 export { FormInput } from './components/interaction/form/FormInput';

package/src/web-components/index.ts

@@ -68,6 +68,8 @@ export { BdsTable } from './ui/bds-table';
 export { BdsPagination } from './ui/bds-pagination';
 export { BdsCheckboxGroup } from './interaction/form/bds-checkbox-group';
 export { BdsRadioGroup } from './interaction/form/bds-radio-group';
+export { BdsFieldGroup } from './interaction/form/bds-field-group';
+export type { FieldGroupVariant as BdsFieldGroupVariant } from './interaction/form/bds-field-group';
 export { BdsFormInput } from './interaction/form/bds-form-input';
 export { BdsCarousel } from './ui/bds-carousel';
 export { BdsCalendar } from './ui/bds-calendar';

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

@@ -65,14 +65,20 @@ export class BdsButton extends LitElement {
       white-space: nowrap;
       line-height: 1;
 
+      /* Identity tokens — override --button_color + --button_on-color to re-theme */
       --button_color:        var(--bds-color_interactive);
       --button_on-color:     var(--bds-color_on-interactive);
+
+      /* Text-safe variant of --button_color for use on page background (outline text/border) */
       --button_color--on-bg: var(--bds-color_interactive_on-bg);
 
-      background-color: var(--button_bg, var(--button_color));
-      color: var(--button_text, var(--button_on-color));
-      border: var(--button_border, none);
-      --bdc_color: transparent;
+      /* Layered cascade: the consumer-facing overrides (--button_bg, --button_text,
+         --button_border) are read OUTERMOST so an ancestor-set value always wins
+         over variant + hover defaults. Variants and hover write to the inner
+         --button_*--variant slot, never to the public tokens. */
+      background-color: var(--button_bg, var(--button_bg--variant, var(--button_color)));
+      color:            var(--button_text, var(--button_text--variant, var(--button_on-color)));
+      --bdc_color:      var(--button_border, var(--button_border--variant, transparent));
 
       box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
       transition: var(--bds-animation_transition),
@@ -83,12 +89,13 @@ export class BdsButton extends LitElement {
       text-decoration: none;
     }
 
-    /* Variants */
+    /* Variants — outline-resting overrides (--button_bg--outline, --button_text--outline,
+       --button_border--outline) are honored if the consumer sets them. */
     .button.outline,
     .button.ghost /* deprecated — use variant="outline" */ {
-      --button_bg:   transparent;
-      --button_text: var(--button_color--on-bg);
-      --bdc_color:   var(--button_color--on-bg);
+      --button_bg--variant:     var(--button_bg--outline, transparent);
+      --button_text--variant:   var(--button_text--outline, var(--button_color--on-bg));
+      --button_border--variant: var(--button_border--outline, var(--button_color--on-bg));
     }
 
     /* Sizes */
@@ -174,18 +181,18 @@ export class BdsButton extends LitElement {
 
       /* Default hover */
       .button.default:hover {
-        --button_bg:          var(--bds-color_bg);
-        --button_text:        var(--bds-color_interactive);
-        --button_pulse-color: var(--bds-color_interactive);
-        --bdc_color:          currentcolor;
+        --button_bg--variant:     var(--button_bg--hover, var(--bds-color_bg));
+        --button_text--variant:   var(--button_text--hover, var(--bds-color_interactive));
+        --button_border--variant: var(--button_border--hover, currentcolor);
+        --button_pulse-color:     var(--button_pulse-color--hover, var(--bds-color_interactive));
       }
 
       /* Outline hover */
       .button.outline:hover,
       .button.ghost:hover {
-        --button_bg:   var(--button_color);
-        --button_text: var(--button_on-color);
-        --bdc_color:   transparent;
+        --button_bg--variant:     var(--button_bg--outline-hover, var(--button_color));
+        --button_text--variant:   var(--button_text--outline-hover, var(--button_on-color));
+        --button_border--variant: var(--button_border--outline-hover, transparent);
       }
     }
 

package/src/web-components/interaction/form/BdsFieldGroup.mdx

@@ -0,0 +1,67 @@
+import { Meta, Canvas } from '@storybook/blocks';
+import * as Stories from './BdsFieldGroup.stories';
+
+<Meta of={Stories} />
+
+# `<bds-field-group>`
+
+Framework-agnostic FieldGroup custom element. Wraps slotted fields in a `<fieldset>` with a styled `<legend>` and lays them out horizontally (with auto-collapse to vertical via CSS container query) or vertically.
+
+Mirrors the React `FieldGroup` component — same token surface, same behavior, same auto-derived collapse threshold.
+
+## Attributes
+
+| Attribute | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `variant` | `horizontal` \| `vertical` | `horizontal` | Layout direction. |
+| `legend` | string | — | Optional legend text. Falls back to `aria-label` semantics if you set that on the host directly. |
+| `disabled` | boolean | `false` | Forwards to the inner `<fieldset>`; the UA cascades it to descendant form controls (light-DOM children projected through the slot). |
+
+## Slots
+
+- `(default)` — projected form fields (`<bds-form-input>`, `<bds-select>`, etc.). The component listens for `slotchange` and surfaces the slotted-element count via `--fieldGroup_field-count`, which the auto-derived collapse threshold reads.
+
+## Examples
+
+### Horizontal
+<Canvas of={Stories.Horizontal} />
+
+### Vertical
+<Canvas of={Stories.Vertical} />
+
+### Horizontal collapses in a narrow container
+<Canvas of={Stories.HorizontalCollapsesInNarrowContainer} />
+
+### Without a legend
+<Canvas of={Stories.WithoutLegend} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## CSS variables
+
+Same surface as the React component. All public tokens are read with foundation-default fallbacks; consumers can set them on the host (or any ancestor) to theme one or many groups without touching internal classes.
+
+### Layout
+
+| Variable | Default |
+|----------|---------|
+| `--fieldGroup_gap` | `var(--bds-space_m)` |
+| `--fieldGroup_min-field-width` | `12rem` |
+| `--fieldGroup_collapse-threshold` | `calc(N × min-field-width + (N − 1) × gap)` (computed) |
+
+### Legend
+
+| Variable | Default |
+|----------|---------|
+| `--fieldGroup_legend-color` | `var(--bds-color_on-bg)` |
+| `--fieldGroup_legend-font-size` | `var(--bds-font_size--heading-3)` |
+| `--fieldGroup_legend-font-weight` | `var(--bds-font_weight--semibold)` |
+| `--fieldGroup_legend-line-height` | `var(--bds-font_line-height--heading)` |
+| `--fieldGroup_legend-padding-block` | `var(--bds-space_xs)` |
+| `--fieldGroup_legend-gap` | `var(--bds-space_m)` |
+| `--fieldGroup_legend-border-block-end` | `1px solid var(--bds-color_bg--subtle)` |
+
+## Notes on shadow DOM
+
+The component renders its own `<fieldset>` inside the shadow root and projects fields through a `<slot>`. Because slotted elements stay in the host's light DOM, the native `fieldset[disabled]` cascade onto descendants is browser-dependent — modern browsers do propagate disabled to slotted form controls; older ones may not. If you support an older runtime and need a hard guarantee, set `disabled` on each slotted field too.

package/src/web-components/interaction/form/BdsFieldGroup.stories.tsx

@@ -0,0 +1,110 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index'; // auto-registers all custom elements
+
+function BdsFieldGroup({
+  legend,
+  variant,
+  disabled,
+  children,
+}: {
+  legend?: string;
+  variant?: 'horizontal' | 'vertical';
+  disabled?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-field-group',
+    {
+      legend: legend || undefined,
+      variant: variant || undefined,
+      disabled: disabled || undefined,
+    },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Form/FieldGroup',
+  component: BdsFieldGroup,
+  tags: ['!stable', 'experimental'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Framework-agnostic FieldGroup. Wraps slotted fields in a `<fieldset>` ' +
+          'and lays them out horizontally with a CSS container query that auto-collapses ' +
+          'to a single column when the host is too narrow to fit a complete row at minimum field width.',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'select', options: ['horizontal', 'vertical'] },
+    legend: { control: 'text' },
+    disabled: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsFieldGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const field = (name: string, label: string, type = 'text') =>
+  React.createElement('bds-form-input', { name, label, type });
+
+export const Horizontal: Story = {
+  args: { legend: 'Contact details', variant: 'horizontal' },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('first', 'First name')}
+      {field('last', 'Last name')}
+      {field('email', 'Email', 'email')}
+    </BdsFieldGroup>
+  ),
+};
+
+export const Vertical: Story = {
+  args: { legend: 'Contact details', variant: 'vertical' },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('first', 'First name')}
+      {field('last', 'Last name')}
+      {field('email', 'Email', 'email')}
+    </BdsFieldGroup>
+  ),
+};
+
+export const HorizontalCollapsesInNarrowContainer: Story = {
+  name: 'Horizontal — collapses in narrow container',
+  args: { legend: 'Same fields, narrower parent', variant: 'horizontal' },
+  render: args => (
+    <div style={{ inlineSize: '20rem', border: '1px dashed currentcolor', padding: '1rem' }}>
+      <BdsFieldGroup {...args}>
+        {field('first', 'First name')}
+        {field('last', 'Last name')}
+        {field('email', 'Email', 'email')}
+      </BdsFieldGroup>
+    </div>
+  ),
+};
+
+export const WithoutLegend: Story = {
+  args: { variant: 'horizontal' },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('q', 'Query')}
+      {field('from', 'From', 'date')}
+      {field('to', 'To', 'date')}
+    </BdsFieldGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { legend: 'Disabled section', variant: 'horizontal', disabled: true },
+  render: args => (
+    <BdsFieldGroup {...args}>
+      {field('first', 'First name')}
+      {field('last', 'Last name')}
+    </BdsFieldGroup>
+  ),
+};

package/src/web-components/interaction/form/bds-checkbox-group.ts

@@ -64,6 +64,7 @@ export class BdsCheckboxGroup extends LitElement {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
 

package/src/web-components/interaction/form/bds-field-group.spec.ts

@@ -0,0 +1,64 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsFieldGroup } from './bds-field-group';
+
+describe('bds-field-group', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-field-group')).toBe(BdsFieldGroup);
+  });
+
+  it('renders a fieldset in the shadow DOM', async () => {
+    const el = await fixture('<bds-field-group></bds-field-group>');
+    expect(el.shadowRoot!.querySelector('fieldset')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders the legend when the legend attribute is set', async () => {
+    const el = await fixture('<bds-field-group legend="Contact details"></bds-field-group>');
+    const legend = el.shadowRoot!.querySelector('legend');
+    expect(legend?.textContent?.trim()).toBe('Contact details');
+    cleanup(el);
+  });
+
+  it('omits the legend element when no legend attribute is set', async () => {
+    const el = await fixture('<bds-field-group></bds-field-group>');
+    expect(el.shadowRoot!.querySelector('legend')).toBeNull();
+    cleanup(el);
+  });
+
+  it('reflects the default horizontal variant onto the host', async () => {
+    const el = await fixture('<bds-field-group></bds-field-group>') as BdsFieldGroup;
+    expect(el.getAttribute('variant')).toBe('horizontal');
+  });
+
+  it('honors variant="vertical" on the host', async () => {
+    const el = await fixture('<bds-field-group variant="vertical"></bds-field-group>') as BdsFieldGroup;
+    expect(el.getAttribute('variant')).toBe('vertical');
+    cleanup(el);
+  });
+
+  it('forwards the disabled attribute to the inner fieldset', async () => {
+    const el = await fixture('<bds-field-group disabled></bds-field-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset') as HTMLFieldSetElement;
+    expect(fieldset.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('renders a slot for projected fields', async () => {
+    const el = await fixture(
+      '<bds-field-group><span id="a"></span><span id="b"></span></bds-field-group>',
+    );
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    expect(el.querySelectorAll('span').length).toBe(2);
+    cleanup(el);
+  });
+
+  it('exposes the slotted-element count as --fieldGroup_field-count after slotchange', async () => {
+    const el = await fixture(
+      '<bds-field-group><span></span><span></span><span></span></bds-field-group>',
+    ) as BdsFieldGroup;
+    // slotchange fires synchronously after the initial render; allow a microtask.
+    await new Promise(r => requestAnimationFrame(() => r(null)));
+    expect(el.style.getPropertyValue('--fieldGroup_field-count')).toBe('3');
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/form/bds-field-group.ts

@@ -0,0 +1,157 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+export type FieldGroupVariant = 'horizontal' | 'vertical';
+
+/**
+ * `<bds-field-group>` — framework-agnostic FieldGroup custom element.
+ *
+ * Semantically groups related form fields under a single `<fieldset>` and
+ * lays them out either horizontally (with a CSS container query that
+ * collapses to a vertical stack when the FieldGroup itself is too narrow)
+ * or vertically. Mirrors the React `FieldGroup` component.
+ *
+ * Attributes:
+ *   variant  — "horizontal" (default) | "vertical"
+ *   legend   — optional legend text rendered above the fields
+ *   disabled — boolean; forwarded to the inner <fieldset>
+ *
+ * Slots:
+ *   (default) — form fields (any element). The slotted-element count is
+ *     measured on each `slotchange` and surfaced via the
+ *     `--fieldGroup_field-count` custom property, which the auto-derived
+ *     collapse threshold reads.
+ *
+ * @example
+ * <bds-field-group variant="horizontal" legend="Contact details">
+ *   <bds-form-input label="First name" name="first"></bds-form-input>
+ *   <bds-form-input label="Last name"  name="last"></bds-form-input>
+ *   <bds-form-input label="Email"      name="email"></bds-form-input>
+ * </bds-field-group>
+ */
+export class BdsFieldGroup extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+
+      /* Establish an inline-size containment context so the @container rule
+         queries the host's own width — independent of the viewport. */
+      container-type: inline-size;
+      container-name: field-group;
+
+      /* Auto-derived collapse threshold (mirror of the React component).
+         --fieldGroup_field-count is set inline by _onSlotChange; the other
+         tokens use foundation-default fallbacks so the calc rebuilds when
+         a consumer overrides --fieldGroup_min-field-width or _gap. */
+      --fieldGroup_collapse-threshold:
+        calc(
+          var(--fieldGroup_field-count, 1)
+          * var(--fieldGroup_min-field-width, 12rem)
+          + (var(--fieldGroup_field-count, 1) - 1)
+          * var(--fieldGroup_gap, var(--bds-space_m))
+        );
+    }
+
+    fieldset {
+      border: 0;
+      margin: 0;
+      padding: 0;
+      min-inline-size: 0;
+    }
+
+    .legend {
+      inline-size: 100%;
+      padding-inline: 0;
+
+      padding-block:
+        var(--fieldGroup_legend-padding-block, var(--bds-space_xs));
+      margin-block-end:
+        var(--fieldGroup_legend-gap, var(--bds-space_m));
+      border-block-end:
+        var(--fieldGroup_legend-border-block-end, 1px solid var(--bds-color_bg--subtle));
+
+      color:
+        var(--fieldGroup_legend-color, var(--bds-color_on-bg));
+      font-family: var(--bds-font_family--body);
+      font-size:
+        var(--fieldGroup_legend-font-size, var(--bds-font_size--heading-3));
+      font-weight:
+        var(--fieldGroup_legend-font-weight, var(--bds-font_weight--semibold));
+      line-height:
+        var(--fieldGroup_legend-line-height, var(--bds-font_line-height--heading));
+    }
+
+    .fields {
+      display: flex;
+      flex-direction: column;
+      gap: var(--fieldGroup_gap, var(--bds-space_m));
+    }
+
+    :host([variant='horizontal']) .fields {
+      flex-flow: row wrap;
+    }
+
+    :host([variant='horizontal']) .fields ::slotted(*) {
+      flex: 1 1 var(--fieldGroup_min-field-width, 12rem);
+      min-inline-size: 0;
+    }
+
+    /* Auto-collapse: when the host's inline-size can't fit a complete
+       horizontal row, switch to a single-column stack. Threshold scales
+       with the actual slotted-element count (see :host calc above). */
+    @container field-group (max-inline-size: var(--fieldGroup_collapse-threshold)) {
+      :host([variant='horizontal']) .fields {
+        flex-direction: column;
+      }
+
+      :host([variant='horizontal']) .fields ::slotted(*) {
+        flex: 1 1 auto;
+      }
+    }
+  `;
+
+  static properties = {
+    variant:  { type: String, reflect: true },
+    legend:   { type: String },
+    disabled: { type: Boolean, reflect: true },
+  };
+
+  declare variant: FieldGroupVariant;
+  declare legend: string;
+  declare disabled: boolean;
+
+  constructor() {
+    super();
+    this.variant = 'horizontal';
+    this.legend = '';
+    this.disabled = false;
+  }
+
+  // Arrow-bound for stable identity (unused here but matches the
+  // bds-popover / bds-button conventions for handlers attached in render).
+  private _onSlotChange = (e: Event) => {
+    const slot = e.target as HTMLSlotElement;
+    const count = slot.assignedElements().length;
+    this.style.setProperty('--fieldGroup_field-count', String(count));
+  };
+
+  render() {
+    return html`
+      <fieldset ?disabled=${this.disabled}>
+        ${this.legend
+          ? html`<legend class="legend">${this.legend}</legend>`
+          : nothing}
+        <div class="fields">
+          <slot @slotchange=${this._onSlotChange}></slot>
+        </div>
+      </fieldset>
+    `;
+  }
+}
+
+customElements.define('bds-field-group', BdsFieldGroup);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-field-group': BdsFieldGroup;
+  }
+}

package/src/web-components/interaction/form/bds-form-input.ts

@@ -138,6 +138,7 @@ export class BdsFormInput extends LitElement {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
 

package/src/web-components/interaction/form/bds-radio-group.ts

@@ -66,6 +66,7 @@ export class BdsRadioGroup extends LitElement {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
 

package/src/web-components/ui/bds-alert.ts

@@ -41,36 +41,40 @@ export class BdsAlert extends LitElement {
       gap: var(--bds-space_s);
       padding: var(--bds-space_m);
       border-radius: var(--bds-border_radius--s);
-      border-inline-start: var(--bds-space_s) solid var(--alert_border, var(--bds-color_blue));
-      background-color: var(--alert_bg, var(--bds-color_blue--subtle));
-      color: var(--alert_text, var(--bds-color_on-blue--subtle));
+      /* Layered cascade: public overrides (--alert_bg, --alert_text, --alert_border)
+         are read OUTERMOST so an ancestor-set value always wins over variant
+         defaults. Variants write to the inner --alert_*--variant slot. */
+      background-color:    var(--alert_bg, var(--alert_bg--variant, var(--bds-color_blue--subtle)));
+      color:               var(--alert_text, var(--alert_text--variant, var(--bds-color_on-blue--subtle)));
+      border-inline-start: var(--bds-space_s) solid var(--alert_border, var(--alert_border--variant, var(--bds-color_blue)));
       font-size: var(--bds-font_size--body);
       line-height: var(--bds-font_line-height--body);
     }
 
-    /* Variant colours */
+    /* Per-variant resting overrides — consumers can theme per-variant via
+       --alert_bg--info / --alert_bg--success / ... */
     :host([variant='info']) .alert {
-      --alert_bg:     var(--bds-color_blue--subtle);
-      --alert_text:   var(--bds-color_on-blue--subtle);
-      --alert_border: var(--bds-color_blue);
+      --alert_bg--variant:     var(--alert_bg--info, var(--bds-color_blue--subtle));
+      --alert_text--variant:   var(--alert_text--info, var(--bds-color_on-blue--subtle));
+      --alert_border--variant: var(--alert_border--info, var(--bds-color_blue));
     }
 
     :host([variant='success']) .alert {
-      --alert_bg:     var(--bds-color_success--subtle);
-      --alert_text:   var(--bds-color_on-success--subtle);
-      --alert_border: var(--bds-color_success);
+      --alert_bg--variant:     var(--alert_bg--success, var(--bds-color_success--subtle));
+      --alert_text--variant:   var(--alert_text--success, var(--bds-color_on-success--subtle));
+      --alert_border--variant: var(--alert_border--success, var(--bds-color_success));
     }
 
     :host([variant='warning']) .alert {
-      --alert_bg:     var(--bds-color_orange--subtle);
-      --alert_text:   var(--bds-color_on-orange--subtle);
-      --alert_border: var(--bds-color_warning);
+      --alert_bg--variant:     var(--alert_bg--warning, var(--bds-color_orange--subtle));
+      --alert_text--variant:   var(--alert_text--warning, var(--bds-color_on-orange--subtle));
+      --alert_border--variant: var(--alert_border--warning, var(--bds-color_warning));
     }
 
     :host([variant='error']) .alert {
-      --alert_bg:     rgb(from var(--bds-color_error) r g b / 12%);
-      --alert_text:   var(--bds-color_on-bg);
-      --alert_border: var(--bds-color_error);
+      --alert_bg--variant:     var(--alert_bg--error, rgb(from var(--bds-color_error) r g b / 12%));
+      --alert_text--variant:   var(--alert_text--error, var(--bds-color_on-bg));
+      --alert_border--variant: var(--alert_border--error, var(--bds-color_error));
     }
 
     /* Icon slot wrapper — hidden unless slot has content */