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

package/dist/components/icon/Icon.stories.js

@@ -1,27 +1,998 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { Button } from '../button/Button';
 import { Icon } from './Icon';
 import { allowedIcons } from './allowedIcons';
 import { iconSizes } from './types';
+// ---------------------------------------------------------------------------
+// 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 (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(DocHeading, { children: "Icon catalogue" }), _jsx(IconGalleryTemplate, {}), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// 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' },
+            },
         },
     },
 };
 export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...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 = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        gap: 'var(--spacing-xlarge)',
+        alignItems: 'flex-end',
+    }, children: [_jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx(Icon, { name: "dot", size: 12 }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "12" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "dense UI only" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "(tables, compact lists)" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx(Icon, { name: "graduation-cap", size: 16 }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "16" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "default (almost everything)" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "\u00A0" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx(Icon, { name: "files", size: 24 }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "24" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "high-significance only" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "(empty states, hero callouts)" })] })] }));
+const CurrentColorInheritanceTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "The same icon with no `color` prop \u2014 inheriting parent `color` in each case" }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-grey-900)',
+            }, children: [_jsx(Icon, { name: "info", size: 16 }), _jsx("span", { className: "ds-text", children: "Body text colour (--color-grey-900)" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-brand-700)',
+            }, children: [_jsx(Icon, { name: "info", size: 16 }), _jsx("span", { className: "ds-text", children: "Brand heading colour (--color-brand-700)" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-semantic-destructive-600)',
+            }, children: [_jsx(Icon, { name: "info", size: 16 }), _jsx("span", { className: "ds-text", children: "Error text colour (--color-semantic-destructive-600)" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-grey-400)',
+            }, children: [_jsx(Icon, { name: "info", size: 16 }), _jsx("span", { className: "ds-text", children: "Disabled/muted colour (--color-grey-400)" })] })] }));
+const SemanticColoursTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Status icons \u2014 the only case where passing `color` explicitly is correct" }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-semantic-info-600)',
+            }, children: [_jsx(Icon, { name: "circle-alert", size: 16, color: "var(--color-semantic-info-600)" }), _jsx("span", { className: "ds-text", children: "Heads up" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-semantic-success-600)',
+            }, children: [_jsx(Icon, { name: "circle-check", size: 16, color: "var(--color-semantic-success-600)" }), _jsx("span", { className: "ds-text", children: "Saved successfully" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-semantic-warning-600)',
+            }, children: [_jsx(Icon, { name: "triangle-alert", size: 16, color: "var(--color-semantic-warning-600)" }), _jsx("span", { className: "ds-text", children: "Check before submitting" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-small)',
+                color: 'var(--color-semantic-destructive-600)',
+            }, children: [_jsx(Icon, { name: "circle-x", size: 16, color: "var(--color-semantic-destructive-600)" }), _jsx("span", { className: "ds-text", children: "Save failed" })] })] }));
+const AccessibleLabelTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-xlarge)',
+    }, children: [_jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-destructive-600)' }, children: "Without screenReaderText \u2014 screen reader announces NOTHING (correct for decorative use)" }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "triangle-alert", size: 16 }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "Decorative \u2014 sits next to visible text, no SR text needed" })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Screen reader: (silence \u2014 SVG has aria-hidden)" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "With screenReaderText=\"Warning:\" \u2014 screen reader announces \"Warning:\" from the sr-only span" }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "triangle-alert", size: 16, screenReaderText: "Warning:" }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "Meaningful \u2014 standalone icon, SR text carries the label" })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Screen reader: \"Warning:\"" })] })] }));
+const DecorativeVsMeaningfulTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-xlarge)',
+    }, children: [_jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Decorative \u2014 icon accompanies visible button text. No screenReaderText needed. Screen reader announces \"Edit\" from the button text." }), _jsx(Button, { variant: "secondary", type: "button", iconRightName: "pencil", children: "Edit" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Screen reader: \"Edit, button\"" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Meaningful \u2014 icon-only button. Accessible name via iconRightScreenReaderText. No screenReaderText needed on Icon itself." }), _jsx(Button, { variant: "tertiary", type: "button", iconRightName: "pencil", iconRightScreenReaderText: "Edit student record" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Screen reader: \"Edit student record, button\"" })] })] }));
+const CustomSolidVariantsTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-xlarge)',
+    }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Outline (default) vs filled (emphasis) \u2014 never mix in the same UI context" }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Confirmation emphasis" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "check", size: 24 }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "check (outline)" })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "check-solid", size: 24, color: "var(--color-semantic-success-600)" }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "check-solid (filled)" })] })] })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Rejection/remove emphasis" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "x", size: 24 }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "x (outline)" })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "x-solid", size: 24, color: "var(--color-semantic-destructive-600)" }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "x-solid (filled)" })] })] })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Favourite/bookmark active state" }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-xlarge)', alignItems: 'center' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "favourite-outline", size: 24 }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "favourite-outline" })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "favourite-filled", size: 24, color: "var(--color-brand-600)" }), _jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "favourite-filled" })] })] })] })] }));
+const ICON_CATEGORIES = [
+    {
+        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 = () => (_jsx("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        width: '100%',
+        maxWidth: '900px',
+    }, children: ICON_CATEGORIES.map(category => (_jsxs("div", { style: { marginBottom: 'var(--spacing-xxlarge)' }, children: [_jsx("p", { className: "ds-text", style: {
+                    margin: '0 0 var(--spacing-large) 0',
+                    color: 'var(--color-grey-600)',
+                    fontWeight: 'var(--font-weight-semi-bold)',
+                }, children: category.heading }), _jsx("div", { style: {
+                    display: 'grid',
+                    gridTemplateColumns: 'repeat(auto-fill, minmax(7rem, 1fr))',
+                    gap: 'var(--spacing-small)',
+                }, children: category.icons.map(name => (_jsxs("div", { 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)',
+                    }, children: [_jsx(Icon, { name: name, size: 16 }), _jsx("span", { className: "ds-text", style: {
+                                color: 'var(--color-grey-600)',
+                                wordBreak: 'break-word',
+                                textAlign: 'center',
+                                fontSize: 'var(--font-size-1-11)',
+                            }, children: name })] }, name))) })] }, category.heading))) }));
+const InButtonContextTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Button manages Icon internally \u2014 use iconLeftName/iconRightName, not", ' ', '<Icon>', ' ', "as a child"] }), _jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap', alignItems: 'center' }, children: [_jsx(Button, { variant: "primary", type: "button", iconLeftName: "plus", children: "Add student" }), _jsx(Button, { variant: "secondary", type: "button", iconRightName: "chevron-down", children: "Select year group" }), _jsx(Button, { variant: "tertiary", type: "button", iconRightName: "3-dot", iconRightScreenReaderText: "More actions" })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "The icon-only tertiary button above should be wrapped in a TooltipWrapper in production to provide a hover/focus label for sighted mouse users." })] }));
+const InStatusIndicatorContextTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Bulk action validation summary \u2014 icons communicate outcome severity at a glance" }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "circle-check", size: 16, color: "var(--color-semantic-success-600)", screenReaderText: "Success:" }), _jsx("span", { className: "ds-text", children: "3 marksheets saved" })] }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "triangle-alert", size: 16, color: "var(--color-semantic-warning-600)", screenReaderText: "Warning:" }), _jsx("span", { className: "ds-text", children: "2 conflicts to review" })] }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Icon, { name: "circle-x", size: 16, color: "var(--color-semantic-destructive-600)", screenReaderText: "Error:" }), _jsx("span", { className: "ds-text", children: "1 submission failed" })] })] })] }));
+const InEmptyStateContextTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+        textAlign: 'center',
+    }, children: [_jsx(Icon, { name: "files", size: 24, color: "var(--color-grey-400)" }), _jsx("p", { className: "ds-text", style: { margin: 0, fontWeight: 'var(--font-weight-semi-bold)' }, children: "No reports yet" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Upload your first report to get started." })] }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    args: {
+        name: '3-dot',
+        size: 16,
+    },
+    render: args => _jsx(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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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(' '));
 //# sourceMappingURL=Icon.stories.js.map