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

package/dist/components/badge/Badge.stories.js

@@ -1,24 +1,186 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { Icon } from '../icon/Icon';
 import { Badge } from './Badge';
-const colours = [
-    'purple',
-    'salmon',
-    'teal',
-    'yellow',
-    'green',
-    'orange',
-    'blue',
-];
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'Badge is a compact numeric count indicator that sits alongside icons, labels, or controls to communicate',
+    'quantities at a glance — unread messages, behaviour event totals, pending form responses.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- **Unread notification counts** — messages, alerts, or action items awaiting review',
+    '- **Status totals** — number of students flagged, responses submitted, events logged',
+    '- **Count-adjacent icons** — a bell icon with a Badge communicates "3 unread notifications"',
+    '- **Tab bar counts** — urgent items in a specific tab need a visual quantity signal',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    'Badge is for **numbers only**. It is not a label, filter toggle, or status dot.',
+    '',
+    '| Component | Use for |',
+    '|---|---|',
+    '| `Badge` | Numeric counts: `3`, `12`, `99+` |',
+    '| [`Tag`](?path=/docs/components-tag--docs) | Category labels: `English`, `Year 9`, `GCSE` |',
+    '| [`Pill`](?path=/docs/components-pill--docs) | Filter toggles: `Active`, `Archived`, `Flagged` |',
+    '| [`Dot`](?path=/docs/components-dot--docs) | Status indicator (no number): presence, colour-coded state |',
+    '',
+    '```tsx',
+    '// BAD — numbers require different emphasis and spacing than category labels',
+    '<Badge colour="purple">English</Badge>',
+    '',
+    '// GOOD — use Tag for category labels',
+    '<Tag color="purple">English</Tag>',
+    '```',
+    '',
+    '---',
+    '',
+    '### Design guidance',
+    '',
+    '- **Three sizes** — `sm` (`--badge-small-size`, 1.125rem / 18px), `md` (`--badge-medium-size`,',
+    '  1.25rem / 20px, default), `lg` (`--badge-large-size`, 1.5rem / 24px). All three use',
+    '  `--border-radius-round` (a fully circular radius) so single-digit badges appear as perfect circles',
+    '  and multi-digit badges expand into pills.',
+    '- **Font weight** — `--badge-font-weight` resolves to `--font-weight-semi-bold` (600) across all sizes.',
+    '- **Default colour** — no `colour` prop renders with `--color-grey-800` background and',
+    '  `--color-mono-white` text (charcoal). All seven extended-palette colours are also available.',
+    '- **Colour contrast pairings** — white text on salmon, green, and the default charcoal.',
+    '  Dark text (`--color-extended-colours-{colour}-800`) on purple, teal, yellow, orange, and blue.',
+    '- **`99+` convention** — when a count exceeds 99, display `"99+"` rather than the real number to',
+    '  keep the badge compact and avoid layout overflow.',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Accessibility',
+    '',
+    '- **Keyboard** — Badge is a purely presentational `<span>`. It has no interactive behaviour and is',
+    '  not focusable.',
+    '- **Screen readers** — by default, the badge content is read as inline text. If the badge sits',
+    '  next to an icon or label that already provides context, the count alone may be confusing',
+    '  ("3" without context means nothing).',
+    '- **`a11yLabel` pattern** — pass a full human-readable string like `"3 unread messages"`. The',
+    '  component sets `aria-label` on the wrapper `<span>` and wraps `children` in an',
+    '  `aria-hidden="true"` span to suppress the duplicate numeric announcement. The screen reader',
+    '  then announces the full label instead of just the number.',
+    '- **Do not rely on colour alone** — the numeric value must be visible. Never convey meaning',
+    '  exclusively through badge colour without a label or supporting text.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { Badge } from '@arbor-education/design-system.components';",
+    '',
+    'function MyBadge(props: Badge.Props) { ... }',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `Badge.Props` | Full props interface |',
+    "| `Badge.Size` | `'sm' \\| 'md' \\| 'lg'` |",
+    "| `Badge.Colour` | `'purple' \\| 'salmon' \\| 'teal' \\| 'yellow' \\| 'green' \\| 'orange' \\| 'blue'` (same scale as `Dot.Colour`) |",
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Tag](?path=/docs/components-tag--docs) · [Pill](?path=/docs/components-pill--docs) · [Dot](?path=/docs/components-dot--docs) · [Icon](?path=/docs/components-icon--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 BadgeDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Data
+// ---------------------------------------------------------------------------
+const colours = ['purple', 'salmon', 'teal', 'yellow', 'green', 'orange', 'blue'];
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
-    tags: ['autodocs'],
     title: 'Components/Badge',
     component: Badge,
+    parameters: {
+        layout: 'centered',
+        docs: {
+            page: BadgeDocsPage,
+        },
+    },
+    tags: ['autodocs'],
     argTypes: {
-        size: { control: 'select', options: ['sm', 'md', 'lg'] },
-        colour: { control: 'select', options: [undefined, ...colours] },
+        children: {
+            control: 'text',
+            description: [
+                'The count to display inside the badge. Should always be a number or short numeric string.',
+                'For counts above 99, use `"99+"` to keep the badge compact.',
+                'Badge is for numbers only — do not pass category labels or text strings.',
+            ].join(' '),
+            table: {
+                type: { summary: 'React.ReactNode' },
+            },
+        },
+        size: {
+            control: 'select',
+            options: ['sm', 'md', 'lg'],
+            description: [
+                'Controls the height, min-width, padding, font-size, and border-radius of the badge as a single unit.',
+                '`sm` — 1.125rem / 18px via `--badge-small-size`.',
+                '`md` — 1.25rem / 20px via `--badge-medium-size` (default).',
+                '`lg` — 1.5rem / 24px via `--badge-large-size`.',
+                'All sizes use `--border-radius-round` so single-digit badges appear as circles and multi-digit badges expand into pills.',
+            ].join(' '),
+            table: {
+                type: { summary: "'sm' | 'md' | 'lg'" },
+                defaultValue: { summary: "'md'" },
+            },
+        },
+        colour: {
+            control: 'select',
+            options: [undefined, ...colours],
+            description: [
+                'Extended-palette colour applied to the badge background.',
+                'When omitted (default), the badge renders with `--color-grey-800` (charcoal) background and white text.',
+                'White text pairings: salmon, green, and the default charcoal.',
+                'Dark text pairings (`--color-extended-colours-{colour}-800`): purple, teal, yellow, orange, blue.',
+                'Do not rely on colour alone to communicate meaning — the numeric value must always be visible.',
+            ].join(' '),
+            table: {
+                type: { summary: "'purple' | 'salmon' | 'teal' | 'yellow' | 'green' | 'orange' | 'blue' | undefined" },
+                defaultValue: { summary: 'undefined (charcoal)' },
+            },
+        },
+        a11yLabel: {
+            control: 'text',
+            description: [
+                'Accessible label for the badge. Sets `aria-label` on the wrapper `<span>` and wraps',
+                '`children` in an `aria-hidden="true"` span to suppress the duplicate numeric announcement.',
+                'Use when the badge sits next to an icon or element that provides no visible label — e.g.',
+                '`a11yLabel="5 unread messages"` next to a bell icon.',
+                'When omitted, the numeric content is announced as-is by screen readers.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        className: {
+            control: false,
+            description: 'Additional CSS class names appended to the badge element. Use sparingly — prefer size and colour props.',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
     },
 };
 export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
 const withDescription = (story, description) => ({
     ...story,
     parameters: {
@@ -31,21 +193,458 @@ const withDescription = (story, description) => ({
         },
     },
 });
-export const Count = withDescription({
+// ---------------------------------------------------------------------------
+// Template components for composition stories
+// (Named components avoid react-hooks lint issues — the react-hooks ESLint
+//  plugin is NOT configured in this project, so do NOT add eslint-disable.)
+// ---------------------------------------------------------------------------
+const WithIconTemplate = () => (_jsx("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+    }, children: _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { position: 'relative', display: 'inline-flex', alignItems: 'center', gap: 'var(--spacing-xsmall)' }, children: [_jsx(Icon, { name: "mail", size: 16, screenReaderText: "Notifications" }), _jsx(Badge, { children: "3" })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Notifications" })] }) }));
+const InlineWithTextTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "Behaviour events" }), _jsx(Badge, { children: "14" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "Pending exclusions" }), _jsx(Badge, { colour: "salmon", children: "3" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx("span", { className: "ds-text", style: { color: 'var(--color-grey-600)' }, children: "Attendance alerts" }), _jsx(Badge, { colour: "orange", children: "27" })] })] }));
+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(Badge, { size: "sm", children: "7" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }, children: "sm \u2014 1.125rem" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }, children: "--badge-small-size" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx(Badge, { size: "md", children: "7" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }, children: "md \u2014 1.25rem" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }, children: "--badge-medium-size" })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 'var(--spacing-large)',
+            }, children: [_jsx(Badge, { size: "lg", children: "7" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }, children: "lg \u2014 1.5rem" }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }, children: "--badge-large-size" })] })] }));
+const AllColoursTemplate = () => (_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: "Default (charcoal) + all 7 extended-palette colours" }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Badge, { children: "9" }), _jsx("span", { className: "ds-text", style: { fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }, children: "default" })] }), colours.map(c => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Badge, { colour: c, children: "9" }), _jsx("span", { className: "ds-text", style: { fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }, children: c })] }, c)))] })] }));
+const AllVariantsTemplate = () => (_jsx("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-xlarge)',
+    }, children: ['sm', 'md', 'lg'].map(size => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Size:", ' ', size] }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-large)', alignItems: 'center' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Badge, { size: size, children: "9" }), _jsx("span", { className: "ds-text", style: { fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }, children: "default" })] }), colours.map(c => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }, children: [_jsx(Badge, { size: size, colour: c, children: "9" }), _jsx("span", { className: "ds-text", style: { fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }, children: c })] }, c)))] })] }, size))) }));
+const A11yWithLabelTemplate = () => (_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 a11yLabel \u2014 screen reader announces \"5\" (no context)" }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }, children: [_jsx(Icon, { name: "mail", size: 16, screenReaderText: "Notifications" }), _jsx(Badge, { children: "5" })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Screen reader: \"mail Notifications, 5\"" })] }), _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 a11yLabel \u2014 screen reader announces the full meaningful label" }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }, children: [_jsx(Icon, { name: "mail", size: 16 }), _jsx(Badge, { a11yLabel: "5 unread messages", children: "5" })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Screen reader: \"5 unread messages\"" })] })] }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
     args: {
         children: '3',
+        size: 'md',
+        colour: undefined,
     },
-}, 'Shows the default numeric Badge used for counts and status totals.');
-export const WithA11yLabel = withDescription({
-    args: {
-        children: '3',
-        a11yLabel: '3 selected items',
-    },
-}, 'Adds an accessible label when the visual content alone is not descriptive enough.');
-export const Sizes = withDescription({
-    render: () => (_jsxs("div", { style: { display: 'flex', gap: '1rem', alignItems: 'center' }, children: [_jsx(Badge, { size: "sm", children: "1" }), _jsx(Badge, { size: "md", children: "2" }), _jsx(Badge, { size: "lg", children: "3" })] })),
-}, 'Compares the small, medium, and large Badge size variants.');
-export const Colours = withDescription({
-    render: () => (_jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }, children: colours.map(c => (_jsx(Badge, { colour: c, size: "md", children: c.slice(0, 1).toUpperCase() }, c))) })),
-}, 'Displays each available Badge colour variant side by side.');
+    render: args => _jsx(Badge, { ...args }),
+}, 'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore sizes, colours, and the a11yLabel pattern. Tip: try `size="sm"` for navigation contexts or `colour="salmon"` for urgent counts.');
+export const SingleDigit = withDescription({
+    args: { children: '3' },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+function BadgeSingleDigitExample() {
+  return <Badge>3</Badge>;
+}
+
+export default BadgeSingleDigitExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A single-digit count — the canonical badge case. Because `min-width` equals `height` via `--badge-medium-size`, single-digit badges render as perfect circles. This circular geometry is intentional: it signals "count" rather than "label" at a glance.');
+export const DoubleDigit = withDescription({
+    args: { children: '12' },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+function BadgeDoubleDigitExample() {
+  return <Badge>12</Badge>;
+}
+
+export default BadgeDoubleDigitExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A double-digit count, showing how the badge expands into a pill when content exceeds the minimum width. All three sizes use `--border-radius-round` so the pill shape is consistent regardless of size.');
+export const Overflow = withDescription({
+    args: { children: '99+' },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+function BadgeOverflowExample() {
+  return <Badge>99+</Badge>;
+}
+
+export default BadgeOverflowExample;
+`.trim(),
+            },
+        },
+    },
+}, 'The standard truncation convention for counts above 99. Always display `"99+"` rather than the real number to prevent layout overflow and keep the badge visually compact. Never render a three-digit count like `"247"` — it breaks the badge geometry.');
+export const Zero = withDescription({
+    args: { children: '0' },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+function BadgeZeroExample() {
+  return <Badge>0</Badge>;
+}
+
+export default BadgeZeroExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A zero count is a valid, intentional state — it signals that all notifications have been read or all items have been resolved. Do not hide the badge when the count reaches zero unless the design explicitly calls for it; the badge disappearing can be confusing.');
+export const WithIcon = withDescription({
+    render: WithIconTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge, Icon } from '@arbor-education/design-system.components';
+
+function WithIconTemplate() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <div style={{ position: 'relative', display: 'inline-flex', alignItems: 'center', gap: 'var(--spacing-xsmall)' }}>
+          <Icon name="mail" size={16} screenReaderText="Notifications" />
+          <Badge>3</Badge>
+        </div>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+          Notifications
+        </p>
+      </div>
+    </div>
+  );
+}
+
+export default WithIconTemplate;
+`.trim(),
+            },
+        },
+    },
+}, 'The most common real-world usage pattern: a mail icon paired with a count badge and a "Notifications" label. The `Icon` component uses `screenReaderText="Notifications"` for its own label. The badge here has no `a11yLabel` — the adjacent visible label "Notifications" provides the context. For icon-only contexts with no visible label, always add `a11yLabel`.');
+export const InlineWithText = withDescription({
+    render: InlineWithTextTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+function InlineWithTextTemplate() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+          Behaviour events
+        </span>
+        <Badge>14</Badge>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+          Pending exclusions
+        </span>
+        <Badge colour="salmon">3</Badge>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+          Attendance alerts
+        </span>
+        <Badge colour="orange">27</Badge>
+      </div>
+    </div>
+  );
+}
+
+export default InlineWithTextTemplate;
+`.trim(),
+            },
+        },
+    },
+}, 'Badge next to a text label in a statistics row. The badge uses `flex-shrink: 0` via `ds-badge` so it never squishes inside a flex container. All three rows use design token colours — salmon for urgent (pending exclusions), orange for elevated (attendance alerts), and the default charcoal for neutral counts.');
+export const AllSizes = withDescription({
+    render: AllSizesTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+function AllSizesTemplate() {
+  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)' }}>
+        <Badge size="sm">7</Badge>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }}>
+          sm — 1.125rem
+        </p>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }}>
+          --badge-small-size
+        </p>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <Badge size="md">7</Badge>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }}>
+          md — 1.25rem
+        </p>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }}>
+          --badge-medium-size
+        </p>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <Badge size="lg">7</Badge>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }}>
+          lg — 1.5rem
+        </p>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)' }}>
+          --badge-large-size
+        </p>
+      </div>
+    </div>
+  );
+}
+
+export default AllSizesTemplate;
+`.trim(),
+            },
+        },
+    },
+}, 'All three sizes side by side with their token names and resolved rem values. `sm` is right for navigation items and tab bars. `md` (the default) suits most standalone badge contexts. `lg` is appropriate when badge counts need to be more prominent — for example in a dashboard summary card. Never mix sizes arbitrarily — pick the size that matches the surrounding typographic scale.');
+export const AllColours = withDescription({
+    render: AllColoursTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+const colours = ['purple', 'salmon', 'teal', 'yellow', 'green', 'orange', 'blue'] as const;
+
+function AllColoursTemplate() {
+  return (
+    <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)' }}>
+        Default (charcoal) + all 7 extended-palette colours
+      </p>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <Badge>9</Badge>
+          <span className="ds-text" style={{ fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }}>default</span>
+        </div>
+        {colours.map(c => (
+          <div key={c} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+            <Badge colour={c}>9</Badge>
+            <span className="ds-text" style={{ fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }}>{c}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default AllColoursTemplate;
+`.trim(),
+            },
+        },
+    },
+}, 'The default charcoal (no `colour` prop) first, followed by all seven extended-palette colours. White text renders on salmon and green; dark text (`--color-extended-colours-{colour}-800`) renders on purple, teal, yellow, orange, and blue for WCAG contrast compliance. Remember: colour alone must not be the only signal — the numeric value is always the primary communicator.');
+export const AllVariants = withDescription({
+    render: AllVariantsTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge } from '@arbor-education/design-system.components';
+
+const colours = ['purple', 'salmon', 'teal', 'yellow', 'green', 'orange', 'blue'] as const;
+
+function AllVariantsTemplate() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-xlarge)',
+      }}
+    >
+      {(['sm', 'md', 'lg'] as const).map(size => (
+        <div key={size} style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+            Size: {size}
+          </p>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+            <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+              <Badge size={size}>9</Badge>
+              <span className="ds-text" style={{ fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }}>default</span>
+            </div>
+            {colours.map(c => (
+              <div key={c} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+                <Badge size={size} colour={c}>9</Badge>
+                <span className="ds-text" style={{ fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }}>{c}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+export default AllVariantsTemplate;
+`.trim(),
+            },
+        },
+    },
+}, 'Full 3 × 8 grid: all three sizes crossed with all eight colour states (default charcoal + 7 palette colours). Use this story as a complete visual reference for the Badge component. Each cell uses the same count (`"9"`) to make size and colour comparisons accurate.');
+export const A11yWithLabel = withDescription({
+    render: A11yWithLabelTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Badge, Icon } from '@arbor-education/design-system.components';
+
+function A11yWithLabelTemplate() {
+  return (
+    <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 a11yLabel — screen reader announces "5" (no context)
+        </p>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+          <Icon name="mail" size={16} screenReaderText="Notifications" />
+          <Badge>5</Badge>
+        </div>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+          Screen reader: "mail Notifications, 5"
+        </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 a11yLabel — screen reader announces the full meaningful label
+        </p>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+          <Icon name="mail" size={16} />
+          <Badge a11yLabel="5 unread messages">5</Badge>
+        </div>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+          Screen reader: "5 unread messages"
+        </p>
+      </div>
+    </div>
+  );
+}
+export default A11yWithLabelTemplate;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'Accessibility contrast: top row shows a badge **without** `a11yLabel` — a screen reader',
+    'moving through the icon and badge would announce the icon text and then the bare number `"5"`,',
+    'providing no context about what those 5 items are.',
+    '',
+    'The bottom row adds `a11yLabel="5 unread messages"`. The component sets `aria-label` on the',
+    'wrapper `<span>` and wraps `children` in an `aria-hidden="true"` span. The screen reader now',
+    'announces `"5 unread messages"` as a single coherent label — no duplicate number, full context.',
+    '',
+    'Use `a11yLabel` whenever the badge sits next to an icon-only element or in a context where',
+    'the number alone would be ambiguous to a screen reader user.',
+].join(' '));
 //# sourceMappingURL=Badge.stories.js.map