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

package/src/components/grid/Grid.stories.tsx

@@ -0,0 +1,1130 @@
+import type { CSSProperties } from 'react';
+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 { Grid } from './Grid.js';
+import { Avatar } from 'Components/avatar/Avatar';
+import { Badge } from 'Components/badge/Badge';
+import { Button } from 'Components/button/Button';
+import { DataViewCard } from 'Components/dataViewCard/DataViewCard';
+import { Heading } from 'Components/heading/Heading';
+import { KPICard } from 'Components/kpiCard/KPICard';
+import { KVPList } from 'Components/kvpList/KVPList';
+import { Section } from 'Components/section/Section';
+import { Tag } from 'Components/tag/Tag';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Grid is a compound layout component that implements the',
+  '[GOV.UK Frontend grid system](https://frontend.design-system.service.gov.uk/styles/layout/).',
+  'It provides a structured, column-based page layout that matches the GOV.UK design',
+  'patterns used across Arbor\'s school management interface.',
+  '',
+  'The component exposes three building blocks through a single compound API:',
+  '',
+  '| Part | Class rendered | Description |',
+  '|---|---|---|',
+  '| `<Grid>` | `govuk-main-wrapper` | Page-level wrapper for all layout content |',
+  '| `<Grid.Row>` | `govuk-grid-row` | Horizontal row — contains one or more columns |',
+  '| `<Grid.Column>` | `govuk-grid-column-{width}` | A single column within a row |',
+  '',
+  '### Important: `Grid.Row` and `Grid.Column` are only available via the compound API',
+  '',
+  '`GridRow` and `GridColumn` are **not** individually exported from the package.',
+  'You must always use the compound form:',
+  '',
+  '```tsx',
+  "import { Grid } from '@arbor-education/design-system.components';",
+  '',
+  '// Correct',
+  '<Grid.Row>',
+  '  <Grid.Column columnWidth="two-thirds">...</Grid.Column>',
+  '</Grid.Row>',
+  '',
+  '// Wrong — these imports do not exist in the package',
+  "import { GridRow, GridColumn } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '### GOV.UK grid styles are bundled',
+  '',
+  'The `govuk-grid-row` and `govuk-grid-column-*` styles are compiled into the library\'s',
+  'CSS bundle — import `@arbor-education/design-system.components/dist/index.css` and',
+  'columns will lay out correctly with no additional stylesheet required.',
+  '',
+  'The `govuk-main-wrapper` class applied to the `Grid` root is **not** part of the bundled',
+  'grid object — it is a semantic class name only. If your page relies on GOV.UK\'s own',
+  '`govuk-main-wrapper` padding, load the GOV.UK Frontend stylesheet separately.',
+].join('\n');
+
+const PROPS_INTRO = 'The interactive canvas below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+const USAGE_GUIDANCE = [
+  '### When to use Grid',
+  '',
+  '- **Building GOV.UK-pattern page layouts** — sidebar + main content, full-width sections,',
+  '  or equal-width columns that follow the service manual\'s grid',
+  '- **Creating standardised column-based structure** across Arbor\'s school management pages',
+  '  so layouts stay consistent and accessible',
+  '- **School MIS page layouts** such as a student profile page (narrow summary sidebar + wide',
+  '  main content) or a dashboard with four equal-width metric cards',
+  '',
+  '---',
+  '',
+  '### When NOT to use Grid',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Generic flexbox or grid inside a card or small component | Plain `div` with inline styles or a utility class |',
+  '| Custom breakpoints beyond GOV.UK Frontend\'s defaults | Custom CSS — GOV.UK columns use fixed breakpoints |',
+  '| Columns deeply nested inside an already-padded container | Avoid nesting — `govuk-main-wrapper` carries page-level padding |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### GOV.UK grid styles are bundled — no extra stylesheet needed for columns',
+  '',
+  '`govuk-grid-row` and `govuk-grid-column-*` styles are compiled into',
+  '`@arbor-education/design-system.components/dist/index.css` via the library\'s SCSS bundle.',
+  'Importing the library\'s CSS is sufficient for `Grid.Row` and `Grid.Column` to lay out correctly.',
+  '',
+  '`govuk-main-wrapper` (applied to the `Grid` root) is **not** part of the bundled grid object.',
+  'It is a semantic class name. If your application depends on GOV.UK Frontend\'s own',
+  '`govuk-main-wrapper` padding styles, load the GOV.UK Frontend stylesheet separately.',
+  '',
+  '---',
+  '',
+  '### Compound component API',
+  '',
+  'Only `Grid` and `GridProps` are exported from the package. Access rows and columns',
+  'through the compound API:',
+  '',
+  '```tsx',
+  "import { Grid, type GridProps } from '@arbor-education/design-system.components';",
+  '',
+  '<Grid>',
+  '  <Grid.Row>',
+  '    <Grid.Column columnWidth="one-third">Sidebar</Grid.Column>',
+  '    <Grid.Column columnWidth="two-thirds">Main content</Grid.Column>',
+  '  </Grid.Row>',
+  '</Grid>',
+  '```',
+  '',
+  '---',
+  '',
+  '### `Grid.Column` props',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `columnWidth` | `\'one-quarter\' \\| \'three-quarters\' \\| \'one-third\' \\| \'two-thirds\' \\| \'one-half\' \\| \'full\'` | `\'full\'` | GOV.UK grid column width class |',
+  '| `className` | `string` | — | Additional CSS classes |',
+  '| `children` | `ReactNode` | — | Column content |',
+  '',
+  '### `Grid.Row` props',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `className` | `string` | — | Additional CSS classes |',
+  '| `children` | `ReactNode` | — | One or more `Grid.Column` elements |',
+  '',
+  '---',
+  '',
+  '### Column widths must sum to a full row',
+  '',
+  'The component does **not** enforce that column widths add up. Columns that exceed 100%',
+  'will wrap to a new line; columns that total less than 100% will leave empty space.',
+  'Always verify widths sum correctly:',
+  '',
+  '| Combination | Total |',
+  '|---|---|',
+  '| `one-half` + `one-half` | 100% |',
+  '| `one-third` + `two-thirds` | 100% |',
+  '| `one-quarter` + `three-quarters` | 100% |',
+  '| `one-quarter` × 4 | 100% |',
+  '| `full` | 100% |',
+  '',
+  '---',
+  '',
+  '### Do NOT add padding or margin directly to `Grid.Column`',
+  '',
+  'GOV.UK Frontend uses gutters (padding) on grid column elements. Adding extra `padding`',
+  'or `margin` to the column itself will break the gutter calculations and misalign content.',
+  'Always put inner spacing on a wrapper `div` **inside** the column:',
+  '',
+  '```tsx',
+  '// Correct',
+  '<Grid.Column columnWidth="one-third">',
+  '  <div style={{ padding: \'var(--spacing-medium)\' }}>Sidebar content</div>',
+  '</Grid.Column>',
+  '',
+  '// Wrong — overrides GOV.UK gutter padding',
+  '<Grid.Column columnWidth="one-third" className="my-padded-column">',
+  '  Sidebar content',
+  '</Grid.Column>',
+  '```',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Grid, type GridProps } from '@arbor-education/design-system.components';",
+  '',
+  'function MyLayout(props: GridProps) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `GridProps` | Props for the `<Grid>` root element |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Row](?path=/docs/components-row--docs) · [Section](?path=/docs/components-section--docs) · [Modal](?path=/docs/components-modals-modal--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Placeholder box — used only in schematic stories to make column boundaries
+// visible. Each column in a row is given a distinct hue (cycled by position)
+// so it is obvious where one column ends and the next begins. The real-page
+// composition stories below do not use this — they render true page content.
+// ---------------------------------------------------------------------------
+
+const PLACEHOLDER_HUES = ['blue', 'green', 'purple', 'orange', 'teal', 'salmon', 'yellow'] as const;
+
+const placeholderStyle = (index: number): CSSProperties => {
+  const hue = PLACEHOLDER_HUES[index % PLACEHOLDER_HUES.length];
+  return {
+    background: `var(--color-extended-colours-${hue}-100)`,
+    border: `var(--border-width-thin) solid var(--color-extended-colours-${hue}-500)`,
+    borderRadius: 'var(--border-radius-small)',
+    padding: 'var(--spacing-medium)',
+    color: `var(--color-extended-colours-${hue}-800)`,
+    fontSize: 'var(--font-size-200)',
+    fontWeight: 500,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function GridDocsPage() {
+  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/Grid',
+  component: Grid,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: GridDocsPage },
+  },
+  argTypes: {
+    className: {
+      control: false,
+      description: 'Additional CSS class names applied to the `govuk-main-wrapper` root element.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    children: {
+      control: false,
+      description: 'One or more `Grid.Row` elements that make up the page layout.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+  },
+} satisfies Meta<typeof Grid>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const AllWidthsTemplate = () => (
+  <Grid>
+    {(['full', 'three-quarters', 'two-thirds', 'one-half', 'one-third', 'one-quarter'] as const).map((width, index) => (
+      <Grid.Row key={width}>
+        <Grid.Column columnWidth={width}>
+          <div style={placeholderStyle(index)}>{width}</div>
+        </Grid.Column>
+      </Grid.Row>
+    ))}
+  </Grid>
+);
+
+const MultipleRowsTemplate = () => (
+  <Grid>
+    <Grid.Row>
+      <Grid.Column columnWidth="full">
+        <div style={placeholderStyle(0)}>Page header — full width</div>
+      </Grid.Column>
+    </Grid.Row>
+    <Grid.Row>
+      <Grid.Column columnWidth="one-third">
+        <div style={placeholderStyle(0)}>Navigation</div>
+      </Grid.Column>
+      <Grid.Column columnWidth="two-thirds">
+        <div style={placeholderStyle(1)}>Main content</div>
+      </Grid.Column>
+    </Grid.Row>
+    <Grid.Row>
+      <Grid.Column columnWidth="full">
+        <div style={placeholderStyle(0)}>Footer — full width</div>
+      </Grid.Column>
+    </Grid.Row>
+  </Grid>
+);
+
+const FourQuartersTemplate = () => (
+  <Grid>
+    <Grid.Row>
+      <Grid.Column columnWidth="one-quarter">
+        <div style={placeholderStyle(0)}>Student summary</div>
+      </Grid.Column>
+      <Grid.Column columnWidth="one-quarter">
+        <div style={placeholderStyle(1)}>Attendance</div>
+      </Grid.Column>
+      <Grid.Column columnWidth="one-quarter">
+        <div style={placeholderStyle(2)}>Assessment</div>
+      </Grid.Column>
+      <Grid.Column columnWidth="one-quarter">
+        <div style={placeholderStyle(3)}>Finance</div>
+      </Grid.Column>
+    </Grid.Row>
+  </Grid>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {},
+    render: args => (
+      <Grid {...args}>
+        <Grid.Row>
+          <Grid.Column columnWidth="full">
+            <div style={placeholderStyle(0)}>Main content — full width</div>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+  },
+  [
+    'The simplest Grid usage: a single `Grid.Row` containing one `Grid.Column` set to `full` width.',
+    'Use this as your starting point and add more columns or rows as the layout requires.',
+    'The `className` prop on the Controls panel applies to the `govuk-main-wrapper` root.',
+  ].join(' '),
+);
+
+export const OneHalf: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="one-half">
+            <div style={placeholderStyle(0)}>Student information</div>
+          </Grid.Column>
+          <Grid.Column columnWidth="one-half">
+            <div style={placeholderStyle(1)}>Attendance overview</div>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function OneHalfExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-half">
+          Student information
+        </Grid.Column>
+        <Grid.Column columnWidth="one-half">
+          Attendance overview
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default OneHalfExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Two equal `one-half` columns placed side by side.',
+    'Use this when two content areas carry equal visual weight, such as a student information',
+    'panel alongside an attendance summary.',
+  ].join(' '),
+);
+
+export const OneThirdTwoThirds: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="one-third">
+            <div style={placeholderStyle(0)}>Navigation</div>
+          </Grid.Column>
+          <Grid.Column columnWidth="two-thirds">
+            <div style={placeholderStyle(1)}>Main content</div>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function SidebarLayoutExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-third">
+          Navigation
+        </Grid.Column>
+        <Grid.Column columnWidth="two-thirds">
+          Main content
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default SidebarLayoutExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The canonical GOV.UK sidebar + main content pattern.',
+    'A narrow left-hand `one-third` column holds navigation or filters,',
+    'while the `two-thirds` column carries the primary page content.',
+  ].join(' '),
+);
+
+export const TwoThirdsOneThird: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="two-thirds">
+            <div style={placeholderStyle(0)}>Assessment results</div>
+          </Grid.Column>
+          <Grid.Column columnWidth="one-third">
+            <div style={placeholderStyle(1)}>Filters</div>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function ReversedSidebarExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="two-thirds">
+          Assessment results
+        </Grid.Column>
+        <Grid.Column columnWidth="one-third">
+          Filters
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default ReversedSidebarExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The reversed layout — main content on the left with a narrower right-hand sidebar.',
+    'Useful when filter controls or contextual information should sit to the right of primary content.',
+  ].join(' '),
+);
+
+export const OneQuarterThreeQuarters: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="one-quarter">
+            <div style={placeholderStyle(0)}>Navigation</div>
+          </Grid.Column>
+          <Grid.Column columnWidth="three-quarters">
+            <div style={placeholderStyle(1)}>Main content</div>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function NarrowSidebarExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-quarter">
+          Navigation
+        </Grid.Column>
+        <Grid.Column columnWidth="three-quarters">
+          Main content
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default NarrowSidebarExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A narrow `one-quarter` sidebar paired with a wide `three-quarters` content area.',
+    'Use this when the sidebar needs to be more compact than the standard `one-third` variant,',
+    'such as a compact navigation list alongside a data-dense report.',
+  ].join(' '),
+);
+
+export const ThreeQuartersOneQuarter: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="three-quarters">
+            <div style={placeholderStyle(0)}>Main content</div>
+          </Grid.Column>
+          <Grid.Column columnWidth="one-quarter">
+            <div style={placeholderStyle(1)}>Summary panel</div>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function WideContentNarrowPanelExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="three-quarters">
+          Main content
+        </Grid.Column>
+        <Grid.Column columnWidth="one-quarter">
+          Summary panel
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default WideContentNarrowPanelExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Wide primary content on the left with a compact right-hand summary panel.',
+    'The `three-quarters` + `one-quarter` split gives you the most content space',
+    'while still showing a supplementary panel — ideal for report views with a key-metrics sidebar.',
+  ].join(' '),
+);
+
+export const FourQuarters: Story = withDescription(
+  {
+    render: FourQuartersTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function FourQuartersExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-quarter">
+          Student summary
+        </Grid.Column>
+        <Grid.Column columnWidth="one-quarter">
+          Attendance
+        </Grid.Column>
+        <Grid.Column columnWidth="one-quarter">
+          Assessment
+        </Grid.Column>
+        <Grid.Column columnWidth="one-quarter">
+          Finance
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default FourQuartersExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Four equal `one-quarter` columns across a single row — the card-grid pattern.',
+    'Use this for dashboard metric cards, category overviews, or any set of four equal-weight items',
+    'that should be presented side by side at the page level.',
+  ].join(' '),
+);
+
+export const MultipleRows: Story = withDescription(
+  {
+    render: MultipleRowsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+function MultipleRowsExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="full">
+          Page header — full width
+        </Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-third">
+          Navigation
+        </Grid.Column>
+        <Grid.Column columnWidth="two-thirds">
+          Main content
+        </Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="full">
+          Footer — full width
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default MultipleRowsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Multiple `Grid.Row` instances stacked inside a single `Grid` wrapper.',
+    'Each row is independent — rows can use different column configurations.',
+    'The `Grid` root (`govuk-main-wrapper`) wraps all rows and provides the outer page padding.',
+  ].join(' '),
+);
+
+export const AllWidths: Story = withDescription(
+  {
+    render: AllWidthsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Grid } from '@arbor-education/design-system.components';
+
+// All six columnWidth values, each in its own row for comparison
+function AllWidthsExample() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column columnWidth="full">full</Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="three-quarters">three-quarters</Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="two-thirds">two-thirds</Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-half">one-half</Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-third">one-third</Grid.Column>
+      </Grid.Row>
+      <Grid.Row>
+        <Grid.Column columnWidth="one-quarter">one-quarter</Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+export default AllWidthsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'All six available `columnWidth` values shown in isolation, one per row, from widest to narrowest.',
+    'Use this as a visual reference when choosing the right column proportion for your layout.',
+  ].join(' '),
+);
+
+// ---------------------------------------------------------------------------
+// Real-page composition examples
+// ---------------------------------------------------------------------------
+
+const kpiRowStyle: CSSProperties = {
+  display: 'flex',
+  gap: 'var(--spacing-medium)',
+  marginBottom: 'var(--spacing-medium)',
+};
+
+const pageHeaderStyle: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  paddingBottom: 'var(--spacing-medium)',
+  borderBottom: 'var(--border-width-thin) solid var(--color-neutral-200)',
+  marginBottom: 'var(--spacing-medium)',
+};
+
+const actionRowStyle: CSSProperties = {
+  display: 'flex',
+  gap: 'var(--spacing-small)',
+};
+
+const sidebarInnerStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  gap: 'var(--spacing-medium)',
+  paddingRight: 'var(--spacing-medium)',
+};
+
+export const StudentProfilePage: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="full">
+            <div style={pageHeaderStyle}>
+              <div>
+                <Heading level={1}>Emma Johnson</Heading>
+                <div style={{ display: 'flex', gap: 'var(--spacing-small)', marginTop: 'var(--spacing-xsmall)' }}>
+                  <Tag color="blue">Year 9</Tag>
+                  <Tag color="teal">Set 2</Tag>
+                  <Tag color="green">On Roll</Tag>
+                </div>
+              </div>
+              <div style={actionRowStyle}>
+                <Button variant="secondary" size="S" iconLeftName="pencil">Edit</Button>
+                <Button variant="secondary" size="S" iconLeftName="file">Print</Button>
+                <Button variant="primary" size="S">Contact Home</Button>
+              </div>
+            </div>
+          </Grid.Column>
+        </Grid.Row>
+
+        <Grid.Row>
+          <Grid.Column columnWidth="one-quarter">
+            <div style={sidebarInnerStyle}>
+              <Avatar size="extra-large" initials="EJ" />
+              <KVPList>
+                <KVPList.Row orientation="vertical">
+                  <KVPList.Term>Date of Birth</KVPList.Term>
+                  <KVPList.Definition>12 Mar 2010</KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="vertical">
+                  <KVPList.Term>Tutor Group</KVPList.Term>
+                  <KVPList.Definition>9B</KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="vertical">
+                  <KVPList.Term>Form Tutor</KVPList.Term>
+                  <KVPList.Definition>Mr T. Harris</KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="vertical">
+                  <KVPList.Term>SEN Status</KVPList.Term>
+                  <KVPList.Definition>
+                    <Tag color="orange">Monitor</Tag>
+                  </KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="vertical">
+                  <KVPList.Term>FSM</KVPList.Term>
+                  <KVPList.Definition>Yes</KVPList.Definition>
+                </KVPList.Row>
+              </KVPList>
+            </div>
+          </Grid.Column>
+
+          <Grid.Column columnWidth="three-quarters">
+            <Section title="Academic Overview" headingLevel={2}>
+              <div style={kpiRowStyle}>
+                <KPICard label="Attendance" value={94.2} isPercentage />
+                <KPICard label="Sessions This Term" value={128} />
+                <KPICard label="Unauthorised Absences" value={3} />
+                <KPICard label="Behaviour Points" value={12} />
+              </div>
+            </Section>
+
+            <Section title="Recent Classes" headingLevel={2}>
+              <div style={{ display: 'flex', gap: 'var(--spacing-medium)', flexWrap: 'wrap' }}>
+                <DataViewCard
+                  header="Mathematics"
+                  rows={[
+                    { label: 'Teacher', value: 'Ms R. Patel' },
+                    { label: 'Room', value: 'B14' },
+                    { label: 'Last Grade', value: 'A' },
+                  ]}
+                />
+                <DataViewCard
+                  header="English Literature"
+                  rows={[
+                    { label: 'Teacher', value: 'Mr D. Clarke' },
+                    { label: 'Room', value: 'A03' },
+                    { label: 'Last Grade', value: 'B+' },
+                  ]}
+                />
+                <DataViewCard
+                  header="Science"
+                  rows={[
+                    { label: 'Teacher', value: 'Dr S. Okafor' },
+                    { label: 'Room', value: 'Lab 2' },
+                    { label: 'Last Grade', value: 'A*' },
+                  ]}
+                />
+              </div>
+            </Section>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      layout: 'fullscreen',
+    },
+  },
+  [
+    'A realistic student profile page composed entirely from design system components.',
+    'The `one-quarter` sidebar holds identity details while `three-quarters` carries KPI metrics and class cards.',
+    'Use this pattern when a student record needs a persistent summary alongside rich contextual content.',
+  ].join(' '),
+);
+
+export const AttendanceDashboard: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="full">
+            <div style={pageHeaderStyle}>
+              <div>
+                <Heading level={1}>Attendance Overview</Heading>
+                <div style={{ display: 'flex', gap: 'var(--spacing-small)', marginTop: 'var(--spacing-xsmall)' }}>
+                  <Badge colour="teal">Autumn Term 2024</Badge>
+                  <Badge colour="blue">All Year Groups</Badge>
+                </div>
+              </div>
+              <div style={actionRowStyle}>
+                <Button variant="secondary" size="S" iconLeftName="download">Export</Button>
+                <Button variant="primary" size="S">Generate Report</Button>
+              </div>
+            </div>
+          </Grid.Column>
+        </Grid.Row>
+
+        <Grid.Row>
+          <Grid.Column columnWidth="one-quarter">
+            <KPICard label="Overall Attendance" value={96.1} isPercentage />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-quarter">
+            <KPICard label="Persistent Absentees" value={23} />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-quarter">
+            <KPICard label="Sessions Recorded" value={2840} />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-quarter">
+            <KPICard label="Punctuality Issues" value={11} />
+          </Grid.Column>
+        </Grid.Row>
+
+        <Grid.Row>
+          <Grid.Column columnWidth="two-thirds">
+            <Section title="Lowest Attendance" headingLevel={2}>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+                <DataViewCard
+                  header="Callum Wright"
+                  avatar={{ initials: 'CW' }}
+                  rows={[
+                    { label: 'Year Group', value: 'Year 10' },
+                    { label: 'Attendance', value: '71.4%' },
+                    { label: 'Unauthorised', value: '14 sessions' },
+                  ]}
+                />
+                <DataViewCard
+                  header="Priya Sharma"
+                  avatar={{ initials: 'PS' }}
+                  rows={[
+                    { label: 'Year Group', value: 'Year 8' },
+                    { label: 'Attendance', value: '74.8%' },
+                    { label: 'Unauthorised', value: '11 sessions' },
+                  ]}
+                />
+                <DataViewCard
+                  header="Jordan Blake"
+                  avatar={{ initials: 'JB' }}
+                  rows={[
+                    { label: 'Year Group', value: 'Year 11' },
+                    { label: 'Attendance', value: '78.2%' },
+                    { label: 'Unauthorised', value: '9 sessions' },
+                  ]}
+                />
+              </div>
+            </Section>
+          </Grid.Column>
+
+          <Grid.Column columnWidth="one-third">
+            <Section title="Filter by Year Group" headingLevel={2}>
+              <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-xsmall)' }}>
+                {['Year 7', 'Year 8', 'Year 9', 'Year 10', 'Year 11', 'Year 12', 'Year 13'].map(year => (
+                  <Tag key={year} color="neutral">{year}</Tag>
+                ))}
+              </div>
+            </Section>
+
+            <Section title="Absence Codes" headingLevel={2}>
+              <KVPList>
+                <KVPList.Row orientation="horizontal">
+                  <KVPList.Term>Authorised</KVPList.Term>
+                  <KVPList.Definition prominence="strong">847</KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="horizontal">
+                  <KVPList.Term>Unauthorised</KVPList.Term>
+                  <KVPList.Definition prominence="strong">312</KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="horizontal">
+                  <KVPList.Term>Medical</KVPList.Term>
+                  <KVPList.Definition prominence="strong">204</KVPList.Definition>
+                </KVPList.Row>
+                <KVPList.Row orientation="horizontal">
+                  <KVPList.Term>Holiday</KVPList.Term>
+                  <KVPList.Definition prominence="strong">58</KVPList.Definition>
+                </KVPList.Row>
+              </KVPList>
+            </Section>
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      layout: 'fullscreen',
+    },
+  },
+  [
+    'A school attendance dashboard showing the full-width four-column KPI pattern followed by a',
+    '`two-thirds` + `one-third` detail layout.',
+    'The left column surfaces the students most at risk; the right column holds quick filters and summary stats.',
+  ].join(' '),
+);
+
+export const StaffDirectory: Story = withDescription(
+  {
+    render: () => (
+      <Grid>
+        <Grid.Row>
+          <Grid.Column columnWidth="full">
+            <div style={pageHeaderStyle}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+                <Heading level={1}>Staff Directory</Heading>
+                <Badge colour="blue">24 staff</Badge>
+              </div>
+              <Button variant="primary" size="S" iconLeftName="plus">Add Staff Member</Button>
+            </div>
+          </Grid.Column>
+        </Grid.Row>
+
+        <Grid.Row>
+          <Grid.Column columnWidth="full">
+            <div style={{ display: 'flex', gap: 'var(--spacing-xsmall)', marginBottom: 'var(--spacing-medium)', flexWrap: 'wrap' }}>
+              {[
+                { label: 'Teaching', color: 'blue' },
+                { label: 'Support', color: 'teal' },
+                { label: 'Leadership', color: 'purple' },
+                { label: 'Admin', color: 'orange' },
+              ].map(({ label, color }) => (
+                <Tag key={label} color={color as 'blue' | 'teal' | 'purple' | 'orange'}>{label}</Tag>
+              ))}
+            </div>
+          </Grid.Column>
+        </Grid.Row>
+
+        <Grid.Row>
+          <Grid.Column columnWidth="one-third">
+            <DataViewCard
+              header="Sarah Thompson"
+              avatar={{ initials: 'ST' }}
+              rows={[
+                { label: 'Role', value: 'Head of Maths' },
+                { label: 'Department', value: 'Mathematics' },
+                { label: 'Email', value: 's.thompson@school.edu' },
+              ]}
+            />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-third">
+            <DataViewCard
+              header="James Okafor"
+              avatar={{ initials: 'JO' }}
+              rows={[
+                { label: 'Role', value: 'SENCO' },
+                { label: 'Department', value: 'Inclusion' },
+                { label: 'Email', value: 'j.okafor@school.edu' },
+              ]}
+            />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-third">
+            <DataViewCard
+              header="Rachel Patel"
+              avatar={{ initials: 'RP' }}
+              rows={[
+                { label: 'Role', value: 'Science Teacher' },
+                { label: 'Department', value: 'Science' },
+                { label: 'Email', value: 'r.patel@school.edu' },
+              ]}
+            />
+          </Grid.Column>
+        </Grid.Row>
+
+        <Grid.Row>
+          <Grid.Column columnWidth="one-third">
+            <DataViewCard
+              header="David Clarke"
+              avatar={{ initials: 'DC' }}
+              rows={[
+                { label: 'Role', value: 'English Teacher' },
+                { label: 'Department', value: 'English' },
+                { label: 'Email', value: 'd.clarke@school.edu' },
+              ]}
+            />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-third">
+            <DataViewCard
+              header="Amara Diallo"
+              avatar={{ initials: 'AD' }}
+              rows={[
+                { label: 'Role', value: 'Deputy Head' },
+                { label: 'Department', value: 'Leadership' },
+                { label: 'Email', value: 'a.diallo@school.edu' },
+              ]}
+            />
+          </Grid.Column>
+          <Grid.Column columnWidth="one-third">
+            <DataViewCard
+              header="Tom Harris"
+              avatar={{ initials: 'TH' }}
+              rows={[
+                { label: 'Role', value: 'PE Teacher' },
+                { label: 'Department', value: 'PE & Sport' },
+                { label: 'Email', value: 't.harris@school.edu' },
+              ]}
+            />
+          </Grid.Column>
+        </Grid.Row>
+      </Grid>
+    ),
+    parameters: {
+      controls: { disable: true },
+      layout: 'fullscreen',
+    },
+  },
+  [
+    'A staff directory page demonstrating the three-column `one-third` grid pattern across multiple rows.',
+    'Each `DataViewCard` represents a staff member with avatar, role, and contact details.',
+    'The filter tags at the top use a full-width row; the card grid rows beneath are fully independent.',
+  ].join(' '),
+);