@arbor-education/design-system.components 1.0.5 → 2.0.0

package/src/components/button/Button.stories.tsx

@@ -10,6 +10,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { useState, useRef } from 'react';
 import { Button } from './Button.js';
+import { Icon } from 'Components/icon/Icon';
 
 // ---------------------------------------------------------------------------
 // Component description — built as a joined array to avoid no-useless-escape
@@ -23,8 +24,9 @@ import { Button } from './Button.js';
 
 const DESCRIPTION_INTRO = [
   'The **Button** is the primary interactive control in the Arbor design system. It wraps a native',
-  '`<button>` element with `forwardRef` support, consistent design tokens, icon slots, and a full set',
-  'of variant and state modifiers.',
+  '`<button>` element with `forwardRef` support, consistent design tokens, and a full set',
+  'of variant and state modifiers. Icons are composed via `children` using the `Icon` component,',
+  'so consumers control icon placement, colour, and accessible text directly.',
 ].join('\n');
 
 const USAGE_GUIDANCE = [
@@ -69,9 +71,10 @@ const DEVELOPER_NOTES = [
   '### Critical gotchas',
   '',
   '#### 1. The `type` attribute trap',
-  'The `type` prop is **deliberately omitted** from the component\'s prop spread',
-  '(`Omit<ButtonHTMLAttributes<HTMLButtonElement>, \'type\' | \'onClick\'>` on `Button.tsx` line 24).',
-  'This means the underlying `<button>` has no `type` attribute, and browsers default to',
+  '`type` is a fully typed prop (`\'button\' | \'submit\' | \'reset\'`, inherited from',
+  '`ButtonHTMLAttributes<HTMLButtonElement>`), but the component **does not default it**',
+  '— there is no `type = \'button\'` fallback in `Button.tsx`. This means that if you omit it,',
+  'the underlying `<button>` has no `type` attribute, and browsers default to',
   '`type="submit"`. If this button lives inside a `<form>`, clicking it **will submit the form**',
   'unless you explicitly pass `type="button"`.',
   '',
@@ -83,17 +86,22 @@ const DEVELOPER_NOTES = [
   '<Button variant="secondary" type="button" onClick={handleCancel}>Cancel</Button>',
   '```',
   '',
-  '#### 2. Icon-only accessibility',
-  'When `children` is omitted, the component enters icon-only mode (`ds-button--icon-only`). The icon',
-  'name becomes the default screen reader text, but icon names like `"3-dot"` or `"x"` are not',
-  'meaningful in context. Always provide `iconLeftScreenReaderText` or `iconRightScreenReaderText`.',
+  '#### 2. Icons are composed via `children`',
+  'Icons are no longer separate props — render an `Icon` as part of `children`, placed before and/or',
+  'after the label text. Set the explicit `isRound` prop for square, no-padding sizing when there is',
+  'no visible label. Because the icon is just a child element, always pass `screenReaderText` on the',
+  '`Icon` yourself when it is the button\'s only accessible content — icon names like `"3-dot"` or',
+  '`"x"` are not meaningful in context. When an icon sits alongside a visible label (e.g. a trailing',
+  'chevron), omit `screenReaderText` so it stays decorative and does not duplicate the label.',
   '',
   '```tsx',
-  '// BAD — screen reader says "3-dot"',
-  '<Button variant="secondary" iconRightName="3-dot" />',
+  '// BAD — no accessible name at all',
+  '<Button variant="secondary" isRound><Icon name="3-dot" /></Button>',
   '',
   '// GOOD',
-  '<Button variant="secondary" iconRightName="3-dot" iconRightScreenReaderText="More actions" />',
+  '<Button variant="secondary" isRound>',
+  '  <Icon name="3-dot" screenReaderText="More actions" />',
+  '</Button>',
   '```',
   '',
   '---',
@@ -103,10 +111,32 @@ const DEVELOPER_NOTES = [
   '- Native `<button>` — focusable with Tab, activated with Space or Enter',
   '- Focus ring: 3px outline using `--focus-border` and `--color-brand-500` via `--focus-color-focus`',
   '- `disabled` removes the button from tab order AND blocks pointer events (`opacity: 0.5; cursor: not-allowed; pointer-events: none`)',
-  '- Icon-only mode: provide `iconLeftScreenReaderText` / `iconRightScreenReaderText` for meaningful labels',
+  '- Icon-only mode (`isRound`): always pass `screenReaderText` on the child `Icon` — it is the button\'s only accessible label',
   '- The `error` prop is **purely visual** (adds a red border) — it carries no ARIA semantics.',
   '  The consumer is still responsible for communicating the error state to assistive tech — e.g.',
   '  setting `aria-invalid` on the associated input or wiring `aria-describedby` to an error message.',
+  '- `disabled` sets `pointer-events: none` via CSS, so `onClick` genuinely cannot fire while disabled —',
+  '  no defensive guard is needed inside the handler itself.',
+  '',
+  '---',
+  '',
+  '#### Focus, hover, and active are CSS-only',
+  'There is no `focused` / `hovered` / `active` prop. Each variant defines its own `:focus`, `:hover`,',
+  'and `:active` rules directly in `button.scss` — these are native pseudo-classes on the underlying',
+  '`<button>`, not something Storybook Controls can toggle. To see them, interact with the rendered',
+  'button in the canvas (click, tab to it, or hover over it).',
+  '',
+  '---',
+  '',
+  '#### The `` `[key: `data-${string}`]: unknown` `` index signature',
+  '`ButtonProps` includes a narrow catch-all that matches **only** `data-*` keys, spread via `...rest`',
+  'straight onto the native `<button>` element — the one open-ended attribute pattern with no fixed',
+  'name list (`data-testid`, `data-component`, etc.). `aria-*` and all standard HTML attributes are',
+  'separately and fully typed via `ButtonHTMLAttributes`, so they do not need this catch-all. Because',
+  'the signature is scoped to `data-*`, a typo in a known prop name (e.g. `isRond` instead of `isRound`)',
+  'is a **compile error**, not a silent unrecognised DOM attribute — this used to be a blanket',
+  '`[key: string]: unknown` that swallowed any misspelled or removed prop name; it was narrowed for',
+  'exactly this reason.',
   '',
   '---',
   '',
@@ -209,10 +239,9 @@ const meta = {
     children: {
       control: 'text',
       description: [
-        'Button label content. Accepts any `React.ReactNode`.',
-        'When omitted (and at least one icon prop is provided), the button enters',
-        'icon-only mode (`ds-button--icon-only`) — square aspect ratio, no padding compensation needed.',
-        'Always pair icon-only mode with descriptive `iconLeftScreenReaderText` / `iconRightScreenReaderText`.',
+        'Button label content. Accepts any `React.ReactNode`, including `Icon` elements placed before',
+        'and/or after the label text — Button renders `children` as-is with no separate icon slots.',
+        'For an icon-only button, set `isRound` and always pass `screenReaderText` on the `Icon`.',
       ].join(' '),
       table: {
         type: { summary: 'React.ReactNode' },
@@ -256,94 +285,16 @@ const meta = {
         defaultValue: { summary: 'true' },
       },
     },
-    iconLeftName: {
-      control: 'select',
-      options: [
-        undefined,
-        'plus',
-        'pencil',
-        'save',
-        'trash',
-        'download',
-        'upload',
-        'mail',
-        'search',
-        'info',
-        'check',
-        'x',
-        'arrow-left',
-        'arrow-right',
-        'settings',
-        'loader',
-        '3-dot',
-        'user',
-        'send',
-      ],
-      description: [
-        'Name of an icon to render **before** the button label at 16px.',
-        'Renders an `<Icon>` component with `size={16}`.',
-        'Screen reader text defaults to the icon name — always override with `iconLeftScreenReaderText`',
-        'when the icon name is not meaningful in context (e.g. `"3-dot"`, `"x"`).',
-      ].join(' '),
-      table: {
-        type: { summary: 'IconName' },
-        defaultValue: { summary: 'undefined' },
-      },
-    },
-    iconLeftScreenReaderText: {
-      control: 'text',
-      description: [
-        'Screen reader label for the left icon.',
-        'Defaults to the icon name when omitted.',
-        'In icon-only mode this becomes the accessible label for the entire button — make it descriptive.',
-      ].join(' '),
-      table: {
-        type: { summary: 'string' },
-      },
-    },
-    iconRightName: {
-      control: 'select',
-      options: [
-        undefined,
-        'plus',
-        'pencil',
-        'save',
-        'trash',
-        'download',
-        'upload',
-        'mail',
-        'search',
-        'info',
-        'check',
-        'x',
-        'arrow-right',
-        'chevron-down',
-        'chevron-up',
-        'settings',
-        'loader',
-        '3-dot',
-        'external-link',
-        'send',
-      ],
-      description: [
-        'Name of an icon to render **after** the button label at 16px.',
-        'Renders an `<Icon>` component with `size={16}`.',
-        'Screen reader text defaults to the icon name — always override with `iconRightScreenReaderText`.',
-      ].join(' '),
-      table: {
-        type: { summary: 'IconName' },
-        defaultValue: { summary: 'undefined' },
-      },
-    },
-    iconRightScreenReaderText: {
-      control: 'text',
+    isRound: {
+      control: 'boolean',
       description: [
-        'Screen reader label for the right icon.',
-        'Defaults to the icon name when omitted.',
-        'In icon-only mode this is the accessible label — always set it explicitly.',
+        'Applies equal padding on all sides (`ds-button--round`) for a square, compact button.',
+        'Commonly used for icon-only buttons — in that case, always pass `screenReaderText` on the child',
+        '`Icon`, since it becomes the button\'s only accessible label.',
       ].join(' '),
       table: {
-        type: { summary: 'string' },
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
       },
     },
     borderless: {
@@ -518,10 +469,9 @@ const LoadingCompositionTemplate = () => {
         variant="primary"
         type="button"
         disabled={loading}
-        iconLeftName={loading ? 'loader' : undefined}
-        iconLeftScreenReaderText={loading ? 'Loading, please wait' : undefined}
         onClick={handleClick}
       >
+        {loading && <Icon name="loader" screenReaderText="Loading, please wait" />}
         {loading ? 'Exporting...' : 'Export to CSV'}
       </Button>
     </div>
@@ -545,7 +495,7 @@ export const Default: Story = withDescription(
     },
     render: args => <Button {...args} />,
   },
-  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore variants, sizes, icons, and states. Tip: try setting `iconLeftName` to `"save"` or `"plus"` to see the icon slot in action.',
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore variants, sizes, and states. See the `WithIconLeft` / `WithIconRight` / `IconOnly` stories for icon composition, since icons are rendered via `children` rather than a Controls-editable prop.',
 );
 
 export const Primary: Story = withDescription(
@@ -721,7 +671,12 @@ export const Dropdown: Story = withDescription(
     args: {
       variant: 'dropdown',
       size: 'M',
-      children: 'Select year group',
+      children: (
+        <>
+          Select year group
+          <Icon name="chevron-down" />
+        </>
+      ),
     },
     parameters: {
       docs: {
@@ -729,11 +684,13 @@ export const Dropdown: Story = withDescription(
           language: 'tsx',
           code: `
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function ButtonDropdownExample() {
   return (
-    <Button variant="dropdown" size="M" iconRightName="chevron-down" iconRightScreenReaderText="Open dropdown">
+    <Button variant="dropdown" size="M">
       Select year group
+      <Icon name="chevron-down" />
     </Button>
   );
 }
@@ -748,8 +705,8 @@ export default ButtonDropdownExample;
     'The `dropdown` variant has `justify-content: space-between` and specific padding designed for use as a',
     'dropdown trigger — a trailing chevron icon aligns to the right edge automatically. Used internally by',
     '`SelectDropdown`, `ColourPickerDropdown`, and `UserDropdown`, and available to consumers for custom',
-    'dropdown triggers. Pair it with a chevron icon (e.g. `iconRightName="chevron-down"`) for the canonical',
-    'look.',
+    'dropdown triggers. Pair it with a trailing chevron `Icon` (e.g. `<Icon name="chevron-down" />`) for the',
+    'canonical look — it is decorative, so it does not need `screenReaderText` when a visible label is present.',
   ].join(' '),
 );
 
@@ -940,9 +897,12 @@ export const WithIconLeft: Story = withDescription(
     args: {
       variant: 'primary',
       size: 'M',
-      children: 'Export to CSV',
-      iconLeftName: 'download',
-      iconLeftScreenReaderText: 'Download',
+      children: (
+        <>
+          <Icon name="download" />
+          Export to CSV
+        </>
+      ),
     },
     parameters: {
       docs: {
@@ -950,10 +910,12 @@ export const WithIconLeft: Story = withDescription(
           language: 'tsx',
           code: `
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function ButtonWithIconLeftExample() {
   return (
-    <Button variant="primary" size="M" iconLeftName="download" iconLeftScreenReaderText="Download">
+    <Button variant="primary" size="M">
+      <Icon name="download" />
       Export to CSV
     </Button>
   );
@@ -965,7 +927,7 @@ export default ButtonWithIconLeftExample;
       },
     },
   },
-  'Icon on the left of the label via `iconLeftName`. The icon renders at 16px. `iconLeftScreenReaderText` overrides the accessible label for the icon — here it is set to `"Download"` which is more natural than the icon name `"download"` (though similar in this case). Use left icons for actions where the icon reinforces the verb: download, add, send.',
+  'Icon placed before the label by rendering an `Icon` as the first child. `Icon` defaults to `size={16}` and `color="currentColor"`, so it inherits the button\'s text colour automatically. The icon sits next to a visible label here, so it is left decorative (no `screenReaderText`). Use leading icons for actions where the icon reinforces the verb: download, add, send.',
 );
 
 export const WithIconRight: Story = withDescription(
@@ -973,9 +935,12 @@ export const WithIconRight: Story = withDescription(
     args: {
       variant: 'secondary',
       size: 'M',
-      children: 'Send to parents',
-      iconRightName: 'send',
-      iconRightScreenReaderText: 'Send',
+      children: (
+        <>
+          Send to parents
+          <Icon name="send" />
+        </>
+      ),
     },
     parameters: {
       docs: {
@@ -983,11 +948,13 @@ export const WithIconRight: Story = withDescription(
           language: 'tsx',
           code: `
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function ButtonWithIconRightExample() {
   return (
-    <Button variant="secondary" size="M" iconRightName="send" iconRightScreenReaderText="Send">
+    <Button variant="secondary" size="M">
       Send to parents
+      <Icon name="send" />
     </Button>
   );
 }
@@ -998,7 +965,7 @@ export default ButtonWithIconRightExample;
       },
     },
   },
-  'Icon on the right of the label via `iconRightName`. Right icons typically indicate direction or outcome: `arrow-right` for "next", `external-link` for "opens in new tab", `chevron-down` for "opens a menu". Pair right icons with the `dropdown` variant for SelectDropdown triggers.',
+  'Icon placed after the label by rendering an `Icon` as the last child. Trailing icons typically indicate direction or outcome: `arrow-right` for "next", `external-link` for "opens in new tab", `chevron-down` for "opens a menu". Pair a trailing chevron `Icon` with the `dropdown` variant for SelectDropdown-style triggers.',
 );
 
 export const WithBothIcons: Story = withDescription(
@@ -1006,11 +973,13 @@ export const WithBothIcons: Story = withDescription(
     args: {
       variant: 'primary',
       size: 'M',
-      children: 'Generate report',
-      iconLeftName: 'sparkles',
-      iconLeftScreenReaderText: 'AI generated',
-      iconRightName: 'arrow-right',
-      iconRightScreenReaderText: 'Continue',
+      children: (
+        <>
+          <Icon name="sparkles" screenReaderText="AI generated" />
+          Generate report
+          <Icon name="arrow-right" />
+        </>
+      ),
     },
     parameters: {
       docs: {
@@ -1018,18 +987,14 @@ export const WithBothIcons: Story = withDescription(
           language: 'tsx',
           code: `
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function ButtonWithBothIconsExample() {
   return (
-    <Button
-      variant="primary"
-      size="M"
-      iconLeftName="sparkles"
-      iconLeftScreenReaderText="AI generated"
-      iconRightName="arrow-right"
-      iconRightScreenReaderText="Continue"
-    >
+    <Button variant="primary" size="M">
+      <Icon name="sparkles" screenReaderText="AI generated" />
       Generate report
+      <Icon name="arrow-right" />
     </Button>
   );
 }
@@ -1040,7 +1005,7 @@ export default ButtonWithBothIconsExample;
       },
     },
   },
-  'Both icon slots used simultaneously. Left icon reinforces the action type (`sparkles` for AI-generated), right icon indicates direction or outcome (`arrow-right` for proceed). The dual-icon pattern is rare — only use it when both icons add distinct meaning. The label should be short enough that the button does not become unwieldy.',
+  'Both a leading and trailing icon used simultaneously. The leading icon carries its own `screenReaderText` ("AI generated") because that meaning is not otherwise conveyed by the label — the trailing `arrow-right` is purely decorative (proceed/continue) so it has none. The dual-icon pattern is rare — only use it when both icons add distinct meaning, and keep the label short enough that the button does not become unwieldy.',
 );
 
 export const IconOnly: Story = withDescription(
@@ -1048,8 +1013,8 @@ export const IconOnly: Story = withDescription(
     args: {
       variant: 'secondary',
       size: 'M',
-      iconRightName: '3-dot',
-      iconRightScreenReaderText: 'More actions',
+      isRound: true,
+      children: <Icon name="3-dot" screenReaderText="More actions" />,
     },
     parameters: {
       docs: {
@@ -1057,9 +1022,14 @@ export const IconOnly: Story = withDescription(
           language: 'tsx',
           code: `
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function ButtonIconOnlyExample() {
-  return <Button variant="secondary" size="M" iconRightName="3-dot" iconRightScreenReaderText="More actions" />;
+  return (
+    <Button variant="secondary" size="M" isRound>
+      <Icon name="3-dot" screenReaderText="More actions" />
+    </Button>
+  );
 }
 
 export default ButtonIconOnlyExample;
@@ -1068,7 +1038,7 @@ export default ButtonIconOnlyExample;
       },
     },
   },
-  'Icon-only mode is triggered automatically when `children` is omitted and at least one icon prop is provided. The component adds `ds-button--icon-only` for square sizing. **Always** provide `iconRightScreenReaderText` (or `iconLeftScreenReaderText`) — the icon name `"3-dot"` is meaningless to a screen reader. This story uses `"More actions"` which clearly communicates the button\'s purpose.',
+  'Set `isRound` for square, no-padding sizing (`ds-button--round`) when there is no visible label. **Always** pass `screenReaderText` on the `Icon` in this mode — the icon name `"3-dot"` is meaningless to a screen reader, and with no other text content the button would otherwise have no accessible name at all. This story uses `"More actions"` which clearly communicates the button\'s purpose. Note: `isRound` already zeroes padding via CSS, so combining it with `hasHorizontalPadding={false}` is redundant — the two do not stack.',
 );
 
 export const IconOnlyAccessibility: Story = withDescription(
@@ -1077,13 +1047,12 @@ export const IconOnlyAccessibility: Story = withDescription(
       <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
         <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
           <p style={{ margin: 0, color: 'var(--color-semantic-destructive-600)' }}>
-            Bad — screen reader announces "3-dot" or "x" (the raw icon name)
+            Bad — no accessible name at all (screenReaderText omitted)
           </p>
           <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
-            {/* No screenReaderText override — falls back to icon name */}
-            <Button variant="secondary" type="button" iconRightName="3-dot" />
-            <Button variant="secondary" type="button" iconRightName="x" />
-            <Button variant="secondary" type="button" iconRightName="pencil" />
+            <Button variant="secondary" type="button" isRound><Icon name="3-dot" /></Button>
+            <Button variant="secondary" type="button" isRound><Icon name="x" /></Button>
+            <Button variant="secondary" type="button" isRound><Icon name="pencil" /></Button>
           </div>
         </div>
         <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
@@ -1091,9 +1060,9 @@ export const IconOnlyAccessibility: Story = withDescription(
             Good — screen reader announces a human-readable action name
           </p>
           <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
-            <Button variant="secondary" type="button" iconRightName="3-dot" iconRightScreenReaderText="More actions" />
-            <Button variant="secondary" type="button" iconRightName="x" iconRightScreenReaderText="Dismiss" />
-            <Button variant="secondary" type="button" iconRightName="pencil" iconRightScreenReaderText="Edit student details" />
+            <Button variant="secondary" type="button" isRound><Icon name="3-dot" screenReaderText="More actions" /></Button>
+            <Button variant="secondary" type="button" isRound><Icon name="x" screenReaderText="Dismiss" /></Button>
+            <Button variant="secondary" type="button" isRound><Icon name="pencil" screenReaderText="Edit student details" /></Button>
           </div>
         </div>
       </div>
@@ -1104,22 +1073,23 @@ export const IconOnlyAccessibility: Story = withDescription(
           language: 'tsx',
           code: `
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function ButtonIconOnlyAccessibilityExample() {
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
-      {/* Bad — screen reader announces raw icon names */}
+      {/* Bad — no accessible name at all */}
       <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
-        <Button variant="secondary" type="button" iconRightName="3-dot" />
-        <Button variant="secondary" type="button" iconRightName="x" />
-        <Button variant="secondary" type="button" iconRightName="pencil" />
+        <Button variant="secondary" type="button" isRound><Icon name="3-dot" /></Button>
+        <Button variant="secondary" type="button" isRound><Icon name="x" /></Button>
+        <Button variant="secondary" type="button" isRound><Icon name="pencil" /></Button>
       </div>
 
       {/* Good — human-readable action names */}
       <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
-        <Button variant="secondary" type="button" iconRightName="3-dot" iconRightScreenReaderText="More actions" />
-        <Button variant="secondary" type="button" iconRightName="x" iconRightScreenReaderText="Dismiss" />
-        <Button variant="secondary" type="button" iconRightName="pencil" iconRightScreenReaderText="Edit student details" />
+        <Button variant="secondary" type="button" isRound><Icon name="3-dot" screenReaderText="More actions" /></Button>
+        <Button variant="secondary" type="button" isRound><Icon name="x" screenReaderText="Dismiss" /></Button>
+        <Button variant="secondary" type="button" isRound><Icon name="pencil" screenReaderText="Edit student details" /></Button>
       </div>
     </div>
   );
@@ -1131,7 +1101,7 @@ export default ButtonIconOnlyAccessibilityExample;
       },
     },
   },
-  'Icon-only accessibility contrast. The top row has no `iconRightScreenReaderText` override — screen readers announce the raw icon names (`"3-dot"`, `"x"`, `"pencil"`). The bottom row overrides with human-readable action names. Always provide `iconLeftScreenReaderText` or `iconRightScreenReaderText` when using icon-only buttons — the icon name is almost never descriptive enough in context.',
+  'Icon-only accessibility contrast. The top row omits `screenReaderText` on the `Icon` — since Button no longer supplies a fallback, these buttons have **no accessible name at all**. The bottom row sets `screenReaderText` with human-readable action names. Always pass `screenReaderText` on the `Icon` when using `isRound` — the icon name is almost never descriptive enough in context, and unlike before, Button will not fall back to it for you.',
 );
 
 export const Disabled: Story = withDescription(
@@ -1190,72 +1160,6 @@ export default ButtonErrorStateExample;
   'The `error` prop adds a red border (`--color-semantic-destructive-500`) via `ds-button--error`. This is used by `SelectDropdown` and other form-field trigger buttons to indicate validation failure on the field. It is **purely visual** — no `aria-invalid` is set on the button itself. Consumers are responsible for communicating the error state to assistive tech (e.g. `aria-invalid` on the associated input).',
 );
 
-export const Borderless: Story = withDescription(
-  {
-    args: {
-      variant: 'tertiary',
-      size: 'M',
-      children: 'Settings',
-      iconLeftName: 'settings',
-      iconLeftScreenReaderText: 'Settings',
-      borderless: true,
-    },
-    parameters: {
-      docs: {
-        source: {
-          language: 'tsx',
-          code: `
-import { Button } from '@arbor-education/design-system.components';
-
-function ButtonBorderlessExample() {
-  return (
-    <Button variant="tertiary" size="M" iconLeftName="settings" iconLeftScreenReaderText="Settings" borderless>
-      Settings
-    </Button>
-  );
-}
-
-export default ButtonBorderlessExample;
-`.trim(),
-        },
-      },
-    },
-  },
-  'The `borderless` prop removes the border entirely via `ds-button--borderless`. Useful in toolbar contexts where a visible border would add visual noise — for example, icon-adjacent utility buttons in a rich text editor toolbar or a data grid header. Pairs naturally with `variant="tertiary"` and an icon.',
-);
-
-export const NoHorizontalPadding: Story = withDescription(
-  {
-    args: {
-      variant: 'text-link',
-      size: 'M',
-      children: 'View full attendance report',
-      hasHorizontalPadding: false,
-    },
-    parameters: {
-      docs: {
-        source: {
-          language: 'tsx',
-          code: `
-import { Button } from '@arbor-education/design-system.components';
-
-function ButtonNoHorizontalPaddingExample() {
-  return (
-    <Button variant="text-link" size="M" hasHorizontalPadding={false}>
-      View full attendance report
-    </Button>
-  );
-}
-
-export default ButtonNoHorizontalPaddingExample;
-`.trim(),
-        },
-      },
-    },
-  },
-  '`hasHorizontalPadding={false}` removes horizontal padding via `ds-button--no-horizontal-padding`. The canonical use case is a `text-link` variant sitting inline in a form label or table cell, where the default padding would indent the text away from the surrounding content. Do not use this as a general layout escape hatch — it is specifically for flush-mounted inline actions.',
-);
-
 export const FormTypeAttribute: Story = withDescription(
   {
     render: FormTypeAttributeTemplate,
@@ -1315,10 +1219,10 @@ export default FormTypeAttributeExample;
     },
   },
   [
-    '**Critical gotcha demo.** The `type` prop is explicitly omitted from `ButtonProps` via',
-    '`Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "onClick">`. This means `<Button>` never',
-    'sets a `type` attribute, and browsers default to `type="submit"`. Any `<Button>` inside a `<form>`',
-    'will submit that form on click unless you pass `type="button"` explicitly.',
+    '**Critical gotcha demo.** `type` is a typed prop, but `Button` never defaults it — there is no',
+    '`type = \'button\'` fallback in the component. This means `<Button>` never sets a `type` attribute',
+    'on its own, and browsers default to `type="submit"`. Any `<Button>` inside a `<form>` will submit',
+    'that form on click unless you pass `type="button"` explicitly.',
     '',
     'This story shows a form with both patterns side by side. The "Cancel" button uses `type="button"`',
     'so clicking it does not submit. The "Save attendance" button uses `type="submit"` to intentionally',
@@ -1326,6 +1230,77 @@ export default FormTypeAttributeExample;
   ].join(' '),
 );
 
+export const Borderless: Story = withDescription(
+  {
+    args: {
+      variant: 'tertiary',
+      size: 'M',
+      borderless: true,
+      children: (
+        <>
+          <Icon name="settings" />
+          Settings
+        </>
+      ),
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
+
+function ButtonBorderlessExample() {
+  return (
+    <Button variant="tertiary" size="M" borderless>
+      <Icon name="settings" />
+      Settings
+    </Button>
+  );
+}
+
+export default ButtonBorderlessExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The `borderless` prop removes the border entirely via `ds-button--borderless`. Useful in toolbar contexts where a visible border would add visual noise — for example, icon-adjacent utility buttons in a rich text editor toolbar or a data grid header. Pairs naturally with `variant="tertiary"` and a leading icon.',
+);
+
+export const NoHorizontalPadding: Story = withDescription(
+  {
+    args: {
+      variant: 'text-link',
+      size: 'M',
+      children: 'View full attendance report',
+      hasHorizontalPadding: false,
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonNoHorizontalPaddingExample() {
+  return (
+    <Button variant="text-link" size="M" hasHorizontalPadding={false}>
+      View full attendance report
+    </Button>
+  );
+}
+
+export default ButtonNoHorizontalPaddingExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  '`hasHorizontalPadding={false}` removes horizontal padding via `ds-button--no-horizontal-padding`. The canonical use case is a `text-link` variant sitting inline in a form label or table cell, where the default padding would indent the text away from the surrounding content. Do not use this as a general layout escape hatch — it is specifically for flush-mounted inline actions.',
+);
+
 export const LoadingComposition: Story = withDescription(
   {
     render: LoadingCompositionTemplate,
@@ -1336,6 +1311,7 @@ export const LoadingComposition: Story = withDescription(
           code: `
 import { useState } from 'react';
 import { Button } from '@arbor-education/design-system.components';
+import { Icon } from '@arbor-education/design-system.components';
 
 function LoadingCompositionExample() {
   const [loading, setLoading] = useState(false);
@@ -1359,10 +1335,9 @@ function LoadingCompositionExample() {
         variant="primary"
         type="button"
         disabled={loading}
-        iconLeftName={loading ? 'loader' : undefined}
-        iconLeftScreenReaderText={loading ? 'Loading, please wait' : undefined}
         onClick={handleClick}
       >
+        {loading && <Icon name="loader" screenReaderText="Loading, please wait" />}
         {loading ? 'Exporting...' : 'Export to CSV'}
       </Button>
     </div>
@@ -1376,10 +1351,10 @@ export default LoadingCompositionExample;
     },
   },
   [
-    'Button has **no built-in loading state** — compose one with `disabled`, `iconLeftName`, and a label change.',
-    'This pattern uses `disabled={loading}` to block interaction during the async operation, `iconLeftName="loader"`',
-    'to show a spinner icon, and `iconLeftScreenReaderText="Loading, please wait"` so screen reader users are',
-    'informed. After 2 seconds the mock export resolves and the button returns to its default state.',
+    'Button has **no built-in loading state** — compose one with `disabled`, a conditional `Icon`, and a label change.',
+    'This pattern uses `disabled={loading}` to block interaction during the async operation, a conditionally',
+    'rendered `<Icon name="loader" screenReaderText="Loading, please wait" />` to show a spinner icon with an',
+    'accessible announcement. After 2 seconds the mock export resolves and the button returns to its default state.',
     '',
     'The `loader` icon (`LoaderCircle` from Lucide) does not spin by default — animate it with a CSS',
     '`animation: spin 1s linear infinite` keyframe on the `svg` within the button if your design requires it.',
@@ -1460,5 +1435,5 @@ export default ClickTrackingExample;
       },
     },
   },
-  'Demonstrates that `onClick` fires correctly with each button activation (click, Space, Enter). The counter increments on every activation. Note `type="button"` — this story\'s button is not inside a form but it is good practice to always be explicit about `type` to avoid accidental form submissions.',
+  'Demonstrates that `onClick` fires correctly with each button activation (click, Space, Enter). The counter increments on every activation. Note `type="button"` — this story\'s button is not inside a form but it is good practice to always be explicit about `type` to avoid accidental form submissions. The `onClick` signature also accepts `...otherArgs: unknown[]` (non-standard) — this exists to support legacy callers that wrap `Button` and invoke the handler with extra arguments beyond the click event.',
 );