@boostdev/design-system-components 2.15.0 → 2.17.0

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

@@ -1,5 +1,6 @@
 import { LitElement, css, html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
 
 /**
  * `<bds-form-input>` — form-associated text input with label, hint, and error support.
@@ -83,6 +84,7 @@ export class BdsFormInput extends LitElement {
 
     :host([error]) .wrapper {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     .wrapper:focus-within {
@@ -91,6 +93,7 @@ export class BdsFormInput extends LitElement {
 
     :host([error]) .wrapper:focus-within {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     .input {
@@ -140,20 +143,7 @@ export class BdsFormInput extends LitElement {
       display: none;
     }
 
-    .message {
-      margin-block-start: var(--bds-space_xxs);
-      font-size: var(--bds-font_size--body--s);
-      font-family: var(--bds-font_family--body);
-    }
-
-    .message--error {
-      color: var(--bds-color_error);
-    }
-
-    .message--hint {
-      color: var(--bds-color_on-bg--subtle);
-      font-style: italic;
-    }
+    ${fieldMessageStyles}
   `;
 
   static properties = {
@@ -265,8 +255,8 @@ export class BdsFormInput extends LitElement {
         />
         <span class="suffix"><slot name="suffix"></slot></span>
       </div>
-      ${this.error ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>` : ''}
-      ${this.hint ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>` : ''}
+      ${this.error ? renderFieldMessage('error', errorId, this.error) : ''}
+      ${this.hint ? renderFieldMessage('hint', hintId, this.hint) : ''}
     `;
   }
 }

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

@@ -1,4 +1,5 @@
 import { LitElement, css, html } from 'lit';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
 
 /**
  * `<bds-number-input>` — form-associated Number Input with stepper buttons.
@@ -72,6 +73,7 @@ export class BdsNumberInput extends LitElement {
 
     :host([error]) .row {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     .row:focus-within {
@@ -80,6 +82,7 @@ export class BdsNumberInput extends LitElement {
 
     :host([error]) .row:focus-within {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     .row:focus-within:has(:focus-visible) {
@@ -154,20 +157,7 @@ export class BdsNumberInput extends LitElement {
       color: var(--numberInput_stepper-color, var(--bds-color_interactive));
     }
 
-    .message {
-      margin-block-start: var(--bds-space_xxs);
-      font-size: var(--bds-font_size--body--s);
-      font-family: var(--bds-font_family--body);
-    }
-
-    .message--error {
-      color: var(--bds-color_error);
-    }
-
-    .message--hint {
-      color: var(--bds-color_on-bg--subtle);
-      font-style: italic;
-    }
+    ${fieldMessageStyles}
   `;
 
   static properties = {
@@ -292,9 +282,9 @@ export class BdsNumberInput extends LitElement {
         </button>
       </div>
       ${this.error
-        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        ? renderFieldMessage('error', errorId, this.error)
         : this.hint
-          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          ? renderFieldMessage('hint', hintId, this.hint)
           : ''}
     `;
   }

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

@@ -112,8 +112,37 @@ describe('bds-radio-group', () => {
   });
 
   it('uses medium font-weight token for the legend (not semibold)', () => {
-    const styles = BdsRadioGroup.styles.toString();
-    expect(styles).toContain('--bds-font_weight--medium');
-    expect(styles).not.toContain('--bds-font_weight--semibold');
+    const legendRule = BdsRadioGroup.styles.toString().match(/\.legend \{[^}]*\}/)?.[0] ?? '';
+    expect(legendRule).toContain('--bds-font_weight--medium');
+    expect(legendRule).not.toContain('--bds-font_weight--semibold');
+  });
+
+  it('shows the error icon in the message', async () => {
+    const el = await fixture('<bds-radio-group label="Test" error="Required field"></bds-radio-group>');
+    const message = el.shadowRoot!.querySelector('.message--error')!;
+    expect(message.querySelector('svg')?.getAttribute('aria-hidden')).toBe('true');
+    expect(message.textContent).toContain('Required field');
+    cleanup(el);
+  });
+
+  it('propagates error to slotted bds-radio elements', async () => {
+    const el = await fixture(
+      '<bds-radio-group label="Test" error="Required field"><bds-radio value="a">A</bds-radio><bds-radio value="b">B</bds-radio></bds-radio-group>',
+    );
+    const children = Array.from(el.querySelectorAll('bds-radio'));
+    expect(children.every(child => child.hasAttribute('error'))).toBe(true);
+    cleanup(el);
+  });
+
+  it('removes propagated error when the group error clears, keeping an individual error', async () => {
+    const el = await fixture(
+      '<bds-radio-group label="Test" error="Required field"><bds-radio value="a">A</bds-radio><bds-radio value="b" error>B</bds-radio></bds-radio-group>',
+    ) as BdsRadioGroup;
+    el.error = undefined;
+    await el.updateComplete;
+    const [first, second] = Array.from(el.querySelectorAll('bds-radio'));
+    expect(first.hasAttribute('error')).toBe(false);
+    expect(second.hasAttribute('error')).toBe(true);
+    cleanup(el);
   });
 });

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

@@ -1,4 +1,5 @@
 import { LitElement, css, html, nothing } from 'lit';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
 
 /**
  * `<bds-radio-group>` — groups related radio buttons with a shared label and name.
@@ -67,19 +68,10 @@ export class BdsRadioGroup extends LitElement {
       gap: var(--bds-space_xs);
     }
 
+    ${fieldMessageStyles}
+
     .message {
       margin-block-start: var(--bds-space_xs);
-      font-size: var(--bds-font_size--body--s);
-      font-family: var(--bds-font_family--body);
-    }
-
-    .message--error {
-      color: var(--bds-color_error);
-    }
-
-    .message--hint {
-      color: var(--bds-color_on-bg--subtle);
-      font-style: italic;
     }
   `;
 
@@ -136,9 +128,29 @@ export class BdsRadioGroup extends LitElement {
     });
   };
 
+  /**
+   * Propagates the group's `error` to slotted `<bds-radio>` elements so they show
+   * the error ring. A radio individually marked `error` in markup keeps it.
+   */
+  private _propagateError = () => {
+    this.querySelectorAll('bds-radio').forEach(radio => {
+      const el = radio as HTMLElement;
+      if (this.error) {
+        if (!el.hasAttribute('error')) {
+          el.setAttribute('data-bds-group-error', '');
+        }
+        el.setAttribute('error', '');
+      } else if (el.hasAttribute('data-bds-group-error')) {
+        el.removeAttribute('error');
+        el.removeAttribute('data-bds-group-error');
+      }
+    });
+  };
+
   private _propagateToRadios = () => {
     this._propagateName();
     this._propagateDisabled();
+    this._propagateError();
   };
 
   connectedCallback() {
@@ -149,7 +161,7 @@ export class BdsRadioGroup extends LitElement {
 
   updated(changed: Map<string, unknown>) {
     super.updated(changed);
-    if (changed.has('name') || changed.has('disabled')) {
+    if (changed.has('name') || changed.has('disabled') || changed.has('error')) {
       this._propagateToRadios();
     }
   }
@@ -173,9 +185,9 @@ export class BdsRadioGroup extends LitElement {
           <slot @slotchange=${this._propagateToRadios}></slot>
         </div>
         ${this.error
-          ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+          ? renderFieldMessage('error', errorId, this.error)
           : this.hint
-            ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+            ? renderFieldMessage('hint', hintId, this.hint)
             : ''}
       </fieldset>
     `;

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

@@ -103,6 +103,7 @@ export class BdsRadio extends LitElement {
 
     :host([error]) .input {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     .textWrapper {

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

@@ -1,4 +1,5 @@
 import { LitElement, css, html, nothing } from 'lit';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
 
 export interface SelectOption {
   value: string;
@@ -110,22 +111,9 @@ export class BdsSelect extends LitElement {
 
     :host([error]) .select {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
-    .message {
-      margin-block-start: var(--bds-space_xxs);
-      font-size: var(--bds-font_size--body--s);
-      font-family: var(--bds-font_family--body);
-    }
-
-    .message--error {
-      color: var(--bds-color_error);
-    }
-
-    .message--hint {
-      color: var(--bds-color_on-bg--subtle);
-      font-style: italic;
-    }
 
     .chevron {
       position: absolute;
@@ -142,6 +130,8 @@ export class BdsSelect extends LitElement {
       inline-size: 100%;
       block-size: 100%;
     }
+
+    ${fieldMessageStyles}
   `;
 
   static properties = {
@@ -259,9 +249,9 @@ export class BdsSelect extends LitElement {
         </span>
       </div>
       ${this.error
-        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        ? renderFieldMessage('error', errorId, this.error)
         : this.hint
-          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          ? renderFieldMessage('hint', hintId, this.hint)
           : ''}
     `;
   }

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

@@ -1,4 +1,5 @@
 import { LitElement, css, html } from 'lit';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
 
 /**
  * `<bds-slider>` — form-associated Slider / Range Input custom element.
@@ -147,20 +148,6 @@ export class BdsSlider extends LitElement {
       border-radius: var(--slider_track-radius, var(--bds-border_radius--full));
     }
 
-    .message {
-      margin-block-start: var(--bds-space_xxs);
-      font-size: var(--bds-font_size--body--s);
-      font-family: var(--bds-font_family--body);
-    }
-
-    .message--error {
-      color: var(--bds-color_error);
-    }
-
-    .message--hint {
-      color: var(--bds-color_on-bg--subtle);
-      font-style: italic;
-    }
 
     @media (prefers-reduced-motion: reduce) {
       .input,
@@ -169,6 +156,8 @@ export class BdsSlider extends LitElement {
         transition: none;
       }
     }
+
+    ${fieldMessageStyles}
   `;
 
   static properties = {
@@ -293,9 +282,9 @@ export class BdsSlider extends LitElement {
         />
       </div>
       ${this.error
-        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        ? renderFieldMessage('error', errorId, this.error)
         : this.hint
-          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          ? renderFieldMessage('hint', hintId, this.hint)
           : ''}
     `;
   }

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

@@ -142,6 +142,7 @@ export class BdsSwitch extends LitElement {
        switch still shows the active colour even when it also has an error. */
     :host([error]) .track {
       --bdc_color: var(--switch_border-color--error, var(--bds-color_error));
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     .input:checked + .track {

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

@@ -1,4 +1,5 @@
 import { LitElement, css, html } from 'lit';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
 
 /**
  * `<bds-textarea>` — form-associated Textarea custom element.
@@ -99,26 +100,15 @@ export class BdsTextarea extends LitElement {
 
     :host([error]) .textarea {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
     :host([error]) .textarea:focus {
       --bdc_color: var(--bdc_color--error);
+      --bdc-outline_width: var(--bdc-outline_width--error, 2px);
     }
 
-    .message {
-      margin-block-start: var(--bds-space_xxs);
-      font-size: var(--bds-font_size--body--s);
-      font-family: var(--bds-font_family--body);
-    }
-
-    .message--error {
-      color: var(--bds-color_error);
-    }
-
-    .message--hint {
-      color: var(--bds-color_on-bg--subtle);
-      font-style: italic;
-    }
+    ${fieldMessageStyles}
   `;
 
   static properties = {
@@ -225,9 +215,9 @@ export class BdsTextarea extends LitElement {
         @change=${this._handleChange}
       ></textarea>
       ${this.error
-        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        ? renderFieldMessage('error', errorId, this.error)
         : this.hint
-          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          ? renderFieldMessage('hint', hintId, this.hint)
           : ''}
     `;
   }

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

@@ -0,0 +1,62 @@
+import { render } from 'lit';
+import { fieldMessageStyles, renderFieldMessage } from './field-message';
+import { BdsFormInput } from './bds-form-input';
+import { BdsTextarea } from './bds-textarea';
+import { BdsSelect } from './bds-select';
+import { BdsCombobox } from './bds-combobox';
+import { BdsNumberInput } from './bds-number-input';
+import { BdsCheckbox } from './bds-checkbox';
+import { BdsRadio } from './bds-radio';
+import { BdsSwitch } from './bds-switch';
+
+const renderInto = (template: ReturnType<typeof renderFieldMessage>): HTMLElement => {
+  const host = document.createElement('div');
+  render(template, host);
+  return host;
+};
+
+describe('field-message', () => {
+  it('renders the error with role alert, the id and an aria-hidden icon', () => {
+    const host = renderInto(renderFieldMessage('error', 'err-1', 'Invalid email'));
+    const message = host.querySelector('p')!;
+    expect(message.id).toBe('err-1');
+    expect(message.getAttribute('role')).toBe('alert');
+    expect(message.classList.contains('message--error')).toBe(true);
+    expect(message.querySelector('svg')?.getAttribute('aria-hidden')).toBe('true');
+    expect(message.textContent).toContain('Invalid email');
+  });
+
+  it('renders the hint without role and without icon', () => {
+    const host = renderInto(renderFieldMessage('hint', 'hint-1', 'We never share it'));
+    const message = host.querySelector('p')!;
+    expect(message.id).toBe('hint-1');
+    expect(message.hasAttribute('role')).toBe(false);
+    expect(message.querySelector('svg')).toBeNull();
+  });
+
+  it('reads every message look from a --formMessage_* hook', () => {
+    const css = fieldMessageStyles.toString();
+    [
+      '--formMessage_gap',
+      '--formMessage_color--error',
+      '--formMessage_font-weight--error',
+      '--formMessage_icon-size',
+      '--formMessage_color--hint',
+      '--formMessage_font-style--hint',
+      '--formMessage_font-size',
+    ].forEach(hook => expect(css).toContain(hook));
+  });
+
+  it.each([
+    ['bds-form-input', BdsFormInput],
+    ['bds-textarea', BdsTextarea],
+    ['bds-select', BdsSelect],
+    ['bds-combobox', BdsCombobox],
+    ['bds-number-input', BdsNumberInput],
+    ['bds-checkbox', BdsCheckbox],
+    ['bds-radio', BdsRadio],
+    ['bds-switch', BdsSwitch],
+  ])('%s widens the outline in the error state', (_tag, ctor) => {
+    expect(ctor.styles.toString()).toContain('--bdc-outline_width: var(--bdc-outline_width--error, 2px)');
+  });
+});

package/src/web-components/interaction/form/field-message.ts

@@ -0,0 +1,55 @@
+import { css, html, svg } from 'lit';
+import type { TemplateResult } from 'lit';
+
+/**
+ * Shared look and markup for the error and hint message under a form control.
+ * Every `bds-*` form control spreads `fieldMessageStyles` into its own styles and
+ * renders its message with `renderFieldMessage()`, so the controls cannot drift.
+ *
+ * Hooks: --formMessage_gap, --formMessage_color--error, --formMessage_font-weight--error,
+ * --formMessage_icon-size, --formMessage_color--hint, --formMessage_font-style--hint,
+ * --formMessage_font-size.
+ */
+export const fieldMessageStyles = css`
+  .message {
+    margin-block-start: var(--bds-space_xxs);
+    font-size: var(--formMessage_font-size, var(--bds-font_size--body--s));
+    font-family: var(--bds-font_family--body);
+  }
+
+  .message--error {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--formMessage_gap, var(--bds-space_xxs));
+    color: var(--formMessage_color--error, var(--bds-color_error_on-bg));
+    font-weight: var(--formMessage_font-weight--error, var(--bds-font_weight--semibold));
+  }
+
+  .message__icon {
+    flex-shrink: 0;
+    inline-size: var(--formMessage_icon-size, 1.15em);
+    block-size: var(--formMessage_icon-size, 1.15em);
+  }
+
+  .message--hint {
+    color: var(--formMessage_color--hint, inherit);
+    font-style: var(--formMessage_font-style--hint, italic);
+  }
+`;
+
+// Phosphor "warning-circle" (fill)
+const warningIcon = svg`<svg class="message__icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm-8,56a8,8,0,0,1,16,0v56a8,8,0,0,1-16,0Zm8,104a12,12,0,1,1,12-12A12,12,0,0,1,128,184Z"></path></svg>`;
+
+/**
+ * Renders the message paragraph. The error variant gets `role="alert"` and a
+ * leading icon; the hint variant is plain text. `id` is the one the control
+ * references from `aria-describedby`.
+ */
+export const renderFieldMessage = (
+  kind: 'error' | 'hint',
+  id: string,
+  text: string,
+): TemplateResult =>
+  kind === 'error'
+    ? html`<p id=${id} class="message message--error" role="alert">${warningIcon}${text}</p>`
+    : html`<p id=${id} class="message message--hint">${text}</p>`;

package/src/web-components/layout/BdsGrid.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsGrid.stories';
 
 Framework-agnostic Grid layout custom element. Built on the `@boostdev/design-system-foundation` grid tokens.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/layout/BdsGrid.stories.tsx

@@ -70,7 +70,7 @@ const cellStyle = {
 const meta = {
   title: 'Web Components/Layout/Grid',
   component: BdsGrid,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     variant: { control: 'select', options: ['main', 'page', 'funnel', 'custom'] },

package/src/web-components/layout/BdsGridItem.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsGridItem.stories';
 
 Grid cell for `<bds-grid>`. Sets `grid-column` / `grid-row` on its host element using the foundation span tokens.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Examples
 

package/src/web-components/layout/BdsGridItem.stories.tsx

@@ -38,7 +38,7 @@ const cellStyle = {
 const meta = {
   title: 'Web Components/Layout/GridItem',
   component: BdsGridItem,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     columnSpan: {

package/src/web-components/ui/BdsAlert.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsAlert.stories';
 
 Framework-agnostic alert custom element for inline status messages. Supports four semantic variants, an optional heading, and a dismissible mode.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -38,6 +38,9 @@ import '@boostdev/design-system-components/web-components';
 ### Dismissible
 <Canvas of={Stories.Dismissible} />
 
+### Gradient
+<Canvas of={Stories.Gradient} />
+
 ## Props
 
 <ArgTypes of={Stories} />
@@ -47,6 +50,7 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and icon |
+| `appearance` | `"default" \| "gradient"` | `"default"` | `gradient` fades the variant tint to the surface, with a 3px accent line and a shadow |
 | `heading` | string | — | Optional heading displayed above body content |
 | `title` | string | — | **Deprecated.** Alias for `heading`, used as a fallback when `heading` is unset. Avoid: it shares its name with the global HTML `title` attribute, which makes the browser show a native tooltip on hover. Will be removed in a later major — use `heading` instead. |
 | `dismissible` | boolean | `false` | Shows a dismiss (×) button |
@@ -58,6 +62,21 @@ import '@boostdev/design-system-components/web-components';
 | `(default)` | Alert body text or content |
 | `icon` | Custom icon, placed left of the content area |
 
+## CSS Custom Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--alert_bg` / `--alert_text` / `--alert_border` | per variant | Colours for all variants. Per-variant forms: `--alert_bg--info`, `--alert_text--info`, `--alert_border--info` (and `success`, `warning`, `error`). |
+| `--alert_bg--error` / `--alert_text--error` / `--alert_border--error` | `var(--bds-color_error--subtle)` / `var(--bds-color_on-error--subtle)` / `var(--bds-color_error)` | Error variant colours, the subtle pair like the other variants |
+| `--alert_border-width` | `var(--bds-space_s)` (`3px` with `appearance="gradient"`) | Width of the inline-start accent line |
+| `--alert_gradient` | `linear-gradient(100deg, transparent 35%, var(--bds-color_bg--strong, var(--bds-color_bg)) 100%)` | Gradient over the variant background, `appearance="gradient"` only |
+| `--alert_shadow` | `var(--bds-shadow_s)` | Box shadow, `appearance="gradient"` only |
+| `--alert_accent--info` | `var(--bds-color_on-blue--subtle)` | Accent line colour with `appearance="gradient"`; `--alert_border--info` and `--alert_border` win |
+| `--alert_accent--success` | `var(--bds-color_on-success--subtle)` | Same, success |
+| `--alert_accent--warning` | `var(--bds-color_warning)` | Same, warning |
+| `--alert_accent--error` | `var(--bds-color_error)` | Same, error |
+| `--alert_dismiss-border` / `--alert_dismiss-radius` / `--alert_dismiss-opacity--hover` | | Dismiss button border, radius and hover opacity |
+
 ## Events
 
 | Event | Detail | Bubbles | Composed | Description |

package/src/web-components/ui/BdsAlert.stories.tsx

@@ -1,17 +1,19 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { AlertVariant } from './bds-alert';
+import type { AlertAppearance, AlertVariant } from './bds-alert';
 import '../index'; // auto-registers all custom elements
 
 // Thin React wrapper so Storybook controls work with the custom element's props
 function BdsAlert({
   variant = 'info',
+  appearance,
   heading,
   dismissible,
   children,
   onDismiss,
 }: {
   variant?: AlertVariant;
+  appearance?: AlertAppearance;
   heading?: string;
   dismissible?: boolean;
   children?: React.ReactNode;
@@ -19,7 +21,7 @@ function BdsAlert({
 }) {
   return React.createElement(
     'bds-alert',
-    { variant, heading, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
+    { variant, appearance, heading, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
     children,
   );
 }
@@ -27,10 +29,11 @@ function BdsAlert({
 const meta = {
   title: 'Web Components/UI/Alert',
   component: BdsAlert,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+    appearance: { control: 'select', options: ['default', 'gradient'] },
   },
 } satisfies Meta<typeof BdsAlert>;
 
@@ -58,3 +61,26 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+const gradientIcon = (path: string) =>
+  React.createElement(
+    'svg',
+    { slot: 'icon', viewBox: '0 0 24 24', width: 20, height: 20, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+    React.createElement('circle', { cx: 12, cy: 12, r: 10 }),
+    React.createElement('path', { d: path }),
+  );
+
+export const Gradient: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: 500 }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v =>
+        React.createElement(
+          'bds-alert',
+          { key: v, variant: v, appearance: 'gradient', heading: v.charAt(0).toUpperCase() + v.slice(1) },
+          gradientIcon(v === 'success' ? 'm8 12 3 3 5-6' : v === 'info' ? 'M12 16v-4M12 8h.01' : 'M12 7v6M12 16h.01'),
+          `This is a ${v} alert.`,
+        ),
+      )}
+    </div>
+  ),
+};