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

package/src/components/badge/Badge.stories.tsx

@@ -1,30 +1,229 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { Icon } from 'Components/icon/Icon';
 import { Badge, type BadgeColour } from './Badge';
 
-const colours: BadgeColour[] = [
-  'purple',
-  'salmon',
-  'teal',
-  'yellow',
-  'green',
-  'orange',
-  'blue',
-];
-
-const meta: Meta<typeof Badge> = {
-  tags: ['autodocs'],
+// ---------------------------------------------------------------------------
+// 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 (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Data
+// ---------------------------------------------------------------------------
+
+const colours: BadgeColour[] = ['purple', 'salmon', 'teal', 'yellow', 'green', 'orange', 'blue'];
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
   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' },
+      },
+    },
   },
-};
+} satisfies Meta<typeof Badge>;
 
 export default meta;
-
+// Use StoryObj<typeof Badge> (not typeof meta) so that render-only stories are
+// not forced to provide args for the required `children` prop — the template
+// components supply their own Badge instances directly.
 type Story = StoryObj<typeof Badge>;
 
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
 const withDescription = (story: Story, description: string): Story => ({
   ...story,
   parameters: {
@@ -38,37 +237,665 @@ const withDescription = (story: Story, description: string): Story => ({
   },
 });
 
-export const Count: Story = withDescription({
-  args: {
-    children: '3',
+// ---------------------------------------------------------------------------
+// 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 = () => (
+  <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>
+);
+
+const InlineWithTextTemplate = () => (
+  <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>
+);
+
+const AllSizesTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      gap: 'var(--spacing-xlarge)',
+      alignItems: 'flex-end',
+    }}
+  >
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <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>
+);
+
+const AllColoursTemplate = () => (
+  <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' }}>
+      {/* Default charcoal first */}
+      <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>
+);
+
+const AllVariantsTemplate = () => (
+  <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>
+);
+
+const A11yWithLabelTemplate = () => (
+  <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>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      children: '3',
+      size: 'md',
+      colour: undefined,
+    },
+    render: args => <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: Story = 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: Story = 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: Story = 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: Story = 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(),
+        },
+      },
+    },
   },
-}, 'Shows the default numeric Badge used for counts and status totals.');
+  '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: Story = 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 const WithA11yLabel: Story = withDescription({
-  args: {
-    children: '3',
-    a11yLabel: '3 selected items',
+export default WithIconTemplate;
+`.trim(),
+        },
+      },
+    },
   },
-}, 'Adds an accessible label when the visual content alone is not descriptive enough.');
+  '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 Sizes: Story = withDescription({
-  render: () => (
-    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
-      <Badge size="sm">1</Badge>
-      <Badge size="md">2</Badge>
-      <Badge size="lg">3</Badge>
+export const InlineWithText: Story = 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>
-  ),
-}, 'Compares the small, medium, and large Badge size variants.');
+  );
+}
 
-export const Colours: Story = withDescription({
-  render: () => (
-    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>
-      {colours.map(c => (
-        <Badge key={c} colour={c} size="md">
-          {c.slice(0, 1).toUpperCase()}
-        </Badge>
+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: Story = 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: Story = 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: Story = 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>
-  ),
-}, 'Displays each available Badge colour variant side by side.');
+  );
+}
+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: Story = 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(' '),
+);