@arbor-education/design-system.components 0.25.1 → 0.25.3

package/src/components/row/Row.stories.tsx

@@ -9,28 +9,33 @@ import {
   Title,
 } from '@storybook/addon-docs/blocks';
 import { fn } from 'storybook/test';
+import { Section } from 'Components/section/Section.js';
 
 import { Row } from './Row.js';
+import { Badge } from 'Components/badge/Badge';
+import { Tag } from 'Components/tag/Tag';
+import { Icon } from 'Components/icon/Icon';
 
 // ---------------------------------------------------------------------------
-// Content strings for the custom DocsPage
+// Docs page content
 // ---------------------------------------------------------------------------
 
 const DESCRIPTION_INTRO = [
-  '`Row` is a single-line display component used to present a labelled piece of data — optionally with a supporting note — inside summary panels, detail cards, or any section-style layout.',
-  'When an `onClick` handler is provided the row becomes fully interactive: it gains hover and focus styles, renders a pair of animated directional icons, and responds to keyboard activation via **Enter** and **Space**.',
+  '`Row` is a single-line display component for presenting a labelled piece of data inside summary panels, detail cards, or section-style layouts.',
+  'Pass an `onClick` handler to make the row fully interactive — it enters the tab order, gains hover and focus styles, and renders a pair of animated directional icons.',
+  'Pass `href` to turn the value into a native anchor link, supporting any protocol including `mailto:` and `tel:`.',
 ].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 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',
   '',
-  '- Displaying a labelled piece of read-only data inside a detail panel or summary card (e.g. "Year group · Year 9").',
+  '- Displaying a labelled key-value pair in a detail panel or summary card (e.g. "Year group · Year 9").',
   '- Rendering a list of named data points where a consistent label/value layout improves scannability.',
-  '- Providing a tappable/clickable drill-down link to a related record or page when `onClick` is supplied.',
-  '- Showing supplementary context alongside a value (e.g. a last-updated timestamp in the `note` slot).',
+  '- Providing a clickable drill-down link to a related record when `onClick` is supplied.',
+  '- Wrapping a value in a native link (URL, email address, phone number) via the `href` prop.',
+  '- Showing supplementary context alongside a value (e.g. a threshold note or timestamp in the `note` slot).',
   '',
   '---',
   '',
@@ -38,45 +43,76 @@ const USAGE_GUIDANCE = [
   '',
   '| Situation | Use instead |',
   '|---|---|',
-  '| Navigation links | Native `<a>` or router `<Link>` — a `div` with `onClick` is not a true anchor |',
   '| Tabular data with sortable columns | [`Table`](?path=/docs/components-table--docs) |',
+  '| Form controls with labels | [`FormField`](?path=/docs/components-formfield--docs) |',
   '| Toggling or selecting items | Checkbox or radio group |',
-  '| Form controls | [`FormField`](?path=/docs/components-formfield--docs) with an appropriate input |',
+  '| Navigation links standing alone | Native `<a>` or router `<Link>` |',
 ].join('\n');
 
 const DEVELOPER_NOTES = [
   '### Clickable vs static rows',
   '',
-  'The `onClick` prop is the **sole toggle** for all clickable behaviour — there is no separate `isClickable` prop or variant enum.',
+  'The `onClick` prop is the **sole toggle** for all interactive behaviour — there is no separate `isClickable` prop.',
   '',
   '| State | `tabIndex` | CSS modifier | Icons rendered |',
   '|---|---|---|---|',
   '| Static | `-1` (not in tab order) | — | None |',
   '| Clickable | `0` (in tab order) | `ds-row--clickable` | `chevron-right` + `arrow-right` |',
   '',
-  '**Dual-icon swap:** Both icons are always rendered when `onClick` is provided, but CSS controls their visibility:',
+  '**Dual-icon swap:** Both icons are always in the DOM when `onClick` is provided. CSS controls visibility —',
+  'at rest `chevron-right` shows; on hover/focus `arrow-right` shows. No JavaScript state is involved.',
   '',
-  '- **At rest:** `chevron-right` is visible; `arrow-right` is hidden via `display: none`.',
-  '- **On hover / focus:** `chevron-right` is hidden; `arrow-right` becomes visible.',
+  '---',
+  '',
+  '### The `href` prop and value fallback',
+  '',
+  'When `href` is provided, the value is wrapped in a native `<a>` element:',
+  '',
+  '```tsx',
+  '// value becomes the link text',
+  '<Row label="Email" value="admin@school.com" href="mailto:admin@school.com" />',
+  '',
+  '// href becomes the link text when value is omitted — avoid with special protocols',
+  '<Row label="Profile" href="/students/123" />',
+  '```',
   '',
-  'This swap is driven entirely by CSS — no JavaScript state is involved.',
+  '> **⚠️ Always provide `value` when using `mailto:` or `tel:` hrefs.** Without `value`, the raw protocol',
+  '> string (e.g. `"mailto:admin@school.com"`) is used as link text.',
   '',
   '---',
   '',
   '### Keyboard activation',
   '',
-  'Clickable rows respond to **Enter** and **Space** keydown events by firing the `onClick` handler.',
+  'Clickable rows respond to **Enter** and **Space** keydown events.',
+  'The focus ring uses `box-shadow: 0 0 0 3px var(--color-brand-300)` — applied on `:focus`.',
   '',
   '---',
   '',
   '### Accessibility gap',
   '',
-  '> **Known limitation:** Clickable `Row` instances render as a `<div>` with no `role="button"` attribute.',
-  '> Screen readers will not announce the element as a button, and `getByRole("button")` will not find it.',
+  '> **Known limitation:** The clickable row renders as a `<div>` with no `role="button"` attribute.',
+  '> Screen readers will not announce it as interactive. Keyboard users can still activate it, but',
+  '> VoiceOver/NVDA users have no indication the row is actionable.',
   '',
-  '`Row` does **not** spread arbitrary HTML attributes. The `className` prop is the only escape hatch.',
-  'Consumers **cannot** add `aria-label`, `aria-describedby`, `data-testid`, or any HTML attribute without modifying the component source.',
-  'These are documented design-debt items for a future accessibility audit.',
+  '`href` rows render a real `<a>` tag — full native link semantics and announced correctly by screen readers.',
+  '',
+  '`Row` does **not** spread arbitrary HTML attributes. `className` and `style` are the only escape hatches.',
+  '',
+  '---',
+  '',
+  '### Component tokens',
+  '',
+  'Row is themed entirely through `--section-list-row-*` component tokens:',
+  '',
+  '| Token | Purpose |',
+  '|---|---|',
+  '| `--section-list-row-default-color-background` | Resting background colour |',
+  '| `--section-list-row-hover-hover-bg` | Hover background (clickable rows only) |',
+  '| `--section-list-row-spacing-vertical` | Top/bottom padding |',
+  '| `--section-list-row-spacing-horizontal` | Left/right padding |',
+  '| `--section-list-row-radius` | Border radius |',
+  '| `--section-list-row-default-color-icon-arrow` | Chevron/arrow icon stroke at rest |',
+  '| `--section-list-row-hover-color-icon-arrow` | Chevron/arrow icon stroke on hover |',
   '',
   '---',
   '',
@@ -85,12 +121,15 @@ const DEVELOPER_NOTES = [
   '```ts',
   "import { Row } from '@arbor-education/design-system.components';",
   "import type { RowProps } from '@arbor-education/design-system.components';",
+  "import type { ReactNode } from 'react';",
   '',
   'type RowProps = {',
   '  className?: string;',
-  '  label?: string;',
-  '  value?: string;',
-  '  note?: string;',
+  '  style?: CSSProperties;',
+  '  label?: ReactNode;',
+  '  value?: ReactNode;',
+  '  href?: string;',
+  '  note?: ReactNode;',
   '  onClick?: MouseEventHandler<HTMLDivElement>;',
   '};',
   '```',
@@ -99,7 +138,7 @@ const DEVELOPER_NOTES = [
 const RELATED_COMPONENTS = [
   '## Related components',
   '',
-  '[Section](?path=/docs/components-section--docs) · [Card](?path=/docs/components-card--docs) · [Table](?path=/docs/components-table--docs)',
+  '[Section](?path=/docs/components-section--docs) · [Card](?path=/docs/components-card--docs) · [Table](?path=/docs/components-table--docs) · [FormField](?path=/docs/components-formfield--docs)',
 ].join('\n');
 
 // ---------------------------------------------------------------------------
@@ -131,11 +170,12 @@ function RowDocsPage() {
 // Meta
 // ---------------------------------------------------------------------------
 
-const meta: Meta<typeof Row> = {
+const meta = {
   title: 'Components/Row',
   component: Row,
   tags: ['autodocs'],
   parameters: {
+    layout: 'padded',
     docs: {
       page: RowDocsPage,
     },
@@ -143,12 +183,12 @@ const meta: Meta<typeof Row> = {
   argTypes: {
     label: {
       description: [
-        'The left-hand label that identifies the data point.',
-        'Renders inside a `<span>` with a minimum width of 190 px so labels align consistently across stacked rows.',
+        'Left-column text identifying the data point.',
+        'Rendered in a `<span>` with semi-bold weight and a maximum width of 190 px so labels align consistently across stacked rows.',
       ].join(' '),
       control: 'text',
       table: {
-        type: { summary: 'string' },
+        type: { summary: 'ReactNode' },
         defaultValue: { summary: 'undefined' },
       },
     },
@@ -156,6 +196,20 @@ const meta: Meta<typeof Row> = {
       description: [
         'The right-hand value corresponding to the label.',
         'Renders in the centre column with `flex-grow: 1`, filling available width.',
+        'When `href` is provided, this becomes the anchor text.',
+        'If `href` is set and `value` is omitted, the href string itself is used as the link text.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    href: {
+      description: [
+        'When provided, wraps `value` in a native `<a>` element pointing to this URL.',
+        'Supports any protocol — `https://`, `mailto:`, `tel:`, etc.',
+        'Always provide `value` when using `mailto:` or `tel:` — without it the raw protocol string becomes the link text.',
       ].join(' '),
       control: 'text',
       table: {
@@ -165,8 +219,9 @@ const meta: Meta<typeof Row> = {
     },
     note: {
       description: [
-        'Optional supplementary text rendered after the value — displayed in italics.',
-        'Useful for timestamps, caveats, or secondary context.',
+        'Supplementary italic text rendered right-aligned after the value.',
+        'When present, the CSS `:has()` selector reduces the value column\'s `flex-basis` from 70% to 50% to make room.',
+        'Useful for thresholds, last-updated timestamps, or secondary context.',
       ].join(' '),
       control: 'text',
       table: {
@@ -176,9 +231,9 @@ const meta: Meta<typeof Row> = {
     },
     onClick: {
       description: [
-        'When provided, the row becomes interactive: it enters the tab order (`tabIndex={0}`),',
-        'gains the `ds-row--clickable` modifier, shows hover/focus styles, and renders dual directional icons.',
-        'Supports **Enter** and **Space** keyboard activation.',
+        'When provided, activates all clickable behaviour: the row enters the tab order (`tabIndex={0}`),',
+        'gains the `ds-row--clickable` modifier, shows hover/focus styles, and renders the dual directional icon pair.',
+        'Responds to **Enter** and **Space** keyboard events.',
       ].join(' '),
       action: 'onClick',
       control: false,
@@ -188,21 +243,26 @@ const meta: Meta<typeof Row> = {
       },
     },
     className: {
-      description: [
-        'Additional CSS class names applied to the root `<div>`.',
-        'This is the only HTML-attribute escape hatch — arbitrary HTML attributes cannot be passed via props.',
-      ].join(' '),
+      description: 'Additional CSS class names applied to the root `<div>`. The only HTML-attribute escape hatch — arbitrary attributes like `aria-label` or `data-testid` cannot be passed without modifying the component.',
       control: 'text',
       table: {
         type: { summary: 'string' },
         defaultValue: { summary: 'undefined' },
       },
     },
+    style: {
+      description: 'Inline styles applied to the root `<div>`.',
+      control: false,
+      table: {
+        type: { summary: 'CSSProperties' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
   },
-};
+} satisfies Meta<typeof Row>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Row>;
 
 // ---------------------------------------------------------------------------
 // Helper
@@ -212,10 +272,97 @@ const withDescription = (story: Story, description: string): Story => ({
   ...story,
   parameters: {
     ...story.parameters,
-    docs: { ...story.parameters?.docs, description: { story: description } },
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
   },
 });
 
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const MixedClickableAndStaticTemplate = () => (
+  <Section title="Pupil details">
+    <Row label="Name" value="Amara Osei-Bonsu" />
+    <Row label="Year group" value="Year 10" />
+    <Row label="Form" value="10JH" />
+    <Row
+      label="SEN status"
+      value="SEN Support"
+      note="Review due May 2026"
+      onClick={() => {}}
+    />
+    <Row
+      label="Attendance (YTD)"
+      value="88.3%"
+      note="Below 90% threshold"
+      onClick={() => {}}
+    />
+  </Section>
+);
+
+const InSectionTemplate = () => (
+  <Section title="Personal details">
+    <Row label="Pupil" value="Amara Osei-Bonsu" />
+    <Row label="Date of birth" value="14 March 2010" />
+    <Row label="Admission number" value="001847" />
+    <Row label="UPN" value="A823456789012" />
+    <Row
+      label="Email address"
+      value="a.osei-bonsu@pupil.school.example"
+      href="mailto:a.osei-bonsu@pupil.school.example"
+    />
+  </Section>
+);
+
+const AccessibilityNotesTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+      <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-3-14)' }}>
+        Static row —
+        {' '}
+        <code>tabIndex=&quot;-1&quot;</code>
+        , no ARIA role, not in tab order
+      </p>
+      <Row label="Year group" value="Year 9" />
+    </div>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+      <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-3-14)' }}>
+        Clickable row —
+        {' '}
+        <code>tabIndex=&quot;0&quot;</code>
+        , keyboard-activatable, but
+        {' '}
+        <strong>
+          no
+          <code>role=&quot;button&quot;</code>
+        </strong>
+        {' '}
+        — screen readers may not announce it as interactive
+      </p>
+      <Row label="SEN record" value="SEN Support" onClick={() => {}} />
+    </div>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+      <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-3-14)' }}>
+        href row — renders a real
+        {' '}
+        <code>&lt;a&gt;</code>
+        {' '}
+        tag with full native link semantics ✓
+      </p>
+      <Row
+        label="Email address"
+        value="admin@school.example"
+        href="mailto:admin@school.example"
+      />
+    </div>
+  </div>
+);
+
 // ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
@@ -230,7 +377,7 @@ export const Default: Story = withDescription(
     },
     render: args => <Row {...args} />,
   },
-  'The default story is wired to the Controls panel. By default it is clickable — remove `onClick` from the controls to switch to static mode and observe how the icons and hover behaviour disappear.',
+  'The interactive canvas — every prop is wired to the Controls panel. By default the row is clickable — clear `onClick` from the controls to switch to static mode and observe how the icons and hover behaviour disappear.',
 );
 
 export const LabelOnly: Story = withDescription(
@@ -253,10 +400,10 @@ export default EnrolmentStatusRow;
     },
     render: () => <Row label="Enrolment status" />,
   },
-  'Minimum meaningful render — a label with no value or note. Both sibling `<span>` elements still render in the DOM (they are unconditionally present), but remain empty.',
+  'Minimum meaningful render — a label with no value, href, or note. The value and note `<span>` elements still render in the DOM but remain empty. The row holds its correct minimum height.',
 );
 
-export const LabelAndValue: Story = withDescription(
+export const ValueOnly: Story = withDescription(
   {
     parameters: {
       controls: { disable: true },
@@ -266,17 +413,17 @@ export const LabelAndValue: Story = withDescription(
           code: `
 import { Row } from '@arbor-education/design-system.components';
 
-function DateOfBirthRow() {
-  return <Row label="Date of birth" value="14 March 2009" />;
+function ActiveStatusRow() {
+  return <Row value="Active" />;
 }
-export default DateOfBirthRow;
+export default ActiveStatusRow;
 `.trim(),
         },
       },
     },
-    render: () => <Row label="Date of birth" value="14 March 2009" />,
+    render: () => <Row value="Active" />,
   },
-  'The canonical two-column layout. The label column enforces a minimum width of 190 px so values align consistently when multiple rows are stacked.',
+  'A value with no label — the label column renders empty. Valid but uncommon; most real-world rows pair a label with every value.',
 );
 
 export const WithNote: Story = withDescription(
@@ -311,7 +458,138 @@ export default AttendanceRow;
       />
     ),
   },
-  'Adding a `note` renders supplementary italic text alongside the value. Use it for thresholds, last-updated timestamps, or secondary context that helps a user interpret the value.',
+  'Adding `note` renders supplementary italic text right-aligned after the value. The CSS `:has()` selector automatically shrinks the value column from 70% to 50% flex-basis to make room. Use notes for thresholds, last-updated timestamps, or secondary context that helps interpret the value.',
+);
+
+export const WithHref: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function ProfileLinkRow() {
+  return (
+    <Row
+      label="Student profile"
+      value="View full profile"
+      href="/students/amara-osei-bonsu"
+    />
+  );
+}
+export default ProfileLinkRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Row
+        label="Student profile"
+        value="View full profile"
+        href="/students/amara-osei-bonsu"
+      />
+    ),
+  },
+  'When `href` is provided alongside `value`, the value text becomes the anchor text. The `<a>` element carries full native link semantics — right-click opens the browser context menu, the link can be opened in a new tab, and screen readers announce it correctly as a link.',
+);
+
+export const WithHrefFallback: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+// ⚠️ href without value — the href string becomes the link text
+function HrefFallbackRow() {
+  return <Row label="Profile" href="/students/123" />;
+}
+export default HrefFallbackRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => <Row label="Profile" href="/students/123" />,
+  },
+  'When `href` is set but `value` is omitted, the href string itself is used as the link text (`value || href`). For plain paths like `/students/123` this is acceptable. For `mailto:` or `tel:` hrefs, the raw URI string is exposed to the user — always pair those with an explicit `value`. See the **WithHrefMailto** story for the correct email pattern.',
+);
+
+export const WithHrefMailto: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function EmailRow() {
+  return (
+    <Row
+      label="Email address"
+      value="j.smith@school.example"
+      href="mailto:j.smith@school.example"
+    />
+  );
+}
+export default EmailRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Row
+        label="Email address"
+        value="j.smith@school.example"
+        href="mailto:j.smith@school.example"
+      />
+    ),
+  },
+  'The canonical email-address pattern: `href="mailto:..."` opens the user\'s mail client and `value` is the human-readable address shown as link text. Always provide `value` with `mailto:` hrefs — omitting it exposes the raw protocol string (e.g. `"mailto:j.smith@school.example"`) as link text.',
+);
+
+export const WithHrefAndNote: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function GuardianEmailRow() {
+  return (
+    <Row
+      label="Guardian email"
+      value="s.okafor@guardian.example"
+      href="mailto:s.okafor@guardian.example"
+      note="Primary contact"
+    />
+  );
+}
+export default GuardianEmailRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Row
+        label="Guardian email"
+        value="s.okafor@guardian.example"
+        href="mailto:s.okafor@guardian.example"
+        note="Primary contact"
+      />
+    ),
+  },
+  '`href` and `note` used together. The anchor sits in the value column while the note stays right-aligned. The CSS `:has()` reflow is active — the value column narrows to 50% flex-basis to accommodate the note.',
 );
 
 export const Clickable: Story = withDescription(
@@ -346,7 +624,7 @@ export default ClassRow;
       />
     ),
   },
-  'Providing an `onClick` handler activates all clickable behaviour: the row gains `ds-row--clickable`, enters the tab order, shows hover/focus styles, and renders the dual-icon pair. **Hover the row** to see the icon swap from `chevron-right` to `arrow-right`. Press **Enter** or **Space** to fire the handler.',
+  'Providing `onClick` activates all clickable behaviour: `ds-row--clickable` modifier, pointer cursor, hover background, and the dual icon pair. **Hover the row** to see `chevron-right` swap to `arrow-right` — a pure CSS transition with no JavaScript state. Press **Tab** to focus, then **Enter** or **Space** to fire the handler.',
 );
 
 export const ClickableWithNote: Story = withDescription(
@@ -383,7 +661,83 @@ export default GuardianRow;
       />
     ),
   },
-  'All four content props used together with a clickable row. The note remains visible while the row is fully interactive — useful when secondary context (like "Primary contact") helps the user decide whether to navigate.',
+  'Clickable row with all three right-side elements active: value, note, and the chevron/arrow icon pair. The note takes 20% flex-basis; the value narrows to 50%; the icon is flex-shrunk. The secondary context ("Primary contact") persists alongside the navigation affordance.',
+);
+
+export const MixedClickableAndStatic: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Section } from '@arbor-education/design-system.components';
+
+function PupilDetailSection() {
+  return (
+    <Section title="Pupil details">
+      <Row label="Name" value="Amara Osei-Bonsu" />
+      <Row label="Year group" value="Year 10" />
+      <Row label="Form" value="10JH" />
+      <Row
+        label="SEN status"
+        value="SEN Support"
+        note="Review due May 2026"
+        onClick={() => navigateToSENRecord()}
+      />
+      <Row
+        label="Attendance (YTD)"
+        value="88.3%"
+        note="Below 90% threshold"
+        onClick={() => navigateToAttendance()}
+      />
+    </Section>
+  );
+}
+export default PupilDetailSection;
+`.trim(),
+        },
+      },
+    },
+    render: MixedClickableAndStaticTemplate,
+  },
+  'Static and clickable rows freely mixed inside a `Section`. Static rows display data; clickable rows provide navigation affordance. The visual contrast — pointer cursor, hover background, directional icon — makes the interactive rows immediately distinguishable without extra labelling.',
+);
+
+export const InSection: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Section } from '@arbor-education/design-system.components';
+
+function PersonalDetailsSection() {
+  return (
+    <Section title="Personal details">
+      <Row label="Pupil" value="Amara Osei-Bonsu" />
+      <Row label="Date of birth" value="14 March 2010" />
+      <Row label="Admission number" value="001847" />
+      <Row label="UPN" value="A823456789012" />
+      <Row
+        label="Email address"
+        value="a.osei-bonsu@pupil.school.example"
+        href="mailto:a.osei-bonsu@pupil.school.example"
+      />
+    </Section>
+  );
+}
+export default PersonalDetailsSection;
+`.trim(),
+        },
+      },
+    },
+    render: InSectionTemplate,
+  },
+  'The canonical real-world usage: `Row` components as children of a `Section`. The `Section` provides the container heading and background; each `Row` handles the label/value layout. Most product uses of `Row` are inside a `Section`.',
 );
 
 export const LongContent: Story = withDescription(
@@ -398,7 +752,7 @@ import { Row } from '@arbor-education/design-system.components';
 
 function LongContentExample() {
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
       <Row
         label="Special educational needs and disabilities coordinator"
         value="Mrs Jacqueline Abernathy-Thornton"
@@ -419,7 +773,7 @@ export default LongContentExample;
       },
     },
     render: () => (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
         <Row
           label="Special educational needs and disabilities coordinator"
           value="Mrs Jacqueline Abernathy-Thornton"
@@ -434,7 +788,7 @@ export default LongContentExample;
       </div>
     ),
   },
-  'Long label and value strings exercise the flex layout. The label column maintains its 190 px minimum width, which may compress the value column significantly in narrow containers.',
+  'Long label and value strings exercise the flex layout. The label column enforces a 190 px maximum width — long labels wrap rather than compress the value column. Test your specific container widths if you have long copy in narrow panels.',
 );
 
 export const MultipleRows: Story = withDescription(
@@ -447,55 +801,259 @@ export const MultipleRows: Story = withDescription(
           code: `
 import { Row } from '@arbor-education/design-system.components';
 
-function PupilDetailPanel() {
+function PupilDataList() {
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
       <Row label="Pupil" value="Amara Osei-Bonsu" />
       <Row label="Year group" value="Year 10" />
       <Row label="Form" value="10JH" />
       <Row label="Admission number" value="001847" />
       <Row label="UPN" value="A823456789012" />
-      <Row
-        label="SEN status"
-        value="SEN Support"
-        note="Review due May 2026"
-        onClick={() => navigateToSENRecord()}
-      />
-      <Row
-        label="Attendance (YTD)"
-        value="88.3%"
-        note="Below 90% threshold"
-        onClick={() => navigateToAttendance()}
-      />
     </div>
   );
 }
-export default PupilDetailPanel;
+export default PupilDataList;
 `.trim(),
         },
       },
     },
     render: () => (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
         <Row label="Pupil" value="Amara Osei-Bonsu" />
         <Row label="Year group" value="Year 10" />
         <Row label="Form" value="10JH" />
         <Row label="Admission number" value="001847" />
         <Row label="UPN" value="A823456789012" />
+      </div>
+    ),
+  },
+  'Multiple static rows stacked with `gap: var(--spacing-xsmall)`. Each `Row` carries its own background and padding — the gap sits between rows. Use `Section` as the outer container in production to get the correct heading and container treatment.',
+);
+
+export const ReactNodeInValue: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Badge } from '@arbor-education/design-system.components';
+
+function SENStatusRows() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <Row label="SEN status" value={<Badge colour="orange">SEN Support</Badge>} />
+      <Row label="Admission type" value={<Badge colour="blue">Looked after child</Badge>} />
+    </div>
+  );
+}
+export default SENStatusRows;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+        <Row label="SEN status" value={<Badge colour="orange">SEN Support</Badge>} />
+        <Row label="Admission type" value={<Badge colour="blue">Looked after child</Badge>} />
+      </div>
+    ),
+  },
+  'The `value` prop accepts any `ReactNode`, so status badges, coloured indicators, or formatted markup can replace plain strings. A `Badge` communicates urgency or category at a glance without the reader having to interpret the text alone.',
+);
+
+export const ReactNodeInNote: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Tag } from '@arbor-education/design-system.components';
+
+function AttendanceRows() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <Row label="Attendance this term" value="91.4%" note={<Tag color="orange">Below target</Tag>} />
+      <Row label="Reading age" value="8y 4m" note={<Tag color="green">On track</Tag>} />
+    </div>
+  );
+}
+export default AttendanceRows;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+        <Row label="Attendance this term" value="91.4%" note={<Tag color="orange">Below target</Tag>} />
+        <Row label="Reading age" value="8y 4m" note={<Tag color="green">On track</Tag>} />
+      </div>
+    ),
+  },
+  'The `note` slot accepts any `ReactNode` — a coloured `Tag` conveys urgency or status at a glance without burying it in prose. Pair with a plain-text `value` so the primary reading stays clean while the note provides a quick visual cue about whether the value is within an expected range.',
+);
+
+export const ReactNodeInLabel: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Icon } from '@arbor-education/design-system.components';
+
+function AnnotatedLabelRows() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <Row
+        label={
+          <span style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+            Pupil premium <Icon name="info" size={16} />
+          </span>
+        }
+        value="Free school meals — ever 6"
+      />
+      <Row
+        label={
+          <span style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+            EHCP status <Icon name="info" size={16} />
+          </span>
+        }
+        value="EHC plan in place"
+      />
+    </div>
+  );
+}
+export default AnnotatedLabelRows;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
         <Row
-          label="SEN status"
-          value="SEN Support"
-          note="Review due May 2026"
-          onClick={fn()}
+          label={(
+            <span style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+              Pupil premium
+              {' '}
+              <Icon name="info" size={16} />
+            </span>
+          )}
+          value="Free school meals — ever 6"
         />
         <Row
-          label="Attendance (YTD)"
-          value="88.3%"
-          note="Below 90% threshold"
-          onClick={fn()}
+          label={(
+            <span style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+              EHCP status
+              {' '}
+              <Icon name="info" size={16} />
+            </span>
+          )}
+          value="EHC plan in place"
         />
       </div>
     ),
   },
-  'A realistic pupil detail panel — the most common real-world usage. Static and clickable rows can be freely mixed. The `gap: var(--spacing-small)` wrapper token matches the spacing the component uses internally, keeping visual rhythm consistent.',
+  'The `label` slot accepts any `ReactNode` — inline icons can annotate labels that require clarification. An `Icon` placed inline with the label text signals to the user that more information is available, without cluttering the value column.',
+);
+
+export const AccessibilityNotes: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+// Static: tabIndex="-1", no ARIA role, not keyboard-focusable
+<Row label="Year group" value="Year 9" />
+
+// Clickable: tabIndex="0", Enter/Space activate onClick
+// ⚠️ No role="button" — screen readers may not announce as interactive
+<Row label="SEN record" value="SEN Support" onClick={handleClick} />
+
+// href: real <a> tag — full native link semantics, announced as a link ✓
+<Row label="Email address" value="admin@school.example" href="mailto:admin@school.example" />
+`.trim(),
+        },
+      },
+    },
+    render: AccessibilityNotesTemplate,
+  },
+  [
+    '**Known accessibility gap:** Clickable rows (`onClick` provided) render as a `<div>` with no `role="button"`.',
+    'Screen readers will not announce them as interactive.',
+    'Keyboard users can still activate via Tab + Enter/Space, but VoiceOver/NVDA users have no indication the row is actionable.',
+    '',
+    '`href` rows are the exception — they render a real `<a>` tag with full native link semantics.',
+    '',
+    'If your use case requires screen-reader announcements on clickable rows, pass `className` with a workaround or request a component update.',
+  ].join(' '),
+);
+
+export const CustomClassAndStyle: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function HighlightedRow() {
+  return (
+    <Row
+      label="Safeguarding flag"
+      value="CP Plan — Stage 3"
+      className="my-highlighted-row"
+      style={{ borderLeft: '4px solid var(--color-semantic-destructive-600)' }}
+    />
+  );
+}
+export default HighlightedRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Row
+        label="Safeguarding flag"
+        value="CP Plan — Stage 3"
+        className="my-highlighted-row"
+        style={{ borderLeft: '4px solid var(--color-semantic-destructive-600)' }}
+      />
+    ),
+  },
+  '`className` and `style` are the only HTML-attribute escape hatches — `Row` does not spread arbitrary HTML attributes. Use `className` to apply component-token overrides or modifier classes; use `style` for one-off inline tweaks.',
+);
+
+export const EmptyRow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+// All props omitted — renders three empty spans in a flex container
+function EmptyRowExample() {
+  return <Row />;
+}
+export default EmptyRowExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => <Row />,
+  },
+  'All props omitted. The component renders without crashing — three empty `<span>` elements in a flex container at the default row height. A `Row` with no props is visible as an empty strip, not invisible, so conditionally-rendered row content produces a layout placeholder rather than disappearing silently.',
 );