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

package/src/components/icon/Icon.stories.tsx

@@ -1,30 +1,1464 @@
-import type { Meta } from '@storybook/react-vite';
+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 { Button } from 'Components/button/Button';
 import { Icon } from './Icon';
 import { allowedIcons } from './allowedIcons';
 import { iconSizes } from './types';
 
-const meta: Meta<typeof Icon> = {
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Icon renders a single SVG icon from the Arbor design system icon set — built on the',
+  '[Lucide](https://lucide.dev) library with a small set of custom Arbor-specific additions.',
+  'Every icon is named with a kebab-case key and accessed via the `name` prop.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Support an action** — a leading `plus` icon before "Add student" makes the button scannable at a glance',
+  '- **Indicate status** — `circle-check`, `triangle-alert`, `circle-x` paired with status text communicate severity',
+  '- **Reinforce key information** — `graduation-cap` next to a student name, `date` next to a date field',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '- **As decoration or filler** — every icon must earn its place. Icons that add no meaning create visual noise',
+  '  and slow down scanning.',
+  '- **As the sole communicator of critical meaning** — colour-blind users and screen reader users depend on',
+  '  text alongside icons. An icon alone is never sufficient for critical information.',
+  '',
+  '---',
+  '',
+  '### Design guidance',
+  '',
+  '#### Three sizes only',
+  '',
+  'Arbor uses exactly three icon sizes (Confluence page 2431778909):',
+  '',
+  '| Size | Token | Use when |',
+  '|---|---|---|',
+  '| `12` | `--icon-size-xsmall` | Dense UI only — table cells, compact lists, tight badges |',
+  '| `16` | `--icon-size-small` | **Default** — almost every icon in the system |',
+  '| `24` | `--icon-size-medium` | High-significance only — empty states, hero callouts |',
+  '',
+  'The token names (`--icon-size-xsmall`, `--icon-size-small`, `--icon-size-medium`) are consumed by',
+  'other SCSS files (e.g. Checkbox, NumberInput) for sizing adjacent containers. The `Icon` component',
+  'itself takes the numeric value directly (`size={16}`) — but if you need to size a container around',
+  'an icon, reference the token.',
+  '',
+  '**Sizes do not change across breakpoints** — layout changes; icon sizes do not.',
+  '',
+  '#### Lucide outline set',
+  '',
+  'Arbor uses the Lucide outline (stroke) icon set. Do not mix filled styles unless it is a',
+  'deliberate system-wide decision. The exception is the `check-solid`, `x-solid`, and `favourite-filled`',
+  'variants — these are purpose-built for specific semantic emphasis states.',
+  '',
+  '#### Icon placement',
+  '',
+  '- **Icon before label** — the default pattern for action buttons and form labels',
+  '- **Trailing icons** — use for action-indicator icons: `chevron-down` (opens menu), `external-link`',
+  '  (opens new tab), `arrow-right` (advances a step). These communicate what happens AFTER the action.',
+  '- **Icon-only** — only when the meaning is completely unambiguous (e.g. a close button on a modal',
+  '  after the user has already opened it) OR when space is severely constrained. Always add an',
+  '  accessible label AND a tooltip in icon-only contexts.',
+  '',
+  '#### `currentColor` is a powerful default',
+  '',
+  'The `color` prop defaults to `"currentColor"`, so the icon inherits the text colour of its parent',
+  'element. This is especially useful for icon + label pairings — style the wrapper once and the icon',
+  'tracks the label through state changes (hover, active, disabled) for free.',
+  '',
+  '```tsx',
+  '// Icon inherits the wrapper colour — the icon and label stay in sync.',
+  '<span style={{ color: "var(--color-brand-700)" }}>',
+  '  <Icon name="pencil" />',
+  '  Edit year group',
+  '</span>',
+  '```',
+  '',
+  'Pass `color` explicitly when:',
+  '',
+  '- The icon carries a **specific semantic meaning** regardless of context — status icons where',
+  '  the colour IS the message (info / success / warning / error)',
+  '- The icon must stay a fixed brand or accent colour independent of surrounding text',
+  '',
+  '```tsx',
+  '// BAD — hardcoded hex breaks theming and dark mode',
+  '<Icon name="circle-check" color="#078427" />',
+  '',
+  '// GOOD — use a design token so the colour travels with the theme',
+  '<Icon name="circle-check" color="var(--color-semantic-success-600)" />',
+  '```',
+  '',
+  '---',
+  '',
+  '### Named icon aliases worth knowing',
+  '',
+  '| `name` value | Renders | Notes |',
+  '|---|---|---|',
+  '| `grab` | GripVertical | Drag handle — always pair with drag-and-drop behaviour |',
+  '| `date` | CalendarFold | Preferred alias for calendar/date field icons |',
+  '| `staff` | GraduationCap | Same icon as `graduation-cap` — use `staff` for staff contexts |',
+  '| `guardians` | Users | Use for parent/guardian relationships |',
+  '| `group` | UsersRound | Use for student groups and cohorts |',
+  '| `3-dot` | EllipsisVertical | Same icon as `ellipsis-vertical` — canonical Arbor alias for "more actions" menus |',
+  '| `loader` | LoaderCircle | Loading spinner glyph. No rotation is applied by the Icon component itself — add a `spin` CSS animation on the parent or via `className` if your design calls for rotation |',
+  '| `sorting` | ArrowDownUp | Table column sort toggle |',
+  '| `shrink` | Minimize2 | Collapse / exit fullscreen |',
+  '',
+  '---',
+  '',
+  '### Custom and solid variants',
+  '',
+  '| `name` | Description |',
+  '|---|---|',
+  '| `check-solid` | Filled check mark — for confirmation emphasis (e.g. "saved" state) |',
+  '| `x-solid` | Filled X — for rejection/remove emphasis |',
+  '| `favourite-filled` | Star with fill — for active/selected favourite state |',
+  '| `favourite-outline` | Star outline — for default/unselected favourite state |',
+  '| `ask-arbor` | Custom Arbor AI brand icon |',
+  '| `google` | Custom Google brand icon |',
+  '',
+  'Use outline as the default and filled only for selected/active/confirmation states.',
+  'Never mix filled and outline icons in the same UI context.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical patterns',
+  '',
+  '#### `aria-hidden` + `sr-only` pattern',
+  '',
+  'The SVG always renders with `aria-hidden="true"` (and `role="img"`). This means screen readers',
+  'skip the SVG entirely. See: [Why `aria-hidden` beats `aria-label` on SVGs](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/)',
+  '',
+  'When you pass `screenReaderText`, the component renders a `<span class="sr-only">` immediately',
+  'after the SVG. Screen readers announce the span; they never see the SVG.',
+  '',
+  '```tsx',
+  '// The SVG is hidden from AT. The span is visually hidden but readable by AT.',
+  '<Icon name="triangle-alert" screenReaderText="Warning:" />',
+  '// Renders: <svg aria-hidden /> <span class="sr-only">Warning:</span>',
+  '```',
+  '',
+  '#### Decorative vs meaningful — when to use `screenReaderText`',
+  '',
+  '| Situation | Pattern | Why |',
+  '|---|---|---|',
+  '| Icon next to visible text (`<button>Edit <Icon name="pencil" /></button>`) | Omit `screenReaderText` | Screen reader reads "Edit". Adding SR text causes "Edit pencil" duplication |',
+  '| Icon-only button (`<button><Icon name="pencil" /></button>`) | Use `aria-label` on the button, OR `screenReaderText` on Icon | The button needs ONE accessible name |',
+  '| Standalone status icon in a summary list | Use `screenReaderText` | No adjacent text; icon must carry its own meaning |',
+  '',
+  '**The rule:** one accessible name per element. Choose where to put it, but never duplicate it.',
+  '',
+  '#### Icon-only buttons require BOTH accessible label AND tooltip',
+  '',
+  'Per Confluence guidance: icon-only buttons must have an accessible label (via `aria-label` on the',
+  'button or `screenReaderText` on the Icon) **and** a tooltip on hover/focus. The label serves',
+  'keyboard/AT users; the tooltip serves sighted mouse users who may not recognise the icon.',
+  '',
+  '```tsx',
+  '// Pair with TooltipWrapper in production',
+  '<TooltipWrapper content="Edit student record">',
+  '  <button aria-label="Edit student record">',
+  '    <Icon name="pencil" size={16} />',
+  '  </button>',
+  '</TooltipWrapper>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **SVG always `aria-hidden`** — the SVG element is always hidden from assistive tech regardless of',
+  '  whether `screenReaderText` is provided. Never attempt to put an accessible label directly on the SVG.',
+  '- **Decorative icons** — omit `screenReaderText`. The icon adds no information beyond the visible text.',
+  '- **Meaningful icons** — provide `screenReaderText` OR put `aria-label` on the interactive parent.',
+  '- **Status icons** — must be paired with visible text where possible (WCAG 1.4.1: use of colour).',
+  '  Do not rely on icon colour alone to communicate success, warning, or error.',
+  '- **Icon-only interactions** — must have accessible label + tooltip on hover/focus.',
+  '- **Avoid `title` attributes** — Lucide SVGs sometimes include `<title>` elements; Arbor\'s `allowedIcons`',
+  '  wrapper suppresses these via `aria-hidden`. Do not rely on SVG `title` for accessible names.',
+  '- **"Opens in new tab"** — communicate this in text (`<span class="sr-only">opens in new tab</span>`),',
+  '  not only via the `external-link` icon.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Icon } from '@arbor-education/design-system.components';",
+  '',
+  'function MyIcon(props: Icon.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `Icon.Props` | Full props interface |',
+  '| `Icon.Name` | Union of all icon name strings — see argTypes for full list |',
+  '| `Icon.Size` | `12 \\| 16 \\| 24` |',
+  '| `Icon.CustomProps` | Props for custom SVG icons |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Button](?path=/docs/components-button--docs) · [Banner](?path=/docs/components-banner--docs) · [Badge](?path=/docs/components-badge--docs) · [Dot](?path=/docs/components-dot--docs) · [Tag](?path=/docs/components-tag--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 IconDocsPage() {
+  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="" />
+      <DocHeading>Icon catalogue</DocHeading>
+      <IconGalleryTemplate />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
   title: 'Components/Icon',
   component: Icon,
-};
-
-export const Default = {
-  args: {
-    name: '3-dot',
-    size: 16,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      page: IconDocsPage,
+    },
   },
+  tags: ['autodocs'],
   argTypes: {
     name: {
       control: 'select',
-      description: 'Icon name',
       options: Object.keys(allowedIcons),
+      description: [
+        'Kebab-case key identifying the icon to render. Required.',
+        'Maps to an entry in `allowedIcons` — TypeScript errors on any unknown value.',
+        'There are currently 106 valid options covering navigation, actions, status,',
+        'content, data, people, and system contexts.',
+        'Commonly used: `pencil` (edit), `trash` (delete), `plus` (add), `x` (close/remove),',
+        '`check` (confirm), `3-dot` (more actions), `chevron-down` (expand), `triangle-alert` (warning).',
+      ].join(' '),
+      table: {
+        type: { summary: 'IconName' },
+      },
     },
     size: {
       control: 'select',
-      description: 'Icon size',
-      options: iconSizes,
+      options: [...iconSizes],
+      description: [
+        'Pixel size of the icon SVG. Only three values are valid: `12`, `16`, `24`.',
+        '`12` — dense UI only (table cells, compact lists).',
+        '`16` — default for almost every icon in the system.',
+        '`24` — high-significance only (empty states, hero callouts).',
+        'Do not use arbitrary pixel sizes — the three-sizes-only rule is a deliberate design constraint',
+        'that keeps the visual rhythm of the system consistent across all surfaces.',
+      ].join(' '),
+      table: {
+        type: { summary: '12 | 16 | 24' },
+        defaultValue: { summary: '16' },
+      },
+    },
+    color: {
+      control: 'text',
+      description: [
+        'SVG fill/stroke colour. Defaults to `"currentColor"` — the icon inherits the text colour of its parent.',
+        'The default shines for icon + label pairings: style the wrapper once and the icon tracks the label',
+        'through hover, active, and disabled states for free.',
+        'Pass `color` explicitly when the icon carries a specific semantic meaning (status icons where the',
+        'colour IS the message) or must stay a fixed brand/accent colour regardless of context.',
+        'Always use design tokens (CSS custom properties) — never hardcode hex values.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "'currentColor'" },
+      },
+    },
+    screenReaderText: {
+      control: 'text',
+      description: [
+        'Accessible label for meaningful (non-decorative) icons.',
+        'When provided, renders a `<span class="sr-only">` after the SVG. Screen readers announce the span;',
+        'the SVG is always `aria-hidden="true"` and is never announced.',
+        'Omit for decorative icons that sit next to visible text — adding SR text to decorative icons',
+        'causes duplication (e.g. "Edit pencil" instead of just "Edit").',
+        'For icon-only buttons, put `aria-label` on the button element instead — or use this prop',
+        'and let the button\'s accessible name derive from its content.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      control: 'text',
+      description: [
+        'Additional CSS class names appended to the SVG element.',
+        'The component always prefixes with `ds-icon ds-icon-{name}` — the `className` prop',
+        'appends after those base classes.',
+        'Use sparingly: prefer `color` and `size` props for styling. `className` is mainly',
+        'useful for one-off layout adjustments (e.g. vertical alignment with adjacent text).',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
   },
-};
+} satisfies Meta<typeof Icon>;
 
 export default meta;
+// Use StoryObj<typeof Icon> (not typeof meta) so that render-only stories are not
+// forced to provide args for the required `name` prop.
+type Story = StoryObj<typeof Icon>;
+
+// ---------------------------------------------------------------------------
+// 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,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components for composition stories
+// (Named components avoid hooks-in-callbacks lint issues — the react-hooks ESLint
+//  plugin is NOT configured in this project, so do NOT add eslint-disable.)
+// ---------------------------------------------------------------------------
+
+const AllSizesTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      gap: 'var(--spacing-xlarge)',
+      alignItems: 'flex-end',
+    }}
+  >
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <Icon name="dot" size={12} />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        12
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        dense UI only
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        (tables, compact lists)
+      </p>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <Icon name="graduation-cap" size={16} />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        16
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        default (almost everything)
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        &nbsp;
+      </p>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <Icon name="files" size={24} />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        24
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        high-significance only
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        (empty states, hero callouts)
+      </p>
+    </div>
+  </div>
+);
+
+const CurrentColorInheritanceTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      The same icon with no `color` prop — inheriting parent `color` in each case
+    </p>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-grey-900)',
+      }}
+    >
+      <Icon name="info" size={16} />
+      <span className="ds-text">Body text colour (--color-grey-900)</span>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-brand-700)',
+      }}
+    >
+      <Icon name="info" size={16} />
+      <span className="ds-text">Brand heading colour (--color-brand-700)</span>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-semantic-destructive-600)',
+      }}
+    >
+      <Icon name="info" size={16} />
+      <span className="ds-text">Error text colour (--color-semantic-destructive-600)</span>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-grey-400)',
+      }}
+    >
+      <Icon name="info" size={16} />
+      <span className="ds-text">Disabled/muted colour (--color-grey-400)</span>
+    </div>
+  </div>
+);
+
+const SemanticColoursTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      Status icons — the only case where passing `color` explicitly is correct
+    </p>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-semantic-info-600)',
+      }}
+    >
+      <Icon name="circle-alert" size={16} color="var(--color-semantic-info-600)" />
+      <span className="ds-text">Heads up</span>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-semantic-success-600)',
+      }}
+    >
+      <Icon name="circle-check" size={16} color="var(--color-semantic-success-600)" />
+      <span className="ds-text">Saved successfully</span>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-semantic-warning-600)',
+      }}
+    >
+      <Icon name="triangle-alert" size={16} color="var(--color-semantic-warning-600)" />
+      <span className="ds-text">Check before submitting</span>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-small)',
+        color: 'var(--color-semantic-destructive-600)',
+      }}
+    >
+      <Icon name="circle-x" size={16} color="var(--color-semantic-destructive-600)" />
+      <span className="ds-text">Save failed</span>
+    </div>
+  </div>
+);
+
+const AccessibleLabelTemplate = () => (
+  <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 className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-destructive-600)' }}>
+        Without screenReaderText — screen reader announces NOTHING (correct for decorative use)
+      </p>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="triangle-alert" size={16} />
+        <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+          Decorative — sits next to visible text, no SR text needed
+        </span>
+      </div>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Screen reader: (silence — SVG has aria-hidden)
+      </p>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-success-600)' }}>
+        With screenReaderText="Warning:" — screen reader announces "Warning:" from the sr-only span
+      </p>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="triangle-alert" size={16} screenReaderText="Warning:" />
+        <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+          Meaningful — standalone icon, SR text carries the label
+        </span>
+      </div>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Screen reader: "Warning:"
+      </p>
+    </div>
+  </div>
+);
+
+const DecorativeVsMeaningfulTemplate = () => (
+  <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 className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Decorative — icon accompanies visible button text. No screenReaderText needed.
+        Screen reader announces "Edit" from the button text.
+      </p>
+      <Button variant="secondary" type="button" iconRightName="pencil">
+        Edit
+      </Button>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Screen reader: "Edit, button"
+      </p>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Meaningful — icon-only button. Accessible name via iconRightScreenReaderText.
+        No screenReaderText needed on Icon itself.
+      </p>
+      <Button
+        variant="tertiary"
+        type="button"
+        iconRightName="pencil"
+        iconRightScreenReaderText="Edit student record"
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Screen reader: "Edit student record, button"
+      </p>
+    </div>
+  </div>
+);
+
+const CustomSolidVariantsTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-xlarge)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      Outline (default) vs filled (emphasis) — never mix in the same UI context
+    </p>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Confirmation emphasis
+      </p>
+      <div style={{ display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Icon name="check" size={24} />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>check (outline)</span>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Icon name="check-solid" size={24} color="var(--color-semantic-success-600)" />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>check-solid (filled)</span>
+        </div>
+      </div>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Rejection/remove emphasis
+      </p>
+      <div style={{ display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Icon name="x" size={24} />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>x (outline)</span>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Icon name="x-solid" size={24} color="var(--color-semantic-destructive-600)" />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>x-solid (filled)</span>
+        </div>
+      </div>
+    </div>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Favourite/bookmark active state
+      </p>
+      <div style={{ display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Icon name="favourite-outline" size={24} />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>favourite-outline</span>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Icon name="favourite-filled" size={24} color="var(--color-brand-600)" />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>favourite-filled</span>
+        </div>
+      </div>
+    </div>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// IconGallery — all icons grouped by semantic category
+// ---------------------------------------------------------------------------
+
+type IconCategory = {
+  heading: string;
+  icons: Array<keyof typeof allowedIcons>;
+};
+
+const ICON_CATEGORIES: IconCategory[] = [
+  {
+    heading: 'Navigation',
+    icons: [
+      'arrow-up', 'arrow-down', 'arrow-left', 'arrow-right',
+      'arrow-right-from-line', 'arrow-up-right',
+      'chevron-up', 'chevron-down', 'chevron-left', 'chevron-right',
+      'chevrons-left', 'chevrons-right',
+      'corner-down-left', 'menu',
+      'ellipsis', 'ellipsis-vertical', '3-dot', 'grab',
+    ],
+  },
+  {
+    heading: 'Actions',
+    icons: [
+      'pencil', 'trash', 'save', 'copy', 'download', 'upload',
+      'share', 'send', 'redo', 'undo', 'plus', 'minus',
+      'circle-plus', 'iteration-ccw', 'switch-camera',
+    ],
+  },
+  {
+    heading: 'Status / severity',
+    icons: [
+      'info', 'circle-alert', 'triangle-alert',
+      'circle-check', 'circle-check-big', 'circle-x',
+      'circle-help', 'check', 'check-solid', 'x', 'x-solid',
+    ],
+  },
+  {
+    heading: 'Content / media',
+    icons: [
+      'file', 'files', 'clipboard', 'clipboard-list',
+      'book-open', 'camera', 'mic', 'paperclip',
+      'sheet', 'table',
+      'sparkles', 'party-popper', 'lightbulb',
+      'favourite-outline', 'favourite-filled',
+    ],
+  },
+  {
+    heading: 'Charts / data',
+    icons: [
+      'chart-column-increasing', 'chart-spline',
+      'trending-up', 'trending-down',
+      'percent', 'circle-percent',
+      'sorting', 'funnel', 'sliders-horizontal', 'list-filter-plus',
+    ],
+  },
+  {
+    heading: 'People / org',
+    icons: [
+      'user', 'guardians', 'group', 'staff', 'graduation-cap',
+    ],
+  },
+  {
+    heading: 'System / state',
+    icons: [
+      'eye', 'eye-off', 'lock', 'lock-open', 'loader',
+      'pin', 'flag', 'house', 'history', 'clock-3', 'date',
+      'settings', 'expand', 'shrink', 'link', 'external-link',
+      'log-out', 'search', 'mail', 'phone', 'smartphone',
+      'monitor', 'projector', 'archive',
+    ],
+  },
+  {
+    heading: 'Other / misc',
+    icons: [
+      'dot', 'layout-list', 'list', 'grid-3x3',
+      'paint-bucket', 'message-square-more',
+    ],
+  },
+  {
+    heading: 'Custom / brand',
+    icons: ['ask-arbor', 'google'],
+  },
+];
+
+const IconGalleryTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      width: '100%',
+      maxWidth: '900px',
+    }}
+  >
+    {ICON_CATEGORIES.map(category => (
+      <div
+        key={category.heading}
+        style={{ marginBottom: 'var(--spacing-xxlarge)' }}
+      >
+        <p
+          className="ds-text"
+          style={{
+            margin: '0 0 var(--spacing-large) 0',
+            color: 'var(--color-grey-600)',
+            fontWeight: 'var(--font-weight-semi-bold)',
+          }}
+        >
+          {category.heading}
+        </p>
+        <div
+          style={{
+            display: 'grid',
+            gridTemplateColumns: 'repeat(auto-fill, minmax(7rem, 1fr))',
+            gap: 'var(--spacing-small)',
+          }}
+        >
+          {category.icons.map(name => (
+            <div
+              key={name}
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 'var(--spacing-xsmall)',
+                padding: 'var(--spacing-medium)',
+                borderRadius: 'var(--border-radius-small)',
+                border: '1px solid var(--color-grey-200)',
+                background: 'var(--color-grey-100)',
+              }}
+            >
+              <Icon name={name} size={16} />
+              <span
+                className="ds-text"
+                style={{
+                  color: 'var(--color-grey-600)',
+                  wordBreak: 'break-word',
+                  textAlign: 'center',
+                  fontSize: 'var(--font-size-1-11)',
+                }}
+              >
+                {name}
+              </span>
+            </div>
+          ))}
+        </div>
+      </div>
+    ))}
+  </div>
+);
+
+const InButtonContextTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      Button manages Icon internally — use iconLeftName/iconRightName, not
+      {' '}
+      {'<Icon>'}
+      {' '}
+      as a child
+    </p>
+    <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap', alignItems: 'center' }}>
+      <Button variant="primary" type="button" iconLeftName="plus">
+        Add student
+      </Button>
+      <Button
+        variant="secondary"
+        type="button"
+        iconRightName="chevron-down"
+      >
+        Select year group
+      </Button>
+      {/* Icon-only tertiary — in production, wrap in TooltipWrapper for hover/focus affordance */}
+      <Button
+        variant="tertiary"
+        type="button"
+        iconRightName="3-dot"
+        iconRightScreenReaderText="More actions"
+      />
+    </div>
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+      The icon-only tertiary button above should be wrapped in a TooltipWrapper in production
+      to provide a hover/focus label for sighted mouse users.
+    </p>
+  </div>
+);
+
+const InStatusIndicatorContextTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      Bulk action validation summary — icons communicate outcome severity at a glance
+    </p>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon
+          name="circle-check"
+          size={16}
+          color="var(--color-semantic-success-600)"
+          screenReaderText="Success:"
+        />
+        <span className="ds-text">3 marksheets saved</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon
+          name="triangle-alert"
+          size={16}
+          color="var(--color-semantic-warning-600)"
+          screenReaderText="Warning:"
+        />
+        <span className="ds-text">2 conflicts to review</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon
+          name="circle-x"
+          size={16}
+          color="var(--color-semantic-destructive-600)"
+          screenReaderText="Error:"
+        />
+        <span className="ds-text">1 submission failed</span>
+      </div>
+    </div>
+  </div>
+);
+
+const InEmptyStateContextTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      gap: 'var(--spacing-large)',
+      textAlign: 'center',
+    }}
+  >
+    <Icon name="files" size={24} color="var(--color-grey-400)" />
+    <p className="ds-text" style={{ margin: 0, fontWeight: 'var(--font-weight-semi-bold)' }}>
+      No reports yet
+    </p>
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      Upload your first report to get started.
+    </p>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      name: '3-dot',
+      size: 16,
+    },
+    render: args => <Icon {...args} />,
+  },
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore all 106+ icon names, all three sizes, and the screenReaderText pattern. Tip: try `name="loader"` with `size={24}` to see the large format, or `screenReaderText="Warning"` with `name="triangle-alert"` to explore the sr-only pattern.',
+);
+
+export const AllSizes: Story = withDescription(
+  {
+    render: AllSizesTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function AllSizesExample() {
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'flex-end' }}>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <Icon name="dot" size={12} />
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>12 — dense UI only</p>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <Icon name="graduation-cap" size={16} />
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>16 — default</p>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <Icon name="files" size={24} />
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>24 — high-significance only</p>
+      </div>
+    </div>
+  );
+}
+export default AllSizesExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'All three valid sizes side by side with their intended use cases.',
+    '',
+    '**12** (`--icon-size-xsmall`) — dense UI only. Table cells, compact lists, tight inline indicators.',
+    'Too small for standalone use or touch targets.',
+    '',
+    '**16** (`--icon-size-small`) — the default for almost everything in the system.',
+    'Balances visual weight against surrounding text at standard body size.',
+    '',
+    '**24** (`--icon-size-medium`) — reserved for high-significance moments: empty states, hero callouts,',
+    'onboarding prompts. Using 24px icons in dense list or form contexts creates visual imbalance.',
+    '',
+    'Never use arbitrary sizes outside these three — the size constraint is a deliberate design system rule.',
+  ].join(' '),
+);
+
+export const CurrentColorInheritance: Story = withDescription(
+  {
+    render: CurrentColorInheritanceTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function CurrentColorInheritanceExample() {
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      {/* Icon inherits the wrapper colour — no color prop needed */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)', color: 'var(--color-grey-900)' }}>
+        <Icon name="info" size={16} />
+        <span className="ds-text">Body text colour (--color-grey-900)</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)', color: 'var(--color-brand-700)' }}>
+        <Icon name="info" size={16} />
+        <span className="ds-text">Brand heading colour (--color-brand-700)</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)', color: 'var(--color-semantic-destructive-600)' }}>
+        <Icon name="info" size={16} />
+        <span className="ds-text">Error text colour (--color-semantic-destructive-600)</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)', color: 'var(--color-grey-400)' }}>
+        <Icon name="info" size={16} />
+        <span className="ds-text">Disabled/muted colour (--color-grey-400)</span>
+      </div>
+    </div>
+  );
+}
+export default CurrentColorInheritanceExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The `color` prop defaults to `"currentColor"` — the SVG inherits the `color` CSS property of its',
+    'parent element. This story shows the **same `<Icon name="info" />` with no `color` prop** inside',
+    'four different parent containers.',
+    '',
+    'The icon colour tracks the parent text colour automatically. This is especially handy for icon + label',
+    'pairings: style the wrapper once and the icon follows the label through hover, active, and disabled',
+    'states. It also lets you control a whole cluster of icons by setting one CSS token on their shared',
+    'parent, instead of threading `color` through each `<Icon>`.',
+  ].join(' '),
+);
+
+export const SemanticColours: Story = withDescription(
+  {
+    render: SemanticColoursTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function SemanticColoursExample() {
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="circle-alert" size={16} color="var(--color-semantic-info-600)" />
+        <span className="ds-text">Heads up</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="circle-check" size={16} color="var(--color-semantic-success-600)" />
+        <span className="ds-text">Saved successfully</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="triangle-alert" size={16} color="var(--color-semantic-warning-600)" />
+        <span className="ds-text">Check before submitting</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="circle-x" size={16} color="var(--color-semantic-destructive-600)" />
+        <span className="ds-text">Save failed</span>
+      </div>
+    </div>
+  );
+}
+export default SemanticColoursExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A canonical use case for passing `color` explicitly: status icons that must communicate severity',
+    'independently of the surrounding text colour. (You can also pass `color` anywhere else it makes',
+    'sense — for brand accents, fixed-colour service logos, or intentionally muted empty-state glyphs —',
+    'just always prefer a design token over a hardcoded hex.)',
+    '',
+    'Each row pairs an icon with a text label using the same semantic colour token. This satisfies',
+    'WCAG 1.4.1 (use of colour) — the meaning is communicated by both the icon shape AND the colour',
+    'AND the text label, not by colour alone.',
+    '',
+    'Tokens used: `--color-semantic-info-600`, `--color-semantic-success-600`,',
+    '`--color-semantic-warning-600`, `--color-semantic-destructive-600`.',
+  ].join(' '),
+);
+
+export const AccessibleLabel: Story = withDescription(
+  {
+    render: AccessibleLabelTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function AccessibleLabelExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)', padding: 'var(--spacing-xlarge)' }}>
+      {/* Decorative — no screenReaderText, sits next to visible text */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="triangle-alert" size={16} />
+        <span className="ds-text">Decorative — sits next to visible text, no SR text needed</span>
+      </div>
+      {/* Meaningful — standalone icon, screenReaderText carries the label */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="triangle-alert" size={16} screenReaderText="Warning:" />
+        <span className="ds-text">Meaningful — standalone icon, SR text carries the label</span>
+      </div>
+    </div>
+  );
+}
+export default AccessibleLabelExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The `aria-hidden` + `sr-only` pattern in practice.',
+    '',
+    'The SVG **always** has `aria-hidden="true"` — screen readers skip it entirely.',
+    'When `screenReaderText` is provided, a `<span class="sr-only">` is rendered immediately after',
+    'the SVG. Screen readers announce the span; they never see the SVG.',
+    '',
+    'See: [Why aria-hidden beats aria-label on SVGs](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/)',
+    '',
+    '**Top row** — no `screenReaderText`. The icon is purely decorative in the context of accompanying',
+    'visible text. Screen reader announces nothing from the icon (which is correct).',
+    '',
+    '**Bottom row** — `screenReaderText="Warning:"` provided. The `<span class="sr-only">` carries',
+    'the accessible label. Screen reader announces "Warning:".',
+  ].join(' '),
+);
+
+export const DecorativeVsMeaningful: Story = withDescription(
+  {
+    render: DecorativeVsMeaningfulTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function DecorativeVsMeaningfulExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)', padding: 'var(--spacing-xlarge)' }}>
+      {/* Decorative — icon accompanies visible button text. Screen reader: "Edit, button" */}
+      <Button variant="secondary" type="button" iconRightName="pencil">
+        Edit
+      </Button>
+      {/* Meaningful — icon-only button. iconRightScreenReaderText provides accessible name. */}
+      <Button
+        variant="tertiary"
+        type="button"
+        iconRightName="pencil"
+        iconRightScreenReaderText="Edit student record"
+      />
+    </div>
+  );
+}
+export default DecorativeVsMeaningfulExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Two composed button examples showing the two main accessibility patterns.',
+    '',
+    '**Decorative (top):** the pencil icon sits next to visible "Edit" text in the button.',
+    'No `screenReaderText` on the Icon. The button\'s accessible name is "Edit" — from the visible text.',
+    'Adding SR text here would cause "Edit pencil" duplication.',
+    '',
+    '**Meaningful (bottom):** an icon-only button with no visible text.',
+    '`aria-label="Edit student record"` on the `<button>` element provides the accessible name.',
+    'No `screenReaderText` needed on the Icon — the button already has one accessible name.',
+    '',
+    'The rule is: **one accessible name per interactive element**. Choose where to put it, but never',
+    'duplicate it. For icon-only buttons in production, also add a TooltipWrapper for sighted mouse users.',
+  ].join(' '),
+);
+
+export const CustomSolidVariants: Story = withDescription(
+  {
+    render: CustomSolidVariantsTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function CustomSolidVariantsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)', padding: 'var(--spacing-xlarge)' }}>
+      {/* Confirmation emphasis — outline vs filled */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }}>
+        <Icon name="check" size={24} />
+        <Icon name="check-solid" size={24} color="var(--color-semantic-success-600)" />
+      </div>
+      {/* Rejection/remove emphasis — outline vs filled */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }}>
+        <Icon name="x" size={24} />
+        <Icon name="x-solid" size={24} color="var(--color-semantic-destructive-600)" />
+      </div>
+      {/* Favourite active state — outline vs filled */}
+      <div style={{ display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }}>
+        <Icon name="favourite-outline" size={24} />
+        <Icon name="favourite-filled" size={24} color="var(--color-brand-600)" />
+      </div>
+    </div>
+  );
+}
+export default CustomSolidVariantsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Arbor\'s three filled/solid icon variants alongside their outline equivalents.',
+    '',
+    '`check-solid` — a custom filled check mark. Use for confirmed/completed states where the standard',
+    'outline `check` feels too subtle. Pair with `--color-semantic-success-600`.',
+    '',
+    '`x-solid` — a custom filled X. Use for rejected/removed/dismissed states.',
+    'Pair with `--color-semantic-destructive-600`.',
+    '',
+    '`favourite-filled` — the `Star` icon rendered with a fill matching its colour.',
+    'Use for the active "favourited" state. Toggle with `favourite-outline` for the default state.',
+    '',
+    '**Design rule:** never mix filled and outline icons in the same UI context. If you use',
+    '`check-solid` for one state, use `check` (outline) for the other — don\'t swap to a different icon.',
+  ].join(' '),
+);
+
+export const InButtonContext: Story = withDescription(
+  {
+    render: InButtonContextTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button } from '@arbor-education/design-system.components';
+
+function InButtonContextExample() {
+  return (
+    <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap', alignItems: 'center' }}>
+      <Button variant="primary" type="button" iconLeftName="plus">
+        Add student
+      </Button>
+      <Button variant="secondary" type="button" iconRightName="chevron-down">
+        Select year group
+      </Button>
+      {/* Icon-only — wrap in TooltipWrapper in production for hover/focus affordance */}
+      <Button
+        variant="tertiary"
+        type="button"
+        iconRightName="3-dot"
+        iconRightScreenReaderText="More actions"
+      />
+    </div>
+  );
+}
+export default InButtonContextExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'How Icon appears in real Button usage.',
+    '',
+    '**Do not** render `<Icon>` as a child of `<Button>` directly. The `Button` component manages',
+    'its own icon rendering internally via `iconLeftName` and `iconRightName` props.',
+    '',
+    '`iconLeftName="plus"` — icon before label (the default icon+label pattern for action buttons).',
+    '',
+    '`iconRightName="chevron-down"` — trailing action-indicator icon (communicates "opens a menu").',
+    '',
+    'Icon-only tertiary with `iconRightScreenReaderText="More actions"` — in production, this should',
+    'be wrapped in a `TooltipWrapper` to provide a hover/focus label for sighted users per Confluence',
+    'guidance on icon-only interactive elements.',
+  ].join(' '),
+);
+
+export const InStatusIndicatorContext: Story = withDescription(
+  {
+    render: InStatusIndicatorContextTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function InStatusIndicatorContextExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="circle-check" size={16} color="var(--color-semantic-success-600)" screenReaderText="Success:" />
+        <span className="ds-text">3 marksheets saved</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="triangle-alert" size={16} color="var(--color-semantic-warning-600)" screenReaderText="Warning:" />
+        <span className="ds-text">2 conflicts to review</span>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+        <Icon name="circle-x" size={16} color="var(--color-semantic-destructive-600)" screenReaderText="Error:" />
+        <span className="ds-text">1 submission failed</span>
+      </div>
+    </div>
+  );
+}
+export default InStatusIndicatorContextExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A realistic validation summary panel — the kind that appears after a bulk marksheet save action.',
+    '',
+    'Each row uses a status icon with explicit `color` AND `screenReaderText`. The `screenReaderText`',
+    'is important here: the icons are standalone status indicators, not decorative accompaniments to',
+    'already-labelled text.',
+    '',
+    'Screen reader output: "Success: 3 marksheets saved", "Warning: 2 conflicts to review",',
+    '"Error: 1 submission failed". The SR prefix communicates severity before the message.',
+    '',
+    'Note `--spacing-small` gap between icon and text — tight enough to read as a unit,',
+    'loose enough not to crowd.',
+  ].join(' '),
+);
+
+export const InEmptyStateContext: Story = withDescription(
+  {
+    render: InEmptyStateContextTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon } from '@arbor-education/design-system.components';
+
+function InEmptyStateContextExample() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+        textAlign: 'center',
+      }}
+    >
+      <Icon name="files" size={24} color="var(--color-grey-400)" />
+      <p className="ds-text" style={{ margin: 0, fontWeight: 'var(--font-weight-semi-bold)' }}>
+        No reports yet
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Upload your first report to get started.
+      </p>
+    </div>
+  );
+}
+export default InEmptyStateContextExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The canonical use case for `size={24}` — an empty state layout.',
+    '',
+    'The `files` icon at 24px is large enough to anchor the empty state visually without',
+    'being overwhelming. `color="var(--color-grey-400)"` renders it muted — the icon is a',
+    'supporting visual element, not the primary message.',
+    '',
+    'This pattern appears throughout Arbor wherever a list, table, or content area has no data.',
+    'Follow this layout: centred icon (size 24, muted grey) → bold heading → supporting subtext.',
+    '',
+    'Do not use `size={24}` in list items, table cells, or button icons — reserve it for',
+    'full-area statements like this one.',
+  ].join(' '),
+);