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

package/src/components/banner/Banner.stories.tsx

@@ -1,96 +1,1114 @@
-import type { Meta } from '@storybook/react-vite';
+import { useState } 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 { fn } from 'storybook/test';
 import { Banner, BANNER_LEVEL } from './Banner';
 
-const meta: Meta<typeof Banner> = {
-  tags: ['autodocs'],
+// Banner is Object.assign(BannerRoot, {...}) — Storybook reads the internal
+// function name 'BannerRoot' for code generation. Setting displayName here
+// ensures the global source transform uses the correct public export name.
+(Banner as unknown as { displayName: string }).displayName = 'Banner';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Banner is a full-width horizontal strip placed at the top of a page or surface to deliver page-level state,',
+  'system guidance, or high-risk alerts. Unlike inline notifications, a Banner addresses the entire surface',
+  '— think of it as the town crier of your UI.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Page-level state** — information that applies to everything the user sees on the current surface',
+  '- **System problems** — connectivity issues, failed background syncs, service degradation',
+  '- **High-risk situations** — data that is locked, read-only, or from a prior academic year',
+  '- **Essential page guidance** — critical "how this page works" context a user must not miss',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Inline field errors | Form validation (field-level error messages) |',
+  '| Success messages / snackbars | [`Toast`](?path=/docs/components-toast--docs) |',
+  '| More than one alert on the same surface | Consolidate, prioritise, or use a different pattern |',
+  '| Marketing / promotional copy | A dedicated promotional component |',
+  '',
+  '---',
+  '',
+  '### Design guidance',
+  '',
+  '**Four semantic variants:**',
+  '',
+  '- `INFO` (blue) — helpful context the user should know but does not need to act on immediately',
+  '- `NEUTRAL` (transparent background) — non-urgent notes that do not carry urgency or risk',
+  '- `WARNING` (amber) — something is risky or incomplete, but the user can still proceed',
+  '- `DESTRUCTIVE` (red) — a serious error or locked state **(legacy only — see critical notes below)**',
+  '',
+  '**Tone of voice:** Confident, straightforward, positive. Short sentences, plain language, active voice.',
+  'State impact before action. CTAs must use active verbs ("Fix settings", "Review exclusions") — never "Click here".',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical notes',
+  '',
+  '#### `DESTRUCTIVE` = "Error" in design docs',
+  '',
+  'The source enum uses developer naming (`BANNER_LEVEL.DESTRUCTIVE`) but the Confluence design spec',
+  'calls this variant **"Error"**. They are the same thing. If you are reading the design spec and see',
+  '"Error banner", reach for `BANNER_LEVEL.DESTRUCTIVE` in code.',
+  '',
+  '#### Error banners are legacy-only',
+  '',
+  'Per current design guidance, `BANNER_LEVEL.DESTRUCTIVE` should only appear in legacy surfaces.',
+  'For new features, prefer `WARNING` (risky-but-reversible state) or a page-level empty state.',
+  'Error notifications should be backed by reliable, confirmed system/data state — not manual admin notes.',
+  '',
+  '#### One banner per surface — hard rule',
+  '',
+  'Never render more than one Banner on the same page or surface at a time. The `AllVariants` story',
+  'in this file is a **visual reference only**. In a real application, pick the one Banner that',
+  'matters most and surface only that.',
+  '',
+  '#### Persistent — no built-in dismiss',
+  '',
+  'Banner has no close button and no auto-dismiss timer. It stays visible until the underlying condition',
+  'resolves. If your product requirement calls for a dismissible banner, wrap `Banner` in your own',
+  '`useState` + conditional render (see the `DismissiblePattern` story for the recommended approach).',
+  '',
+  '#### No automatic `role="alert"`',
+  '',
+  'Banner does **not** set `role="alert"` or `role="status"` automatically. Static banners (present on',
+  'page load) do not need these roles. If your banner appears dynamically in response to a user action',
+  '(e.g. after a failed save), you are responsible for adding `role="alert"` via the `className` prop',
+  'or by wrapping the Banner and managing ARIA outside the component.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **Static banners** (present on load) need no special ARIA. Screen readers encounter them in normal',
+  '  document flow as heading + paragraph content.',
+  '- **Dynamic banners** (appear after user action): add `role="alert"` externally. Do not overuse alert',
+  '  roles — they interrupt screen reader flow and should only fire when the banner content is truly',
+  '  time-sensitive.',
+  '- **Colour alone** must not be the only signal of severity. The banner text must describe the impact.',
+  '- **Icons** receive `aria-hidden="true"` by default (handled by the `Icon` component) when they',
+  '  duplicate the meaning already expressed in text.',
+  '- **Focus order:** page title → banner content → interactive controls. Do not break this by',
+  '  positioning the banner after the main content area.',
+  '- **CTA button keyboard access:** the optional text-link button is keyboard-focusable and activated',
+  '  by Enter/Space. Its label must make sense out of context — "Fix settings" beats "Click here".',
+  '',
+  '---',
+  '',
+  '### Component tokens',
+  '',
+  'Banner exposes a structured set of CSS custom properties for theming. The naming pattern is:',
+  '',
+  '`--banner-{level}-color-{role}` where `{level}` is `info | neutral | warning | destructive`',
+  'and `{role}` is `background | border | text | icon`.',
+  '',
+  'Example: `--banner-info-color-background` controls the Info variant background.',
+  '',
+  'These tokens wrap the semantic colour system (`--color-semantic-info-*`, etc.) — always use the',
+  'banner-specific tokens rather than the underlying semantic ones so that theme overrides propagate',
+  'correctly. Note that the Neutral variant intentionally has no background token — the transparent',
+  'background is by design.',
+  '',
+  'Layout tokens: `--banner-spacing-vertical`, `--banner-spacing-horizontal`, `--banner-spacing-gap`,',
+  '`--banner-radius`.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Banner, BANNER_LEVEL } from '@arbor-education/design-system.components';",
+  '',
+  'function MyBanner(props: Banner.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `Banner.Props` | Full props interface |',
+  '| `Banner.Level` | Enum — use as `Banner.Level.INFO`, `.NEUTRAL`, `.WARNING`, `.DESTRUCTIVE`. Replaces the old flat `BANNER_LEVEL` import. |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Toast](?path=/docs/components-toast--docs) · [Modal](?path=/docs/components-modals-modal--docs) · [Button](?path=/docs/components-button--docs) · [Icon](?path=/docs/components-icon--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 BannerDocsPage() {
+  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>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Curated icon options for the Controls panel.
+// Only icons that make semantic sense in a banner context are listed.
+// All names verified against src/components/icon/allowedIcons.tsx.
+// ---------------------------------------------------------------------------
+
+const BANNER_ICON_OPTIONS: Array<string | undefined> = [
+  undefined,
+  'info',
+  'triangle-alert',
+  'circle-alert',
+  'circle-check',
+  'lock',
+  'lock-open',
+  'sparkles',
+  'lightbulb',
+  'mail',
+  'user',
+  'date',
+  'settings',
+  'flag',
+  'clock-3',
+];
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
   title: 'Components/Banner',
   component: Banner,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: BannerDocsPage,
+    },
+  },
   argTypes: {
     level: {
-      control: { type: 'select' },
+      control: 'select',
       options: Object.values(BANNER_LEVEL),
+      description: [
+        'Semantic variant controlling the colour scheme and default icon.',
+        '`INFO` (blue) — helpful context.',
+        '`NEUTRAL` (transparent) — non-urgent notes.',
+        '`WARNING` (amber) — risky but recoverable.',
+        '`DESTRUCTIVE` (red) — serious error or locked state.',
+        'Note: the design spec calls `DESTRUCTIVE` the "Error" variant — they are the same thing.',
+      ].join(' '),
+      table: {
+        type: { summary: 'BANNER_LEVEL' },
+        defaultValue: { summary: 'BANNER_LEVEL.NEUTRAL' },
+      },
+    },
+    title: {
+      control: 'text',
+      description: [
+        'Optional heading rendered as an `<h3>` inside the banner.',
+        'Use a short noun phrase (e.g. "Session expiring soon") rather than a full sentence.',
+        'Keep it under 8 words — longer headings push the CTA button onto an awkward line.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    text: {
+      control: 'text',
+      description: [
+        'Body copy for the banner. 1–2 sentences is ideal.',
+        'State the impact before the action: "The census period is closed. Export data before Friday."',
+        'If body copy fills more than 3 lines, consider a Modal instead.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    icon: {
+      control: 'select',
+      options: BANNER_ICON_OPTIONS,
+      description: [
+        'Override the default icon for this level.',
+        'Default icons: `info` for INFO and NEUTRAL, `triangle-alert` for WARNING, `circle-alert` for DESTRUCTIVE.',
+        'Use a more specific metaphor when it helps (e.g. `lock` for a locked record, `circle-check` for a completed state).',
+        'Icon colour is controlled by the level token, not the icon choice.',
+        'All options in this control are verified against the allowedIcons set.',
+      ].join(' '),
+      table: {
+        type: { summary: 'IconName' },
+        defaultValue: { summary: 'Auto per level' },
+      },
+    },
+    hideIcon: {
+      control: 'boolean',
+      description: [
+        'When `true`, completely suppresses the icon — no space is reserved and the central container',
+        'expands to fill the full width.',
+        'Use sparingly: icons reinforce the semantic level at a glance for users who scan.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    buttonText: {
+      control: 'text',
+      description: [
+        'Label for the optional text-link CTA button rendered at the trailing edge of the banner.',
+        'Must use an active verb: "Fix settings", "Review exclusions", "Switch to current year".',
+        'Keep it short — the button has `text-wrap: nowrap` and the banner does not wrap to a second row.',
+        'Do not use "Click here" — it conveys no information to screen reader users navigating by links.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    buttonOnClick: {
+      control: false,
+      description: [
+        'Click handler for the CTA button.',
+        'Required when `buttonText` is provided — otherwise the button renders with no action.',
+        'Receives the native `React.MouseEvent<HTMLButtonElement>` so you can call `e.preventDefault()` if needed.',
+      ].join(' '),
+      table: {
+        type: { summary: '(e: React.MouseEvent<HTMLButtonElement>) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      control: false,
+      description: [
+        'Additional CSS class names appended to the root `<div>` via CVA.',
+        'Merges cleanly with the `ds-banner--{level}` modifier — no specificity conflicts.',
+        'Primary use: add `role="alert"` via a utility class, or apply a custom top-margin for layout.',
+        'Do not use this to override banner colours — use the `--banner-*` CSS tokens instead.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
   },
   args: {
-    buttonOnClick: () => { console.log('click!'); },
+    buttonOnClick: fn(),
   },
-};
+} satisfies Meta<typeof Banner>;
 
-export const Neutral = {
-  args: {
-    text: 'This is a neutral banner message with some useful information for the user.',
+export default meta;
+type Story = StoryObj<typeof Banner>;
+
+// ---------------------------------------------------------------------------
+// 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 for stateful or compositional stories.
+// Named components avoid react-hooks lint issues — the react-hooks ESLint
+// plugin is NOT configured in this project, so do NOT add eslint-disable.
+// ---------------------------------------------------------------------------
+
+const DismissibleTemplate = () => {
+  const [visible, setVisible] = useState(true);
+
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Banner has no built-in dismiss. Consumers implement it with useState + conditional render:
+      </p>
+      {/* Banner is conditionally rendered — when visible is false, it disappears entirely.
+          The consumer owns this state. If the dismissed state should persist across page loads,
+          store it in localStorage or your app state layer. */}
+      {visible && (
+        <Banner
+          level={BANNER_LEVEL.WARNING}
+          text="Some marksheet entries have not been saved. Please review before leaving the page."
+          buttonText="Dismiss"
+          buttonOnClick={() => setVisible(false)}
+        />
+      )}
+      {!visible && (
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+          Banner dismissed. In a real app, reload the page or resolve the underlying condition to show it again.
+        </p>
+      )}
+    </div>
+  );
 };
 
-export const Info = {
-  args: {
-    level: BANNER_LEVEL.INFO,
-    text: 'Your session will expire in 10 minutes. Save your work to avoid losing changes.',
+const AllVariantsTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-xxlarge)',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-warning-600)', fontStyle: 'italic' }}>
+      Reference layout only — never ship multiple banners on one surface.
+    </p>
+
+    {/* INFO */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>INFO</p>
+      <Banner
+        level={BANNER_LEVEL.INFO}
+        text="Your session will expire in 10 minutes. Save your work to avoid losing changes."
+      />
+    </div>
+
+    {/* NEUTRAL — wrapped in a grey-100 swatch so the transparent background is visible */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        NEUTRAL (shown against a grey-100 backdrop — the banner itself is transparent)
+      </p>
+      <div style={{ background: 'var(--color-grey-100)', borderRadius: 'var(--border-radius-small)', padding: 'var(--spacing-large)' }}>
+        <Banner
+          level={BANNER_LEVEL.NEUTRAL}
+          text="You are viewing last year's data. Switch to the current academic year to make changes."
+        />
+      </div>
+    </div>
+
+    {/* WARNING */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>WARNING</p>
+      <Banner
+        level={BANNER_LEVEL.WARNING}
+        text="The marksheet has unsaved entries. Review before leaving to avoid data loss."
+      />
+    </div>
+
+    {/* DESTRUCTIVE */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        DESTRUCTIVE (called "Error" in design spec — legacy use only)
+      </p>
+      <Banner
+        level={BANNER_LEVEL.DESTRUCTIVE}
+        text="This student record is locked because the reporting period has been closed."
+      />
+    </div>
+  </div>
+);
+
+const ContentGuidelinesTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-xxlarge)',
+    }}
+  >
+    {/* IDEAL */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-success-600)' }}>
+        Ideal — short title, 1–2 line body, active verb CTA
+      </p>
+      <Banner
+        level={BANNER_LEVEL.WARNING}
+        title="Reporting period closing soon"
+        text="The census submission deadline is Friday 17 April at 5pm."
+        buttonText="Review exclusions"
+        buttonOnClick={() => undefined}
+      />
+    </div>
+
+    {/* TOO LONG */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-destructive-600)' }}>
+        Too long — paragraph-length body belongs in a Modal, not a Banner
+      </p>
+      <Banner
+        level={BANNER_LEVEL.WARNING}
+        title="Action required before the reporting period closes"
+        text="The census submission window closes at 5pm on Friday 17 April. You must review all exclusion records, verify that attendance data has been finalised for every year group, and confirm that your designated senior leader has approved the submission. Failure to complete these steps before the deadline will require an extension request to your local authority, which may take up to 10 working days to process."
+        buttonText="Learn more"
+        buttonOnClick={() => undefined}
+      />
+    </div>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.NEUTRAL,
+      text: "You are viewing last year's data. Switch to the current academic year to make changes.",
+    },
+    render: args => <Banner {...args} />,
   },
-};
+  [
+    'The interactive canvas story — every prop is wired to the **Controls** panel below.',
+    'Use the controls to explore all four levels, toggle `hideIcon`, add a `title`, provide `buttonText`,',
+    'and override the default `icon`. Start by changing `level` to see the colour scheme shift.',
+  ].join(' '),
+);
 
-export const Warning = {
-  args: {
-    level: BANNER_LEVEL.WARNING,
-    text: 'This action may affect student records. Please review before proceeding.',
+export const Info: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.INFO,
+      text: 'Your session will expire in 10 minutes. Save your work to avoid losing changes.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerInfoExample() {
+  return (
+    <Banner
+      level={Banner.Level.INFO}
+      text="Your session will expire in 10 minutes. Save your work to avoid losing changes."
+    />
+  );
+}
+
+export default BannerInfoExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '**Info (blue)** — helpful context the user should know but does not need to act on right now.',
+    'Use for non-urgent system messages like session warnings, scheduled maintenance, or general guidance.',
+    'The default icon is `info`. The blue colour scheme communicates "pay attention" without alarm.',
+  ].join(' '),
+);
 
-export const Destructive = {
-  args: {
-    level: BANNER_LEVEL.DESTRUCTIVE,
-    text: 'Something went wrong. Please contact your system administrator.',
+export const Neutral: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.NEUTRAL,
+      text: "You are viewing last year's data. Switch to the current academic year to make changes.",
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerNeutralExample() {
+  return (
+    <Banner
+      level={Banner.Level.NEUTRAL}
+      text="You are viewing last year's data. Switch to the current academic year to make changes."
+    />
+  );
+}
+
+export default BannerNeutralExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '**Neutral (transparent)** — contextual notes that carry no urgency or risk.',
+    'The banner background is transparent, inheriting the page surface behind it.',
+    'Use for orientation messages: "you are in read-only view", "this is archived data", "filters are active".',
+    'The `AllVariants` story wraps this in a grey-100 backdrop so the transparent background is visible against white.',
+  ].join(' '),
+);
 
-export const WithTitle = {
-  args: {
-    level: BANNER_LEVEL.INFO,
-    title: 'Important Update',
-    text: 'A new version of the system is available. Refresh the page to apply updates.',
+export const Warning: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.WARNING,
+      text: 'The marksheet has unsaved entries. Review before leaving to avoid data loss.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerWarningExample() {
+  return (
+    <Banner
+      level={Banner.Level.WARNING}
+      text="The marksheet has unsaved entries. Review before leaving to avoid data loss."
+    />
+  );
+}
+
+export default BannerWarningExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '**Warning (amber)** — something is risky or incomplete, but the user can still proceed.',
+    'Reserve Warning for situations where continuing without action could lead to a recoverable bad outcome:',
+    'unsaved data, missing required setup, outdated records, approaching deadlines.',
+    'The amber colour is attention-grabbing without implying a hard stop.',
+  ].join(' '),
+);
 
-export const WithButton = {
-  args: {
-    level: BANNER_LEVEL.WARNING,
-    text: 'You have unsaved changes that will be lost.',
-    buttonText: 'Undo changes',
-    buttonOnClick: () => { console.log('Banner button clicked'); },
+export const Destructive: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.DESTRUCTIVE,
+      text: 'This student record is locked because the reporting period has been closed.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerDestructiveExample() {
+  return (
+    <Banner
+      level={Banner.Level.DESTRUCTIVE}
+      text="This student record is locked because the reporting period has been closed."
+    />
+  );
+}
+
+export default BannerDestructiveExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '**Destructive / "Error" (red) — legacy use only.**',
+    '',
+    'The source enum is `BANNER_LEVEL.DESTRUCTIVE` but the Confluence design spec calls this variant "Error".',
+    'They are the same thing — if you see "Error banner" in design docs, use `BANNER_LEVEL.DESTRUCTIVE` in code.',
+    '',
+    'Per current design guidance, this variant is for **legacy surfaces only**. On new features,',
+    'reach for `WARNING` (risky-but-reversible) or a page-level empty state instead.',
+    'Error banners should be backed by reliable, confirmed system/data state — not manual admin notes.',
+  ].join(' '),
+);
 
-export const WithTitleAndButton = {
-  args: {
-    level: BANNER_LEVEL.INFO,
-    title: 'Scheduled Maintenance',
-    text: 'The system will be unavailable on Saturday 1st March between 2am–4am.',
-    buttonText: 'Learn more',
-    buttonOnClick: () => { console.log('Banner button clicked'); },
+export const WithTitle: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.INFO,
+      title: 'Session expiring soon',
+      text: 'Your session will expire in 10 minutes. Save your work to avoid losing changes.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerWithTitleExample() {
+  return (
+    <Banner
+      level={Banner.Level.INFO}
+      title="Session expiring soon"
+      text="Your session will expire in 10 minutes. Save your work to avoid losing changes."
+    />
+  );
+}
+
+export default BannerWithTitleExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'The canonical structure when both a heading and body copy are needed.',
+    'The `title` renders as an `<h3 class="ds-banner__title">` — keep it under 8 words.',
+    'Use a short noun phrase, not a full sentence. The body copy fills in the detail.',
+    'When title and text are both present, the title acts as a visual anchor for users scanning the page.',
+  ].join(' '),
+);
 
-export const TitleOnly = {
-  args: {
-    level: BANNER_LEVEL.NEUTRAL,
-    title: 'No results found for the selected filters.',
+export const WithButton: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.WARNING,
+      text: "The census submission deadline is Friday 17 April at 5pm. Don't leave it to the last minute.",
+      buttonText: 'Review exclusions',
+      buttonOnClick: fn(),
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerWithButtonExample() {
+  return (
+    <Banner
+      level={Banner.Level.WARNING}
+      text="The census submission deadline is Friday 17 April at 5pm. Don't leave it to the last minute."
+      buttonText="Review exclusions"
+      buttonOnClick={() => {}}
+    />
+  );
+}
+
+export default BannerWithButtonExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'A banner with an optional text-link CTA at the trailing edge.',
+    'The button uses `color: inherit`, so its text colour matches the level — amber on Warning, blue on Info, etc.',
+    'Always use an active verb: "Fix settings", "Review exclusions", "Switch to current year".',
+    'Keep button labels short — the button has `text-wrap: nowrap` and the banner does not wrap to a second row.',
+  ].join(' '),
+);
 
-export const CustomIcon = {
-  args: {
-    level: BANNER_LEVEL.INFO,
-    icon: 'circle-check',
-    text: 'Your changes have been saved successfully.',
+export const WithTitleAndButton: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.INFO,
+      title: 'Scheduled maintenance',
+      text: 'The system will be unavailable on Saturday 19 April between 2am–4am.',
+      buttonText: 'Learn more',
+      buttonOnClick: fn(),
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerWithTitleAndButtonExample() {
+  return (
+    <Banner
+      level={Banner.Level.INFO}
+      title="Scheduled maintenance"
+      text="The system will be unavailable on Saturday 19 April between 2am–4am."
+      buttonText="Learn more"
+      buttonOnClick={() => {}}
+    />
+  );
+}
+
+export default BannerWithTitleAndButtonExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'The full Banner structure: icon + title + body + CTA.',
+    'This is the maximum content a banner should carry. If you find yourself needing more,',
+    'consider a Modal — the banner flex layout is `row nowrap` and will not wrap to a second line.',
+    'The CTA button inherits the level text colour and sits flush to the trailing edge.',
+  ].join(' '),
+);
 
-export const HideIcon = {
-  args: {
-    level: BANNER_LEVEL.WARNING,
-    hideIcon: true,
-    text: 'This banner has its icon hidden.',
+export const TitleOnly: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.NEUTRAL,
+      title: 'No students match the selected filters.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerTitleOnlyExample() {
+  return (
+    <Banner
+      level={Banner.Level.NEUTRAL}
+      title="No students match the selected filters."
+    />
+  );
+}
+
+export default BannerTitleOnlyExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'A banner with only a `title` — no body copy.',
+    'Valid for situations where the heading is self-explanatory and body text would be redundant.',
+    'If the message requires any clarification or a call-to-action, add `text` and/or `buttonText`.',
+  ].join(' '),
+);
 
-export default meta;
+export const TextOnly: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.INFO,
+      text: 'The census submission deadline is Friday 17 April at 5pm.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerTextOnlyExample() {
+  return (
+    <Banner
+      level={Banner.Level.INFO}
+      text="The census submission deadline is Friday 17 April at 5pm."
+    />
+  );
+}
+
+export default BannerTextOnlyExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A banner with body copy only — no title heading.',
+    'Appropriate for short, self-contained messages that do not need a heading to orient the user.',
+    'When the message is 1 clear sentence, `title` is optional overhead.',
+  ].join(' '),
+);
+
+export const CustomIcon: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.INFO,
+      icon: 'lock',
+      title: 'Record locked',
+      text: 'This student record is read-only. The reporting period for this academic year has been closed.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerCustomIconExample() {
+  return (
+    <Banner
+      level={Banner.Level.INFO}
+      icon="lock"
+      title="Record locked"
+      text="This student record is read-only. The reporting period for this academic year has been closed."
+    />
+  );
+}
+
+export default BannerCustomIconExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Override the default icon with a more specific metaphor.',
+    'Here `lock` (instead of the default `info`) communicates the locked-record context at a glance.',
+    'The icon colour still comes from the level token — swapping the icon shape does not change the colour.',
+    'Good overrides: `lock` / `lock-open` for access states, `circle-check` for confirmed states,',
+    '`sparkles` for AI-assisted features, `date` for deadline-related messages.',
+  ].join(' '),
+);
+
+export const HideIcon: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.WARNING,
+      hideIcon: true,
+      text: 'You are viewing data for a student who has left this school. Some fields may be read-only.',
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerHideIconExample() {
+  return (
+    <Banner
+      level={Banner.Level.WARNING}
+      hideIcon
+      text="You are viewing data for a student who has left this school. Some fields may be read-only."
+    />
+  );
+}
+
+export default BannerHideIconExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Set `hideIcon={true}` to completely suppress the icon.',
+    'No space is reserved — the central container expands to fill the full width.',
+    'Use sparingly: the icon provides a quick visual severity signal for users who scan.',
+    'A valid case is when the banner sits in a context where the surrounding chrome already conveys severity,',
+    'and the icon would be visually redundant.',
+  ].join(' '),
+);
+
+export const AllVariants: Story = withDescription(
+  {
+    render: AllVariantsTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerAllVariantsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xxlarge)' }}>
+      {/* INFO */}
+      <Banner
+        level={Banner.Level.INFO}
+        text="Your session will expire in 10 minutes. Save your work to avoid losing changes."
+      />
+
+      {/* NEUTRAL — wrap in a grey-100 container so transparent background is visible */}
+      <div style={{ background: 'var(--color-grey-100)', borderRadius: 'var(--border-radius-small)', padding: 'var(--spacing-large)' }}>
+        <Banner
+          level={Banner.Level.NEUTRAL}
+          text="You are viewing last year's data. Switch to the current academic year to make changes."
+        />
+      </div>
+
+      {/* WARNING */}
+      <Banner
+        level={Banner.Level.WARNING}
+        text="The marksheet has unsaved entries. Review before leaving to avoid data loss."
+      />
+
+      {/* DESTRUCTIVE — legacy use only */}
+      <Banner
+        level={Banner.Level.DESTRUCTIVE}
+        text="This student record is locked because the reporting period has been closed."
+      />
+    </div>
+  );
+}
+
+export default BannerAllVariantsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'All four variants stacked for visual comparison.',
+    '',
+    '**Important:** This layout is a Storybook-only reference. Never ship multiple banners on the same surface.',
+    'Pick the one that matters most and surface only that. The Neutral variant is shown against a',
+    'grey-100 backdrop to make its transparent background visible.',
+  ].join(' '),
+);
+
+export const ContentGuidelines: Story = withDescription(
+  {
+    render: ContentGuidelinesTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerContentGuidelinesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xxlarge)' }}>
+      {/* Ideal — short title, 1–2 line body, active verb CTA */}
+      <Banner
+        level={Banner.Level.WARNING}
+        title="Reporting period closing soon"
+        text="The census submission deadline is Friday 17 April at 5pm."
+        buttonText="Review exclusions"
+        buttonOnClick={() => {}}
+      />
+
+      {/* Too long — paragraph-length body belongs in a Modal, not a Banner */}
+      <Banner
+        level={Banner.Level.WARNING}
+        title="Action required before the reporting period closes"
+        text="The census submission window closes at 5pm on Friday 17 April. You must review all exclusion records, verify that attendance data has been finalised for every year group, and confirm that your designated senior leader has approved the submission."
+        buttonText="Learn more"
+        buttonOnClick={() => {}}
+      />
+    </div>
+  );
+}
+
+export default BannerContentGuidelinesExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Content length guidelines: what good looks like vs what should be a Modal instead.',
+    '',
+    'The **ideal** banner (top) has a short title, a 1–2 sentence body, and an active-verb CTA.',
+    'The **too long** banner (bottom) carries a multi-sentence paragraph that would be better served by a Modal',
+    'or a dedicated help page. A Banner is a strip, not a notice board.',
+  ].join(' '),
+);
+
+export const DismissiblePattern: Story = withDescription(
+  {
+    render: DismissibleTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Banner } from '@arbor-education/design-system.components';
+
+function DismissibleBanner() {
+  const [visible, setVisible] = useState(true);
+
+  if (!visible) return null;
+
+  return (
+    <Banner
+      level={Banner.Level.WARNING}
+      text="Some marksheet entries have not been saved. Please review before leaving the page."
+      buttonText="Dismiss"
+      buttonOnClick={() => setVisible(false)}
+    />
+  );
+}
+
+export default DismissibleBanner;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The recommended consumer pattern for a dismissible banner.',
+    '',
+    'Banner has **no built-in dismiss** — it is intentionally persistent so it stays visible until',
+    'the underlying condition is resolved. When your requirement calls for user-dismissal, wrap Banner',
+    'in `useState` + conditional render in your own component. The CTA button triggers `setVisible(false)`.',
+    '',
+    'If the dismissed state should persist across page reloads, store the flag in `localStorage`',
+    'or your application state layer — the Banner component itself has no opinion about persistence.',
+  ].join(' '),
+);
+
+export const LegacyErrorWarning: Story = withDescription(
+  {
+    args: {
+      level: BANNER_LEVEL.DESTRUCTIVE,
+      icon: 'circle-alert',
+      title: 'Submission failed',
+      text: 'The exclusion could not be submitted. Contact your system administrator if this problem persists.',
+      buttonText: 'Fix settings',
+      buttonOnClick: fn(),
+    },
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Banner } from '@arbor-education/design-system.components';
+
+function BannerLegacyErrorWarningExample() {
+  return (
+    /* Legacy use only — prefer Banner.Level.WARNING on new surfaces */
+    <Banner
+      level={Banner.Level.DESTRUCTIVE}
+      icon="circle-alert"
+      title="Submission failed"
+      text="The exclusion could not be submitted. Contact your system administrator if this problem persists."
+      buttonText="Fix settings"
+      buttonOnClick={() => {}}
+    />
+  );
+}
+
+export default BannerLegacyErrorWarningExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '**Legacy use only.** This story demonstrates the `DESTRUCTIVE` ("Error") variant.',
+    '',
+    'Per design guidance: Error banners should only appear on **legacy surfaces**.',
+    'For new alerts on modern pages, prefer:',
+    '',
+    '- `WARNING` — for risky-but-reversible situations ("some data has not been saved")',
+    '- Page-level empty states — when there is nothing to show due to an error condition',
+    '- [`Toast`](?path=/docs/components-toast--docs) — for ephemeral success/error feedback after a user action',
+    '',
+    'Error banners must be backed by reliable, confirmed system state — not advisory text added manually.',
+  ].join(' '),
+);