@arbor-education/design-system.components 0.12.0 → 0.13.1

package/src/components/formField/FormField.stories.tsx

@@ -1,181 +1,1598 @@
 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 { fn } from 'storybook/test';
-
 import { comboboxPeopleOptions } from '../../mocks/comboboxStoryOptions';
 import { FormField } from './FormField';
 
-const meta: Meta<typeof FormField> = {
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'FormField is the **complete form field assembly**: it wires together a label, an optional',
+  'description, any of eight input controls, an optional helper link, and an error message — all',
+  'with the correct accessibility connections built in automatically.',
+  '',
+  'Think of it as a filing cabinet drawer with everything pre-labelled: you tell it what kind of',
+  'input you need (`inputType`), give it a label and an `id`, and it handles the `htmlFor`,',
+  '`aria-describedby`, `aria-invalid`, and `hasError` wiring for you.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Any labelled input in an Arbor form — enrolment, student records, timetabling, attendance',
+  '- When you need built-in error state management without writing the aria connections yourself',
+  '- When a field needs a helper link to external documentation or a field description below the label',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Scenario | Use instead |',
+  '|---|---|',
+  '| Raw input without a label | Use the individual input component (`TextInput`, etc.) directly |',
+  '| Grouping several related fields (address, name) | Wrap multiple `FormField`s in a `Fieldset` |',
+  '| Non-standard input control | Compose the label + input yourself using `Label` + the input component |',
+  '',
+  '---',
+  '',
+  '### The eight input types',
+  '',
+  '| `inputType` | Renders | Typical use |',
+  '|---|---|---|',
+  '| `"text"` (default) | `TextInput` | Names, codes, short free text |',
+  '| `"textarea"` | `TextArea` | Notes, medical conditions, long free text |',
+  '| `"number"` | `NumberInput` | Class sizes, ages, counts |',
+  '| `"time"` | `TimeInput` | Registration time, period start/end |',
+  '| `"colourPicker"` | `ColourPickerDropdown` | Form group or subject colour |',
+  '| `"selectDropdown"` | `SelectDropdown` | Year group, term, single or multi select |',
+  '| `"datePicker"` | `DatePicker` | Date of birth, enrolment date |',
+  '| `"combobox"` | `Combobox` | Searchable people picker, tutor assignment |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical gotchas — read before using',
+  '',
+  '**1. Always provide `id`.** The `id` prop drives `label[htmlFor]`, and the `aria-describedby`',
+  'IDs for the description and error spans. Omit it and the a11y wiring silently breaks — no TS',
+  'error, just inaccessible markup. Treat it as required.',
+  '',
+  '**2. Never set `hasError`, `aria-invalid`, or `aria-describedby` in `inputProps`.** FormField',
+  'builds these automatically from `errorText` and `fieldDescription`. If you set them in',
+  '`inputProps`, they will be overridden — but the intent becomes confusing and may produce',
+  'conflicting values depending on spread order.',
+  '',
+  '**3. `helperLinkText` and `helperLinkUrl` must both be provided.** Providing only one renders',
+  'nothing — the component renders neither the link text nor the URL if the pair is incomplete.',
+  '',
+  '**4. `helperLink` and `fieldDescription` are mutually exclusive by design.** The component',
+  'will render both if you supply both, but the Confluence design spec prohibits this combination.',
+  'Use one or the other, never both.',
+  '',
+  '**5. `errorText` and `helperLink` CAN coexist.** Both appear inside the same `ds-form-field__message`',
+  'container: error rendered first, helper link second (stacked vertically).',
+  '',
+  '**6. `fieldDescription` persists during errors.** The description span stays visible even when',
+  '`errorText` is set. It is not hidden or replaced by the error.',
+  '',
+  '**7. Always provide `label` when using `helperLinkText`.** The helper link `aria-label` is',
+  'constructed as `"${label} helper link"`. Omit `label` and the aria-label becomes `"undefined helper link"`.',
+  '',
+  '**8. Optional fields: use the label suffix convention.** There is no `required` prop and no',
+  'asterisk pattern. Mark optional fields by appending `"(optional)"` to the label text, e.g.',
+  '`label="Middle name (optional)"`. All fields without this suffix are implicitly required.',
+  '',
+  '**9. `NumberInput` renders `type="text"` internally.** Do not pass `type` in `inputProps` when',
+  '`inputType="number"` — it is ignored and may produce confusing behaviour. The component uses',
+  '`inputMode="numeric"` for mobile keyboards.',
+  '',
+  '**10. `TimeInput` switches to Combobox mode when `options` is provided.** Pass an array of',
+  '`"HH:MM"` strings to `inputProps.options` to replace the native time picker with a searchable',
+  'dropdown of preset times.',
+  '',
+  '**11. The helper link does NOT open in a new tab.** There is no `target="_blank"` on the anchor.',
+  'This is a known limitation — Confluence guidance says it should open a new tab, but the current',
+  'implementation does not do this. Bear it in mind when linking to external documentation.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- `id` drives all ARIA wiring — treat it as required even though TypeScript allows it to be omitted',
+  '- `fieldDescription` is connected via `aria-describedby` automatically — never wire this yourself',
+  '- `errorText` sets both `hasError` and `aria-invalid` on the inner input, and a description via `aria-describedby`',
+  '- The error span contains a `triangle-alert` icon; the icon is decorative (the text carries the meaning)',
+  '- Visible labels are always required — never rely on placeholder text as a substitute for a label',
+  '- For grouped fields (address blocks, name fields) wrap in `Fieldset` with a `legend`',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { FormField } from '@arbor-education/design-system.components';",
+  '',
+  'function MyField(props: FormField.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `FormField.Props` | Full props interface |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[TextInput](?path=/docs/components-formfield-inputs-textinput--docs) · ',
+  '[TextArea](?path=/docs/components-formfield-inputs-textarea--docs) · ',
+  '[NumberInput](?path=/docs/components-formfield-inputs-numeric--docs) · ',
+  '[TimeInput](?path=/docs/components-formfield-inputs-timeinput--docs) · ',
+  '[SelectDropdown](?path=/docs/components-formfield-inputs-selectdropdown--docs) · ',
+  '[ColourPickerDropdown](?path=/docs/components-formfield-inputs-colourpickerdropdown--docs) · ',
+  '[DatePicker](?path=/docs/components-datepicker--docs) · ',
+  '[Combobox](?path=/docs/components-combobox--docs) · ',
+  '[Fieldset](?path=/docs/components-formfield-fieldset--docs) · ',
+  '[Label](?path=/docs/components-formfield-inputs-label--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 FormFieldDocsPage() {
+  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/FormField',
   component: FormField,
-};
-
-export const Default = {
-  args: {
-    id: 'text-input',
-    label: 'Text Input',
-    inputProps: {
-      placeholder: 'Enter your text',
-      onChange: fn(),
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      page: FormFieldDocsPage,
     },
-    helperLinkText: 'More information',
-    helperLinkUrl: 'https://www.google.com',
-    errorText: 'This is some error text',
-    fieldDescription: 'This is some descriptive text for the field',
-    inputType: 'text',
   },
   argTypes: {
-    'helperLinkText': {
+    id: {
       control: 'text',
-      description: 'Helper link text',
+      description: [
+        '**Practically required.** Drives `label[htmlFor]` and the `aria-describedby` IDs for the',
+        'field description (`{id}-description`) and error message (`{id}-error`).',
+        'Omit it and all accessibility wiring silently breaks — no TypeScript error, just broken a11y.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    'helperLinkUrl': {
+    label: {
       control: 'text',
-      description: 'Helper link URL',
+      description: [
+        'Visible label rendered above the input via the `Label` component (`ds-label`).',
+        'Short, sentence case. Use `"Field name (optional)"` suffix for optional fields — there is',
+        'no `required` prop and no asterisk convention.',
+        '**Also required when using `helperLinkText`** — the link\'s `aria-label` uses this value verbatim.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    'errorText': {
-      control: 'text',
-      description: 'Error text',
+    inputType: {
+      control: 'select',
+      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
+      description: [
+        'Determines which input component is rendered.',
+        'Defaults to `"text"` (renders `TextInput`).',
+        '`"textarea"` → `TextArea` (auto-grows); `"number"` → `NumberInput` (spinner buttons + decimal);',
+        '`"time"` → `TimeInput` (native picker or combobox preset mode);',
+        '`"colourPicker"` → `ColourPickerDropdown` (hex colour sketch picker in a dropdown);',
+        '`"selectDropdown"` → `SelectDropdown` (single or multi select with grouping);',
+        '`"datePicker"` → `DatePicker` (calendar popover);',
+        '`"combobox"` → `Combobox` (searchable, type-ahead).',
+      ].join(' '),
+      table: {
+        type: { summary: "'text' | 'textarea' | 'number' | 'time' | 'colourPicker' | 'selectDropdown' | 'datePicker' | 'combobox'" },
+        defaultValue: { summary: "'text'" },
+      },
     },
-    'fieldDescription': {
+    fieldDescription: {
       control: 'text',
-      description: 'Field description',
+      description: [
+        'Static guidance rendered below the label, above the input.',
+        'Automatically connected to the input via `aria-describedby`.',
+        'Target 20–60 characters. Good examples: `"Shown on the parent-facing report"`,',
+        '`"Up to 30 characters"`, `"Format: DD/MM/YYYY"`.',
+        '**Stays visible when `errorText` is set** — it is not replaced by the error.',
+        '**Mutually exclusive with `helperLinkText` / `helperLinkUrl`** per Confluence design spec.',
+      ].join(' '),
+      table: {
+        type: { summary: 'ReactNode' },
+      },
     },
-    'inputType': {
-      control: 'select',
-      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
-      description: 'Input type',
+    helperLinkText: {
+      control: 'text',
+      description: [
+        'Text for an external documentation link rendered below the input.',
+        '**Both `helperLinkText` AND `helperLinkUrl` must be provided** — supplying only one renders nothing.',
+        'Use action-led copy: `"Learn more"`, `"View guidance"`, `"See SEN framework"`.',
+        '**Mutually exclusive with `fieldDescription`** per Confluence design spec.',
+        '**Known limitation:** the link has no `target="_blank"` and does not open in a new tab.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    'inputProps.size': {
-      control: 'select',
-      options: ['M', 'S'],
-      description: 'Input size',
+    helperLinkUrl: {
+      control: 'text',
+      description: [
+        'URL for the helper link. **Must be paired with `helperLinkText`** — supplying only one renders nothing.',
+        'Typically points to Confluence guidance or external documentation.',
+        '**Known limitation:** no `target="_blank"` — does not open in a new tab.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    'inputProps.disabled': {
-      control: 'boolean',
-      description: 'Disable the input',
+    errorText: {
+      control: 'text',
+      description: [
+        'Error message rendered below the input with a `triangle-alert` icon.',
+        'Setting this automatically applies `hasError` and `aria-invalid` to the inner input,',
+        'and adds an `aria-describedby` reference to the error span.',
+        'Write errors as: what went wrong + how to fix it.',
+        'Example: `"Enter a date in DD/MM/YYYY format"`. One error per field.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    'inputProps.placeholder': {
+    className: {
       control: 'text',
-      description: 'Input placeholder text',
+      description: [
+        'Additional CSS class(es) applied to the **root `div`** (`ds-form-field`), not the inner input.',
+        'Use for layout overrides only — do not use to style the input itself.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    inputProps: {
+      control: false,
+      description: [
+        'Props spread onto the inner input component. The shape narrows based on `inputType`.',
+        '**Do NOT set `hasError`, `aria-invalid`, or `aria-describedby` here** — FormField builds',
+        'these automatically. They are spread BEFORE `inputProps` and will be overridden.',
+        'The Controls panel cannot represent this discriminated union — configure it in the story code.',
+      ].join(' '),
+      table: {
+        type: { summary: 'TextInputProps | TextAreaProps | NumberInputProps | TimeInputProps | ColourPickerDropdownProps | SelectDropdownInputProps | DatePickerProps | ComboboxProps' },
+      },
     },
   },
-};
+} satisfies Meta<typeof FormField>;
 
-type Story = StoryObj<typeof meta>;
+export default meta;
 
-// Form example with multiple inputs
-export const FormExample: Story = {
-  render: () => (
-    <div style={{ width: '400px', display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+// Use StoryObj<typeof FormField> (not typeof meta) so render-only stories are not
+// forced to provide args for the required discriminated-union props.
+type Story = StoryObj<typeof FormField>;
+
+// ---------------------------------------------------------------------------
+// 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,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      id: 'student-surname',
+      label: 'Surname',
+      inputType: 'text',
+      inputProps: {
+        placeholder: 'e.g. Nylund',
+      },
+    },
+    render: args => <FormField {...args} />,
+  },
+  'The interactive canvas. Every top-level prop is wired to the Controls panel below. Use the controls to toggle `errorText`, add a `fieldDescription`, switch `inputType`, or add a `helperLinkUrl`. **Note:** `inputProps` cannot be controlled from the panel — it represents a discriminated union that changes shape with `inputType`. Edit the story code to configure it.',
+);
+
+export const WithFieldDescription: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithFieldDescriptionExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
       <FormField
-        id="first-name"
-        label="First Name"
-        inputProps={{
-          placeholder: 'Enter your first name',
-        }}
+        id="preferred-name"
+        label="Preferred name (optional)"
+        fieldDescription="Shown on the parent-facing report card"
+        inputProps={{ placeholder: 'e.g. Rose' }}
       />
       <FormField
-        id="last-name"
-        label="Last Name"
+        id="medical-notes"
+        label="Medical conditions"
+        fieldDescription="Up to 30 characters. Visible to form tutors only."
+        inputType="textarea"
+        inputProps={{ placeholder: 'e.g. Asthma — uses inhaler before PE' }}
+      />
+    </div>
+  );
+}
+export default WithFieldDescriptionExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="preferred-name"
+          label="Preferred name (optional)"
+          fieldDescription="Shown on the parent-facing report card"
+          inputProps={{ placeholder: 'e.g. Rose' }}
+        />
+        <FormField
+          id="medical-notes"
+          label="Medical conditions"
+          fieldDescription="Up to 30 characters. Visible to form tutors only."
+          inputType="textarea"
+          inputProps={{ placeholder: 'e.g. Asthma — uses inhaler before PE' }}
+        />
+      </div>
+    ),
+  },
+  [
+    'A field description provides static contextual guidance below the label — it tells the user what',
+    'the field is for or what format to use. It appears above the input and stays visible even when',
+    'an error is shown.',
+    '',
+    '**Content guidance:** target 20–60 characters. Use it for format hints (`"DD/MM/YYYY"`) or',
+    'visibility notes (`"Shown on the parent-facing report"`). Do not use it for validation messages',
+    '— that is what `errorText` is for.',
+    '',
+    '**Never combine with `helperLinkText` / `helperLinkUrl`.** Per Confluence design spec these are',
+    'mutually exclusive — `fieldDescription` is for static guidance, the helper link is for external',
+    'documentation. Using both creates visual noise and breaks the design intent.',
+  ].join('\n'),
+);
+
+export const WithHelperLink: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithHelperLinkExample() {
+  return (
+    <FormField
+      id="sen-category"
+      label="SEN category"
+      inputType="selectDropdown"
+      inputProps={{
+        options: [
+          { label: 'Cognition and learning', value: 'cognition-learning' },
+          { label: 'Communication and interaction', value: 'communication-interaction' },
+          { label: 'Social, emotional and mental health', value: 'semh' },
+          { label: 'Sensory and physical needs', value: 'sensory-physical' },
+        ],
+        placeholder: 'Select a category',
+        onSelectionChange: (values) => console.log(values),
+      }}
+      helperLinkText="View SEN framework"
+      helperLinkUrl="https://www.gov.uk/government/publications/send-code-of-practice-0-to-25"
+    />
+  );
+}
+export default WithHelperLinkExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <FormField
+          id="sen-category"
+          label="SEN category"
+          inputType="selectDropdown"
+          inputProps={{
+            options: [
+              { label: 'Cognition and learning', value: 'cognition-learning' },
+              { label: 'Communication and interaction', value: 'communication-interaction' },
+              { label: 'Social, emotional and mental health', value: 'semh' },
+              { label: 'Sensory and physical needs', value: 'sensory-physical' },
+            ],
+            placeholder: 'Select a category',
+            onSelectionChange: fn(),
+          }}
+          helperLinkText="View SEN framework"
+          helperLinkUrl="https://www.gov.uk/government/publications/send-code-of-practice-0-to-25"
+        />
+      </div>
+    ),
+  },
+  [
+    'The helper link renders below the input as an action-led anchor with a `arrow-up-right` icon.',
+    'It connects to external documentation — DfE guidance, Confluence pages, or statutory frameworks.',
+    '',
+    '**Both props required:** `helperLinkText` and `helperLinkUrl` must both be set. Providing only',
+    'one renders nothing at all.',
+    '',
+    '**Known limitation:** the anchor has no `target="_blank"` — it does not open in a new tab.',
+    'Confluence design guidance says it should, but the current implementation navigates in the same',
+    'tab. Bear this in mind for links to external documentation.',
+    '',
+    '**Never combine with `fieldDescription`.** Per Confluence design spec these are mutually exclusive.',
+    'The helper link is for external documentation; `fieldDescription` is for inline static guidance.',
+    '',
+    '**Always provide `label` when using `helperLinkText`.** The link\'s `aria-label` is built as',
+    '`"${label} helper link"`. Omit `label` and screen readers announce `"undefined helper link"`.',
+  ].join('\n'),
+);
+
+export const WithError: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithErrorExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="date-of-birth"
+        label="Date of birth"
+        inputType="datePicker"
+        inputProps={{ onChange: (date) => console.log(date) }}
+        errorText="Enter a date in DD/MM/YYYY format"
+      />
+      <FormField
+        id="class-size"
+        label="Class size"
+        inputType="number"
+        inputProps={{ min: 1, max: 35, placeholder: '30' }}
+        errorText="Class size must be between 1 and 35"
+      />
+    </div>
+  );
+}
+export default WithErrorExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="date-of-birth"
+          label="Date of birth"
+          inputType="datePicker"
+          inputProps={{ onChange: fn() }}
+          errorText="Enter a date in DD/MM/YYYY format"
+        />
+        <FormField
+          id="class-size"
+          label="Class size"
+          inputType="number"
+          inputProps={{ min: 1, max: 35, placeholder: '30' }}
+          errorText="Class size must be between 1 and 35"
+        />
+      </div>
+    ),
+  },
+  [
+    'The error state. Setting `errorText` automatically:',
+    '',
+    '- Renders a `triangle-alert` icon followed by the error message below the input',
+    '- Applies `hasError={true}` to the inner input (which adds `ds-input--error` classes)',
+    '- Sets `aria-invalid={true}` on the inner input',
+    '- Adds the error span to the input\'s `aria-describedby`',
+    '',
+    '**Write errors as:** what went wrong + how to fix it. `"Enter a date in DD/MM/YYYY format"` is',
+    'better than `"Invalid date"`. `"Class size must be between 1 and 35"` beats `"Invalid number"`.',
+    '',
+    '**One error per field.** FormField only accepts a single `errorText` string — render one clear,',
+    'actionable message rather than a list.',
+    '',
+    '**Do NOT set `hasError` or `aria-invalid` in `inputProps`** — FormField sets these for you.',
+  ].join('\n'),
+);
+
+export const WithErrorAndFieldDescription: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithErrorAndFieldDescriptionExample() {
+  return (
+    <FormField
+      id="student-upn"
+      label="Unique Pupil Number (UPN)"
+      fieldDescription="13-character code on previous school letter"
+      inputProps={{ placeholder: 'e.g. A123456789012' }}
+      errorText="Enter a valid 13-character UPN — check the letter from the previous school"
+    />
+  );
+}
+export default WithErrorAndFieldDescriptionExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <FormField
+          id="student-upn"
+          label="Unique Pupil Number (UPN)"
+          fieldDescription="13-character code on previous school letter"
+          inputProps={{ placeholder: 'e.g. A123456789012' }}
+          errorText="Enter a valid 13-character UPN — check the letter from the previous school"
+        />
+      </div>
+    ),
+  },
+  [
+    'Both `fieldDescription` and `errorText` can coexist. The description stays visible above the',
+    'input as usual; the error appears below. Both are connected to the input via `aria-describedby`',
+    'so screen readers announce both the description context and the error.',
+    '',
+    'This is confirmed behaviour from the source: `fieldDescription` is never hidden when an error',
+    'is active. The design rationale is that the description provides context the user still needs',
+    'to fix the error correctly.',
+    '',
+    'The `aria-describedby` value will be `"{id}-description {id}-error"` — both IDs concatenated.',
+  ].join('\n'),
+);
+
+export const WithErrorAndHelperLink: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithErrorAndHelperLinkExample() {
+  return (
+    <FormField
+      id="attendance-code"
+      label="Attendance code"
+      inputProps={{ placeholder: 'e.g. B' }}
+      errorText="Enter a valid DfE attendance code (single letter A–Z)"
+      helperLinkText="View attendance code reference"
+      helperLinkUrl="https://www.gov.uk/government/publications/school-attendance"
+    />
+  );
+}
+export default WithErrorAndHelperLinkExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <FormField
+          id="attendance-code"
+          label="Attendance code"
+          inputProps={{ placeholder: 'e.g. B' }}
+          errorText="Enter a valid DfE attendance code (single letter A–Z)"
+          helperLinkText="View attendance code reference"
+          helperLinkUrl="https://www.gov.uk/government/publications/school-attendance"
+        />
+      </div>
+    ),
+  },
+  [
+    '`errorText` and the helper link CAN appear together — this is the one exception where the',
+    'message container renders both elements simultaneously: the error appears first, the helper link',
+    'below it.',
+    '',
+    'This is useful when the validation failure is likely to require the user to look up a reference',
+    '— for example, an attendance code or a statutory identifier.',
+  ].join('\n'),
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="admissions-number"
+        label="Admissions number"
+        fieldDescription="Assigned by your local authority — cannot be edited"
+        inputProps={{ disabled: true, value: 'ADM-2024-00412', readOnly: true }}
+      />
+      <FormField
+        id="school-urn"
+        label="School URN"
+        fieldDescription="Unique Reference Number — set by Ofsted"
+        inputProps={{ disabled: true, value: '123456' }}
+      />
+    </div>
+  );
+}
+export default DisabledExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="admissions-number"
+          label="Admissions number"
+          fieldDescription="Assigned by your local authority — cannot be edited"
+          inputProps={{ disabled: true, value: 'ADM-2024-00412', readOnly: true }}
+        />
+        <FormField
+          id="school-urn"
+          label="School URN"
+          fieldDescription="Unique Reference Number — set by Ofsted"
+          inputProps={{ disabled: true, value: '123456' }}
+        />
+      </div>
+    ),
+  },
+  [
+    'Pass `disabled: true` inside `inputProps` to disable the inner input. The label and description',
+    'remain visible for context; the input becomes non-interactive and muted.',
+    '',
+    '**Disabled vs read-only:** disabled fields are not focusable and are not submitted with form data.',
+    'Read-only fields (`readOnly: true`) ARE focusable and their value IS submitted. Use read-only',
+    'when the user should be able to select and copy the value (e.g. a generated code or reference).',
+    '',
+    '**Do not show errors on disabled fields** — a user cannot fix a field they cannot edit.',
+  ].join('\n'),
+);
+
+export const TextArea: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function TextAreaExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="pastoral-notes"
+        label="Pastoral notes"
+        inputType="textarea"
+        fieldDescription="Visible to form tutor and head of year only"
         inputProps={{
-          placeholder: 'Enter your first name',
+          placeholder: 'e.g. Supporting bereavement — meeting with school counsellor Tuesdays',
+          rows: 3,
         }}
       />
       <FormField
-        id="email"
-        label="Email"
+        id="medical-conditions"
+        label="Medical conditions (optional)"
+        inputType="textarea"
         inputProps={{
-          placeholder: 'Enter your email',
+          placeholder: 'e.g. Type 1 diabetes — checks blood sugar before lunch',
+          rows: 3,
         }}
-        helperLinkText="More information"
-        helperLinkUrl="https://www.google.com"
       />
+    </div>
+  );
+}
+export default TextAreaExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="pastoral-notes"
+          label="Pastoral notes"
+          inputType="textarea"
+          fieldDescription="Visible to form tutor and head of year only"
+          inputProps={{
+            placeholder: 'e.g. Supporting bereavement — meeting with school counsellor Tuesdays',
+            rows: 3,
+          }}
+        />
+        <FormField
+          id="medical-conditions"
+          label="Medical conditions (optional)"
+          inputType="textarea"
+          inputProps={{
+            placeholder: 'e.g. Type 1 diabetes — checks blood sugar before lunch',
+            rows: 3,
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="textarea"` renders a `TextArea` — a multi-line input that grows automatically as',
+    'the user types (`autoSize={true}` is the default). The initial height is controlled by the',
+    '`rows` prop in `inputProps`.',
+    '',
+    '**Use for:** pastoral notes, medical conditions, free-text feedback, long descriptions.',
+    '',
+    '**Auto-sizing:** the textarea expands vertically as the user types — it does not scroll.',
+    'To opt out, pass `autoSize: false` in `inputProps`.',
+    '',
+    '**All shared wiring still applies:** `errorText`, `fieldDescription`, and `id` work identically.',
+  ].join('\n'),
+);
+
+export const NumberInput: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function NumberInputExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
       <FormField
-        id="password"
-        label="Password"
+        id="class-capacity"
+        label="Class capacity"
+        inputType="number"
+        fieldDescription="Maximum number of students in this class"
         inputProps={{
-          placeholder: 'Enter your first name',
-          type: 'password',
+          min: 1,
+          max: 35,
+          step: 1,
+          defaultValue: 30,
         }}
       />
       <FormField
-        id="message"
-        label="Message"
-        inputType="textarea"
+        id="fsm-percentage"
+        label="FSM threshold (%)"
+        inputType="number"
+        fieldDescription="Free school meals eligibility threshold"
         inputProps={{
-          placeholder: 'Enter a lovely message',
+          min: 0,
+          max: 100,
+          step: 5,
+          defaultValue: 20,
         }}
       />
       <FormField
-        id="age"
-        label="Age"
+        id="absence-sessions"
+        label="Absence sessions"
         inputType="number"
+        fieldDescription="Number of half-day sessions (no spinner)"
         inputProps={{
-          placeholder: 'Enter your age',
+          min: 0,
+          max: 200,
+          disableSpinners: true,
+          placeholder: '0',
         }}
       />
+    </div>
+  );
+}
+export default NumberInputExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="class-capacity"
+          label="Class capacity"
+          inputType="number"
+          fieldDescription="Maximum number of students in this class"
+          inputProps={{
+            min: 1,
+            max: 35,
+            step: 1,
+            defaultValue: 30,
+          }}
+        />
+        <FormField
+          id="fsm-percentage"
+          label="FSM threshold (%)"
+          inputType="number"
+          fieldDescription="Free school meals eligibility threshold"
+          inputProps={{
+            min: 0,
+            max: 100,
+            step: 5,
+            defaultValue: 20,
+          }}
+        />
+        <FormField
+          id="absence-sessions"
+          label="Absence sessions"
+          inputType="number"
+          fieldDescription="Number of half-day sessions (no spinner)"
+          inputProps={{
+            min: 0,
+            max: 200,
+            disableSpinners: true,
+            placeholder: '0',
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="number"` renders a `NumberInput` — a text input (`type="text"`, `inputMode="numeric"`)',
+    'with optional ± spinner buttons and decimal-safe arithmetic via `decimal.js`.',
+    '',
+    '**Do NOT pass `type` in `inputProps`.** `NumberInput` renders as `type="text"` internally to',
+    'avoid browser number input quirks. The component handles formatting and validation itself.',
+    '',
+    '**`min` / `max` / `step`:** on blur and on spinner click, the value is clamped to the range.',
+    'Pass `step={5}` for coarse increments (e.g. FSM thresholds at 5% steps).',
+    '',
+    '**`disableSpinners={true}`:** removes the ± buttons for fields where the user should type',
+    'directly rather than increment — large session counts, reference numbers.',
+  ].join('\n'),
+);
+
+export const TimeInput: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function TimeInputExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
       <FormField
-        id="start-time"
-        label="Start time"
+        id="registration-time"
+        label="Registration time"
         inputType="time"
-        inputProps={{
-          'aria-label': 'Start time',
-          'defaultValue': '14:30',
-        }}
+        fieldDescription="Morning registration start time"
+        inputProps={{ defaultValue: '08:45' }}
       />
       <FormField
-        id="colour-dropdown"
-        label="Colour"
-        inputType="colourPicker"
+        id="period-start"
+        label="Period start"
+        inputType="time"
+        fieldDescription="Choose from preset timetable slots"
         inputProps={{
-          onChange: fn(),
+          options: ['08:00', '08:45', '09:30', '10:15', '11:00', '11:45', '12:30', '13:15', '14:00', '14:45', '15:30'],
+          placeholder: 'Select a period',
         }}
       />
+    </div>
+  );
+}
+export default TimeInputExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="registration-time"
+          label="Registration time"
+          inputType="time"
+          fieldDescription="Morning registration start time"
+          inputProps={{ defaultValue: '08:45' }}
+        />
+        <FormField
+          id="period-start"
+          label="Period start"
+          inputType="time"
+          fieldDescription="Choose from preset timetable slots"
+          inputProps={{
+            options: ['08:00', '08:45', '09:30', '10:15', '11:00', '11:45', '12:30', '13:15', '14:00', '14:45', '15:30'],
+            placeholder: 'Select a period',
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="time"` renders a `TimeInput`, which has two modes:',
+    '',
+    '**Native mode** (no `options` prop): renders the browser\'s native `<input type="time">` with a',
+    'clock icon button. The value format is `"HH:MM"` or `"HH:MM:SS"`. Use `granularity="second"`',
+    'in `inputProps` to add seconds precision.',
+    '',
+    '**Combobox mode** (`options` array provided): replaces the native picker with a searchable',
+    'Combobox preset list — ideal for timetabling screens where slots are fixed.',
+    'Pass `options={["08:00", "08:45", ...]}` as an array of `"HH:MM"` strings.',
+    '',
+    'Use `onValueChange` in `inputProps` to receive value changes (accepts a string).',
+    'Use `onChange` if you need the native `ChangeEvent<HTMLInputElement>` interface.',
+  ].join('\n'),
+);
+
+export const WithSelectDropdown: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithSelectDropdownExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
       <FormField
-        id="select-dropdown"
-        label="Select"
+        id="year-group"
+        label="Year group"
         inputType="selectDropdown"
         inputProps={{
-          options: [{ label: 'Option 1', value: 'option1' }, { label: 'Option 2', value: 'option2' }, { label: 'Option 3', value: 'option3' }],
-          onSelectionChange: fn(),
+          options: [
+            { label: 'Year 7', value: 'y7' },
+            { label: 'Year 8', value: 'y8' },
+            { label: 'Year 9', value: 'y9' },
+            { label: 'Year 10', value: 'y10' },
+            { label: 'Year 11', value: 'y11' },
+          ],
+          placeholder: 'Select year group',
+          onSelectionChange: (values) => console.log(values),
         }}
       />
       <FormField
-        id="assignee"
-        label="Assignee"
-        inputType="combobox"
+        id="subject-filter"
+        label="Subjects taught (optional)"
+        inputType="selectDropdown"
+        fieldDescription="Select all that apply"
         inputProps={{
-          options: comboboxPeopleOptions,
-          placeholder: 'Search people...',
-          onValueChange: fn(),
+          multiple: true,
+          options: [
+            { label: 'Maths', value: 'maths' },
+            { label: 'English', value: 'english' },
+            { label: 'Science', value: 'science' },
+            { label: 'History', value: 'history' },
+            { label: 'Geography', value: 'geography' },
+            { label: 'Art', value: 'art' },
+            { label: 'Music', value: 'music' },
+            { label: 'Physical Education', value: 'pe' },
+          ],
+          placeholder: 'Select subjects',
+          onSelectionChange: (values) => console.log(values),
         }}
       />
+    </div>
+  );
+}
+export default WithSelectDropdownExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="year-group"
+          label="Year group"
+          inputType="selectDropdown"
+          inputProps={{
+            options: [
+              { label: 'Year 7', value: 'y7' },
+              { label: 'Year 8', value: 'y8' },
+              { label: 'Year 9', value: 'y9' },
+              { label: 'Year 10', value: 'y10' },
+              { label: 'Year 11', value: 'y11' },
+            ],
+            placeholder: 'Select year group',
+            onSelectionChange: fn(),
+          }}
+        />
+        <FormField
+          id="subject-filter"
+          label="Subjects taught (optional)"
+          inputType="selectDropdown"
+          fieldDescription="Select all that apply"
+          inputProps={{
+            multiple: true,
+            options: [
+              { label: 'Maths', value: 'maths' },
+              { label: 'English', value: 'english' },
+              { label: 'Science', value: 'science' },
+              { label: 'History', value: 'history' },
+              { label: 'Geography', value: 'geography' },
+              { label: 'Art', value: 'art' },
+              { label: 'Music', value: 'music' },
+              { label: 'Physical Education', value: 'pe' },
+            ],
+            placeholder: 'Select subjects',
+            onSelectionChange: fn(),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="selectDropdown"` renders a `SelectDropdown` — a Dropdown-based button trigger with',
+    'a list of selectable options. Supports single select (default) and multi-select (`multiple={true}`).',
+    '',
+    '**Options shape:** each option is `{ label: string; value: string; group?: string }`. Grouped',
+    'options render a bold header row above each group.',
+    '',
+    '**Multi-select:** pass `multiple={true}` in `inputProps`. The trigger shows the count of',
+    'selected values when more than one is chosen.',
+    '',
+    '**Controlled vs uncontrolled:** pass `selectedValues` to control the selection externally;',
+    'omit it for uncontrolled (internal state). Use `initialSelectedValues` to set a default.',
+  ].join('\n'),
+);
+
+export const WithCombobox: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithComboboxExample() {
+  const tutorOptions = [
+    { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
+    { value: 'bob', label: 'Bob Smith', iconName: 'user' },
+    { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
+    { value: 'diana', label: 'Diana Prince', iconName: 'user' },
+  ];
+
+  return (
+    <FormField
+      id="form-tutor"
+      label="Form tutor"
+      inputType="combobox"
+      fieldDescription="Assigned tutor for this form group"
+      inputProps={{
+        options: tutorOptions,
+        placeholder: 'Search by name...',
+        onValueChange: (values) => console.log(values),
+      }}
+    />
+  );
+}
+export default WithComboboxExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <FormField
+          id="form-tutor"
+          label="Form tutor"
+          inputType="combobox"
+          fieldDescription="Assigned tutor for this form group"
+          inputProps={{
+            options: comboboxPeopleOptions,
+            placeholder: 'Search by name...',
+            onValueChange: fn(),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="combobox"` renders a `Combobox` — a searchable, type-ahead selector.',
+    'The user types to filter the options list; results highlight matching characters.',
+    '',
+    '**Use for:** any "select a person" scenario — form tutor assignment, cover teacher lookup,',
+    'parent/guardian search. Works with the `comboboxPeopleOptions` mock for stories.',
+    '',
+    '**`onValueChange`** in `inputProps` receives the selected value as `string[]` (Combobox is',
+    'inherently multi-value even in single-select mode — expect an array of one).',
+    '',
+    '**Options shape:** `{ value: string; label: string; iconName?: IconName; group?: string }`.',
+    'Provide `iconName="user"` for people pickers to render the person icon.',
+    '',
+    '**Note:** `fieldDescription` is shown here alongside the combobox — this is intentional.',
+    'Do not add `helperLinkText` when `fieldDescription` is already present.',
+  ].join('\n'),
+);
+
+export const WithDatePicker: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithDatePickerExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
       <FormField
         id="date-of-birth"
-        label="Date of Birth"
+        label="Date of birth"
+        inputType="datePicker"
+        fieldDescription="Format: DD/MM/YYYY"
+        inputProps={{ onChange: (date) => console.log(date) }}
+      />
+      <FormField
+        id="enrolment-date"
+        label="Enrolment date"
         inputType="datePicker"
-        inputProps={{ onChange: fn() }}
+        inputProps={{
+          onChange: (date) => console.log(date),
+          displayFormat: 'default',
+        }}
       />
     </div>
-  ),
-};
+  );
+}
+export default WithDatePickerExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="date-of-birth"
+          label="Date of birth"
+          inputType="datePicker"
+          fieldDescription="Format: DD/MM/YYYY"
+          inputProps={{ onChange: fn() }}
+        />
+        <FormField
+          id="enrolment-date"
+          label="Enrolment date"
+          inputType="datePicker"
+          inputProps={{
+            onChange: fn(),
+            displayFormat: 'default',
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="datePicker"` renders a `DatePicker` — a text input that opens a calendar popover',
+    'when clicked. The user can type the date directly or pick from the calendar.',
+    '',
+    '**`onChange`** in `inputProps` receives a `Date | undefined` — not a string. Format it for',
+    'display or API submission in your application layer.',
+    '',
+    '**`displayFormat`** controls how the date is shown in the text input. Defaults to `"default"`',
+    '(locale-appropriate). Check the DatePicker stories for the full format reference.',
+    '',
+    '**Portalled component:** the calendar popover is rendered via a portal. Do not wrap this story',
+    'or any component using FormField with `overflow: hidden` or `position: relative` on a tight',
+    'container — it will clip the calendar.',
+  ].join('\n'),
+);
+
+export const OptionalAndRequiredFields: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
 
-export const Combobox: Story = {
-  render: () => (
-    <div data-surface="base" data-colour-mode="light" className="bg-surface text-on-surface-default" style={{ padding: 32, maxWidth: 420 }}>
+function OptionalAndRequiredFieldsExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
       <FormField
-        id="form-field-combobox"
-        label="Assignee"
-        fieldDescription="Search and select a person."
-        inputType="combobox"
+        id="student-forename"
+        label="First name"
+        inputProps={{ placeholder: 'e.g. Rose' }}
+      />
+      <FormField
+        id="student-middle-name"
+        label="Middle name (optional)"
+        inputProps={{ placeholder: 'e.g. Marie' }}
+      />
+      <FormField
+        id="student-surname"
+        label="Surname"
+        inputProps={{ placeholder: 'e.g. Nylund' }}
+      />
+      <FormField
+        id="student-preferred-name"
+        label="Preferred name (optional)"
+        fieldDescription="Used in class registers and parent communications"
+        inputProps={{ placeholder: 'e.g. Rosie' }}
+      />
+      <FormField
+        id="student-legal-name"
+        label="Legal name"
+        fieldDescription="As it appears on official documents"
+        inputProps={{ placeholder: 'e.g. Rose Marie Nylund' }}
+      />
+    </div>
+  );
+}
+export default OptionalAndRequiredFieldsExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="student-forename"
+          label="First name"
+          inputProps={{ placeholder: 'e.g. Rose' }}
+        />
+        <FormField
+          id="student-middle-name"
+          label="Middle name (optional)"
+          inputProps={{ placeholder: 'e.g. Marie' }}
+        />
+        <FormField
+          id="student-surname"
+          label="Surname"
+          inputProps={{ placeholder: 'e.g. Nylund' }}
+        />
+        <FormField
+          id="student-preferred-name"
+          label="Preferred name (optional)"
+          fieldDescription="Used in class registers and parent communications"
+          inputProps={{ placeholder: 'e.g. Rosie' }}
+        />
+        <FormField
+          id="student-legal-name"
+          label="Legal name"
+          fieldDescription="As it appears on official documents"
+          inputProps={{ placeholder: 'e.g. Rose Marie Nylund' }}
+        />
+      </div>
+    ),
+  },
+  [
+    'Arbor uses the **label suffix convention** for optional fields — no asterisk, no `required` prop.',
+    'Append `"(optional)"` directly to the label text: `label="Middle name (optional)"`.',
+    '',
+    'Fields without this suffix are implicitly required. This is a deliberate Confluence design',
+    'decision: marking optional fields (the minority) is less visually noisy than marking required',
+    'fields (the majority) with an asterisk that users learn to ignore anyway.',
+    '',
+    '**Never** use a red asterisk (`*`) required indicator — this is not in the Arbor design system.',
+    '**Never** use placeholder text as a substitute for a label, even for optional fields.',
+  ].join('\n'),
+);
+
+export const WithColourPicker: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithColourPickerExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="form-group-colour"
+        label="Form group colour"
+        inputType="colourPicker"
+        fieldDescription="Shown on the timetable and group list"
+        inputProps={{ onChange: (result) => console.log(result.hex) }}
+      />
+      <FormField
+        id="subject-colour"
+        label="Subject colour (optional)"
+        inputType="colourPicker"
         inputProps={{
-          options: comboboxPeopleOptions,
-          placeholder: 'Search people...',
-          onValueChange: fn(),
+          value: '#e63946',
+          onChange: (result) => console.log(result.hex),
         }}
       />
     </div>
-  ),
-};
+  );
+}
+export default WithColourPickerExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="form-group-colour"
+          label="Form group colour"
+          inputType="colourPicker"
+          fieldDescription="Shown on the timetable and group list"
+          inputProps={{ onChange: fn() }}
+        />
+        <FormField
+          id="subject-colour"
+          label="Subject colour (optional)"
+          inputType="colourPicker"
+          inputProps={{
+            value: '#e63946',
+            onChange: fn(),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="colourPicker"` renders a `ColourPickerDropdown` — a button trigger that opens a',
+    'Sketch colour picker in a Dropdown. The selected colour is previewed in the trigger button.',
+    '',
+    '**`onChange`** in `inputProps` receives a `ColorResult` object from `@uiw/color-convert` —',
+    'use `.hex` to get the hex string: `onChange={(result) => setColour(result.hex)}`.',
+    '',
+    '**`value`** in `inputProps` accepts a hex string (e.g. `"#3cad51"`). Defaults to Arbor green',
+    '(`"#3cad51"`) if not provided.',
+    '',
+    '**Portalled component:** the colour picker popover is rendered via a portal. Do not wrap',
+    'with `overflow: hidden` — it will clip the picker.',
+  ].join('\n'),
+);
 
-export default meta;
+export const CompleteStudentForm: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function CompleteStudentFormExample() {
+  const tutorOptions = [
+    { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
+    { value: 'bob', label: 'Bob Smith', iconName: 'user' },
+    { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
+  ];
+
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p style={{ margin: 0, fontWeight: 'var(--font-weight-semi-bold)', color: 'var(--color-grey-900)' }}>
+        New student record
+      </p>
+      <FormField id="student-first-name" label="First name" inputProps={{ placeholder: 'e.g. Dorothy' }} />
+      <FormField id="student-surname" label="Surname" inputProps={{ placeholder: 'e.g. Zbornak' }} />
+      <FormField
+        id="student-preferred-name"
+        label="Preferred name (optional)"
+        fieldDescription="Used in registers and parent communications"
+        inputProps={{ placeholder: 'e.g. Dot' }}
+      />
+      <FormField
+        id="student-dob"
+        label="Date of birth"
+        inputType="datePicker"
+        fieldDescription="Format: DD/MM/YYYY"
+        inputProps={{ onChange: (date) => console.log(date) }}
+      />
+      <FormField
+        id="student-year-group"
+        label="Year group"
+        inputType="selectDropdown"
+        inputProps={{
+          options: [
+            { label: 'Year 7', value: 'y7' },
+            { label: 'Year 8', value: 'y8' },
+            { label: 'Year 9', value: 'y9' },
+            { label: 'Year 10', value: 'y10' },
+            { label: 'Year 11', value: 'y11' },
+          ],
+          placeholder: 'Select year group',
+          onSelectionChange: (values) => console.log(values),
+        }}
+      />
+      <FormField
+        id="student-form-tutor"
+        label="Form tutor"
+        inputType="combobox"
+        inputProps={{
+          options: tutorOptions,
+          placeholder: 'Search by name...',
+          onValueChange: (values) => console.log(values),
+        }}
+      />
+      <FormField
+        id="student-registration-time"
+        label="Registration time"
+        inputType="time"
+        inputProps={{ defaultValue: '08:45' }}
+      />
+      <FormField
+        id="student-class-size"
+        label="Class size"
+        inputType="number"
+        inputProps={{ min: 1, max: 35, defaultValue: 30 }}
+      />
+      <FormField
+        id="student-group-colour"
+        label="Form group colour"
+        inputType="colourPicker"
+        inputProps={{ onChange: (result) => console.log(result.hex) }}
+      />
+      <FormField
+        id="student-pastoral-notes"
+        label="Pastoral notes (optional)"
+        inputType="textarea"
+        fieldDescription="Visible to form tutor and SENCO only"
+        inputProps={{
+          placeholder: 'e.g. Transitioning from primary — mild anxiety in crowded spaces',
+          rows: 3,
+        }}
+      />
+    </div>
+  );
+}
+export default CompleteStudentFormExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <p className="ds-text" style={{ margin: 0, fontWeight: 'var(--font-weight-semi-bold)', color: 'var(--color-grey-900)' }}>
+          New student record
+        </p>
+        <FormField
+          id="student-first-name"
+          label="First name"
+          inputProps={{ placeholder: 'e.g. Dorothy' }}
+        />
+        <FormField
+          id="student-surname"
+          label="Surname"
+          inputProps={{ placeholder: 'e.g. Zbornak' }}
+        />
+        <FormField
+          id="student-preferred-name"
+          label="Preferred name (optional)"
+          fieldDescription="Used in registers and parent communications"
+          inputProps={{ placeholder: 'e.g. Dot' }}
+        />
+        <FormField
+          id="student-dob"
+          label="Date of birth"
+          inputType="datePicker"
+          fieldDescription="Format: DD/MM/YYYY"
+          inputProps={{ onChange: fn() }}
+        />
+        <FormField
+          id="student-year-group"
+          label="Year group"
+          inputType="selectDropdown"
+          inputProps={{
+            options: [
+              { label: 'Year 7', value: 'y7' },
+              { label: 'Year 8', value: 'y8' },
+              { label: 'Year 9', value: 'y9' },
+              { label: 'Year 10', value: 'y10' },
+              { label: 'Year 11', value: 'y11' },
+            ],
+            placeholder: 'Select year group',
+            onSelectionChange: fn(),
+          }}
+        />
+        <FormField
+          id="student-form-tutor"
+          label="Form tutor"
+          inputType="combobox"
+          inputProps={{
+            options: comboboxPeopleOptions,
+            placeholder: 'Search by name...',
+            onValueChange: fn(),
+          }}
+        />
+        <FormField
+          id="student-registration-time"
+          label="Registration time"
+          inputType="time"
+          inputProps={{ defaultValue: '08:45' }}
+        />
+        <FormField
+          id="student-class-size"
+          label="Class size"
+          inputType="number"
+          inputProps={{ min: 1, max: 35, defaultValue: 30 }}
+        />
+        <FormField
+          id="student-group-colour"
+          label="Form group colour"
+          inputType="colourPicker"
+          inputProps={{ onChange: fn() }}
+        />
+        <FormField
+          id="student-pastoral-notes"
+          label="Pastoral notes (optional)"
+          inputType="textarea"
+          fieldDescription="Visible to form tutor and SENCO only"
+          inputProps={{
+            placeholder: 'e.g. Transitioning from primary — mild anxiety in crowded spaces',
+            rows: 3,
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    'A realistic school record form using all eight `inputType` values together. This shows how',
+    'FormField composes into a real data-entry screen — consistent spacing (`var(--spacing-large)`',
+    'between fields), a shared `maxWidth` container, and school management domain content throughout.',
+    '',
+    'Notice the conventions in action:',
+    '- Implicitly required fields: no suffix (First name, Surname, Date of birth)',
+    '- Explicitly optional fields: `"(optional)"` suffix (Preferred name, Pastoral notes)',
+    '- `fieldDescription` on fields where format or visibility context helps the user',
+    '- `min` / `max` on the number input to constrain class size',
+    '- `comboboxPeopleOptions` mock for the form tutor Combobox',
+    '',
+    'This replaces the old `FormExample` story which used `"1rem"` gaps and non-school copy.',
+  ].join('\n'),
+);