@arbor-education/design-system.components 0.12.0 → 0.13.1

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

@@ -1,9 +1,134 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+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';
+// ---------------------------------------------------------------------------
+// Component description — built as a joined array to avoid no-useless-escape
+// on backtick code spans inside template literals.
+//
+// The global DocsTemplate renders the description BEFORE the Primary story
+// and renders parameters.docs.relatedComponents as a markdown block at the
+// very bottom of the page (after Stories) — so "Related components" does NOT
+// belong in this description.
+// ---------------------------------------------------------------------------
+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.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '| Variant | Use when |',
+    '|---|---|',
+    '| `primary` | The single most important action in a page section — Save, Confirm, Continue |',
+    '| `secondary` | A supporting or alternative action — Cancel, Back, Edit |',
+    '| `tertiary` | A quiet, low-priority action — Clear filters, Reset, optional utility actions |',
+    '| `primary-destructive` | An irreversible, high-impact action — Delete permanently, Expel student |',
+    '| `secondary-destructive` | A softer destructive action that may have a confirmation step — Archive record |',
+    '| `text-link` | An inline contextual action embedded in a sentence or label |',
+    '| `dropdown` | A button styled as a dropdown trigger — uses `justify-content: space-between` so a trailing chevron icon aligns to the right edge. Used internally by `SelectDropdown`, `ColourPickerDropdown`, and `UserDropdown`, and available to consumers for custom dropdown triggers. |',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Instead of Button... | Use... | Why |',
+    '|---|---|---|',
+    '| URL navigation | `<a>` tag | Semantic: links navigate, buttons act |',
+    '| Tab switching | [`Tabs`](?path=/docs/components-tabs--docs) | Correct `role="tab"` semantics |',
+    '| Filter selection | [`Pill`](?path=/docs/components-pill--docs) | Purpose-built toggle for filter UI |',
+    '| Boolean on/off | [`Toggle`](?path=/docs/components-toggle--docs) or [`CheckboxInput`](?path=/docs/components-formfield-inputs-checkbox--docs) | Communicates checked state via ARIA |',
+    '',
+    '---',
+    '',
+    '### Design guidance',
+    '',
+    '- **One primary per section** — using multiple primary buttons in the same form or toolbar dilutes',
+    '  the visual hierarchy. Pick the single most important action.',
+    '- **Destructive tier** — use `primary-destructive` for permanent, unrecoverable operations (delete a',
+    '  student record, permanently remove data). Use `secondary-destructive` for softer operations that',
+    '  may have a confirmation step or are partially reversible (archive, suspend).',
+    '- **Tertiary** is for quiet utility actions. Do not use it as a "Cancel" button next to a Primary —',
+    '  use `secondary` for Cancel so the hierarchy reads clearly.',
+    '- **text-link** is for inline contextual actions. Do not use it as a Cancel in a confirm/cancel row.',
+].join('\n');
+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="submit"`. If this button lives inside a `<form>`, clicking it **will submit the form**',
+    'unless you explicitly pass `type="button"`.',
+    '',
+    '```tsx',
+    '// BAD — will submit any ancestor form',
+    '<Button variant="secondary" onClick={handleCancel}>Cancel</Button>',
+    '',
+    '// GOOD',
+    '<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`.',
+    '',
+    '```tsx',
+    '// BAD — screen reader says "3-dot"',
+    '<Button variant="secondary" iconRightName="3-dot" />',
+    '',
+    '// GOOD',
+    '<Button variant="secondary" iconRightName="3-dot" iconRightScreenReaderText="More actions" />',
+    '```',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- 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',
+    '- 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.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { Button } from '@arbor-education/design-system.components';",
+    '',
+    'function MyButton(props: Button.Props) { ... }',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `Button.Props` | Full props interface |',
+    "| `Button.Variant` | `'primary' \\| 'secondary' \\| 'tertiary' \\| 'primary-destructive' \\| 'secondary-destructive' \\| 'text-link' \\| 'dropdown'` |",
+    "| `Button.Size` | `'M' \\| 'S'` |",
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Icon](?path=/docs/components-icon--docs) · [Dropdown](?path=/docs/components-dropdown--docs) · [Pill](?path=/docs/components-pill--docs) · [Tabs](?path=/docs/components-tabs--docs) · [Toggle](?path=/docs/components-toggle--docs)',
+].join('\n');
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+function ButtonDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
 const meta = {
     title: 'Components/Button',
     component: Button,
     parameters: {
         layout: 'centered',
+        docs: {
+            page: ButtonDocsPage,
+        },
     },
     tags: ['autodocs'],
     argTypes: {
@@ -18,134 +143,1018 @@ const meta = {
                 'text-link',
                 'dropdown',
             ],
-            description: 'Button variant',
+            description: [
+                'Visual style and semantic hierarchy of the button.',
+                '`primary` — main CTA (brand green background, white text).',
+                '`secondary` — supporting action (outlined, brand-coloured text).',
+                '`tertiary` — quiet utility action (text-only style).',
+                '`primary-destructive` — irreversible destructive (red background, white text).',
+                '`secondary-destructive` — softer destructive (red text on white, inverts on hover).',
+                '`text-link` — inline contextual action (underlined text, no box).',
+                '`dropdown` — styled as a dropdown trigger (chevron-friendly layout); used internally by SelectDropdown and friends, also available to consumers.',
+            ].join(' '),
+            table: {
+                type: { summary: "'primary' | 'secondary' | 'tertiary' | 'primary-destructive' | 'secondary-destructive' | 'text-link' | 'dropdown'" },
+                defaultValue: { summary: "'primary'" },
+            },
         },
         size: {
             control: 'select',
             options: ['M', 'S'],
-            description: 'Button size',
+            description: [
+                'Height of the button.',
+                '`M` resolves to `--size-medium` (2.25rem / 36px).',
+                '`S` resolves to `--size-small` (2rem / 32px).',
+                'Note: the tertiary variant uses `--button-small-tertiary-*` tokens for both sizes',
+                'because `--button-medium-tertiary-*` tokens do not exist — this is a known token gap.',
+            ].join(' '),
+            table: {
+                type: { summary: "'M' | 'S'" },
+                defaultValue: { summary: "'M'" },
+            },
+        },
+        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`.',
+            ].join(' '),
+            table: {
+                type: { summary: 'React.ReactNode' },
+            },
         },
         disabled: {
             control: 'boolean',
-            description: 'Disable the button',
+            description: [
+                'Native HTML disabled attribute.',
+                'Applies `opacity: 0.5`, `cursor: not-allowed`, and `pointer-events: none`.',
+                'Removes the button from tab order. Do NOT simulate disabled with manual opacity — use this prop.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
         },
-        children: {
+        error: {
+            control: 'boolean',
+            description: [
+                'Adds a red border (`--color-semantic-destructive-500`) via `ds-button--error`.',
+                'Used by the `dropdown` variant to indicate form validation failure on a SelectDropdown field.',
+                'This is purely visual — it adds no ARIA semantics.',
+                'Consumers are responsible for communicating the error state to assistive tech (e.g. `aria-invalid` on the associated input, or `aria-describedby` pointing to an error message).',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        hasHorizontalPadding: {
+            control: 'boolean',
+            description: [
+                'When `false`, removes horizontal padding via `ds-button--no-horizontal-padding`.',
+                'Use for flush-mounted buttons — e.g. a `text-link` variant sitting inline in a form label',
+                'where you want the text to align with surrounding content without a left indent.',
+                'Do not use as a general layout escape hatch.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                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',
-            description: 'Button text',
+            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.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        borderless: {
+            control: 'boolean',
+            description: [
+                'Removes the border entirely via `ds-button--borderless`.',
+                'For toolbar and icon-button contexts where a visible border would be visually noisy.',
+                'Pairs well with `variant="tertiary"` and an icon.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
         },
         onClick: {
-            action: 'clicked',
+            description: [
+                'Click handler. Receives the `React.MouseEvent` as the first argument.',
+                'Additional spread arguments are accepted (non-standard) to support legacy callers.',
+                'Wire to the Controls action logger with `fn()` in meta.',
+            ].join(' '),
+            table: {
+                type: { summary: '(event: React.MouseEvent<HTMLButtonElement>, ...otherArgs: unknown[]) => void' },
+            },
+        },
+        className: {
+            control: 'text',
+            description: 'Additional CSS class names appended to the button element. Use sparingly — prefer variant and size props.',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: "''" },
+            },
         },
     },
 };
 export default meta;
-// Primary button
-export const Primary = {
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: { ...story.parameters?.docs, description: { story: description } },
+    },
+});
+// ---------------------------------------------------------------------------
+// Stateful template components
+// Named components avoid hooks-in-callbacks lint issues (react-hooks plugin not
+// configured — do NOT add eslint-disable comments for it).
+// ---------------------------------------------------------------------------
+const ClickTrackingTemplate = () => {
+    const [count, setCount] = useState(0);
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Button clicked", ' ', _jsx("strong", { children: count }), ' ', count === 1 ? 'time' : 'times'] }), _jsx(Button, { variant: "primary", type: "button", onClick: () => setCount(c => c + 1), children: "Save attendance" })] }));
+};
+const WithForwardRefTemplate = () => {
+    const buttonRef = useRef(null);
+    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: "Click the trigger to programmatically focus the primary button." }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)' }, children: [_jsx(Button, { variant: "secondary", type: "button", onClick: () => buttonRef.current?.focus(), children: "Focus primary button" }), _jsx(Button, { variant: "primary", type: "button", ref: buttonRef, children: "Save attendance" })] })] }));
+};
+const FormTypeAttributeTemplate = () => {
+    const [submitted, setSubmitted] = useState(false);
+    const [cancelled, setCancelled] = useState(false);
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', minWidth: '340px' }, children: [_jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Both buttons live inside a form. The Cancel button uses", ' ', _jsx("code", { children: "type=\"button\"" }), ' ', "so it does not submit. The Submit button uses", ' ', _jsx("code", { children: "type=\"submit\"" }), "."] }), submitted && (_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "Form submitted! (type=\"submit\" fired)" })), cancelled && !submitted && (_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Cancelled \u2014 form was NOT submitted." })), _jsxs("form", { onSubmit: (e) => {
+                    e.preventDefault();
+                    setSubmitted(true);
+                    setCancelled(false);
+                }, style: { display: 'flex', gap: 'var(--spacing-large)' }, children: [_jsx(Button, { variant: "secondary", type: "button", onClick: () => {
+                            setSubmitted(false);
+                            setCancelled(true);
+                        }, children: "Cancel" }), _jsx(Button, { variant: "primary", type: "submit", children: "Save attendance" })] })] }));
+};
+const LoadingCompositionTemplate = () => {
+    const [loading, setLoading] = useState(false);
+    const [done, setDone] = useState(false);
+    const handleClick = () => {
+        setLoading(true);
+        setDone(false);
+        setTimeout(() => {
+            setLoading(false);
+            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' })] }));
+};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
     args: {
         variant: 'primary',
-        children: 'Button Text',
         size: 'M',
+        children: 'Save attendance',
+        disabled: false,
+        error: false,
+        hasHorizontalPadding: true,
+        borderless: false,
     },
-};
-export const PrimaryIconOnly = {
+    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.');
+export const Primary = withDescription({
     args: {
-        ...Primary.args,
-        children: null,
-        iconRightName: 'info',
+        variant: 'primary',
+        size: 'M',
+        children: 'Save attendance',
     },
-};
-// Secondary button
-export const Secondary = {
-    args: {
-        ...Primary.args,
-        variant: 'secondary',
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonPrimaryExample() {
+  return <Button variant="primary" size="M">Save attendance</Button>;
+}
+
+export default ButtonPrimaryExample;
+`.trim(),
+            },
+        },
     },
-};
-export const SecondaryIconOnly = {
+}, 'The `primary` variant is the main call-to-action. Background resolves to `--button-medium-primary-default-color-background` → `--color-brand-600` (Arbor green). Use at most once per page section. All other actions should be `secondary` or lower in hierarchy.');
+export const Secondary = withDescription({
     args: {
-        ...Primary.args,
         variant: 'secondary',
-        children: null,
-        iconRightName: 'info',
+        size: 'M',
+        children: 'Cancel',
     },
-};
-// Tertiary button
-export const Tertiary = {
-    args: {
-        ...Primary.args,
-        variant: 'tertiary',
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonSecondaryExample() {
+  return <Button variant="secondary" size="M">Cancel</Button>;
+}
+
+export default ButtonSecondaryExample;
+`.trim(),
+            },
+        },
     },
-};
-export const TertiaryIconOnly = {
+}, 'The `secondary` variant is for supporting actions — Cancel, Back, Edit. Outlined with brand-coloured text. Use next to a `primary` button to form a confirm/cancel pair. Never use `text-link` as a Cancel button in a row with Primary.');
+export const Tertiary = withDescription({
     args: {
-        ...Primary.args,
-        children: null,
-        iconRightName: 'info',
         variant: 'tertiary',
+        size: 'M',
+        children: 'Clear filters',
     },
-};
-// Dropdown button
-export const Dropdown = {
-    args: {
-        ...Primary.args,
-        variant: 'dropdown',
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonTertiaryExample() {
+  return <Button variant="tertiary" size="M">Clear filters</Button>;
+}
+
+export default ButtonTertiaryExample;
+`.trim(),
+            },
+        },
     },
-};
-// Primary destructive button
-export const PrimaryDestructive = {
+}, [
+    'The `tertiary` variant is quiet and de-emphasised — for low-priority utility actions like "Clear filters", "Reset", or optional configuration.',
+    '',
+    '**Known token note:** the tertiary variant uses `--button-small-tertiary-*` tokens for **both** `M` and `S` sizes.',
+    '`--button-medium-tertiary-*` tokens do not exist in `tokens.scss`. The visual result is correct and intentional,',
+    'but the token name reflects "small" regardless of the `size` prop. This is a known gap in the token taxonomy.',
+].join(' '));
+export const PrimaryDestructive = withDescription({
     args: {
-        ...Primary.args,
         variant: 'primary-destructive',
+        size: 'M',
+        children: 'Delete permanently',
     },
-};
-export const PrimaryDestructiveIconOnly = {
-    args: {
-        ...Primary.args,
-        children: null,
-        iconRightName: 'info',
-        variant: 'primary-destructive',
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonPrimaryDestructiveExample() {
+  return <Button variant="primary-destructive" size="M">Delete permanently</Button>;
+}
+
+export default ButtonPrimaryDestructiveExample;
+`.trim(),
+            },
+        },
     },
-};
-// Secondary destructive button
-export const SecondaryDestructive = {
+}, 'The `primary-destructive` variant is for irreversible, high-impact actions — permanently deleting a student record, removing an enrolment, expelling a student. Background resolves to `--button-medium-primary-destructive-default-color-background` → `--color-semantic-destructive-500`. Always consider whether a confirmation Modal is warranted before this action executes.');
+export const SecondaryDestructive = withDescription({
     args: {
-        ...Primary.args,
         variant: 'secondary-destructive',
+        size: 'M',
+        children: 'Archive record',
     },
-};
-export const SecondaryDestructiveIconOnly = {
-    args: {
-        ...Primary.args,
-        children: null,
-        iconRightName: 'info',
-        variant: 'secondary-destructive',
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonSecondaryDestructiveExample() {
+  return <Button variant="secondary-destructive" size="M">Archive record</Button>;
+}
+
+export default ButtonSecondaryDestructiveExample;
+`.trim(),
+            },
+        },
     },
-};
-// Text link button
-export const TextLink = {
+}, 'The `secondary-destructive` variant is for softer destructive actions — archiving, suspending, removing from a group. Default state: red text on white background with red border. On hover: white text on red background (token-driven inversion, intentional). Use when the action is destructive but may have a confirmation step or is partially reversible.');
+export const TextLink = withDescription({
     args: {
-        ...Primary.args,
         variant: 'text-link',
+        size: 'M',
+        children: 'View full report',
     },
-};
-// Small buttons
-export const SmallPrimary = {
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonTextLinkExample() {
+  return <Button variant="text-link" size="M">View full report</Button>;
+}
+
+export default ButtonTextLinkExample;
+`.trim(),
+            },
+        },
+    },
+}, 'The `text-link` variant renders as underlined text with no box or padding — for inline contextual actions embedded in sentences, labels, or table cells. Do not use `text-link` in a confirm/cancel button row alongside Primary — that breaks affordance hierarchy. For inline placement, combine with `hasHorizontalPadding={false}` to align the text flush with surrounding content.');
+export const Dropdown = withDescription({
+    args: {
+        variant: 'dropdown',
+        size: 'M',
+        children: 'Select year group',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonDropdownExample() {
+  return (
+    <Button variant="dropdown" size="M" iconRightName="chevron-down" iconRightScreenReaderText="Open dropdown">
+      Select year group
+    </Button>
+  );
+}
+
+export default ButtonDropdownExample;
+`.trim(),
+            },
+        },
+    },
+}, [
+    '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.',
+].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" })] })] })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonAllVariantsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+      {/* Action hierarchy */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap' }}>
+        <Button variant="primary" type="button">Save attendance</Button>
+        <Button variant="secondary" type="button">Cancel</Button>
+        <Button variant="tertiary" type="button">Clear filters</Button>
+      </div>
+      {/* Destructive actions */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap' }}>
+        <Button variant="primary-destructive" type="button">Delete permanently</Button>
+        <Button variant="secondary-destructive" type="button">Archive record</Button>
+      </div>
+      {/* Specialised */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap' }}>
+        <Button variant="text-link" type="button">View full report</Button>
+        <Button variant="dropdown" type="button">Select year group</Button>
+      </div>
+    </div>
+  );
+}
+
+export default ButtonAllVariantsExample;
+`.trim(),
+            },
+        },
+    },
+}, 'All 7 variants at a glance, grouped by hierarchy tier. Action hierarchy (primary / secondary / tertiary), Destructive actions (primary-destructive / secondary-destructive), Specialised (text-link / dropdown). Use this story as a reference for the full visual range of the component.');
+export const AllSizes = 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: "Medium (M) \u2014 2.25rem / 36px via --size-medium" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsx(Button, { variant: "primary", size: "M", type: "button", children: "Save attendance" }), _jsx(Button, { variant: "secondary", size: "M", type: "button", children: "Cancel" }), _jsx(Button, { variant: "tertiary", size: "M", 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-grey-600)' }, children: "Small (S) \u2014 2rem / 32px via --size-small" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsx(Button, { variant: "primary", size: "S", type: "button", children: "Save attendance" }), _jsx(Button, { variant: "secondary", size: "S", type: "button", children: "Cancel" }), _jsx(Button, { variant: "tertiary", size: "S", type: "button", children: "Clear filters" })] })] })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonAllSizesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+      {/* Medium (M) — 2.25rem / 36px */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+        <Button variant="primary" size="M" type="button">Save attendance</Button>
+        <Button variant="secondary" size="M" type="button">Cancel</Button>
+        <Button variant="tertiary" size="M" type="button">Clear filters</Button>
+      </div>
+
+      {/* Small (S) — 2rem / 32px */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+        <Button variant="primary" size="S" type="button">Save attendance</Button>
+        <Button variant="secondary" size="S" type="button">Cancel</Button>
+        <Button variant="tertiary" size="S" type="button">Clear filters</Button>
+      </div>
+    </div>
+  );
+}
+
+export default ButtonAllSizesExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Both sizes side by side. `M` resolves to `--size-medium` (2.25rem, 36px). `S` resolves to `--size-small` (2rem, 32px). Heights are entirely token-driven — never hardcode a height on a button wrapper.');
+export const SmallPrimary = withDescription({
     args: {
-        ...Primary.args,
+        variant: 'primary',
         size: 'S',
+        children: 'Save attendance',
     },
-};
-export const SmallSecondary = {
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonSmallPrimaryExample() {
+  return <Button variant="primary" size="S">Save attendance</Button>;
+}
+
+export default ButtonSmallPrimaryExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Small primary button — 2rem / 32px height via `--size-small`. Use in dense toolbars or compact table headers where the medium size would feel too tall.');
+export const SmallSecondary = withDescription({
     args: {
-        ...Secondary.args,
+        variant: 'secondary',
         size: 'S',
+        children: 'Cancel',
     },
-};
-// Disabled button
-export const Disabled = {
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonSmallSecondaryExample() {
+  return <Button variant="secondary" size="S">Cancel</Button>;
+}
+
+export default ButtonSmallSecondaryExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Small secondary button. Matches the small primary in height for pairing in compact confirm/cancel rows.');
+export const WithIconLeft = withDescription({
+    args: {
+        variant: 'primary',
+        size: 'M',
+        children: 'Export to CSV',
+        iconLeftName: 'download',
+        iconLeftScreenReaderText: 'Download',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonWithIconLeftExample() {
+  return (
+    <Button variant="primary" size="M" iconLeftName="download" iconLeftScreenReaderText="Download">
+      Export to CSV
+    </Button>
+  );
+}
+
+export default ButtonWithIconLeftExample;
+`.trim(),
+            },
+        },
+    },
+}, '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.');
+export const WithIconRight = withDescription({
+    args: {
+        variant: 'secondary',
+        size: 'M',
+        children: 'Send to parents',
+        iconRightName: 'send',
+        iconRightScreenReaderText: 'Send',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonWithIconRightExample() {
+  return (
+    <Button variant="secondary" size="M" iconRightName="send" iconRightScreenReaderText="Send">
+      Send to parents
+    </Button>
+  );
+}
+
+export default ButtonWithIconRightExample;
+`.trim(),
+            },
+        },
+    },
+}, '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.');
+export const WithBothIcons = withDescription({
+    args: {
+        variant: 'primary',
+        size: 'M',
+        children: 'Generate report',
+        iconLeftName: 'sparkles',
+        iconLeftScreenReaderText: 'AI generated',
+        iconRightName: 'arrow-right',
+        iconRightScreenReaderText: 'Continue',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonWithBothIconsExample() {
+  return (
+    <Button
+      variant="primary"
+      size="M"
+      iconLeftName="sparkles"
+      iconLeftScreenReaderText="AI generated"
+      iconRightName="arrow-right"
+      iconRightScreenReaderText="Continue"
+    >
+      Generate report
+    </Button>
+  );
+}
+
+export default ButtonWithBothIconsExample;
+`.trim(),
+            },
+        },
+    },
+}, '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.');
+export const IconOnly = withDescription({
+    args: {
+        variant: 'secondary',
+        size: 'M',
+        iconRightName: '3-dot',
+        iconRightScreenReaderText: 'More actions',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonIconOnlyExample() {
+  return <Button variant="secondary" size="M" iconRightName="3-dot" iconRightScreenReaderText="More actions" />;
+}
+
+export default ButtonIconOnlyExample;
+`.trim(),
+            },
+        },
+    },
+}, '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.');
+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" })] })] })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } 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 */}
+      <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" />
+      </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" />
+      </div>
+    </div>
+  );
+}
+
+export default ButtonIconOnlyAccessibilityExample;
+`.trim(),
+            },
+        },
+    },
+}, '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.');
+export const Disabled = withDescription({
     args: {
-        ...Primary.args,
+        variant: 'primary',
+        size: 'M',
+        children: 'Save attendance',
         disabled: true,
     },
-};
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonDisabledExample() {
+  return <Button variant="primary" size="M" disabled>Save attendance</Button>;
+}
+
+export default ButtonDisabledExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Native HTML `disabled` attribute. Applies `opacity: 0.5`, `cursor: not-allowed`, and `pointer-events: none`. Removes the button from tab order. Do NOT simulate disabled with manual opacity or CSS — use this prop so the browser and assistive technologies also receive the disabled signal.');
+export const ErrorState = withDescription({
+    args: {
+        variant: 'dropdown',
+        size: 'M',
+        children: 'Select year group',
+        error: true,
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonErrorStateExample() {
+  return <Button variant="dropdown" size="M" error>Select year group</Button>;
+}
+
+export default ButtonErrorStateExample;
+`.trim(),
+            },
+        },
+    },
+}, '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: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Button } from '@arbor-education/design-system.components';
+
+function FormTypeAttributeExample() {
+  const [submitted, setSubmitted] = useState(false);
+  const [cancelled, setCancelled] = useState(false);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', minWidth: '340px' }}>
+      {submitted && (
+        <p style={{ color: 'var(--color-semantic-success-600)' }}>
+          Form submitted! (type="submit" fired)
+        </p>
+      )}
+      {cancelled && !submitted && (
+        <p style={{ color: 'var(--color-grey-600)' }}>
+          Cancelled — form was NOT submitted.
+        </p>
+      )}
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          setSubmitted(true);
+          setCancelled(false);
+        }}
+        style={{ display: 'flex', gap: 'var(--spacing-large)' }}
+      >
+        <Button
+          variant="secondary"
+          type="button"
+          onClick={() => {
+            setSubmitted(false);
+            setCancelled(true);
+          }}
+        >
+          Cancel
+        </Button>
+        <Button variant="primary" type="submit">
+          Save attendance
+        </Button>
+      </form>
+    </div>
+  );
+}
+
+export default FormTypeAttributeExample;
+`.trim(),
+            },
+        },
+    },
+}, [
+    '**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.',
+    '',
+    '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 LoadingComposition = withDescription({
+    render: LoadingCompositionTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Button } from '@arbor-education/design-system.components';
+
+function LoadingCompositionExample() {
+  const [loading, setLoading] = useState(false);
+  const [done, setDone] = useState(false);
+
+  const handleClick = () => {
+    setLoading(true);
+    setDone(false);
+    setTimeout(() => {
+      setLoading(false);
+      setDone(true);
+    }, 2000);
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+      {done && (
+        <p style={{ color: 'var(--color-semantic-success-600)' }}>Exported successfully!</p>
+      )}
+      <Button
+        variant="primary"
+        type="button"
+        disabled={loading}
+        iconLeftName={loading ? 'loader' : undefined}
+        iconLeftScreenReaderText={loading ? 'Loading, please wait' : undefined}
+        onClick={handleClick}
+      >
+        {loading ? 'Exporting...' : 'Export to CSV'}
+      </Button>
+    </div>
+  );
+}
+
+export default LoadingCompositionExample;
+`.trim(),
+            },
+        },
+    },
+}, [
+    '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.',
+    '',
+    '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.',
+].join(' '));
+export const WithForwardRef = withDescription({
+    render: WithForwardRefTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useRef } from 'react';
+import { Button } from '@arbor-education/design-system.components';
+
+function WithForwardRefExample() {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+      <p style={{ color: 'var(--color-grey-600)' }}>
+        Click the trigger to programmatically focus the primary button.
+      </p>
+      <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
+        <Button
+          variant="secondary"
+          type="button"
+          onClick={() => buttonRef.current?.focus()}
+        >
+          Focus primary button
+        </Button>
+        <Button variant="primary" type="button" ref={buttonRef}>
+          Save attendance
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export default WithForwardRefExample;
+`.trim(),
+            },
+        },
+    },
+}, '`Button` uses `forwardRef` — it exposes the underlying `<button>` DOM node via `ref`. This story demonstrates programmatic focus: clicking "Focus primary button" calls `buttonRef.current?.focus()` on the second button. Common real-world uses: restoring focus after a modal closes, advancing focus in a multi-step form, or triggering a button from a keyboard shortcut handler.');
+export const ClickTracking = withDescription({
+    render: ClickTrackingTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Button } from '@arbor-education/design-system.components';
+
+function ClickTrackingExample() {
+  const [count, setCount] = useState(0);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+      <p style={{ color: 'var(--color-grey-600)' }}>
+        Button clicked <strong>{count}</strong> {count === 1 ? 'time' : 'times'}
+      </p>
+      <Button variant="primary" type="button" onClick={() => setCount(c => c + 1)}>
+        Save attendance
+      </Button>
+    </div>
+  );
+}
+
+export default ClickTrackingExample;
+`.trim(),
+            },
+        },
+    },
+}, '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.');
 //# sourceMappingURL=Button.stories.js.map