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

package/src/components/avatarGroup/AvatarGroup.stories.tsx

@@ -1,218 +1,1020 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
 import { Avatar } from 'Components/avatar/Avatar';
+import { Button } from 'Components/button/Button';
 import { AvatarGroup } from './AvatarGroup';
 
+// ---------------------------------------------------------------------------
+// Content strings for the custom DocsPage
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`AvatarGroup` renders a horizontal stack of overlapping Avatar thumbnails with an optional overflow badge,',
+  'supporting both a data-driven `items` API and a composable `children` API for maximum flexibility.',
+].join(' ');
+
+const PROPS_INTRO
+  = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Showing a compact summary of participants, collaborators, or assignees on a record (e.g. teachers on a timetable slot, guardians linked to a student).',
+  '- Representing "who has access" or "who is watching" in a list view where space is limited.',
+  '- Surfacing a count of hidden members when there are more people than screen real estate allows.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Scenario | Better alternative |',
+  '|---|---|',
+  '| You need to show full names alongside each avatar | A list of `<Avatar>` components with adjacent labels |',
+  '| You need click / interactive behaviour on each avatar | Wrap individual `<Avatar>` components in buttons |',
+  '| You only have one person to show | A single `<Avatar>` is cleaner and more semantic |',
+  '| The avatars represent non-people entities (subjects, clubs) | An icon list or tag list |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Always supply `label`**',
+  '',
+  'Every `AvatarGroup` in production must have an `aria-label` so screen-reader users know what the group represents:',
+  '',
+  '```tsx',
+  '<AvatarGroup label="Form tutors for Year 11" items={tutors} />',
+  '```',
+  '',
+  '**Two mutually exclusive APIs**',
+  '',
+  'Choose one and stick to it — mixing both on the same component causes a TypeScript error:',
+  '',
+  '```tsx',
+  '// ✅ Items API — pass an array of AvatarGroupItem objects',
+  '<AvatarGroup items={staff} label="Staff" />',
+  '',
+  '// ✅ Children API — compose Avatar elements directly',
+  '<AvatarGroup label="Staff">',
+  '  <Avatar initials="DZ" alt="Dorothy Zbornak" />',
+  '  <Avatar initials="SP" alt="Sophia Petrillo" />',
+  '</AvatarGroup>',
+  '```',
+  '',
+  '**Group `size` wins over individual sizes**',
+  '',
+  'If you pass `size` to the group, it overrides any `size` set on individual items. This is intentional:',
+  '',
+  '```tsx',
+  '// All avatars will render at large, regardless of individual size props',
+  '<AvatarGroup size="large" items={staff} label="Staff" />',
+  '```',
+  '',
+  '**`listOrder="descending"` shows the LAST N items**',
+  '',
+  'When combined with `showMaxItems`, `ascending` shows the first N items and `descending` shows the last N.',
+  'Use `descending` for "most recent contributors" patterns where the latest entries are at the end of the array:',
+  '',
+  '```tsx',
+  '// Shows the 3 most recently active teachers (last 3 in the array)',
+  '<AvatarGroup',
+  '  items={recentTeachers}',
+  '  showMaxItems={3}',
+  '  listOrder="descending"',
+  '  label="Most recently active teachers"',
+  '/>',
+  '```',
+  '',
+  '**Custom overflow label**',
+  '',
+  'Pass a function to `overflowCountLabel` to build a fully descriptive accessible label:',
+  '',
+  '```tsx',
+  '<AvatarGroup',
+  '  items={students}',
+  '  showMaxItems={5}',
+  '  overflowCountLabel={(n) => `${n} more students not shown`}',
+  '  label="Students in tutor group 7B"',
+  '/>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The root element is a `<ul>` — each avatar is a `<li>`. Screen readers receive correct list semantics and item count.',
+  '- Supply `label` (maps to `aria-label` on the `<ul>`) so the list has a meaningful name.',
+  '- The overflow badge uses `role="status"` and an `aria-label` derived from `overflowCountLabel` (default: `"plus N more"`).',
+  '- Set `presentAllUpdatesToScreenReader` when the group updates dynamically — this adds `aria-live="polite"` and `aria-atomic="true"` to the overflow badge so changes are announced.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { AvatarGroup } from '@arbor-education/design-system.components';",
+  "import type { AvatarGroupItem, AvatarGroupListOrder } from '@arbor-education/design-system.components';",
+  '',
+  'type AvatarGroupProps = AvatarGroup.Props;',
+  '```',
+].join('\n');
+
+const AVATAR_GROUP_ITEM_REFERENCE = [
+  '`AvatarGroupItem` is the union type accepted by the `items` array. It supports two shapes so you can',
+  'pass either raw data objects or pre-rendered `<Avatar>` elements:',
+  '',
+  '```ts',
+  "import type { AvatarGroupItem } from '@arbor-education/design-system.components';",
+  '',
+  '// Shape 1 — plain AvatarProps object (most common, data-driven):',
+  'const item: AvatarGroupItem = { initials: "DZ", alt: "Dorothy Zbornak", size: "medium" };',
+  '',
+  '// Shape 2 — pre-rendered <Avatar> element:',
+  'const item: AvatarGroupItem = <Avatar initials="DZ" alt="Dorothy Zbornak" />;',
+  '```',
+  '',
+  'When using the `items` API, the group normalises both shapes internally so you can freely mix them:',
+  '',
+  '```tsx',
+  'const mixed: AvatarGroupItem[] = [',
+  '  { initials: "DZ", alt: "Dorothy Zbornak" },                       // plain object',
+  '  <Avatar initials="RN" alt="Rose Nylund" size="large" />,          // element',
+  '];',
+  '',
+  '<AvatarGroup items={mixed} label="Mixed item types" />',
+  '```',
+  '',
+  'Use the **items API** when avatar data comes from an API response (plain objects). Use the **children API**',
+  '(`<AvatarGroup><Avatar .../></AvatarGroup>`) when you already have `<Avatar>` instances in your render tree.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Avatar](?path=/docs/components-avatar--docs) · [Section](?path=/docs/components-section--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function AvatarGroupDocsPage() {
+  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>AvatarGroupItem reference</DocHeading>
+      <Markdown>{AVATAR_GROUP_ITEM_REFERENCE}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
 const meta: Meta<typeof AvatarGroup> = {
   title: 'Components/AvatarGroup',
   component: AvatarGroup,
   tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: AvatarGroupDocsPage },
+  },
+  argTypes: {
+    items: {
+      description: [
+        'Data-driven API. An array of `AvatarGroupItem` values — each item is either an `AvatarProps`',
+        'plain object (`{ initials, alt, src, size, ... }`) or a pre-rendered `<Avatar>` element.',
+        'Mutually exclusive with `children`.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'readonly AvatarGroupItem[]' },
+      },
+    },
+    children: {
+      description: [
+        'Composable API. Render `<Avatar>` elements as children.',
+        'Fragments are supported — nested Avatars inside `<>...</>` are collected automatically.',
+        'Mutually exclusive with `items`.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'React.ReactNode' },
+      },
+    },
+    showMaxItems: {
+      description: [
+        'Maximum number of avatars to render.',
+        'Any additional avatars are replaced by the `+N` overflow count badge.',
+        'When omitted, all avatars are shown with no badge.',
+      ].join(' '),
+      control: { type: 'number', min: 1, max: 20, step: 1 },
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: 'undefined (show all)' },
+      },
+    },
+    listOrder: {
+      description: [
+        '`ascending` (default) shows the **first** N items; `descending` shows the **last** N items.',
+        'Use `descending` for "most recent contributors" patterns where the latest entries are at the end of the array.',
+      ].join(' '),
+      control: { type: 'radio' },
+      options: ['ascending', 'descending'],
+      table: {
+        type: { summary: "'ascending' | 'descending'" },
+        defaultValue: { summary: "'ascending'" },
+      },
+    },
+    label: {
+      description: [
+        'Sets `aria-label` on the root `<ul>`.',
+        '**Required in production** — without it, screen readers announce a generic unnamed list.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    overflowCountLabel: {
+      description: [
+        'Accessible label for the `+N` overflow badge.',
+        'Pass a static string or a function receiving the overflow count.',
+        'Defaults to `"plus N more"` if omitted.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'string | ((count: number) => string)' },
+        defaultValue: { summary: '"plus N more"' },
+      },
+    },
+    presentAllUpdatesToScreenReader: {
+      description: [
+        'When `true`, adds `aria-live="polite"` and `aria-atomic="true"` to the overflow badge,',
+        'so dynamic additions/removals are announced to screen-reader users.',
+        'Only enable on lists that update at runtime.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    size: {
+      description: [
+        'Group-level size override.',
+        '**This wins over any `size` set on individual Avatar items inside the group**,',
+        'ensuring visual consistency across the whole group.',
+      ].join(' '),
+      control: { type: 'select' },
+      options: ['small', 'medium', 'large', 'extra-large'],
+      table: {
+        type: { summary: "'small' | 'medium' | 'large' | 'extra-large'" },
+        defaultValue: { summary: 'undefined (each avatar uses its own size)' },
+      },
+    },
+    className: {
+      description: 'Additional CSS class names applied to the root `<ul>` element.',
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
 };
 
 export default meta;
-
+// Use StoryObj<typeof AvatarGroup> (not typeof meta) so render-only stories are
+// not forced to provide required args — template components handle their own instances.
 type Story = StoryObj<typeof AvatarGroup>;
 
-const sampleSrc = (id: number) => `https://i.pravatar.cc/150?img=${id}`;
+// ---------------------------------------------------------------------------
+// Shared fixture data
+// ---------------------------------------------------------------------------
 
-export const FromProps: Story = {
-  render: () => (
-    <AvatarGroup
-      label="Team from props"
-      items={[
-        { src: sampleSrc(1), alt: 'Member 1' },
-        { src: sampleSrc(2), alt: 'Member 2' },
-        { initials: 'CM', alt: 'Chris Montgomery' },
-      ]}
-    />
-  ),
-};
+const STAFF_ITEMS: AvatarGroup.Item[] = [
+  { initials: 'DZ', alt: 'Dorothy Zbornak' },
+  { initials: 'RN', alt: 'Rose Nylund' },
+  { initials: 'BD', alt: 'Blanche Devereaux' },
+  { initials: 'SP', alt: 'Sophia Petrillo' },
+  { initials: 'MW', alt: 'Miles Webber' },
+  { initials: 'SZ', alt: 'Stan Zbornak' },
+  { initials: 'CN', alt: 'Charlie Nylund' },
+];
 
-export const SizeOverridesPerAvatar: Story = {
-  name: 'Size Override',
-  render: () => (
-    <AvatarGroup
-      label="All medium even though children are set as small"
-      size="medium"
-      showMaxItems={4}
-      items={[
-        <Avatar
-          key="1"
-          size="small"
-          initials="S1"
-          alt="Small 1"
-        />,
-        <Avatar
-          key="2"
-          size="small"
-          initials="S2"
-          alt="Small 2"
-        />,
-        { size: 'small', initials: 'S3', alt: 'Small 3' },
-        { size: 'small', initials: 'S4', alt: 'Small 4' },
-        { size: 'small', initials: 'S5', alt: 'Small 5' },
-      ]}
-    />
-  ),
-};
+const STUDENT_ITEMS: AvatarGroup.Item[] = [
+  { initials: 'AT', alt: 'Aisha Thompson' },
+  { initials: 'CF', alt: 'Callum Fraser' },
+  { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  { initials: 'OB', alt: 'Oliver Bennett' },
+  { initials: 'PS', alt: 'Priya Sharma' },
+  { initials: 'DM', alt: 'Declan Murphy' },
+  { initials: 'YT', alt: 'Yuki Tanaka' },
+  { initials: 'AO', alt: 'Amara Osei' },
+];
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
 
-export const ComposableChildren: Story = {
-  name: 'Composable Children',
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
   parameters: {
-    docs: {
-      description: {
-        story:
-          'Pass `<Avatar />` nodes as `children`.',
-      },
-    },
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
   },
-  render: () => (
-    <AvatarGroup
-      label="Team (children API)"
-      showMaxItems={3}
-      listOrder="ascending"
+});
+
+// ---------------------------------------------------------------------------
+// Template components for stateful stories
+// ---------------------------------------------------------------------------
+
+const LiveOverflowCounterTemplate = () => {
+  const initialItems: AvatarGroup.Item[] = [
+    { initials: 'AT', alt: 'Aisha Thompson' },
+    { initials: 'CF', alt: 'Callum Fraser' },
+    { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  ];
+
+  const extraItems: AvatarGroup.Item[] = [
+    { initials: 'OB', alt: 'Oliver Bennett' },
+    { initials: 'PS', alt: 'Priya Sharma' },
+    { initials: 'DM', alt: 'Declan Murphy' },
+    { initials: 'YT', alt: 'Yuki Tanaka' },
+  ];
+
+  const [items, setItems] = useState<AvatarGroup.Item[]>(initialItems);
+
+  const addItem = () => {
+    const next = extraItems[items.length - initialItems.length];
+    if (next) setItems(prev => [...prev, next]);
+  };
+
+  const removeItem = () => {
+    if (items.length > 1) setItems(prev => prev.slice(0, -1));
+  };
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
     >
-      <>
-        <Avatar
-          size="small"
-          initials="A"
-          alt="User A"
-        />
-        <Avatar
-          size="small"
-          initials="B"
-          alt="User B"
-        />
-      </>
-      <Avatar
-        size="small"
-        initials="C"
-        alt="User C"
+      <AvatarGroup
+        items={items}
+        showMaxItems={3}
+        size="medium"
+        label="Active session participants"
+        overflowCountLabel={n => `${n} more participants`}
+        presentAllUpdatesToScreenReader
       />
-      <Avatar
-        size="small"
-        initials="D"
-        alt="User D"
+      <div style={{ display: 'flex', gap: 'var(--spacing-medium)' }}>
+        <Button
+          variant="secondary"
+          size="S"
+          onClick={addItem}
+          disabled={items.length >= initialItems.length + extraItems.length}
+        >
+          Add participant
+        </Button>
+        <Button
+          variant="secondary"
+          size="S"
+          onClick={removeItem}
+          disabled={items.length <= 1}
+        >
+          Remove participant
+        </Button>
+      </div>
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)' }}
+      >
+        {items.length}
+        {' '}
+        participant
+        {items.length !== 1 ? 's' : ''}
+        {' '}
+        total — overflow badge shows
+        {' '}
+        {Math.max(0, items.length - 3)}
+        {' '}
+        hidden
+      </p>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      showMaxItems: 4,
+      listOrder: 'ascending',
+      label: 'Teaching staff',
+      size: 'medium',
+      presentAllUpdatesToScreenReader: false,
+    },
+    render: ({ showMaxItems, listOrder, label, size, presentAllUpdatesToScreenReader, className }) => (
+      <AvatarGroup
+        items={STAFF_ITEMS}
+        showMaxItems={showMaxItems}
+        listOrder={listOrder}
+        label={label}
+        size={size}
+        presentAllUpdatesToScreenReader={presentAllUpdatesToScreenReader}
+        className={className}
       />
-      <Avatar
-        size="small"
-        initials="E"
-        alt="User E"
+    ),
+  },
+  'A fully interactive example — the `items` array is fixed at 7 staff members so the overflow badge is visible by default. '
+  + 'Use the **Controls** panel below to change `showMaxItems`, `size`, `listOrder`, and other props.',
+);
+
+export const ItemsApi: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+const students = [
+  { initials: 'AT', alt: 'Aisha Thompson' },
+  { initials: 'CF', alt: 'Callum Fraser' },
+  { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  { initials: 'OB', alt: 'Oliver Bennett' },
+  { initials: 'PS', alt: 'Priya Sharma' },
+];
+
+function TutorGroupAvatars() {
+  return (
+    <AvatarGroup
+      items={students}
+      label="Tutor group 9C"
+      size="medium"
+    />
+  );
+}
+export default TutorGroupAvatars;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <AvatarGroup
+        items={STUDENT_ITEMS.slice(0, 5)}
+        label="Tutor group 9C"
+        size="medium"
       />
+    ),
+  },
+  'The **items API** is the recommended approach when avatar data arrives as a plain array (e.g. from an API response). '
+  + 'Pass an array of `AvatarGroupItem` values — each can be a plain `AvatarProps` object (`{ initials, alt, src, size, ... }`) '
+  + 'or a pre-rendered `<Avatar>` element.',
+);
+
+export const ChildrenApi: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar, AvatarGroup } from '@arbor-education/design-system.components';
+
+function SLTAvatars() {
+  return (
+    <AvatarGroup label="Senior leadership team" size="medium">
+      <Avatar initials="MP" alt="Margaret Pemberton" />
+      <Avatar initials="DO" alt="David Okafor" />
+      <Avatar initials="SR" alt="Siobhan Reilly" />
+      <Avatar initials="RK" alt="Raj Krishnamurthy" />
     </AvatarGroup>
-  ),
-};
+  );
+}
+export default SLTAvatars;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <AvatarGroup label="Senior leadership team" size="medium">
+        <Avatar initials="MP" alt="Margaret Pemberton" />
+        <Avatar initials="DO" alt="David Okafor" />
+        <Avatar initials="SR" alt="Siobhan Reilly" />
+        <Avatar initials="RK" alt="Raj Krishnamurthy" />
+      </AvatarGroup>
+    ),
+  },
+  'The **children API** lets you compose `<Avatar>` elements directly — useful when you already have Avatar '
+  + 'components in your render tree and just want to group them. '
+  + 'Fragments are supported: Avatars inside `<>...</>` wrappers are collected automatically. '
+  + 'The `items` and `children` APIs are mutually exclusive; pick one per component instance.',
+);
+
+export const AllSizes: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+const staff = [
+  { initials: 'DZ', alt: 'Dorothy Zbornak' },
+  { initials: 'RN', alt: 'Rose Nylund' },
+  { initials: 'BD', alt: 'Blanche Devereaux' },
+  { initials: 'SP', alt: 'Sophia Petrillo' },
+];
 
-export const ComposableChildrenDescending: Story = {
-  name: 'Composed + Descending Order',
-  render: () => (
+function AllSizesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <AvatarGroup items={staff} size="small"       label="Staff — small"       showMaxItems={3} />
+      <AvatarGroup items={staff} size="medium"      label="Staff — medium"      showMaxItems={3} />
+      <AvatarGroup items={staff} size="large"       label="Staff — large"       showMaxItems={3} />
+      <AvatarGroup items={staff} size="extra-large" label="Staff — extra-large" showMaxItems={3} />
+    </div>
+  );
+}
+export default AllSizesExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 'var(--spacing-large)',
+        }}
+      >
+        {(['small', 'medium', 'large', 'extra-large'] as const).map(size => (
+          <div
+            key={size}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 'var(--spacing-medium)',
+            }}
+          >
+            <span
+              className="ds-text"
+              style={{ width: '6rem', color: 'var(--color-grey-600)', flexShrink: 0 }}
+            >
+              {size}
+            </span>
+            <AvatarGroup
+              items={STAFF_ITEMS.slice(0, 4)}
+              size={size}
+              label={`Staff group — ${size}`}
+              showMaxItems={3}
+            />
+          </div>
+        ))}
+      </div>
+    ),
+  },
+  'All four avatar sizes — `small`, `medium`, `large`, and `extra-large` — shown side by side. '
+  + 'Use `size` on the group (not on individual items) to keep the stack visually consistent.',
+);
+
+export const GroupSizeOverride: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+// Each item declares a different individual size
+const mixedItems = [
+  { initials: 'DZ', alt: 'Dorothy Zbornak', size: 'small' as const },
+  { initials: 'RN', alt: 'Rose Nylund',     size: 'extra-large' as const },
+  { initials: 'BD', alt: 'Blanche Devereaux', size: 'large' as const },
+  { initials: 'SP', alt: 'Sophia Petrillo', size: 'small' as const },
+];
+
+function GroupSizeOverrideExample() {
+  return (
+    <>
+      {/* Without group size — renders mixed, inconsistent heights */}
+      <AvatarGroup items={mixedItems} label="Mixed sizes — no override" />
+
+      {/* With group size="medium" — ALL avatars flatten to medium */}
+      <AvatarGroup items={mixedItems} size="medium" label="Group size override to medium" />
+    </>
+  );
+}
+export default GroupSizeOverrideExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => {
+      const mixedItems: AvatarGroup.Item[] = [
+        { initials: 'DZ', alt: 'Dorothy Zbornak', size: 'small' },
+        { initials: 'RN', alt: 'Rose Nylund', size: 'extra-large' },
+        { initials: 'BD', alt: 'Blanche Devereaux', size: 'large' },
+        { initials: 'SP', alt: 'Sophia Petrillo', size: 'small' },
+      ];
+      return (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-large)',
+          }}
+        >
+          <div>
+            <p
+              className="ds-text"
+              style={{ marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }}
+            >
+              Without group size — mixed individual sizes (small / extra-large / large / small):
+            </p>
+            <AvatarGroup items={mixedItems} label="Mixed sizes — no group override" />
+          </div>
+          <div>
+            <p
+              className="ds-text"
+              style={{ marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }}
+            >
+              With
+              {' '}
+              <code>size="medium"</code>
+              {' '}
+              on the group — individual sizes are overridden:
+            </p>
+            <AvatarGroup items={mixedItems} size="medium" label="Mixed sizes — group override to medium" />
+          </div>
+        </div>
+      );
+    },
+  },
+  'When you pass `size` to the group, it **overrides** any `size` set on individual items. '
+  + 'The top row has four items each declaring a different size — the result is visually inconsistent. '
+  + 'The bottom row adds `size="medium"` to the group and all avatars snap to the same height.',
+);
+
+export const WithOverflow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+const students = [
+  { initials: 'AT', alt: 'Aisha Thompson' },
+  { initials: 'CF', alt: 'Callum Fraser' },
+  { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  { initials: 'OB', alt: 'Oliver Bennett' },
+  { initials: 'PS', alt: 'Priya Sharma' },
+  { initials: 'DM', alt: 'Declan Murphy' },
+  { initials: 'YT', alt: 'Yuki Tanaka' },
+  { initials: 'AO', alt: 'Amara Osei' },
+];
+
+function OverflowExample() {
+  return (
     <AvatarGroup
-      label="Last three visible"
+      items={students}
+      showMaxItems={4}
+      label="Year 8 English students"
       size="medium"
-      showMaxItems={3}
-      listOrder="descending"
-    >
-      <Avatar
-        initials="A"
-        alt="User A"
-      />
-      <Avatar
-        initials="B"
-        alt="User B"
-      />
-      <Avatar
-        initials="C"
-        alt="User C"
+    />
+  );
+}
+export default OverflowExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <AvatarGroup
+        items={STUDENT_ITEMS}
+        showMaxItems={4}
+        label="Year 8 English students"
+        size="medium"
       />
-      <Avatar
-        initials="D"
-        alt="User D"
+    ),
+  },
+  '`showMaxItems` caps the rendered avatars and replaces the remainder with a `+N` overflow badge. '
+  + 'Here 8 students are in the list but only 4 are shown — the badge reads **+4**. '
+  + 'The badge carries `role="status"` and an accessible label (`"plus 4 more"` by default).',
+);
+
+export const DescendingOverflow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+// Items ordered chronologically — most recent is last in the array
+const recentContributors = [
+  { initials: 'HN', alt: 'Harriet Nwosu' },   // oldest
+  { initials: 'LM', alt: 'Leo Marchetti' },
+  { initials: 'SuP', alt: 'Sunita Patel' },
+  { initials: 'TH', alt: 'Tomás Herrera' },
+  { initials: 'IC', alt: 'Imogen Clarke' },
+  { initials: 'KA', alt: 'Kwame Asante' },     // most recent
+];
+
+function DescendingExample() {
+  return (
+    <>
+      {/* ascending — shows FIRST 3 (Harriet, Leo, Sunita) */}
+      <AvatarGroup
+        items={recentContributors}
+        showMaxItems={3}
+        listOrder="ascending"
+        label="Recent contributors — ascending"
       />
-      <Avatar
-        initials="E"
-        alt="User E"
+
+      {/* descending — shows LAST 3 (Tomás, Imogen, Kwame) */}
+      <AvatarGroup
+        items={recentContributors}
+        showMaxItems={3}
+        listOrder="descending"
+        label="Recent contributors — descending"
       />
-    </AvatarGroup>
-  ),
-};
+    </>
+  );
+}
+export default DescendingExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => {
+      const contributors: AvatarGroup.Item[] = [
+        { initials: 'HN', alt: 'Harriet Nwosu' },
+        { initials: 'LM', alt: 'Leo Marchetti' },
+        { initials: 'SuP', alt: 'Sunita Patel' },
+        { initials: 'TH', alt: 'Tomás Herrera' },
+        { initials: 'IC', alt: 'Imogen Clarke' },
+        { initials: 'KA', alt: 'Kwame Asante' },
+      ];
+      return (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-large)',
+          }}
+        >
+          <div>
+            <p
+              className="ds-text"
+              style={{ marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }}
+            >
+              <code>listOrder="ascending"</code>
+              {' '}
+              — shows the
+              {' '}
+              <strong>first</strong>
+              {' '}
+              3 (Harriet, Leo, Sunita):
+            </p>
+            <AvatarGroup
+              items={contributors}
+              showMaxItems={3}
+              listOrder="ascending"
+              label="Recent contributors — ascending"
+              size="medium"
+            />
+          </div>
+          <div>
+            <p
+              className="ds-text"
+              style={{ marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }}
+            >
+              <code>listOrder="descending"</code>
+              {' '}
+              — shows the
+              {' '}
+              <strong>last</strong>
+              {' '}
+              3 (Tomás, Imogen, Kwame):
+            </p>
+            <AvatarGroup
+              items={contributors}
+              showMaxItems={3}
+              listOrder="descending"
+              label="Recent contributors — descending"
+              size="medium"
+            />
+          </div>
+        </div>
+      );
+    },
+  },
+  '`listOrder` controls **which** items are shown when `showMaxItems` trims the list. '
+  + '`ascending` (default) keeps the **first** N items; `descending` keeps the **last** N items. '
+  + 'This is ideal for "most recent contributors" patterns where new entries are appended to the end of the array.',
+);
 
-export const AscendingWithOverflow: Story = {
-  render: () => (
-    <AvatarGroup
-      label="Ascending overflow"
-      listOrder="ascending"
-      showMaxItems={3}
-      items={[
-        { initials: 'A', alt: 'User A' },
-        { initials: 'B', alt: 'User B' },
-        { initials: 'C', alt: 'User C' },
-        { initials: 'D', alt: 'User D' },
-        { initials: 'E', alt: 'User E' },
-      ]}
-    />
-  ),
-};
+export const CustomOverflowLabel: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
 
-export const DescendingWithOverflow: Story = {
-  render: () => (
+function CustomOverflowLabelExample() {
+  return (
     <AvatarGroup
-      label="Descending overflow"
-      listOrder="descending"
+      items={students}
       showMaxItems={3}
-      items={[
-        { initials: 'A', alt: 'User A' },
-        { initials: 'B', alt: 'User B' },
-        { initials: 'C', alt: 'User C' },
-        { initials: 'D', alt: 'User D' },
-        { initials: 'E', alt: 'User E' },
-      ]}
+      label="Students in tutor group 7B"
+      size="medium"
+      overflowCountLabel={(n) => \`\${n} more students not shown\`}
     />
-  ),
-};
-
-export const CustomOverflowLabel: Story = {
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Custom `overflowCountLabel` values replace the full screen-reader label for the overflow badge instead of appending to the visible `+N` text.',
+  );
+}
+export default CustomOverflowLabelExample;
+`.trim(),
+        },
       },
     },
+    render: () => (
+      <AvatarGroup
+        items={STUDENT_ITEMS}
+        showMaxItems={3}
+        label="Students in tutor group 7B"
+        size="medium"
+        overflowCountLabel={n => `${n} more students not shown`}
+      />
+    ),
   },
-  render: () => (
+  '`overflowCountLabel` accepts a **function** receiving the overflow count and returning an accessible label string. '
+  + 'This example produces `aria-label="5 more students not shown"` on the badge — far more descriptive than the default `"plus 5 more"`. '
+  + 'A plain `string` also works if the label does not need to reflect the count dynamically.',
+);
+
+export const WithAriaLabel: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { AvatarGroup } from '@arbor-education/design-system.components';
+
+function WithAriaLabelExample() {
+  return (
+    // Always supply label — without it, screen readers announce a nameless list
     <AvatarGroup
-      label="Custom overflow copy"
-      showMaxItems={2}
-      overflowCountLabel={n => `${n} more students`}
-      items={[
-        { initials: 'J', alt: 'Jacob' },
-        { initials: 'E', alt: 'Edward' },
-        { initials: 'B', alt: 'Bella' },
-      ]}
+      items={formTutors}
+      label="Form tutors for Year 11"
+      size="medium"
     />
-  ),
-};
+  );
+}
+export default WithAriaLabelExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 'var(--spacing-large)',
+        }}
+      >
+        <div>
+          <p
+            className="ds-text"
+            style={{ marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }}
+          >
+            With
+            {' '}
+            <code>label</code>
+            {' '}
+            — screen reader announces &ldquo;Form tutors for Year 11, list, 4 items&rdquo;:
+          </p>
+          <AvatarGroup items={STAFF_ITEMS.slice(0, 4)} label="Form tutors for Year 11" size="medium" />
+        </div>
+        <div>
+          <p
+            className="ds-text"
+            style={{ marginBottom: 'var(--spacing-small)', color: 'var(--color-semantic-destructive-600)' }}
+          >
+            Without
+            {' '}
+            <code>label</code>
+            {' '}
+            — screen reader announces &ldquo;list, 4 items&rdquo; (avoid in production):
+          </p>
+          <AvatarGroup items={STAFF_ITEMS.slice(0, 4)} size="medium" />
+        </div>
+      </div>
+    ),
+  },
+  'The `label` prop sets `aria-label` on the root `<ul>`. '
+  + 'Without it, screen-reader users hear "list of N items" with no context about what the group represents. '
+  + '**Always provide a meaningful label in production.**',
+);
 
-export const AnnouncedOverflowUpdates: Story = {
-  name: 'Announced Overflow Updates',
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Enables polite live announcements for the built-in overflow badge. Overflow members are not rendered; only the count is shown.',
+export const LiveOverflowCounter: Story = withDescription(
+  {
+    render: () => <LiveOverflowCounterTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, AvatarGroup } from '@arbor-education/design-system.components';
+
+function LiveOverflowCounterExample() {
+  const [items, setItems] = useState([
+    { initials: 'AT', alt: 'Aisha Thompson' },
+    { initials: 'CF', alt: 'Callum Fraser' },
+    { initials: 'FA', alt: 'Fatima Al-Rashid' },
+  ]);
+
+  return (
+    <>
+      <AvatarGroup
+        items={items}
+        showMaxItems={3}
+        size="medium"
+        label="Active session participants"
+        overflowCountLabel={(n) => \`\${n} more participants\`}
+        presentAllUpdatesToScreenReader
+      />
+      <Button
+        variant="secondary"
+        size="S"
+        onClick={() => setItems(prev => [...prev, { initials: 'NP', alt: 'New Participant' }])}
+      >
+        Add participant
+      </Button>
+    </>
+  );
+}
+export default LiveOverflowCounterExample;
+`.trim(),
+        },
       },
     },
   },
-  render: () => (
-    <AvatarGroup
-      label="Live updates team"
-      showMaxItems={2}
-      presentAllUpdatesToScreenReader
-      items={[
-        { initials: 'A', alt: 'User A' },
-        { initials: 'B', alt: 'User B' },
-        { initials: 'C', alt: 'User C' },
-        { initials: 'D', alt: 'User D' },
-      ]}
-    />
-  ),
-};
+  'A live demo of `presentAllUpdatesToScreenReader`. '
+  + 'Use the buttons to add or remove participants — the overflow badge updates and each count change is announced '
+  + 'to screen readers via `aria-live="polite"`. '
+  + 'Only enable this on groups whose membership changes at runtime — on static groups it creates unnecessary noise.',
+);