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

package/dist/components/button/Button.stories.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
 import { useState, useRef } from 'react';
 import { Button } from './Button.js';
+import { Icon } from '../icon/Icon.js';
 // ---------------------------------------------------------------------------
 // Component description — built as a joined array to avoid no-useless-escape
 // on backtick code spans inside template literals.
@@ -13,8 +14,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 = [
     '### When to use',
@@ -57,9 +59,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"`.',
     '',
@@ -71,17 +74,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>',
     '```',
     '',
     '---',
@@ -91,10 +99,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.',
     '',
     '---',
     '',
@@ -176,10 +206,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' },
@@ -223,94 +252,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: {
@@ -392,7 +343,7 @@ const LoadingCompositionTemplate = () => {
             setDone(true);
         }, 2000);
     };
-    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Button has no built-in loading state \u2014 compose it with disabled + a loader icon." }), done && (_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "Exported successfully!" })), _jsx(Button, { variant: "primary", type: "button", disabled: loading, iconLeftName: loading ? 'loader' : undefined, iconLeftScreenReaderText: loading ? 'Loading, please wait' : undefined, onClick: handleClick, children: loading ? 'Exporting...' : 'Export to CSV' })] }));
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Button has no built-in loading state \u2014 compose it with disabled + a loader icon." }), done && (_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "Exported successfully!" })), _jsxs(Button, { variant: "primary", type: "button", disabled: loading, onClick: handleClick, children: [loading && _jsx(Icon, { name: "loader", screenReaderText: "Loading, please wait" }), loading ? 'Exporting...' : 'Export to CSV'] })] }));
 };
 // ---------------------------------------------------------------------------
 // Stories
@@ -408,7 +359,7 @@ export const Default = withDescription({
         borderless: false,
     },
     render: args => _jsx(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 = withDescription({
     args: {
         variant: 'primary',
@@ -557,7 +508,7 @@ export const Dropdown = withDescription({
     args: {
         variant: 'dropdown',
         size: 'M',
-        children: 'Select year group',
+        children: (_jsxs(_Fragment, { children: ["Select year group", _jsx(Icon, { name: "chevron-down" })] })),
     },
     parameters: {
         docs: {
@@ -565,11 +516,13 @@ export const Dropdown = 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>
   );
 }
@@ -583,8 +536,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(' '));
 export const AllVariants = withDescription({
     render: () => (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Action hierarchy" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap' }, children: [_jsx(Button, { variant: "primary", type: "button", children: "Save attendance" }), _jsx(Button, { variant: "secondary", type: "button", children: "Cancel" }), _jsx(Button, { variant: "tertiary", type: "button", children: "Clear filters" })] })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-destructive-600)' }, children: "Destructive actions" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap' }, children: [_jsx(Button, { variant: "primary-destructive", type: "button", children: "Delete permanently" }), _jsx(Button, { variant: "secondary-destructive", type: "button", children: "Archive record" })] })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Specialised" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap' }, children: [_jsx(Button, { variant: "text-link", type: "button", children: "View full report" }), _jsx(Button, { variant: "dropdown", type: "button", children: "Select year group" })] })] })] })),
@@ -709,9 +662,7 @@ export const WithIconLeft = withDescription({
     args: {
         variant: 'primary',
         size: 'M',
-        children: 'Export to CSV',
-        iconLeftName: 'download',
-        iconLeftScreenReaderText: 'Download',
+        children: (_jsxs(_Fragment, { children: [_jsx(Icon, { name: "download" }), "Export to CSV"] })),
     },
     parameters: {
         docs: {
@@ -719,10 +670,12 @@ export const WithIconLeft = 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>
   );
@@ -733,14 +686,12 @@ 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 = withDescription({
     args: {
         variant: 'secondary',
         size: 'M',
-        children: 'Send to parents',
-        iconRightName: 'send',
-        iconRightScreenReaderText: 'Send',
+        children: (_jsxs(_Fragment, { children: ["Send to parents", _jsx(Icon, { name: "send" })] })),
     },
     parameters: {
         docs: {
@@ -748,11 +699,13 @@ export const WithIconRight = 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>
   );
 }
@@ -762,16 +715,12 @@ 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 = withDescription({
     args: {
         variant: 'primary',
         size: 'M',
-        children: 'Generate report',
-        iconLeftName: 'sparkles',
-        iconLeftScreenReaderText: 'AI generated',
-        iconRightName: 'arrow-right',
-        iconRightScreenReaderText: 'Continue',
+        children: (_jsxs(_Fragment, { children: [_jsx(Icon, { name: "sparkles", screenReaderText: "AI generated" }), "Generate report", _jsx(Icon, { name: "arrow-right" })] })),
     },
     parameters: {
         docs: {
@@ -779,18 +728,14 @@ export const WithBothIcons = 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>
   );
 }
@@ -800,13 +745,13 @@ 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 = withDescription({
     args: {
         variant: 'secondary',
         size: 'M',
-        iconRightName: '3-dot',
-        iconRightScreenReaderText: 'More actions',
+        isRound: true,
+        children: _jsx(Icon, { name: "3-dot", screenReaderText: "More actions" }),
     },
     parameters: {
         docs: {
@@ -814,9 +759,14 @@ export const IconOnly = 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;
@@ -824,31 +774,32 @@ 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 = withDescription({
-    render: () => (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-destructive-600)' }, children: "Bad \u2014 screen reader announces \"3-dot\" or \"x\" (the raw icon name)" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)' }, children: [_jsx(Button, { variant: "secondary", type: "button", iconRightName: "3-dot" }), _jsx(Button, { variant: "secondary", type: "button", iconRightName: "x" }), _jsx(Button, { variant: "secondary", type: "button", iconRightName: "pencil" })] })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "Good \u2014 screen reader announces a human-readable action name" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)' }, children: [_jsx(Button, { variant: "secondary", type: "button", iconRightName: "3-dot", iconRightScreenReaderText: "More actions" }), _jsx(Button, { variant: "secondary", type: "button", iconRightName: "x", iconRightScreenReaderText: "Dismiss" }), _jsx(Button, { variant: "secondary", type: "button", iconRightName: "pencil", iconRightScreenReaderText: "Edit student details" })] })] })] })),
+    render: () => (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-destructive-600)' }, children: "Bad \u2014 no accessible name at all (screenReaderText omitted)" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)' }, children: [_jsx(Button, { variant: "secondary", type: "button", isRound: true, children: _jsx(Icon, { name: "3-dot" }) }), _jsx(Button, { variant: "secondary", type: "button", isRound: true, children: _jsx(Icon, { name: "x" }) }), _jsx(Button, { variant: "secondary", type: "button", isRound: true, children: _jsx(Icon, { name: "pencil" }) })] })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "Good \u2014 screen reader announces a human-readable action name" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)' }, children: [_jsx(Button, { variant: "secondary", type: "button", isRound: true, children: _jsx(Icon, { name: "3-dot", screenReaderText: "More actions" }) }), _jsx(Button, { variant: "secondary", type: "button", isRound: true, children: _jsx(Icon, { name: "x", screenReaderText: "Dismiss" }) }), _jsx(Button, { variant: "secondary", type: "button", isRound: true, children: _jsx(Icon, { name: "pencil", screenReaderText: "Edit student details" }) })] })] })] })),
     parameters: {
         docs: {
             source: {
                 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>
   );
@@ -859,7 +810,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 = withDescription({
     args: {
         variant: 'primary',
@@ -908,64 +859,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 = 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 = 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 = withDescription({
     render: FormTypeAttributeTemplate,
     parameters: {
@@ -1023,15 +916,73 @@ 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',
     'submit. Click both and watch the status message.',
 ].join(' '));
+export const Borderless = withDescription({
+    args: {
+        variant: 'tertiary',
+        size: 'M',
+        borderless: true,
+        children: (_jsxs(_Fragment, { children: [_jsx(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 = 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 = withDescription({
     render: LoadingCompositionTemplate,
     parameters: {
@@ -1041,6 +992,7 @@ export const LoadingComposition = 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);
@@ -1064,10 +1016,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>
@@ -1080,10 +1031,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.',
@@ -1156,5 +1107,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.');
 //# sourceMappingURL=Button.stories.js.map