@arbor-education/design-system.components 0.25.2 → 0.25.4

package/dist/components/row/Row.stories.js

@@ -1,25 +1,28 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
 import { fn } from 'storybook/test';
+import { Section } from '../section/Section.js';
 import { Row } from './Row.js';
 import { Badge } from '../badge/Badge.js';
 import { Tag } from '../tag/Tag.js';
 import { Icon } from '../icon/Icon.js';
 // ---------------------------------------------------------------------------
-// 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 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).',
     '',
     '---',
     '',
@@ -27,44 +30,75 @@ 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',
     '',
-    'This swap is driven entirely by CSS — no JavaScript state is involved.',
+    '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" />',
+    '```',
+    '',
+    '> **⚠️ 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.',
+    '',
+    '`href` rows render a real `<a>` tag — full native link semantics and announced correctly by screen readers.',
     '',
-    '`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.',
+    '`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 |',
     '',
     '---',
     '',
@@ -77,8 +111,10 @@ const DEVELOPER_NOTES = [
     '',
     'type RowProps = {',
     '  className?: string;',
+    '  style?: CSSProperties;',
     '  label?: ReactNode;',
     '  value?: ReactNode;',
+    '  href?: string;',
     '  note?: ReactNode;',
     '  onClick?: MouseEventHandler<HTMLDivElement>;',
     '};',
@@ -87,7 +123,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');
 // ---------------------------------------------------------------------------
 // Custom DocsPage
@@ -103,6 +139,7 @@ const meta = {
     component: Row,
     tags: ['autodocs'],
     parameters: {
+        layout: 'padded',
         docs: {
             page: RowDocsPage,
         },
@@ -110,8 +147,8 @@ const meta = {
     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: {
@@ -123,6 +160,8 @@ const meta = {
             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: {
@@ -130,22 +169,35 @@ const meta = {
                 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: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
         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: {
-                type: { summary: 'ReactNode' },
+                type: { summary: 'string' },
                 defaultValue: { summary: 'undefined' },
             },
         },
         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,
@@ -155,16 +207,21 @@ const meta = {
             },
         },
         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' },
+            },
+        },
     },
 };
 export default meta;
@@ -175,10 +232,21 @@ const withDescription = (story, description) => ({
     ...story,
     parameters: {
         ...story.parameters,
-        docs: { ...story.parameters?.docs, description: { story: description } },
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
     },
 });
 // ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+const MixedClickableAndStaticTemplate = () => (_jsxs(Section, { title: "Pupil details", children: [_jsx(Row, { label: "Name", value: "Amara Osei-Bonsu" }), _jsx(Row, { label: "Year group", value: "Year 10" }), _jsx(Row, { label: "Form", value: "10JH" }), _jsx(Row, { label: "SEN status", value: "SEN Support", note: "Review due May 2026", onClick: () => { } }), _jsx(Row, { label: "Attendance (YTD)", value: "88.3%", note: "Below 90% threshold", onClick: () => { } })] }));
+const InSectionTemplate = () => (_jsxs(Section, { title: "Personal details", children: [_jsx(Row, { label: "Pupil", value: "Amara Osei-Bonsu" }), _jsx(Row, { label: "Date of birth", value: "14 March 2010" }), _jsx(Row, { label: "Admission number", value: "001847" }), _jsx(Row, { label: "UPN", value: "A823456789012" }), _jsx(Row, { label: "Email address", value: "a.osei-bonsu@pupil.school.example", href: "mailto:a.osei-bonsu@pupil.school.example" })] }));
+const AccessibilityNotesTemplate = () => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-3-14)' }, children: ["Static row \u2014", ' ', _jsx("code", { children: "tabIndex=\"-1\"" }), ", no ARIA role, not in tab order"] }), _jsx(Row, { label: "Year group", value: "Year 9" })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-3-14)' }, children: ["Clickable row \u2014", ' ', _jsx("code", { children: "tabIndex=\"0\"" }), ", keyboard-activatable, but", ' ', _jsxs("strong", { children: ["no", _jsx("code", { children: "role=\"button\"" })] }), ' ', "\u2014 screen readers may not announce it as interactive"] }), _jsx(Row, { label: "SEN record", value: "SEN Support", onClick: () => { } })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-3-14)' }, children: ["href row \u2014 renders a real", ' ', _jsx("code", { children: "<a>" }), ' ', "tag with full native link semantics \u2713"] }), _jsx(Row, { label: "Email address", value: "admin@school.example", href: "mailto:admin@school.example" })] })] }));
+// ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
 export const Default = withDescription({
@@ -189,7 +257,7 @@ export const Default = withDescription({
         onClick: fn(),
     },
     render: args => _jsx(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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -208,8 +276,8 @@ export default EnrolmentStatusRow;
         },
     },
     render: () => _jsx(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.');
-export const LabelAndValue = withDescription({
+}, '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 ValueOnly = withDescription({
     parameters: {
         controls: { disable: true },
         docs: {
@@ -218,16 +286,16 @@ export const LabelAndValue = 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: () => _jsx(Row, { label: "Date of birth", value: "14 March 2009" }),
-}, 'The canonical two-column layout. The label column enforces a minimum width of 190 px so values align consistently when multiple rows are stacked.');
+    render: () => _jsx(Row, { value: "Active" }),
+}, '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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -252,7 +320,103 @@ export default AttendanceRow;
         },
     },
     render: () => (_jsx(Row, { label: "Attendance this term", value: "91.4%", note: "Below school target of 95%" })),
-}, '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 = 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: () => (_jsx(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 = 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: () => _jsx(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 = 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: () => (_jsx(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 = 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: () => (_jsx(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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -277,7 +441,7 @@ export default ClassRow;
         },
     },
     render: () => (_jsx(Row, { label: "Class", value: "9B/En1 \u2014 English", onClick: fn() })),
-}, '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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -303,7 +467,75 @@ export default GuardianRow;
         },
     },
     render: () => (_jsx(Row, { label: "Guardian", value: "Sarah Okafor", note: "Primary contact", onClick: fn() })),
-}, '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 = 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 = 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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -315,7 +547,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"
@@ -335,8 +567,8 @@ export default LongContentExample;
             },
         },
     },
-    render: () => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx(Row, { label: "Special educational needs and disabilities coordinator", value: "Mrs Jacqueline Abernathy-Thornton", note: "Updated 3 January 2026" }), _jsx(Row, { label: "Pupil premium eligibility reason", value: "Free school meals \u2014 ever 6", note: "Verified by LA", onClick: fn() })] })),
-}, '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.');
+    render: () => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx(Row, { label: "Special educational needs and disabilities coordinator", value: "Mrs Jacqueline Abernathy-Thornton", note: "Updated 3 January 2026" }), _jsx(Row, { label: "Pupil premium eligibility reason", value: "Free school meals \u2014 ever 6", note: "Verified by LA", onClick: fn() })] })),
+}, '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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -346,36 +578,24 @@ export const MultipleRows = 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: () => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx(Row, { label: "Pupil", value: "Amara Osei-Bonsu" }), _jsx(Row, { label: "Year group", value: "Year 10" }), _jsx(Row, { label: "Form", value: "10JH" }), _jsx(Row, { label: "Admission number", value: "001847" }), _jsx(Row, { label: "UPN", value: "A823456789012" }), _jsx(Row, { label: "SEN status", value: "SEN Support", note: "Review due May 2026", onClick: fn() }), _jsx(Row, { label: "Attendance (YTD)", value: "88.3%", note: "Below 90% threshold", onClick: fn() })] })),
-}, '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.');
+    render: () => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx(Row, { label: "Pupil", value: "Amara Osei-Bonsu" }), _jsx(Row, { label: "Year group", value: "Year 10" }), _jsx(Row, { label: "Form", value: "10JH" }), _jsx(Row, { label: "Admission number", value: "001847" }), _jsx(Row, { label: "UPN", value: "A823456789012" })] })),
+}, '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 = withDescription({
     parameters: {
         controls: { disable: true },
@@ -462,4 +682,82 @@ export default AnnotatedLabelRows;
     },
     render: () => (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx(Row, { label: (_jsxs("span", { style: { display: 'flex', alignItems: 'center', gap: 4 }, children: ["Pupil premium", ' ', _jsx(Icon, { name: "info", size: 16 })] })), value: "Free school meals \u2014 ever 6" }), _jsx(Row, { label: (_jsxs("span", { style: { display: 'flex', alignItems: 'center', gap: 4 }, children: ["EHCP status", ' ', _jsx(Icon, { name: "info", size: 16 })] })), value: "EHC plan in place" })] })),
 }, '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 = 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 = 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: () => (_jsx(Row, { label: "Safeguarding flag", value: "CP Plan \u2014 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 = 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: () => _jsx(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.');
 //# sourceMappingURL=Row.stories.js.map