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

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

@@ -1,11 +1,167 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+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 (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
 const meta = {
   title: 'Components/Button',
   component: Button,
   parameters: {
     layout: 'centered',
+    docs: {
+      page: ButtonDocsPage,
+    },
   },
   tags: ['autodocs'],
   argTypes: {
@@ -20,23 +176,205 @@ 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: 'Button 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: [
+        '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: "''" },
+      },
     },
   },
 } satisfies Meta<typeof Button>;
@@ -44,126 +382,1083 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Primary button
-export const Primary: Story = {
-  args: {
-    variant: 'primary',
-    children: 'Button Text',
-    size: 'M',
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story: Story, description: string): Story => ({
+  ...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 (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+      <p style={{ margin: 0, 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 const PrimaryIconOnly: Story = {
-  args: {
-    ...Primary.args,
-    children: null,
-    iconRightName: 'info',
-  },
+const WithForwardRefTemplate = () => {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+      <p style={{ margin: 0, 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>
+  );
 };
 
-// Secondary button
-export const Secondary: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'secondary',
-  },
+const FormTypeAttributeTemplate = () => {
+  const [submitted, setSubmitted] = useState(false);
+  const [cancelled, setCancelled] = useState(false);
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', minWidth: '340px' }}>
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Both buttons live inside a form. The Cancel button uses
+        {' '}
+        <code>type="button"</code>
+        {' '}
+        so it does not submit. The Submit button uses
+        {' '}
+        <code>type="submit"</code>
+        .
+      </p>
+      {submitted && (
+        <p style={{ margin: 0, color: 'var(--color-semantic-success-600)' }}>
+          Form submitted! (type="submit" fired)
+        </p>
+      )}
+      {cancelled && !submitted && (
+        <p style={{ margin: 0, 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 const SecondaryIconOnly: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'secondary',
-    children: null,
-    iconRightName: 'info',
-  },
+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 (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Button has no built-in loading state — compose it with disabled + a loader icon.
+      </p>
+      {done && (
+        <p style={{ margin: 0, 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>
+  );
 };
 
-// Tertiary button
-export const Tertiary: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'tertiary',
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      variant: 'primary',
+      size: 'M',
+      children: 'Save attendance',
+      disabled: false,
+      error: false,
+      hasHorizontalPadding: true,
+      borderless: false,
+    },
+    render: args => <Button {...args} />,
   },
-};
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore variants, sizes, icons, and states. Tip: try setting `iconLeftName` to `"save"` or `"plus"` to see the icon slot in action.',
+);
+
+export const Primary: Story = withDescription(
+  {
+    args: {
+      variant: 'primary',
+      size: 'M',
+      children: 'Save attendance',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
 
-export const TertiaryIconOnly: Story = {
-  args: {
-    ...Primary.args,
-    children: null,
-    iconRightName: 'info',
-    variant: 'tertiary',
+function ButtonPrimaryExample() {
+  return <Button variant="primary" size="M">Save attendance</Button>;
+}
+
+export default ButtonPrimaryExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  '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: Story = withDescription(
+  {
+    args: {
+      variant: 'secondary',
+      size: 'M',
+      children: 'Cancel',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonSecondaryExample() {
+  return <Button variant="secondary" size="M">Cancel</Button>;
+}
 
-// Dropdown button
-export const Dropdown: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'dropdown',
+export default ButtonSecondaryExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  '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: Story = withDescription(
+  {
+    args: {
+      variant: 'tertiary',
+      size: 'M',
+      children: 'Clear filters',
+    },
+    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>;
+}
 
-// Primary destructive button
-export const PrimaryDestructive: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'primary-destructive',
+export default ButtonTertiaryExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '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: Story = withDescription(
+  {
+    args: {
+      variant: 'primary-destructive',
+      size: 'M',
+      children: 'Delete permanently',
+    },
+    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 const PrimaryDestructiveIconOnly: Story = {
-  args: {
-    ...Primary.args,
-    children: null,
-    iconRightName: 'info',
-    variant: 'primary-destructive',
+export default ButtonPrimaryDestructiveExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  '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: Story = withDescription(
+  {
+    args: {
+      variant: 'secondary-destructive',
+      size: 'M',
+      children: 'Archive record',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
 
-// Secondary destructive button
-export const SecondaryDestructive: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'secondary-destructive',
+function ButtonSecondaryDestructiveExample() {
+  return <Button variant="secondary-destructive" size="M">Archive record</Button>;
+}
+
+export default ButtonSecondaryDestructiveExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  '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: Story = withDescription(
+  {
+    args: {
+      variant: 'text-link',
+      size: 'M',
+      children: 'View full report',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
 
-export const SecondaryDestructiveIconOnly: Story = {
-  args: {
-    ...Primary.args,
-    children: null,
-    iconRightName: 'info',
-    variant: 'secondary-destructive',
+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.',
+);
 
-// Text link button
-export const TextLink: Story = {
-  args: {
-    ...Primary.args,
-    variant: 'text-link',
+export const Dropdown: Story = 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(' '),
+);
 
-// Small buttons
-export const SmallPrimary: Story = {
-  args: {
-    ...Primary.args,
-    size: 'S',
+export const AllVariants: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+        {/* Group 1: Action hierarchy */}
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>Action hierarchy</p>
+          <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>
+        </div>
+        {/* Group 2: Destructive actions */}
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-semantic-destructive-600)' }}>Destructive actions</p>
+          <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>
+        </div>
+        {/* Group 3: Specialised */}
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>Specialised</p>
+          <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>
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>Medium (M) — 2.25rem / 36px via --size-medium</p>
+          <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>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>Small (S) — 2rem / 32px via --size-small</p>
+          <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>
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
 
-export const SmallSecondary: Story = {
-  args: {
-    ...Secondary.args,
-    size: 'S',
+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: Story = withDescription(
+  {
+    args: {
+      variant: 'primary',
+      size: 'S',
+      children: 'Save attendance',
+    },
+    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>;
+}
 
-// Disabled button
-export const Disabled: Story = {
-  args: {
-    ...Primary.args,
-    disabled: true,
+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: Story = withDescription(
+  {
+    args: {
+      variant: 'secondary',
+      size: 'S',
+      children: 'Cancel',
+    },
+    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: Story = 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: Story = 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: Story = 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: Story = 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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-semantic-destructive-600)' }}>
+            Bad — screen reader announces "3-dot" or "x" (the raw icon name)
+          </p>
+          <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
+            {/* No screenReaderText override — falls back to icon name */}
+            <Button variant="secondary" type="button" iconRightName="3-dot" />
+            <Button variant="secondary" type="button" iconRightName="x" />
+            <Button variant="secondary" type="button" iconRightName="pencil" />
+          </div>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p style={{ margin: 0, color: 'var(--color-semantic-success-600)' }}>
+            Good — screen reader announces a human-readable action name
+          </p>
+          <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
+            <Button variant="secondary" type="button" iconRightName="3-dot" iconRightScreenReaderText="More actions" />
+            <Button variant="secondary" type="button" iconRightName="x" iconRightScreenReaderText="Dismiss" />
+            <Button variant="secondary" type="button" iconRightName="pencil" iconRightScreenReaderText="Edit student details" />
+          </div>
+        </div>
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    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: Story = 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: Story = withDescription(
+  {
+    args: {
+      variant: 'tertiary',
+      size: 'M',
+      children: 'Settings',
+      iconLeftName: 'settings',
+      iconLeftScreenReaderText: 'Settings',
+      borderless: true,
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonBorderlessExample() {
+  return (
+    <Button variant="tertiary" size="M" iconLeftName="settings" iconLeftScreenReaderText="Settings" borderless>
+      Settings
+    </Button>
+  );
+}
+
+export default ButtonBorderlessExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The `borderless` prop removes the border entirely via `ds-button--borderless`. Useful in toolbar contexts where a visible border would add visual noise — for example, icon-adjacent utility buttons in a rich text editor toolbar or a data grid header. Pairs naturally with `variant="tertiary"` and an icon.',
+);
+
+export const NoHorizontalPadding: Story = withDescription(
+  {
+    args: {
+      variant: 'text-link',
+      size: 'M',
+      children: 'View full attendance report',
+      hasHorizontalPadding: false,
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function ButtonNoHorizontalPaddingExample() {
+  return (
+    <Button variant="text-link" size="M" hasHorizontalPadding={false}>
+      View full attendance report
+    </Button>
+  );
+}
+
+export default ButtonNoHorizontalPaddingExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  '`hasHorizontalPadding={false}` removes horizontal padding via `ds-button--no-horizontal-padding`. The canonical use case is a `text-link` variant sitting inline in a form label or table cell, where the default padding would indent the text away from the surrounding content. Do not use this as a general layout escape hatch — it is specifically for flush-mounted inline actions.',
+);
+
+export const FormTypeAttribute: Story = withDescription(
+  {
+    render: FormTypeAttributeTemplate,
+    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: Story = 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: Story = 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: Story = 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.',
+);