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

package/src/components/dot/Dot.stories.tsx

@@ -1,41 +1,732 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Dot } from './Dot';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { Tag } from 'Components/tag/Tag';
+import { Dot, type DotColour } from './Dot';
 
-const meta: Meta<typeof Dot> = {
-  tags: ['autodocs'],
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Dot is the smallest coloured indicator in the Arbor design system — a fixed 10 × 10 pixel',
+  'circle that communicates status, category, or grouping through colour. It provides the visual',
+  'primitive; the consuming application owns the semantic meaning.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Inside `Tag`\'s `slotStart`** — the canonical dot-prefix pattern for category tags',
+  '  (`"Year 7"`, `"SEN"`, `"Active"`)',
+  '- **Alongside text in lists or tables** — paired with a student name, status label, or row',
+  '  description so that colour is never the sole conveyor of meaning (WCAG 1.4.1)',
+  '- **Chart or map legends** — where an adjacent label names the colour grouping',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Instead of Dot, use | When you need |',
+  '|---|---|',
+  '| [`Badge`](?path=/docs/components-badge--docs) | A numeric count: `3`, `12`, `99+` |',
+  '| [`Icon`](?path=/docs/components-icon--docs) | A recognisable glyph that conveys meaning by shape |',
+  '| [`Tag`](?path=/docs/components-tag--docs) | A text label for metadata or category |',
+  '| [`Pill`](?path=/docs/components-pill--docs) | An interactive filter toggle |',
+  '',
+  '```tsx',
+  '// BAD — Icon name="dot" is Lucide\'s 16 px dot glyph, not the design-system circle',
+  '<Icon name="dot" />',
+  '',
+  '// GOOD — Dot is always 10 × 10 and perfectly round',
+  '<Dot colour="green" />',
+  '```',
+  '',
+  '---',
+  '',
+  '### Arbor de-facto colour semantics',
+  '',
+  'The Arbor platform has established informal conventions for Dot colours. These are **not**',
+  'enforced at the design system level — your application owns the semantic mapping — but',
+  'applying them consistently improves recognition across the product.',
+  '',
+  '| Colour | Arbor convention |',
+  '|---|---|',
+  '| `green` | On track, positive attendance, active |',
+  '| `salmon` | Pupil Premium, attention needed |',
+  '| `orange` | At risk, warning |',
+  '| `purple` | SEN |',
+  '| `teal` | EAL |',
+  '| `blue` | Subject or category grouping |',
+  '| `yellow` | Active, neutral attention |',
+  '',
+  'Limit the number of distinct colours visible at once — per the Pills & Tags & Badges',
+  'Confluence guidance, fewer colours used consistently carry more meaning than a full rainbow.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Closed API',
+  '',
+  'Dot is deliberately closed: `colour` and `label` are the only props. There is no `size`',
+  '(always 10 × 10), no `className` or `style` override, and no `onClick`. If you need a',
+  'different size or a clickable indicator, compose a different component.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'Dot has two modes, controlled by the optional `label` prop:',
+  '',
+  '| Mode | When | Markup |',
+  '|---|---|---|',
+  '| **Decorative** (default) | Adjacent text carries the meaning | `aria-hidden="true"` — invisible to assistive technology |',
+  '| **Meaningful** | Dot is standalone with no adjacent label | `aria-label={label}` — announced by screen readers |',
+  '',
+  'The rule is simple:',
+  '',
+  '- If visible text next to the dot tells users what the colour means — omit `label`.',
+  '- If the dot is the only signal — provide `label`.',
+  '',
+  '**WCAG 1.4.1 Use of Colour**: colour alone must never be the only means of conveying',
+  'information. Either provide a `label`, or pair the dot with adjacent text that carries the',
+  'semantic weight.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Dot } from '@arbor-education/design-system.components';",
+  '',
+  'function MyDot(props: Dot.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `Dot.Props` | Full props interface |',
+  "| `Dot.Colour` | `'purple' \\| 'salmon' \\| 'teal' \\| 'yellow' \\| 'green' \\| 'orange' \\| 'blue'` |",
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Tag](?path=/docs/components-tag--docs) · [Badge](?path=/docs/components-badge--docs) · [Icon](?path=/docs/components-icon--docs) · [Pill](?path=/docs/components-pill--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 DotDocsPage() {
+  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 allColours: DotColour[] = ['purple', 'salmon', 'teal', 'yellow', 'green', 'orange', 'blue'];
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
   title: 'Components/Dot',
   component: Dot,
-};
+  parameters: {
+    layout: 'centered',
+    docs: {
+      page: DotDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    colour: {
+      control: 'select',
+      options: allColours,
+      description: [
+        'The background colour of the circle. **Required** — there is no default.',
+        'Establish a consistent semantic mapping in your application (e.g. green = on track,',
+        'salmon = Pupil Premium) and apply it uniformly.',
+      ].join(' '),
+      table: {
+        type: { summary: "'purple' | 'salmon' | 'teal' | 'yellow' | 'green' | 'orange' | 'blue'" },
+      },
+    },
+    label: {
+      control: 'text',
+      description: [
+        'Accessible label for the dot. When omitted (default), the dot is decorative and',
+        'invisible to assistive technology — correct when adjacent visible text carries the',
+        'meaning. When provided, the screen reader announces the label. Use this prop whenever',
+        'the dot is the sole carrier of information (no adjacent text).',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined (decorative — aria-hidden)' },
+      },
+    },
+  },
+} satisfies Meta<typeof Dot>;
 
 export default meta;
-
+// Use StoryObj<typeof Dot> (not typeof meta) so that render-only stories are
+// not forced to provide args for the required `colour` prop — template
+// components supply their own Dot instances directly.
 type Story = StoryObj<typeof Dot>;
 
-export const Purple: Story = { args: { colour: 'purple' } };
-export const Salmon: Story = { args: { colour: 'salmon' } };
-export const Teal: Story = { args: { colour: 'teal' } };
-export const Yellow: Story = { args: { colour: 'yellow' } };
-export const Green: Story = { args: { colour: 'green' } };
-export const Orange: Story = { args: { colour: 'orange' } };
-export const Blue: Story = { args: { colour: 'blue' } };
-
-export const Labeled: Story = {
-  args: {
-    colour: 'purple',
-    label: 'Priority indicator',
-  },
-};
-
-export const AllColours: Story = {
-  render: () => (
-    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
-      <Dot colour="purple" />
-      <Dot colour="salmon" />
-      <Dot colour="teal" />
-      <Dot colour="yellow" />
-      <Dot colour="green" />
-      <Dot colour="orange" />
-      <Dot colour="blue" />
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components for composition stories
+// (Named components avoid react-hooks lint issues — the react-hooks ESLint
+//  plugin is NOT configured in this project, so do NOT add eslint-disable.)
+// ---------------------------------------------------------------------------
+
+const AllColoursTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      background: 'var(--color-grey-050)',
+      borderRadius: 'var(--border-radius-small)',
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: 'var(--spacing-small)',
+      alignItems: 'center',
+    }}
+  >
+    {allColours.map(colour => (
+      <div
+        key={colour}
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          gap: 'var(--spacing-small)',
+        }}
+      >
+        <Dot colour={colour} label={colour} />
+        <span
+          className="ds-text"
+          style={{ color: 'var(--color-grey-600)' }}
+        >
+          {colour}
+        </span>
+      </div>
+    ))}
+  </div>
+);
+
+const DecorativeVsMeaningfulTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      gap: 'var(--spacing-xlarge)',
+      flexWrap: 'wrap',
+    }}
+  >
+    {/* LEFT: Decorative dot — adjacent text carries meaning */}
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)' }}
+      >
+        Decorative (aria-hidden)
+      </p>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--spacing-small)',
+        }}
+      >
+        {/* No label prop — dot is decorative because "Active" text is present */}
+        <Dot colour="green" />
+        <span className="ds-text">Active</span>
+      </div>
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}
+      >
+        Screen reader: &quot;Active&quot;
+      </p>
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)' }}
+      >
+        The dot renders with no label prop. Adjacent text
+        &quot;Active&quot; carries the full meaning — the dot is
+        a decorative reinforcement only.
+      </p>
+    </div>
+
+    {/* RIGHT: Meaningful dot — standalone, no adjacent text */}
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)' }}
+      >
+        Meaningful (aria-label)
+      </p>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--spacing-small)',
+        }}
+      >
+        {/* label prop set — dot is meaningful, no adjacent text */}
+        <Dot colour="green" label="Active" />
+      </div>
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}
+      >
+        Screen reader: &quot;Active&quot;
+      </p>
+      <p
+        className="ds-text"
+        style={{ margin: 0, color: 'var(--color-grey-600)' }}
+      >
+        The dot renders with
+        {' '}
+        <code>label=&quot;Active&quot;</code>
+        . No adjacent text —
+        so the dot itself must carry the semantic meaning via
+        aria-label.
+      </p>
+    </div>
+  </div>
+);
+
+const InTagContextTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      gap: 'var(--spacing-small)',
+      flexWrap: 'wrap',
+      alignItems: 'center',
+    }}
+  >
+    {/*
+      Dot is decorative in all four Tags below — the Tag's text children
+      carry the semantic meaning. flex-shrink: 0 on ds-dot means the circle
+      never collapses inside Tag's internal flex layout.
+    */}
+    <Tag color="blue" slotStart={<Dot colour="blue" />}>Year 7</Tag>
+    <Tag color="green" slotStart={<Dot colour="green" />}>Active</Tag>
+    <Tag color="purple" slotStart={<Dot colour="purple" />}>SEN</Tag>
+    <Tag color="salmon" slotStart={<Dot colour="salmon" />}>At risk</Tag>
+  </div>
+);
+
+const InStatusListTemplate = () => (
+  <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)' }}
+    >
+      Today's attendance
+    </p>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-small)',
+      }}
+    >
+      {/*
+        Most students share the same "Present" (green) dot.
+        Only flagged entries use different colours. This demonstrates
+        the "establish a semantic mapping and apply it consistently"
+        guidance — a meaningful pattern, not a decorative rainbow.
+
+        All dots here are decorative (no label prop) because the
+        adjacent student name + status text carries the meaning.
+      */}
+      {[
+        { name: 'Ahmed Al-Rashidi', status: 'Present', colour: 'green' as DotColour },
+        { name: 'Maria Santos', status: 'Present', colour: 'green' as DotColour },
+        { name: 'James Okonkwo', status: 'Late', colour: 'yellow' as DotColour },
+        { name: 'Chloe Patel', status: 'Medical', colour: 'teal' as DotColour },
+        { name: 'Oliver Wright', status: 'Absent', colour: 'salmon' as DotColour },
+      ].map(({ name, status, colour }) => (
+        <div
+          key={name}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 'var(--spacing-small)',
+          }}
+        >
+          <Dot colour={colour} />
+          <span className="ds-text">{name}</span>
+          <span
+            className="ds-text"
+            style={{ color: 'var(--color-grey-600)' }}
+          >
+            —
+            {' '}
+            {status}
+          </span>
+        </div>
+      ))}
     </div>
-  ),
-};
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      colour: 'purple',
+    },
+    render: args => <Dot {...args} />,
+  },
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore all 7 colours and toggle the `label` prop to switch between decorative (`aria-hidden`) and meaningful (`aria-label`) modes. Dot is decorative by default: no `label` prop means assistive technology ignores it entirely.',
+);
+
+export const AllColours: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Dot } from '@arbor-education/design-system.components';
+
+const allColours = ['purple', 'salmon', 'teal', 'yellow', 'green', 'orange', 'blue'] as const;
+
+function AllColoursTemplate() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        background: 'var(--color-grey-050)',
+        borderRadius: 'var(--border-radius-small)',
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: 'var(--spacing-small)',
+        alignItems: 'center',
+      }}
+    >
+      {allColours.map(colour => (
+        <div
+          key={colour}
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 'var(--spacing-small)',
+          }}
+        >
+          <Dot colour={colour} label={colour} />
+          <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+            {colour}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+export default AllColoursTemplate;
+`.trim(),
+        },
+      },
+    },
+    render: AllColoursTemplate,
+  },
+  [
+    'All 7 `DotColour` values displayed together. The subtle grey wash (`--color-grey-050`)',
+    'background ensures 10 × 10 circles are visible against white canvas. Each dot uses',
+    '`label={colour}` here so screen readers can navigate the story sensibly — in real',
+    'usage, decorative dots paired with visible text would omit the `label` prop.',
+    '',
+    '**Note:** `DotColour` shares its 7 values with `BadgeColour` — a single colour string',
+    'works for both components without any casting.',
+  ].join(' '),
+);
+
+export const WithAccessibleLabel: Story = withDescription(
+  {
+    args: {
+      colour: 'purple',
+      label: 'Purple — SEN category',
+    },
+    render: args => <Dot {...args} />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Dot } from '@arbor-education/design-system.components';
+
+function WithAccessibleLabelExample() {
+  return <Dot colour="purple" label="Purple — SEN category" />;
+}
+export default WithAccessibleLabelExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A dot with a `label` prop — rendered with `aria-label="Purple — SEN category"` and no',
+    '`aria-hidden`. A screen reader navigating to this element announces the label directly.',
+    'Use this pattern whenever the dot is the sole carrier of information — for example, a',
+    'standalone status indicator in a column with no adjacent text. When visible text is',
+    'present beside the dot, omit `label` instead (see **DecorativeVsMeaningful**).',
+  ].join(' '),
+);
+
+export const DecorativeVsMeaningful: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Dot } from '@arbor-education/design-system.components';
+
+function DecorativeVsMeaningfulTemplate() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        gap: 'var(--spacing-xlarge)',
+        flexWrap: 'wrap',
+      }}
+    >
+      {/* Decorative dot — adjacent text carries meaning */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+          Decorative (aria-hidden)
+        </p>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          {/* No label prop — dot is decorative because "Active" text is present */}
+          <Dot colour="green" />
+          <span className="ds-text">Active</span>
+        </div>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+          Screen reader: "Active"
+        </p>
+      </div>
+
+      {/* Meaningful dot — standalone, no adjacent text */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+          Meaningful (aria-label)
+        </p>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          {/* label prop set — dot is meaningful, no adjacent text */}
+          <Dot colour="green" label="Active" />
+        </div>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+          Screen reader: "Active"
+        </p>
+      </div>
+    </div>
+  );
+}
+export default DecorativeVsMeaningfulTemplate;
+`.trim(),
+        },
+      },
+    },
+    render: DecorativeVsMeaningfulTemplate,
+  },
+  [
+    'The core accessibility teaching story. **Left column**: a decorative dot paired with',
+    'visible text ("Active") — no `label` prop, `aria-hidden="true"`, screen reader',
+    'announces only the text. **Right column**: a standalone meaningful dot — `label="Active"`,',
+    'screen reader announces the label.',
+    '',
+    '**WCAG 1.4.1 Use of Colour**: colour alone must never be the only means of conveying',
+    'information. The rule is: if visible text next to the dot tells users what the colour means,',
+    'omit `label`. If the dot is the only signal, provide `label`.',
+  ].join(' '),
+);
+
+export const InTagContext: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Dot, Tag } from '@arbor-education/design-system.components';
+
+function InTagContextTemplate() {
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        gap: 'var(--spacing-small)',
+        flexWrap: 'wrap',
+        alignItems: 'center',
+      }}
+    >
+      <Tag color="blue" slotStart={<Dot colour="blue" />}>Year 7</Tag>
+      <Tag color="green" slotStart={<Dot colour="green" />}>Active</Tag>
+      <Tag color="purple" slotStart={<Dot colour="purple" />}>SEN</Tag>
+      <Tag color="salmon" slotStart={<Dot colour="salmon" />}>At risk</Tag>
+    </div>
+  );
+}
+export default InTagContextTemplate;
+`.trim(),
+        },
+      },
+    },
+    render: InTagContextTemplate,
+  },
+  [
+    'The canonical Arbor usage pattern: `<Tag slotStart={<Dot colour="..." />}>Label</Tag>`.',
+    'All four dots are **decorative** — no `label` prop — because `Tag`\'s text children',
+    '("Year 7", "Active", "SEN", "At risk") already carry the full semantic meaning.',
+    '',
+    '`flex-shrink: 0` is built into `ds-dot`, so the circle never collapses inside',
+    '`Tag`\'s internal flex layout, even in very narrow containers.',
+    '',
+    '**Colour note:** `Tag` and `Dot` use separate colour props (`TagColor` vs `DotColour`)',
+    'but share the same 7 extended-palette values. Always match both to the same colour',
+    'for visual consistency.',
+  ].join(' '),
+);
+
+export const InStatusList: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Dot } from '@arbor-education/design-system.components';
+
+function InStatusListTemplate() {
+  const students = [
+    { name: 'Ahmed Al-Rashidi', status: 'Present', colour: 'green' as const },
+    { name: 'Maria Santos', status: 'Present', colour: 'green' as const },
+    { name: 'James Okonkwo', status: 'Late', colour: 'yellow' as const },
+    { name: 'Chloe Patel', status: 'Medical', colour: 'teal' as const },
+    { name: 'Oliver Wright', status: 'Absent', colour: 'salmon' as const },
+  ];
+
+  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)' }}>
+        Today's attendance
+      </p>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+        {students.map(({ name, status, colour }) => (
+          <div
+            key={name}
+            style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}
+          >
+            <Dot colour={colour} />
+            <span className="ds-text">{name}</span>
+            <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+              — {status}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+export default InStatusListTemplate;
+`.trim(),
+        },
+      },
+    },
+    render: InStatusListTemplate,
+  },
+  [
+    'A realistic Arbor attendance list: student name, status text, and a Dot for each row.',
+    'Most students share the same `green` dot ("Present") — only flagged entries use',
+    'different colours (`yellow` for Late, `teal` for Medical, `salmon` for Absent).',
+    '',
+    'This demonstrates the key design principle: **establish a semantic colour mapping and',
+    'apply it consistently**. A meaningful pattern — where most rows are one colour and',
+    'exceptions stand out — carries far more information than a decorative rainbow.',
+    '',
+    'All dots here are **decorative** (no `label` prop) because the adjacent name and',
+    'status text ("Ahmed Al-Rashidi — Present") carries the full meaning for every row.',
+    'WCAG 1.4.1 is satisfied by the visible text, not the colour alone.',
+  ].join(' '),
+);