@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/button/button.stories.js

@@ -1,51 +1,67 @@
-import { html } from 'lit';
+import { html, nothing } from 'lit';
 import './button.js';
+import '../icons/close-icon.js';
+import '../icons/plus-icon.js';
 
 export default {
-  title     : 'Components/Button',
+  title     : 'Atoms/Button',
   tags      : ['autodocs'],
   parameters: {
     docs: {
       description: {
         component: `
-Three button components are available:
+Three elements, styled identically and **not** interchangeable:
 
-- \`<bd-button>\` — a standard \`<button>\` element with click/keyboard events and active state
-- \`<bd-button-link>\` — an \`<a>\` tag styled as a button, supports buy link data attributes
-- \`<bd-contact-button>\` — a specialized contact CTA with an arrow icon
+- \`<bd-button>\` — a \`<button>\`. **Performs an action in place.** Announced as
+  "button", activated by Space *and* Enter.
+- \`<bd-button-link>\` — an \`<a href>\`. **Navigates.** Announced as "link",
+  appears in a screen reader's list of links, and supports open-in-new-tab,
+  middle-click and copy-address. Enter only.
+- \`<bd-contact-button>\` — a fixed "Contact us" CTA with a trailing arrow. A
+  preset, not a variant: no size or variant axis.
+
+Pick by what the control *does*, never by how it should look. The two share a
+base class, so \`kind\`, \`size\`, the states and the focus ring are defined once.
 
 ### Usage
 \`\`\`html
-<bd-button kind="primary" size="md">Click me</bd-button>
-<bd-button kind="danger" size="md">Activez votre protection</bd-button>
-<bd-button kind="primary" size="md" shape="rounded">Rounded</bd-button>
-<bd-button-link kind="danger" size="lg" href="/buy">Buy now</bd-button-link>
+<bd-button variant="primary" size="md">Click me</bd-button>
+<bd-button-link variant="accent" size="lg" href="/buy">Buy now</bd-button-link>
 <bd-contact-button label="Contact us" href="/contact"></bd-contact-button>
 \`\`\`
 
-### Kind Values
-| Kind | Class |
+### Kind
+| Kind | Appearance | Was |
+|---|---|---|
+| \`primary\` | blue fill | \`primary\` |
+| \`secondary\` | near-black fill | \`secondary\` |
+| \`tertiary\` | blue 2px outline | \`primary-outline\` |
+| \`ghost\` | dark 2px outline | \`outline\` |
+| \`accent\` | red fill | \`danger\`, \`destructive\` |
+
+All four old values still work as deprecated aliases. Note \`ghost\` here is an
+*outlined* button, not the borderless control the name usually implies.
+
+### Red means conversion, not danger
+
+In this system red is the **conversion** colour — Buy now and equivalents — not
+a destructive signal. That is why the design file carries an \`accent\` and a
+\`destructive\` variant styled identically: they are one variant recorded twice,
+once under the wrong name. \`accent\` is the one that survives here.
+
+The consequence is worth stating plainly: **there is no danger variant.** A
+delete confirmation or a irreversible-action button has nothing to reach for,
+because the obvious colour for it already means "buy". Giving danger its own
+treatment means choosing a colour that is not the conversion red, which is a
+design decision rather than an implementation one.
+
+### State
+| State | |
 |---|---|
-| \`primary\` | \`button--primary\` |
-| \`primary-outline\` | \`button--primary--outline\` |
-| \`outline\` | \`button--outline\` |
-| \`secondary\` | \`button--secondary\` |
-| \`danger\` | \`button--danger\` + \`button--with-arrow\` |
-| \`white\` | \`button--white\` |
-| \`outline-white\` | \`button--outline-white\` |
-
-### Danger hover arrow
-Every \`kind="danger"\` button (both \`bd-button\` and \`bd-button-link\`) has an arrow hover effect by default:
-on hover (and on keyboard \`:focus-visible\`) the label slides to the left and an arrow fades in on the right.
-The button width does not change.
-
-To disable it on a specific button, add the \`no-arrow\` attribute:
-\`\`\`html
-<bd-button kind="danger" no-arrow>No arrow</bd-button>
-\`\`\`
+| \`disabled\` | Filled variants go grey; outlined ones keep a transparent fill and take a subtle border. On the link this drops the \`href\` and sets \`aria-disabled\`, since a link has no native disabled state. |
+| \`loading\` | A spinner in the variant's own colour, sized in \`em\` so it tracks the type scale, plus \`aria-busy\`. Blocks interaction and respects \`prefers-reduced-motion\`. |
 
-The effect can be tuned from outside via CSS custom properties:
-\`--button-arrow-size\`, \`--button-arrow-shift\`, \`--button-arrow-inset\`, \`--button-arrow-offset\`.
+Focus is not in the design, but 2.4.7 requires it, so the focus ring is kept.
 
 ### Size Values
 | Size | Class |
@@ -54,13 +70,27 @@ The effect can be tuned from outside via CSS custom properties:
 | \`md\` | \`button--medium\` |
 | \`lg\` | \`button--large\` |
 
-### Shape Values
-| Shape | Effect |
-|---|---|
-| \`default\` | Border radius from the size (\`--radius-md\` / \`--radius-lg\`) |
-| \`rounded\` | \`button--rounded\` — border radius \`--spacing-30\` |
+### Icon-only
+\`icon-only\` turns either element into a circle around one icon: the arrow on
+the homepage's audience cards, a menu or close toggle. It is a mode, not a
+variant, so every \`variant\`, \`size\`, \`surface\` and state applies unchanged.
+
+\`\`\`html
+<bd-button-link icon-only variant="accent" href="/home" label="Protect your digital life"></bd-button-link>
+<bd-button icon-only variant="ghost" label="Close"><bd-close-icon></bd-close-icon></bd-button>
+\`\`\`
 
-The rounded radius can be overridden via the \`--button-radius-rounded\` CSS custom property.
+- **\`label\` is required.** There is no visible text, so it is the only name
+  the control has. Name what happens, not the picture: "Open menu", not "Menu
+  icon".
+- **The icon is a slot** and defaults to \`bd-arrow-icon\`, the only true
+  shafted arrow. Whatever goes in is sized to the button's step.
+- **The diameter comes from padding**, like the labelled height: 32, 44 and 56
+  for \`sm\`, \`md\` and \`lg\`. Only \`md\` matches the labelled height (33.5,
+  44, 54.5). \`md\` and \`lg\` clear the 44px target; \`sm\` does not.
+- **\`fullwidth\` is ignored**, because a stretched circle is a pill.
+- **\`loading\` replaces the icon** with the spinner at the icon's size, so the
+  circle does not change size while busy.
 
 ### Alignment Values
 | Align | Effect |
@@ -81,12 +111,28 @@ The rounded radius can be overridden via the \`--button-radius-rounded\` CSS cus
       description: 'Accessible aria-label for the button',
       table      : { type: { summary: 'string' }, defaultValue: { summary: 'Buy now' }, category: 'Content' }
     },
-    kind: {
+    variant: {
       control    : { type: 'select' },
-      options    : ['primary', 'primary-outline', 'outline', 'secondary', 'danger', 'white', 'outline-white'],
-      description: 'Visual style variant of the button. `danger` includes the hover arrow by default.',
+      options    : ['primary', 'secondary', 'tertiary', 'ghost', 'accent'],
+      description: 'Visual variant. `tertiary` is a blue outline, `ghost` a dark outline.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: 'primary' }, category: 'Appearance' }
     },
+    disabled: {
+      control    : 'boolean',
+      description: 'Blocks interaction and greys the control. Exempt from contrast requirements under WCAG 1.4.3.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    loading: {
+      control    : 'boolean',
+      description: 'Shows a spinner in the variant colour and sets `aria-busy`.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    surface: {
+      control    : { type: 'inline-radio' },
+      options    : ['light', 'dark'],
+      description: 'The surface the button sits on. `dark` retunes every variant for a hero with a full background colour.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'light' }, category: 'Appearance' }
+    },
     size: {
       control    : { type: 'select' },
       options    : ['sm', 'md', 'lg'],
@@ -94,14 +140,19 @@ The rounded radius can be overridden via the \`--button-radius-rounded\` CSS cus
       table      : { type: { summary: "'sm' | 'md' | 'lg'" }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     },
     shape: {
-      control    : { type: 'select' },
+      control    : { type: 'inline-radio' },
       options    : ['default', 'rounded'],
-      description: 'Shape of the button. `rounded` applies `--spacing-30` border radius.',
+      description: 'Corner shape. `rounded` takes `--radius-3xl` whatever the size.',
       table      : { type: { summary: "'default' | 'rounded'" }, defaultValue: { summary: 'default' }, category: 'Appearance' }
     },
     noArrow: {
       control    : 'boolean',
-      description: '(kind="danger" only) Disables the hover arrow. Attribute: `no-arrow`',
+      description: '(accent only) Opts out of the hover arrow. Attribute: `no-arrow`',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'Appearance' }
+    },
+    iconOnly: {
+      control    : 'boolean',
+      description: 'A circle around one icon instead of a label. Slot any `bd-*-icon`; the default is the arrow. `label` becomes required, since it is the only name the control has.',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'Appearance' }
     },
     fullWidth: {
@@ -139,33 +190,30 @@ The rounded radius can be overridden via the \`--button-radius-rounded\` CSS cus
       control    : 'boolean',
       description: '(ButtonLink only) Adds `data-store-render` and `data-store-buy-link` attributes',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'ButtonLink' }
-    },
-    shadow: {
-      control    : 'boolean',
-      description: '(ButtonLink only) Reflects `shadow` attribute',
-      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'true' }, category: 'ButtonLink' }
     }
   }
 };
 
 const defaultArgs = {
   label     : 'Buy now',
-  kind      : 'primary',
+  variant   : 'primary',
   size      : 'md',
   shape     : 'default',
   noArrow   : false,
+  iconOnly  : false,
   fullWidth : false,
   strong    : false,
   align     : 'left',
   fontSize  : '',
-  fontWeight: ''
+  fontWeight: '',
+  surface   : 'light'
 };
 
 // ─── bd-button Stories ─────────────────────────────────────────────────────
 
 export const ButtonDefault = {
   name      : 'Button — Default',
-  render    : () => html`<bd-button kind="primary" size="md">Buy now</bd-button>`,
+  render    : () => html`<bd-button variant="primary" size="md">Buy now</bd-button>`,
   parameters: { docs: { description: { story: 'Default primary medium button.' } } }
 };
 
@@ -173,14 +221,14 @@ export const ButtonAllKinds = {
   name  : 'Button — All Kinds',
   render: () => html`
     <div style="display:flex; gap:12px; flex-wrap:wrap; align-items:center;">
-      <bd-button kind="primary" size="md">Primary</bd-button>
-      <bd-button kind="primary-outline" size="md">Primary Outline</bd-button>
-      <bd-button kind="outline" size="md">Outline</bd-button>
-      <bd-button kind="secondary" size="md">Secondary</bd-button>
-      <bd-button kind="danger" size="md">Danger</bd-button>
+      <bd-button variant="primary" size="md">primary</bd-button>
+      <bd-button variant="secondary" size="md">secondary</bd-button>
+      <bd-button variant="tertiary" size="md">tertiary</bd-button>
+      <bd-button variant="ghost" size="md">ghost</bd-button>
+      <bd-button variant="accent" size="md">accent</bd-button>
     </div>
   `,
-  parameters: { docs: { description: { story: 'All five `kind` variants side by side. Hover the danger button to see the arrow.' } } }
+  parameters: { docs: { description: { story: 'All five variants. There is no danger variant — see the notes above.' } } }
 };
 
 export const ButtonRounded = {
@@ -188,96 +236,141 @@ export const ButtonRounded = {
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:16px; align-items:flex-start;">
       <div style="display:flex; gap:12px; flex-wrap:wrap; align-items:center;">
-        <bd-button kind="primary" size="md" shape="rounded">Primary</bd-button>
-        <bd-button kind="primary-outline" size="md" shape="rounded">Primary Outline</bd-button>
-        <bd-button kind="outline" size="md" shape="rounded">Outline</bd-button>
-        <bd-button kind="secondary" size="md" shape="rounded">Secondary</bd-button>
-        <bd-button kind="danger" size="md" shape="rounded" strong>Danger</bd-button>
+        <bd-button variant="primary" size="md" shape="rounded">primary</bd-button>
+        <bd-button variant="secondary" size="md" shape="rounded">secondary</bd-button>
+        <bd-button variant="tertiary" size="md" shape="rounded">tertiary</bd-button>
+        <bd-button variant="ghost" size="md" shape="rounded">ghost</bd-button>
+        <bd-button variant="accent" size="md" shape="rounded">accent</bd-button>
       </div>
       <div style="display:flex; gap:12px; flex-wrap:wrap; align-items:center;">
-        <bd-button kind="primary" size="sm" shape="rounded">Small</bd-button>
-        <bd-button kind="primary" size="md" shape="rounded">Medium</bd-button>
-        <bd-button kind="primary" size="lg" shape="rounded">Large</bd-button>
+        <bd-button variant="primary" size="sm" shape="rounded">Small</bd-button>
+        <bd-button variant="primary" size="md" shape="rounded">Medium</bd-button>
+        <bd-button variant="primary" size="lg" shape="rounded">Large</bd-button>
+        <bd-button-link variant="primary" size="md" shape="rounded" href="#">Link</bd-button-link>
+        <bd-contact-button label="Contact us" href="#" shape="rounded"></bd-contact-button>
       </div>
     </div>
   `,
-  parameters: { docs: { description: { story: '`shape="rounded"` applies `--spacing-30` border radius across all kinds and sizes.' } } }
+  parameters: { docs: { description: { story: '`shape="rounded"` replaces the size band\'s corner with `--radius-3xl`, on every variant and size.' } } }
 };
 
-export const ButtonShapeComparison = {
-  name  : 'Button — Default vs Rounded',
+export const ButtonAccentArrow = {
+  name  : 'Button — Accent Hover Arrow',
   render: () => html`
     <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
-      <bd-button kind="primary" size="md">Default</bd-button>
-      <bd-button kind="primary" size="md" shape="rounded">Rounded</bd-button>
+      <bd-button variant="accent" size="sm" strong>Small</bd-button>
+      <bd-button variant="accent" size="md" strong>Activate protection</bd-button>
+      <bd-button variant="accent" size="lg" strong>Large</bd-button>
+      <bd-button-link variant="accent" size="md" strong href="#">Buy now</bd-button-link>
+      <bd-button variant="accent" size="md" strong no-arrow>No arrow</bd-button>
     </div>
   `,
-  parameters: { docs: { description: { story: 'Side-by-side comparison of the `default` and `rounded` shapes.' } } }
+  parameters: { docs: { description: { story: 'Every accent button reveals a trailing arrow on hover and `:focus-visible`: the label slides left and the button keeps its width. `no-arrow` opts out; a disabled or loading button never shows it.' } } }
 };
 
-export const ButtonDangerArrow = {
-  name  : 'Button — Danger (Hover Arrow)',
+export const ButtonAllSizes = {
+  name  : 'Button — All Sizes',
   render: () => html`
-    <div style="display:flex; flex-direction:column; gap:16px; align-items:flex-start;">
-      <p style="font-size:14px; margin:0;">Hover (or Tab to focus) any button to see the arrow.</p>
-      <bd-button kind="danger" size="md" strong>Activez votre protection</bd-button>
-      <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
-        <bd-button kind="danger" size="sm" strong>Small</bd-button>
-        <bd-button kind="danger" size="md" strong>Medium</bd-button>
-        <bd-button kind="danger" size="lg" strong>Large</bd-button>
-      </div>
+    <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
+      <bd-button variant="primary" size="sm">Small</bd-button>
+      <bd-button variant="primary" size="md">Medium</bd-button>
+      <bd-button variant="primary" size="lg">Large</bd-button>
     </div>
   `,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Default behaviour for every `kind="danger"` button: on hover / `:focus-visible` the label slides left and an arrow appears on the right, without changing the button width.'
-      }
-    }
-  }
+  parameters: { docs: { description: { story: 'All three size variants.' } } }
 };
 
-export const ButtonDangerNoArrow = {
-  name  : 'Button — Danger without Arrow',
+const VARIANTS = ['primary', 'secondary', 'tertiary', 'ghost', 'accent'];
+const SIZES = ['sm', 'md', 'lg'];
+
+const strip = label => html`
+  <p style="margin:var(--spacing-16) 0 var(--spacing-8);font:var(--typography-fontSize-xs)/1.4 var(--typography-fontFamily-sans);color:var(--color-neutral-600)">
+    ${label}
+  </p>
+`;
+
+export const ButtonDisabled = {
+  name  : 'Button — Disabled',
   render: () => html`
-    <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
-      <bd-button kind="danger" size="md" strong>With arrow (default)</bd-button>
-      <bd-button kind="danger" size="md" strong no-arrow>Without arrow</bd-button>
+    ${strip('disabled — filled variants grey out, outlined ones keep a transparent fill and take a subtle border')}
+    <div style="display:flex; gap:var(--spacing-12); flex-wrap:wrap; align-items:center;">
+      ${VARIANTS.map(variant => html`<bd-button variant="${variant}" disabled>${variant}</bd-button>`)}
+    </div>
+    ${strip('the same variants enabled, for comparison')}
+    <div style="display:flex; gap:var(--spacing-12); flex-wrap:wrap; align-items:center;">
+      ${VARIANTS.map(variant => html`<bd-button variant="${variant}">${variant}</bd-button>`)}
+    </div>
+    ${strip('bd-button-link disabled — the href is dropped and aria-disabled is set, because a link has no native disabled state')}
+    <div style="display:flex; gap:var(--spacing-12); flex-wrap:wrap; align-items:center;">
+      ${VARIANTS.map(variant => html`<bd-button-link variant="${variant}" href="#" disabled>${variant}</bd-button-link>`)}
     </div>
   `,
-  parameters: { docs: { description: { story: 'Use the `no-arrow` attribute to opt out of the hover arrow on a specific danger button.' } } }
+  parameters: { docs: { description: { story: 'Disabled controls are exempt from contrast requirements under WCAG 1.4.3.' } } }
 };
 
-export const ButtonAllSizes = {
-  name  : 'Button — All Sizes',
+export const ButtonLoading = {
+  name  : 'Button — Loading',
   render: () => html`
-    <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
-      <bd-button kind="primary" size="sm">Small</bd-button>
-      <bd-button kind="primary" size="md">Medium</bd-button>
-      <bd-button kind="primary" size="lg">Large</bd-button>
+    ${strip('loading — the variant keeps its own colours and the spinner is drawn in currentColor')}
+    <div style="display:flex; gap:var(--spacing-12); flex-wrap:wrap; align-items:center;">
+      ${VARIANTS.map(variant => html`<bd-button variant="${variant}" loading>${variant}</bd-button>`)}
+    </div>
+    ${strip('the spinner is sized in em, so it tracks the type scale across sizes')}
+    <div style="display:flex; gap:var(--spacing-12); flex-wrap:wrap; align-items:center;">
+      ${SIZES.map(size => html`<bd-button size="${size}" loading>${size}</bd-button>`)}
     </div>
   `,
-  parameters: { docs: { description: { story: 'All three size variants.' } } }
+  parameters: { docs: { description: { story: 'Sets `aria-busy`, blocks interaction, and falls back to a pulse under `prefers-reduced-motion`.' } } }
+};
+
+const HEROES = [
+  ['blue-500 — the worst case for contrast', 'var(--color-blue-500)'],
+  ['blue-700', 'var(--color-blue-700)'],
+  ['neutral-950', 'var(--color-neutral-950)']
+];
+
+export const ButtonOnDark = {
+  name  : 'Button — On a dark surface',
+  render: () => html`
+    ${HEROES.map(([label, bg]) => html`
+      <p style="margin:var(--spacing-24) 0 var(--spacing-8);font:var(--typography-fontSize-xs)/1.4 var(--typography-fontFamily-sans);color:var(--color-neutral-600)">
+        ${label}
+      </p>
+      <div style="background:${bg};padding:var(--spacing-24);border-radius:var(--radius-md);display:flex;gap:var(--spacing-12);flex-wrap:wrap;align-items:center;">
+        ${VARIANTS.map(variant => html`
+          <bd-button variant="${variant}" surface="dark">${variant}</bd-button>
+        `)}
+        <bd-button variant="primary" surface="dark" disabled>disabled</bd-button>
+        <bd-button variant="accent" surface="dark" loading>loading</bd-button>
+      </div>
+    `)}
+    <p style="margin:var(--spacing-24) 0 var(--spacing-8);font:var(--typography-fontSize-xs)/1.4 var(--typography-fontFamily-sans);color:var(--color-neutral-600)">
+      the same variants without surface="dark", for comparison — this is what a hero looks like today
+    </p>
+    <div style="background:var(--color-blue-500);padding:var(--spacing-24);border-radius:var(--radius-md);display:flex;gap:var(--spacing-12);flex-wrap:wrap;align-items:center;">
+      ${VARIANTS.map(variant => html`<bd-button variant="${variant}">${variant}</bd-button>`)}
+    </div>
+  `,
+  parameters: { docs: { description: { story:
+    'For a hero or panel with a full background colour. The design specifies no on-dark set, so these values are derived from our palette and measured against every plausible hero colour — they need a designer\'s sign-off. ghost drops its ring so it stays distinct from tertiary; accent keeps its red and gains a white boundary.' } } }
 };
 
 export const ButtonFullWidth = {
   name  : 'Button — Full Width',
   render: () => html`
-    <div style="width:400px; display:flex; flex-direction:column; gap:12px;">
-      <bd-button kind="primary" size="md" .fullWidth="${true}">Full Width Button</bd-button>
-      <bd-button kind="danger" size="md" strong .fullWidth="${true}">Full Width Danger</bd-button>
-      <bd-button kind="primary" size="md" shape="rounded" .fullWidth="${true}">Full Width Rounded</bd-button>
+    <div style="width:400px;">
+      <bd-button variant="primary" size="md" .fullWidth="${true}">Full Width Button</bd-button>
     </div>
   `,
-  parameters: { docs: { description: { story: '`fullWidth` set to true — applies `max--width` class. The danger arrow and rounded shape also work at full width.' } } }
+  parameters: { docs: { description: { story: '`fullWidth` set to true — applies `max--width` class.' } } }
 };
 
 export const ButtonStrong = {
   name  : 'Button — Strong (Bold)',
   render: () => html`
     <div style="display:flex; gap:12px;">
-      <bd-button kind="primary" size="md">Normal</bd-button>
-      <bd-button kind="primary" size="md" .strong="${true}">Strong</bd-button>
+      <bd-button variant="primary" size="md">Normal</bd-button>
+      <bd-button variant="primary" size="md" .strong="${true}">Strong</bd-button>
     </div>
   `,
   parameters: { docs: { description: { story: 'Comparison between normal and `strong` (bold) button.' } } }
@@ -287,7 +380,7 @@ export const ButtonAlignCenter = {
   name  : 'Button — Align Center',
   render: () => html`
     <div style="width:100%;">
-      <bd-button kind="primary" size="md" align="center">Centered Button</bd-button>
+      <bd-button variant="primary" size="md" align="center">Centered Button</bd-button>
     </div>
   `,
   parameters: { docs: { description: { story: 'Button centered horizontally using `align="center"`.' } } }
@@ -297,7 +390,7 @@ export const ButtonAlignRight = {
   name  : 'Button — Align Right',
   render: () => html`
     <div style="width:100%;">
-      <bd-button kind="danger" size="md" align="right">Right Aligned Button</bd-button>
+      <bd-button variant="accent" size="md" align="right">Right Aligned Button</bd-button>
     </div>
   `,
   parameters: { docs: { description: { story: 'Button aligned to the right using `align="right"`.' } } }
@@ -308,13 +401,13 @@ export const ButtonAllAlignments = {
   render: () => html`
     <div style="width:100%; max-width:600px; display:flex; flex-direction:column; gap:16px;">
       <div style="border:1px dashed #ccc; padding:12px; border-radius:4px;">
-        <bd-button kind="primary" size="md" align="left">Left (default)</bd-button>
+        <bd-button variant="primary" size="md" align="left">Left (default)</bd-button>
       </div>
       <div style="border:1px dashed #ccc; padding:12px; border-radius:4px;">
-        <bd-button kind="primary" size="md" align="center">Center</bd-button>
+        <bd-button variant="primary" size="md" align="center">Center</bd-button>
       </div>
       <div style="border:1px dashed #ccc; padding:12px; border-radius:4px;">
-        <bd-button kind="primary" size="md" align="right">Right</bd-button>
+        <bd-button variant="primary" size="md" align="right">Right</bd-button>
       </div>
     </div>
   `,
@@ -324,18 +417,18 @@ export const ButtonAllAlignments = {
 export const ButtonCustomTypography = {
   name  : 'Button — Custom Font Size & Weight',
   render: () => html`
-    <bd-button kind="danger" size="md" font-size="20px" font-weight="800">
+    <bd-button variant="accent" size="md" font-size="xl" font-weight="bold">
       Buy now
     </bd-button>
   `,
-  parameters: { docs: { description: { story: 'Custom `font-size` and `font-weight` applied via inline styles. The arrow scales with the font size.' } } }
+  parameters: { docs: { description: { story: 'Custom `font-size` and `font-weight` applied via inline styles.' } } }
 };
 
 export const ButtonKeyboard = {
   name  : 'Button — Keyboard Accessible',
   render: () => html`
     <p style="font-size:14px; margin-bottom:8px;">Tab to focus, press Enter or Space to trigger.</p>
-    <bd-button kind="primary" size="md" label="Keyboard test">Press me</bd-button>
+    <bd-button variant="primary" size="md" label="Keyboard test">Press me</bd-button>
   `,
   parameters: { docs: { description: { story: 'Demonstrates keyboard activation. Enter/Space trigger `custom-click` and toggle the `active` class briefly.' } } }
 };
@@ -345,7 +438,7 @@ export const ButtonKeyboard = {
 export const ButtonLinkDefault = {
   name  : 'ButtonLink — Default',
   render: () => html`
-    <bd-button-link kind="primary" size="md" href="/buy">Buy now</bd-button-link>
+    <bd-button-link variant="primary" size="md" href="/buy">Buy now</bd-button-link>
   `,
   parameters: { docs: { description: { story: 'Default `bd-button-link` rendered as an `<a>` tag.' } } }
 };
@@ -354,55 +447,32 @@ export const ButtonLinkAllKinds = {
   name  : 'ButtonLink — All Kinds',
   render: () => html`
     <div style="display:flex; gap:12px; flex-wrap:wrap; align-items:center;">
-      <bd-button-link kind="primary" size="md" href="#">Primary</bd-button-link>
-      <bd-button-link kind="primary-outline" size="md" href="#">Primary Outline</bd-button-link>
-      <bd-button-link kind="outline" size="md" href="#">Outline</bd-button-link>
-      <bd-button-link kind="secondary" size="md" href="#">Secondary</bd-button-link>
-      <bd-button-link kind="danger" size="md" href="#">Danger</bd-button-link>
+      <bd-button-link variant="primary" size="md" href="#">primary</bd-button-link>
+      <bd-button-link variant="secondary" size="md" href="#">secondary</bd-button-link>
+      <bd-button-link variant="tertiary" size="md" href="#">tertiary</bd-button-link>
+      <bd-button-link variant="ghost" size="md" href="#">ghost</bd-button-link>
+      <bd-button-link variant="accent" size="md" href="#">accent</bd-button-link>
     </div>
   `,
-  parameters: { docs: { description: { story: 'All `kind` variants for `bd-button-link`.' } } }
-};
-
-export const ButtonLinkRounded = {
-  name  : 'ButtonLink — Rounded',
-  render: () => html`
-    <div style="display:flex; gap:12px; flex-wrap:wrap; align-items:center;">
-      <bd-button-link kind="primary" size="md" href="#" shape="rounded">Primary</bd-button-link>
-      <bd-button-link kind="primary-outline" size="md" href="#" shape="rounded">Primary Outline</bd-button-link>
-      <bd-button-link kind="danger" size="md" href="#" shape="rounded" strong>Danger</bd-button-link>
-    </div>
-  `,
-  parameters: { docs: { description: { story: '`shape="rounded"` on `bd-button-link`.' } } }
+  parameters: { docs: { description: { story: 'All `variant` values for `bd-button-link`.' } } }
 };
 
 export const ButtonLinkAllSizes = {
   name  : 'ButtonLink — All Sizes',
   render: () => html`
     <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
-      <bd-button-link kind="danger" size="sm" href="#">Small</bd-button-link>
-      <bd-button-link kind="danger" size="md" href="#">Medium</bd-button-link>
-      <bd-button-link kind="danger" size="lg" href="#">Large</bd-button-link>
-    </div>
-  `,
-  parameters: { docs: { description: { story: 'All three sizes for `bd-button-link` (danger, with hover arrow).' } } }
-};
-
-export const ButtonLinkDangerArrow = {
-  name  : 'ButtonLink — Danger (Hover Arrow)',
-  render: () => html`
-    <div style="display:flex; gap:12px; align-items:center; flex-wrap:wrap;">
-      <bd-button-link kind="danger" size="md" href="#" strong>Activez votre protection</bd-button-link>
-      <bd-button-link kind="danger" size="md" href="#" strong no-arrow>Without arrow</bd-button-link>
+      <bd-button-link variant="accent" size="sm" href="#">Small</bd-button-link>
+      <bd-button-link variant="accent" size="md" href="#">Medium</bd-button-link>
+      <bd-button-link variant="accent" size="lg" href="#">Large</bd-button-link>
     </div>
   `,
-  parameters: { docs: { description: { story: 'The hover arrow is also on by default for `bd-button-link` with `kind="danger"`; `no-arrow` disables it.' } } }
+  parameters: { docs: { description: { story: 'All three sizes for `bd-button-link`.' } } }
 };
 
 export const ButtonLinkBuyLink = {
   name  : 'ButtonLink — Buy Link Mode',
   render: () => html`
-    <bd-button-link kind="danger" size="md" href="/buy" .buyLink="${true}">
+    <bd-button-link variant="accent" size="md" href="/buy" .buyLink="${true}">
       Buy now
     </bd-button-link>
   `,
@@ -413,7 +483,7 @@ export const ButtonLinkFullWidth = {
   name  : 'ButtonLink — Full Width',
   render: () => html`
     <div style="width:400px;">
-      <bd-button-link kind="primary" size="md" href="#" .fullWidth="${true}">
+      <bd-button-link variant="primary" size="md" href="#" .fullWidth="${true}">
         Full Width Link Button
       </bd-button-link>
     </div>
@@ -425,7 +495,7 @@ export const ButtonLinkAlignCenter = {
   name  : 'ButtonLink — Align Center',
   render: () => html`
     <div style="width:100%;">
-      <bd-button-link kind="primary" size="md" href="#" align="center">
+      <bd-button-link variant="primary" size="md" href="#" align="center">
         Centered Link Button
       </bd-button-link>
     </div>
@@ -437,7 +507,7 @@ export const ButtonLinkAlignRight = {
   name  : 'ButtonLink — Align Right',
   render: () => html`
     <div style="width:100%;">
-      <bd-button-link kind="danger" size="md" href="#" align="right">
+      <bd-button-link variant="accent" size="md" href="#" align="right">
         Right Aligned Link Button
       </bd-button-link>
     </div>
@@ -448,13 +518,100 @@ export const ButtonLinkAlignRight = {
 export const ButtonLinkCustomTypography = {
   name  : 'ButtonLink — Custom Typography',
   render: () => html`
-    <bd-button-link kind="danger" size="md" href="#" font-size="18px" font-weight="600">
+    <bd-button-link variant="accent" size="md" href="#" font-size="lg" font-weight="semibold">
       Buy now
     </bd-button-link>
   `,
   parameters: { docs: { description: { story: 'Inline `font-size` and `font-weight` applied to the anchor element.' } } }
 };
 
+// ─── Icon-only ─────────────────────────────────────────────────────────────
+
+const row = 'display:flex; gap:var(--spacing-12); flex-wrap:wrap; align-items:center;';
+
+export const ButtonIconOnly = {
+  name  : 'Button — Icon only',
+  render: () => html`
+    ${SIZES.map(size => html`
+      ${strip(`${size} — every variant`)}
+      <div style="${row}">
+        ${VARIANTS.map(variant => html`<bd-button icon-only variant="${variant}" size="${size}" label="Continue"></bd-button>`)}
+      </div>
+    `)}
+    ${strip('beside a labelled button of the same size — md sits level; sm is 1.5px shorter and lg 1.5px taller')}
+    <div style="${row}">
+      ${SIZES.map(size => html`
+        <bd-button size="${size}">Get protected</bd-button>
+        <bd-button icon-only size="${size}" label="Get protected"></bd-button>
+      `)}
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'The circle is 32, 44 and 56 — equal padding around a 16, 20 and 24 icon. `label` names each one, since there is no visible text.' } } }
+};
+
+export const ButtonIconOnlyStates = {
+  name  : 'Button — Icon only, states',
+  render: () => html`
+    ${strip('disabled — the same treatment as the labelled button')}
+    <div style="${row}">
+      ${VARIANTS.map(variant => html`<bd-button icon-only variant="${variant}" label="Continue" disabled></bd-button>`)}
+    </div>
+    ${strip('loading — the spinner replaces the icon at the icon\'s size, so the circle keeps its size')}
+    <div style="${row}">
+      ${SIZES.map(size => html`
+        <bd-button icon-only size="${size}" label="Continue"></bd-button>
+        <bd-button icon-only size="${size}" label="Continue" loading></bd-button>
+      `)}
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'Focus is the shared two-colour ring, which follows the circle. Tab through the Keyboard story to see it.' } } }
+};
+
+export const ButtonIconOnlyOwnIcon = {
+  name  : 'Button — Icon only, your own icon',
+  render: () => html`
+    ${strip('any bd-*-icon in the slot — sized to the button\'s step, whatever size it was given')}
+    <div style="${row}">
+      <bd-button icon-only variant="ghost" label="Close"><bd-close-icon></bd-close-icon></bd-button>
+      <bd-button icon-only variant="tertiary" label="Add to comparison"><bd-plus-icon></bd-plus-icon></bd-button>
+      <bd-button icon-only variant="tertiary" size="lg" label="Add to comparison"><bd-plus-icon size="xs"></bd-plus-icon></bd-button>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'The last one slots an xs icon into an lg button and still gets 24px: the button owns the glyph size, so a circle never holds an icon too small for it.' } } }
+};
+
+export const ButtonIconOnlyOnBand = {
+  name  : 'Button — Icon only, on a band',
+  render: () => html`
+    ${HEROES.map(([label, bg]) => html`
+      ${strip(`${label} — surface="dark"`)}
+      <div style="background:${bg};padding:var(--spacing-24);border-radius:var(--radius-md);${row}">
+        ${VARIANTS.map(variant => html`<bd-button icon-only variant="${variant}" surface="dark" label="Continue"></bd-button>`)}
+      </div>
+    `)}
+    ${strip('white and outline-white — bd-button-link presets for a full-colour band')}
+    <div style="background:var(--color-surface-brand);padding:var(--spacing-24);border-radius:var(--radius-md);${row}">
+      <bd-button-link icon-only variant="white" href="#" label="Read the Ferrari story"></bd-button-link>
+      <bd-button-link icon-only variant="outline-white" href="#" label="Explore consumer AI"></bd-button-link>
+      <bd-button-link icon-only variant="outline-white" size="lg" href="#" label="Explore consumer AI"></bd-button-link>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'The same surface rules as the labelled button. white and outline-white keep their look on any band.' } } }
+};
+
+export const ButtonLinkIconOnly = {
+  name  : 'ButtonLink — Icon only (homepage audience card)',
+  render: () => html`
+    <div style="max-width:384px;padding:var(--spacing-24);border:var(--border-width-1) solid var(--color-border-container);border-radius:var(--radius-2xl);display:flex;flex-direction:column;align-items:flex-end;gap:var(--spacing-8);">
+      <p style="margin:0;align-self:stretch;font:var(--typography-body-regular-fontWeight) var(--typography-body-regular-fontSize)/var(--typography-body-regular-lineHeight) var(--typography-fontFamily-sans);color:var(--color-text-primary);">
+        AI-powered protection against scams, deepfake fraud, identity theft, and online threats across all your devices.
+      </p>
+      <bd-button-link icon-only variant="accent" href="#" label="Protect your digital life"></bd-button-link>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'As the homepage\'s audience cards use it: accent, md, and a link because it navigates. The name says where it goes; the card\'s title is not its name.' } } }
+};
+
 // ─── bd-contact-button Stories ─────────────────────────────────────────────
 
 export const ContactButtonDefault = {
@@ -481,14 +638,6 @@ export const ContactButtonCustomHref = {
   parameters: { docs: { description: { story: 'Contact button linking to an external support URL.' } } }
 };
 
-export const ContactButtonRounded = {
-  name  : 'ContactButton — Rounded',
-  render: () => html`
-    <bd-contact-button label="Contact us" href="#" shape="rounded"></bd-contact-button>
-  `,
-  parameters: { docs: { description: { story: '`shape="rounded"` on `bd-contact-button`.' } } }
-};
-
 export const ContactButtonAlignCenter = {
   name  : 'ContactButton — Align Center',
   render: () => html`
@@ -515,8 +664,8 @@ export const AllButtonTypes = {
   name  : 'All Button Types',
   render: () => html`
     <div style="display:flex; gap:16px; flex-wrap:wrap; align-items:center;">
-      <bd-button kind="primary" size="md">bd-button</bd-button>
-      <bd-button-link kind="danger" size="md" href="#">bd-button-link</bd-button-link>
+      <bd-button variant="primary" size="md">bd-button</bd-button>
+      <bd-button-link variant="accent" size="md" href="#">bd-button-link</bd-button-link>
       <bd-contact-button label="bd-contact-button" href="#"></bd-contact-button>
     </div>
   `,
@@ -529,7 +678,7 @@ export const Playground = {
   render: (args) => html`
     <div style="width:100%;">
       <bd-button
-        kind="${args.kind}"
+        variant="${args.variant}"
         size="${args.size}"
         shape="${args.shape}"
         label="${args.label}"
@@ -539,23 +688,22 @@ export const Playground = {
         ?no-arrow="${args.noArrow}"
         font-size="${args.fontSize}"
         font-weight="${args.fontWeight}"
-      >${args.label}</bd-button>
+        surface="${args.surface}"
+        ?icon-only="${args.iconOnly}"
+      >${args.iconOnly ? nothing : args.label}</bd-button>
     </div>
   `,
-  parameters: { docs: { description: { story: 'Interactive playground for `bd-button`. Use Controls to adjust all props including shape, alignment and the danger hover arrow.' } } }
+  parameters: { docs: { description: { story: 'Interactive playground for `bd-button`. Use Controls to adjust all props including alignment.' } } }
 };
-
 // ─── White / Outline-White (on dark background) ───────────────────────────
 
 export const ButtonWhiteOnDark = {
   name  : 'Button — White / Outline-White (on dark background)',
   render: () => html`
     <div style="background: linear-gradient(120deg, #0038e0 0%, #061a5c 100%); padding: 48px; border-radius: 12px; display:flex; gap:16px; flex-wrap:wrap; align-items:center; justify-content:center;">
-      <bd-button-link kind="white" size="md" strong href="#">Download BETA Today</bd-button-link>
-      <bd-button-link kind="outline-white" size="md" strong href="#">Read the docs</bd-button-link>
-      <bd-button-link kind="white" size="md" strong href="#" shape="rounded">Rounded White</bd-button-link>
-      <bd-button-link kind="outline-white" size="md" strong href="#" shape="rounded">Rounded Outline</bd-button-link>
+      <bd-button-link variant="white" size="md" strong href="#">Download BETA Today</bd-button-link>
+      <bd-button-link variant="outline-white" size="md" strong href="#">Read the docs</bd-button-link>
     </div>
   `,
-  parameters: { docs: { description: { story: '`white` and `outline-white` kinds, meant for use on colored/dark backgrounds like `bd-cta-banner` or hero sections. Also shown with `shape="rounded"`.' } } }
+  parameters: { docs: { description: { story: '`white` and `outline-white` variants, meant for use on colored/dark backgrounds like `bd-cta-banner` or hero sections.' } } }
 };