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

package/src/components/heading/Heading.stories.tsx

@@ -1,142 +1,774 @@
-import type { Meta } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { Heading } from './Heading';
-import { Button } from '../button/Button';
-import { Icon } from '../icon/Icon';
+import { Button } from 'Components/button/Button';
 import { EditableText } from 'Components/editableText/EditableText';
+import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
 
-const meta: Meta<typeof Heading> = {
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'The **Heading** component is the page-level heading area for Arbor screens. It renders',
+  'a semantic `h1`–`h4` element (driven by the `level` prop) with consistent typography',
+  'tokens and optional inline action controls — all in one composable unit. It grounds the',
+  'user at a glance: "you are HERE, and here is what you can do."',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Page-level headings** — the primary H1 heading at the top of any Arbor page',
+  '- **Entity names** — the name of the thing the user is looking at (a student record, an attendance register, a report)',
+  '- **Section headers** — H2–H4 sub-headings with optional contextual actions',
+  '- **Orienting the user** — any moment where "where am I?" is a genuine question',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Instead of Heading... | Use... | Why |',
+  '|---|---|---|',
+  '| Section headings inside cards or sidebars | Plain `<h2>` / `<h3>` with custom styling | Heading always fills 100% container width; it is designed for page-level layout, not embedded UI |',
+  '| Subtitles or sub-labels under a heading | Nothing — subtitles are **explicitly banned** by the design spec | The design system does not support subtitle slots; adding one breaks the page heading contract |',
+  '| Decorative or marketing text | A plain styled element (`<p>`, `<span>`) | Semantic headings affect page outline and screen reader navigation — don\'t pollute the outline |',
+  '',
+  '---',
+  '',
+  '### Design guidance (from Confluence page 2393767941)',
+  '',
+  '- **Single H1 per page** — using more than one H1 breaks accessibility and dilutes the page hierarchy.',
+  '  The H1 is almost always the entity name.',
+  '- **Actions: max 1 primary + 2 secondary** — the Confluence spec recommends 1–2 total, with a hard ceiling',
+  '  of 3. If you have more than 3 actions, consolidate into a `Dropdown`.',
+  '- **No subtitles** — the design spec explicitly bans subtitle slots in page headings.',
+  '- **Small screens** — heading controls stack below the title. They do NOT collapse into an overflow menu.',
+  '  Keep your action count low so stacking looks intentional on mobile.',
+  '- **Back button** — the back-chevron pattern (tertiary button in the left container) is a **legacy pattern**',
+  '  being phased out. New pages should use deterministic navigation instead.',
+  '',
+  '---',
+  '',
+  '### The compound component split',
+  '',
+  'Heading is a compound component with one static sub-component: `Heading.InnerContainer`.',
+  '',
+  'When you pass **two** `Heading.InnerContainer` children, the heading\'s CSS (`justify-content: space-between`)',
+  'automatically pushes the first container to the left and the second to the right. No extra layout',
+  'wrapper or flex gymnastics needed:',
+  '',
+  '```tsx',
+  '<Heading level={1}>',
+  '  <Heading.InnerContainer>Student records</Heading.InnerContainer>',
+  '  <Heading.InnerContainer>',
+  '    <Button variant="primary" type="button">Save changes</Button>',
+  '  </Heading.InnerContainer>',
+  '</Heading>',
+  '```',
+  '',
+  '`Heading.InnerContainer` is just a `<span>` with `className="ds-heading__inner-container"`. It groups',
+  'content on one side. It inherits the heading\'s typography tokens, so its text renders at the correct',
+  'heading size automatically.',
+  '',
+  '#### `className="medium-spacing-gap"` utility',
+  '',
+  'When multiple buttons sit in a single `Heading.InnerContainer`, add `className="medium-spacing-gap"`',
+  'to that container. This is a global utility class from `src/global.scss` (line 11) that applies',
+  '`gap: var(--spacing-small)` between flex children. It is the canonical way to space multiple buttons',
+  'in a heading — do not add manual margins or padding.',
+  '',
+  '```tsx',
+  '<Heading.InnerContainer className="medium-spacing-gap">',
+  '  <Button variant="secondary" type="button">Cancel</Button>',
+  '  <Button variant="primary" type="button">Save changes</Button>',
+  '</Heading.InnerContainer>',
+  '```',
+  '',
+  '#### Heading.InnerContainer props',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | The content of one "side" of the heading — text, buttons, or any inline element |',
+  '| `className` | `string` | — | Additional CSS classes. Use `"medium-spacing-gap"` (global utility, `src/global.scss` line 11) to add `gap: var(--spacing-small)` between multiple button children |',
+  '| `...rest` | `HTMLAttributes<HTMLSpanElement>` | — | All native `<span>` attributes pass through |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Anti-patterns',
+  '',
+  '1. **Using Heading for section-level headings inside cards or sidebars** — breaks semantic hierarchy',
+  '   and layout. Use a plain `<h2>` / `<h3>` with your own styling.',
+  '2. **Too many action buttons** — max 3 total per Confluence (1 primary + 2 secondary). If you need',
+  '   more, use a `Dropdown` to consolidate.',
+  '3. **Subtitle via creative JSX** — do not pass a third child to simulate a subtitle. The design spec',
+  '   explicitly bans subtitles in page headings.',
+  '4. **Overriding font-size while keeping `level`** — creates a visual/semantic mismatch.',
+  '',
+  '#### Typography tokens',
+  '',
+  'Each `level` maps to a dedicated set of type tokens — for instance `level={1}` uses',
+  '`--type-headings-h1-size`, `--type-headings-h1-family`, `--type-headings-h1-weight`, and',
+  '`--type-headings-h1-line-height`. Heading typography is always driven by design tokens; never',
+  'override `font-size` with a hardcoded value while keeping a `level` prop, as this creates a',
+  'visual/semantic mismatch (screen reader announces "heading level 1" but the user sees h3-sized text).',
+  '',
+  '#### Width and spacing',
+  '',
+  'Heading always fills **100% of its parent container** — this is baked into `.ds-heading`. Do not',
+  'add top or bottom margin to the `Heading` element itself; control vertical rhythm from the page',
+  'layout wrapper.',
+  '',
+  '#### HeadingLevel type',
+  '',
+  '`HeadingLevel` is exported from `Heading.tsx` as `1 | 2 | 3 | 4`, but it is **not re-exported**',
+  'from `src/index.ts` (only `Heading` is). Consumers who need the type must import it directly:',
+  '`import type { HeadingLevel } from \'Components/heading/Heading\'`.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **Single H1 per page** — essential for screen readers; multiple H1s break the page outline',
+  '- **Keyboard order** — the DOM order is left container then right container, matching reading order and Tab sequence',
+  '- **Icon-only buttons in the heading** require a `TooltipWrapper` with an accessible label. A tooltip',
+  '  on hover alone is not sufficient — it must also appear on keyboard focus, and assistive technology',
+  '  must be able to read the label. Always pair `iconRightScreenReaderText` with `TooltipWrapper`.',
+  '- **`id` + `aria-labelledby`** — give the heading an `id` and reference it from an adjacent',
+  '  `<section aria-labelledby="...">` to associate the landmark with its heading. Screen readers',
+  '  announce the section name when the user enters the landmark region.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Heading } from '@arbor-education/design-system.components';",
+  '',
+  'function MyHeading(props: Heading.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `Heading.Props` | Full props interface |',
+  '| `Heading.Level` | `1 \\| 2 \\| 3 \\| 4` |',
+  '| `Heading.InnerContainerProps` | Props for `<Heading.InnerContainer>` |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Section](?path=/docs/components-section--docs) · [Button](?path=/docs/components-button--docs) · [Icon](?path=/docs/components-icon--docs) · [EditableText](?path=/docs/components-editabletext--docs) · [TooltipWrapper](?path=/docs/components-tooltip-tooltipwrapper--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 HeadingDocsPage() {
+  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>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
   title: 'Components/Heading',
   component: Heading,
-};
-
-export const Default = {
-  args: {
-    children: ['Heading Text'],
-    level: 1,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      page: HeadingDocsPage,
+    },
   },
   argTypes: {
     level: {
       control: 'select',
       options: [1, 2, 3, 4],
-      description: 'Heading level (h1-h4)',
+      description: [
+        'Controls **both** the semantic HTML element (`h1`–`h4`) and the typography — each level maps to its own',
+        'set of type tokens (`--type-headings-h{level}-size`, `--type-headings-h{level}-family`, etc.).',
+        'Never override font-size in CSS while keeping this prop, as that creates a visual/semantic mismatch.',
+      ].join(' '),
+      table: {
+        type: { summary: 'HeadingLevel (1 | 2 | 3 | 4)' },
+        defaultValue: { summary: '1' },
+      },
+    },
+    children: {
+      control: false,
+      description: [
+        'Heading content. Accepts plain text for a simple heading, two `Heading.InnerContainer` elements',
+        'for the left/right split layout, or any `ReactNode`. When two `Heading.InnerContainer` children',
+        'are provided, CSS `justify-content: space-between` automatically positions the first left and the',
+        'second right. Disabled in Controls because complex JSX cannot be serialised — use the named stories',
+        'to explore composition patterns.',
+      ].join(' '),
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    className: {
+      control: 'text',
+      description: [
+        'Additional CSS class names appended to the heading element alongside `ds-heading`.',
+        'Use sparingly — prefer `level` for typography and `Heading.InnerContainer` for layout.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    id: {
+      control: 'text',
+      description: [
+        'HTML `id` attribute on the heading element. The canonical accessibility use case is pairing it',
+        'with `aria-labelledby` on an adjacent `<section>` or `<article>`: the screen reader then announces',
+        'the section name when the user enters the landmark region.',
+        'Example: `<Heading id="attendance-heading">Attendance</Heading>`',
+        'with `<section aria-labelledby="attendance-heading">...</section>`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
   },
-  tags: ['autodocs'],
-};
+} satisfies Meta<typeof Heading>;
 
-export const FloatingChildren = {
-  args: {
-    children: [<Heading.InnerContainer key={1}>Text floating left</Heading.InnerContainer>, <span key={2}>Text floating right</span>],
-    level: 1,
-  },
-};
-
-export const HeadingWithSingleButton = {
-  args: {
-    level: 1,
-    children: [
-      <Heading.InnerContainer key={1}>Heading</Heading.InnerContainer>,
-      <Heading.InnerContainer key={2}>
-        <Button>
-          <Icon name="info" />
-          Button Text
-        </Button>
-      </Heading.InnerContainer>,
-    ],
+export default meta;
+type Story = StoryObj<typeof Heading>;
+
+// ---------------------------------------------------------------------------
+// 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 } },
   },
-};
-
-export const HeadingWithMultipleButtons = {
-  args: {
-    level: 1,
-    children: [
-      <Heading.InnerContainer key={1}>Heading</Heading.InnerContainer>,
-      <Heading.InnerContainer key={2} className="medium-spacing-gap">
-        <Button variant="secondary">
-          <Icon name="info" />
-          Button Text
+});
+
+// ---------------------------------------------------------------------------
+// Named template components — avoids hooks-in-callbacks lint issues.
+// react-hooks plugin is NOT configured — do NOT add eslint-disable comments.
+// ---------------------------------------------------------------------------
+
+const AllLevelsTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xxlarge)' }}>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H1 — page-level entity name</p>
+      <Heading level={1}>Student records</Heading>
+    </div>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H2 — primary section heading</p>
+      <Heading level={2}>Attendance register</Heading>
+    </div>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H3 — sub-section heading</p>
+      <Heading level={3}>Assessment marksheet</Heading>
+    </div>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H4 — lowest-level heading</p>
+      <Heading level={4}>Behaviour log</Heading>
+    </div>
+  </div>
+);
+
+const TwoContainersTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer>Student records</Heading.InnerContainer>
+      <Heading.InnerContainer>Actions go here</Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const WithActionButtonTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer>Attendance register</Heading.InnerContainer>
+      <Heading.InnerContainer>
+        <Button variant="primary" type="button">Save changes</Button>
+      </Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const WithMultipleActionsTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer>Assessment marksheet</Heading.InnerContainer>
+      <Heading.InnerContainer className="medium-spacing-gap">
+        <Button variant="secondary" type="button">Export to CSV</Button>
+        <Button variant="primary" type="button">Save changes</Button>
+      </Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const WithIconOnlyActionTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer>Student records</Heading.InnerContainer>
+      <Heading.InnerContainer>
+        <TooltipWrapper tooltipContent="Download student records">
+          <Button
+            variant="secondary"
+            type="button"
+            iconRightName="download"
+            iconRightScreenReaderText="Download student records"
+          />
+        </TooltipWrapper>
+      </Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const WithBackControlLegacyTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer className="medium-spacing-gap">
+        <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+          Back
         </Button>
-        <Button>
-          <Icon name="info" />
-          Button Text
+        Attendance register
+      </Heading.InnerContainer>
+      <Heading.InnerContainer className="medium-spacing-gap">
+        <Button variant="secondary" type="button">Archive</Button>
+        <Button variant="primary" type="button">Save changes</Button>
+      </Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const WithEditableTitleTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <EditableText text="Form 7B Registration" onEditSave={() => {}} />
+    </Heading>
+  </div>
+);
+
+const WithEditableTitleAndActionTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer>
+        <EditableText text="Form 7B Registration" onEditSave={() => {}} />
+      </Heading.InnerContainer>
+      <Heading.InnerContainer>
+        <Button variant="primary" type="button">Save changes</Button>
+      </Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const WithEditableTitleAndMultipleActionsTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)' }}>
+    <Heading level={1}>
+      <Heading.InnerContainer className="medium-spacing-gap">
+        <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+          Back
         </Button>
-      </Heading.InnerContainer>,
-    ],
+        <EditableText text="Autumn term report" onEditSave={() => {}} />
+      </Heading.InnerContainer>
+      <Heading.InnerContainer className="medium-spacing-gap">
+        <Button variant="secondary" type="button">Export to CSV</Button>
+        <Button variant="primary" type="button">Save changes</Button>
+      </Heading.InnerContainer>
+    </Heading>
+  </div>
+);
+
+const AccessibilityLabelledSectionTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      The heading below has an `id`. The section below it references that `id` via `aria-labelledby`.
+      Screen readers announce the section name ("Attendance") when the user enters the landmark region.
+    </p>
+    <Heading id="attendance-heading" level={2}>Attendance</Heading>
+    <section aria-labelledby="attendance-heading" style={{ padding: 'var(--spacing-large)', border: 'var(--border-weight) solid var(--color-grey-300)', borderRadius: 'var(--border-radius-small)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        This section is labelled "Attendance" by the heading above via `aria-labelledby="attendance-heading"`.
+        A screen reader user navigating landmarks will hear: "Attendance, region".
+      </p>
+    </section>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      level: 1,
+      children: 'Student records',
+    },
+    render: args => <Heading {...args} />,
   },
-};
-
-export const HeadingWithButtonsBothSides = {
-  args: {
-    level: 1,
-    children: [
-      <Heading.InnerContainer key={1} className="medium-spacing-gap">
-        <Button variant="tertiary">
-          <Icon name="chevron-left" />
-          Button Text
-        </Button>
-        Heading
-      </Heading.InnerContainer>,
-      <Heading.InnerContainer key={2} className="medium-spacing-gap">
-        <Button variant="secondary">
-          <Icon name="info" />
-          Button Text
-        </Button>
-        <Button>
-          <Icon name="info" />
-          Button Text
-        </Button>
-      </Heading.InnerContainer>,
-    ],
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to change `level` (1–4) and see the heading typography scale live. The `children` control is disabled because complex JSX cannot be round-tripped through Storybook\'s serialiser — use the named stories below to explore composition patterns.',
+);
+
+export const AllLevels: Story = withDescription(
+  {
+    render: AllLevelsTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xxlarge)' }}>
+  <div>
+    <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H1 — page-level entity name</p>
+    <Heading level={1}>Student records</Heading>
+  </div>
+  <div>
+    <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H2 — primary section heading</p>
+    <Heading level={2}>Attendance register</Heading>
+  </div>
+  <div>
+    <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H3 — sub-section heading</p>
+    <Heading level={3}>Assessment marksheet</Heading>
+  </div>
+  <div>
+    <p className="ds-text" style={{ margin: '0 0 var(--spacing-large)', color: 'var(--color-grey-600)' }}>H4 — lowest-level heading</p>
+    <Heading level={4}>Behaviour log</Heading>
+  </div>
+</div>
+`.trim(),
+        },
+      },
+    },
   },
-};
-
-export const HeadingWithEditableText = {
-  args: {
-    level: 1,
-    children: [
-      <EditableText key={2} text="Editable Heading" onEditSave={() => {}} />,
-    ],
+  'All four heading levels stacked vertically. Each level maps to a dedicated set of type tokens — `--type-headings-h{level}-size`, `--type-headings-h{level}-family`, `--type-headings-h{level}-weight`, and `--type-headings-h{level}-line-height` — so the entire type scale is driven by design tokens. H1 line-heights are tall, so `var(--spacing-xxlarge)` gives each heading enough breathing room.',
+);
+
+export const TwoContainers: Story = withDescription(
+  {
+    render: TwoContainersTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer>Student records</Heading.InnerContainer>
+    <Heading.InnerContainer>Actions go here</Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
   },
-};
-
-export const HeadingWithEditableTextAndButton = {
-  args: {
-    level: 1,
-    children: [
-      <Heading.InnerContainer key={1}><EditableText text="Editable Heading" onEditSave={() => {}} /></Heading.InnerContainer>,
-      <Heading.InnerContainer key={2}>
-        <Button>
-          <Icon name="info" />
-          Button Text
-        </Button>
-      </Heading.InnerContainer>,
-    ],
+  [
+    'When two `Heading.InnerContainer` children are provided, the heading\'s CSS (`justify-content: space-between`)',
+    'automatically pushes the first container to the left and the second to the right. No extra wrapper or flex',
+    'gymnastics needed. This is the canonical pattern for any heading that combines a title with action controls.',
+    '',
+    '`Heading.InnerContainer` is a simple `<span className="ds-heading__inner-container">` wrapper — it groups',
+    'content on one "side" of the heading and inherits the heading\'s typography tokens so its text renders at',
+    'the correct size automatically.',
+  ].join(' '),
+);
+
+export const WithActionButton: Story = withDescription(
+  {
+    render: WithActionButtonTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, Button } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer>Attendance register</Heading.InnerContainer>
+    <Heading.InnerContainer>
+      <Button variant="primary" type="button">Save changes</Button>
+    </Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
   },
-};
-
-export const HeadingWithEditableTextAndButtonsBothSides = {
-  args: {
-    level: 1,
-    children: [
-      <Heading.InnerContainer key={1} className="medium-spacing-gap">
-        <Button variant="tertiary">
-          <Icon name="chevron-left" />
-          Button Text
-        </Button>
-        <EditableText text="Editable Heading" onEditSave={() => {}} />
-      </Heading.InnerContainer>,
-      <Heading.InnerContainer key={2} className="medium-spacing-gap">
-        <Button variant="secondary">
-          <Icon name="info" />
-          Button Text
-        </Button>
-        <Button>
-          <Icon name="info" />
-          Button Text
-        </Button>
-      </Heading.InnerContainer>,
-    ],
+  'The most common Heading pattern: title text in the left `Heading.InnerContainer`, one primary action button in the right container. The `justify-content: space-between` CSS keeps the title and button on opposite ends of the heading regardless of how long the title is.',
+);
+
+export const WithMultipleActions: Story = withDescription(
+  {
+    render: WithMultipleActionsTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, Button } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer>Assessment marksheet</Heading.InnerContainer>
+    <Heading.InnerContainer className="medium-spacing-gap">
+      <Button variant="secondary" type="button">Export to CSV</Button>
+      <Button variant="primary" type="button">Save changes</Button>
+    </Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Title left, two action buttons right. When multiple buttons share one `Heading.InnerContainer`, add',
+    '`className="medium-spacing-gap"` to the container. This is a global utility class from `src/global.scss`',
+    'that applies `gap: var(--spacing-small)` between flex children — the canonical way to space multiple',
+    'buttons in a heading. **Max 3 actions total per Confluence** (1 primary + 2 secondary recommended).',
+    'If you need more, consolidate into a `Dropdown`.',
+  ].join(' '),
+);
 
-export default meta;
+export const WithIconOnlyAction: Story = withDescription(
+  {
+    render: WithIconOnlyActionTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, Button, TooltipWrapper } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer>Student records</Heading.InnerContainer>
+    <Heading.InnerContainer>
+      <TooltipWrapper tooltipContent="Download student records">
+        <Button
+          variant="secondary"
+          type="button"
+          iconRightName="download"
+          iconRightScreenReaderText="Download student records"
+        />
+      </TooltipWrapper>
+    </Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Title left, an icon-only action button right. **Icon-only buttons in a heading require a `TooltipWrapper`**',
+    '— hover tooltips alone are not sufficient. The tooltip must appear on keyboard focus too, and assistive',
+    'technology must be able to read the label. Always pair `TooltipWrapper` with a descriptive',
+    '`iconRightScreenReaderText` prop on the button. This story uses both: `tooltipContent="Download student records"`',
+    'for sighted keyboard users and `iconRightScreenReaderText="Download student records"` for screen reader users.',
+  ].join(' '),
+);
+
+export const WithBackControlLegacy: Story = withDescription(
+  {
+    render: WithBackControlLegacyTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, Button } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer className="medium-spacing-gap">
+      <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+        Back
+      </Button>
+      Attendance register
+    </Heading.InnerContainer>
+    <Heading.InnerContainer className="medium-spacing-gap">
+      <Button variant="secondary" type="button">Archive</Button>
+      <Button variant="primary" type="button">Save changes</Button>
+    </Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '**Legacy pattern — do not use on new pages.**',
+    '',
+    'A back-chevron tertiary button in the left `Heading.InnerContainer` with actions in the right. This pattern',
+    'is being phased out across Arbor because browser back history is unreliable — it breaks when users open',
+    'pages in new tabs, arrive via deep links, or navigate in unexpected orders. Design guidance recommends',
+    'deterministic navigation instead (e.g. a `<Link>` to a known parent route).',
+    '',
+    'The story is preserved here for reference while legacy pages are migrated.',
+  ].join(' '),
+);
+
+export const WithEditableTitle: Story = withDescription(
+  {
+    render: WithEditableTitleTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, EditableText } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <EditableText text="Form 7B Registration" onEditSave={() => {}} />
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
+  },
+  '`EditableText` as the heading children — inline-editable heading. Click the pencil icon (or the title text) to enter editing mode. Press Enter or blur the input to save. Press Escape to cancel and revert. Useful for entity names that users should be able to rename directly on the page, such as a form or report title.',
+);
+
+export const WithEditableTitleAndAction: Story = withDescription(
+  {
+    render: WithEditableTitleAndActionTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, Button, EditableText } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer>
+      <EditableText text="Form 7B Registration" onEditSave={() => {}} />
+    </Heading.InnerContainer>
+    <Heading.InnerContainer>
+      <Button variant="primary" type="button">Save changes</Button>
+    </Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
+  },
+  'An editable title in the left `Heading.InnerContainer` with a primary action button in the right. The `EditableText` component fills its container width, so wrapping it in an `InnerContainer` keeps it left-aligned while the button sits at the far right. Click the pencil icon on the title to activate edit mode.',
+);
+
+export const WithEditableTitleAndMultipleActions: Story = withDescription(
+  {
+    render: WithEditableTitleAndMultipleActionsTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading, Button, EditableText } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)' }}>
+  <Heading level={1}>
+    <Heading.InnerContainer className="medium-spacing-gap">
+      <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+        Back
+      </Button>
+      <EditableText text="Autumn term report" onEditSave={() => {}} />
+    </Heading.InnerContainer>
+    <Heading.InnerContainer className="medium-spacing-gap">
+      <Button variant="secondary" type="button">Export to CSV</Button>
+      <Button variant="primary" type="button">Save changes</Button>
+    </Heading.InnerContainer>
+  </Heading>
+</div>
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The full complex composition: back button + editable title in the left container, multiple actions in the right.',
+    '',
+    '**Legacy pattern caveat** — this layout includes the back-button pattern, which is being phased out.',
+    'The back button is shown here for completeness while legacy pages are migrated. On new pages, replace it',
+    'with deterministic navigation. The editable title + multiple-actions layout (without the back button) is',
+    'fully supported.',
+  ].join(' '),
+);
+
+export const AccessibilityLabelledSection: Story = withDescription(
+  {
+    render: AccessibilityLabelledSectionTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Heading } from '@arbor-education/design-system.components';
+
+<div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+  <Heading id="attendance-heading" level={2}>Attendance</Heading>
+  <section
+    aria-labelledby="attendance-heading"
+    style={{
+      padding: 'var(--spacing-large)',
+      border: 'var(--border-weight) solid var(--color-grey-300)',
+      borderRadius: 'var(--border-radius-small)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      Section content — announced as "Attendance, region" by screen readers.
+    </p>
+  </section>
+</div>
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Canonical accessibility pattern: a `Heading` with an `id` prop, referenced by an adjacent `<section aria-labelledby="...">`. When a screen reader user navigates to the section landmark, the browser announces the section\'s accessible name — in this case, "Attendance, region".',
+    '',
+    'This is especially important for pages with multiple regions (attendance, behaviour, academic) — each section',
+    'should be labelled by its heading so keyboard/screen reader users can orient themselves quickly using landmark',
+    'navigation (`F6` in NVDA, the Rotor in VoiceOver).',
+    '',
+    'Pattern: `<Heading id="attendance-heading" level={2}>Attendance</Heading>` paired with',
+    '`<section aria-labelledby="attendance-heading">...</section>`.',
+  ].join(' '),
+);