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

package/dist/components/tag/Tag.stories.js

@@ -1,21 +1,256 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { fn } from '@storybook/test';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
+import { fn } from 'storybook/test';
 import { Dot } from '../dot/Dot';
 import { Icon } from '../icon/Icon';
 import { Tag } from './Tag';
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'Tag is a compact, non-interactive label used to describe metadata, categories, or statuses — think "Year 7", "SEN",',
+    '"Pupil Premium", or "Active". Tags support 8 colour variants, composable leading/trailing slots, and a selection',
+    'state. The remove button exists exclusively for composite chip patterns (like Combobox selection pills); standalone',
+    'tags in metadata lists are never interactive.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- **Student attributes** — year group, form group, special educational needs, funding flags: `Year 7`, `SEN`, `Pupil Premium`',
+    '- **Subject / curriculum labels** — `Maths`, `English`, `Autumn term`',
+    '- **Status descriptors** — `Active`, `On track`, `At risk`, `Assessed`',
+    '- **Category clustering** — a group of Tags on a student profile card describing their characteristics',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Scenario | Use instead |',
+    '|---|---|',
+    '| Filtering results by a category | [`Pill`](?path=/docs/components-pill--docs) |',
+    '| Displaying a numeric count | [`Badge`](?path=/docs/components-badge--docs) |',
+    '| Status dot without any text | [`Dot`](?path=/docs/components-dot--docs) |',
+    '| Clickable action that does something | [`Button`](?path=/docs/components-button--docs) |',
+    '',
+    '```tsx',
+    '// BAD — Tags are non-interactive. Adding onClick to a Tag creates confusion with Pills.',
+    '<Tag onClick={handleClick}>Maths</Tag>',
+    '',
+    '// GOOD — use Pill for filter behaviour',
+    '<Pill onClick={handleClick} text="Maths" />',
+    '```',
+    '',
+    '---',
+    '',
+    '### Design guidance',
+    '',
+    '- **Max 3 words per label** (Confluence design spec). Labels truncate with ellipsis when a max-width is hit.',
+    '  Keep labels short and specific.',
+    '- **Establish a semantic colour mapping in your app** — the design system does NOT map semantic warning/destructive',
+    '  tokens to Tag colours. Tags describe *what something is*, not its urgency. Define your own mapping and',
+    '  apply it consistently (e.g. `salmon` = "Pupil Premium", `purple` = "SEN").',
+    '- **Limit distinct colours visible at once** — Confluence guidance: colour variety hurts scannability.',
+    '  Use neutral for most tags; reach for colour only when it adds genuine semantic value.',
+    '- **Dot prefix** — use `slotStart={<Dot colour="purple" />}` for the canonical dot-prefix pattern.',
+    '  This replaces the old `dotColour` prop (removed in v2). `Dot` is `aria-hidden` when no `label` is passed.',
+    '- **Component tokens** — background colours are controlled by `--tag-category-{colour}-color-background`',
+    '  (one of 8 pale -050 washes). Height, radius, and spacing via `--tag-height`, `--tag-radius`,',
+    '  `--tag-spacing-horizontal`, and `--tag-spacing-gap-horizontal`. Selected state colours via',
+    '  `--tag-selected-color-background` and `--tag-selected-color-border`.',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical patterns',
+    '',
+    '- **`selected` overrides `color`** — when `selected={true}`, the background and border come from',
+    '  `--tag-selected-color-*` tokens regardless of the `color` prop. Selection is a higher-priority signal',
+    '  than categorical colour. Text reverts to neutral regardless of the base colour.',
+    '- **`onRemove` is for composite chip contexts only** — Combobox selection pills, multi-value inputs.',
+    '  Never render a removable Tag in a plain metadata list; Confluence design spec is explicit that',
+    '  regular tags are non-interactive.',
+    '- **`removeButtonTabIndex={-1}` in roving-tabindex parents** — when the parent (e.g. Combobox) manages',
+    '  keyboard focus via a roving tabindex, pass `removeButtonTabIndex={-1}` so users do not tab through',
+    '  every individual X button. The parent moves focus programmatically instead.',
+    '- **`removeLabel` must always be overridden** — the default `"Remove"` is meaningless in isolation.',
+    '  Always pass something like `removeLabel="Remove Year 7"` so screen reader users understand what',
+    '  will be removed.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- **Non-removable Tag** — renders as `<span>` with no `role` and no `tabIndex`. This is correct:',
+    '  non-interactive elements should not be focusable.',
+    '- **Removable Tag** — the remove `<button>` carries an `aria-label` (default `"Remove"`).',
+    '  **Always override this** with something meaningful: `removeLabel="Remove Year 7"`.',
+    '- **`e.stopPropagation()`** — the remove click stops bubbling so composite parents (Combobox,',
+    '  custom chip inputs) do not receive the click as a selection event.',
+    '- **Inside Combobox / composite parent** — pass `removeButtonTabIndex={-1}` and let the parent',
+    '  manage focus. Without this, tab navigation through a group of Tags visits every X button',
+    '  individually, which is jarring and verbose for keyboard users.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { Tag } from '@arbor-education/design-system.components';",
+    '',
+    'function MyTag(props: Tag.Props) { ... }',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `Tag.Props` | Full props interface |',
+    "| `Tag.Color` | `'neutral' \\| 'orange' \\| 'blue' \\| 'green' \\| 'purple' \\| 'teal' \\| 'salmon' \\| 'yellow'` |",
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Badge](?path=/docs/components-badge--docs) · [Pill](?path=/docs/components-pill--docs) · [Dot](?path=/docs/components-dot--docs) · [Combobox](?path=/docs/components-combobox--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 TagDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Data
+// ---------------------------------------------------------------------------
+const allColours = ['neutral', 'orange', 'blue', 'green', 'purple', 'teal', 'salmon', 'yellow'];
+// Realistic Arbor content mapped to each colour for AllColours story
+const colourLabels = {
+    neutral: 'Year 7',
+    orange: 'At risk',
+    blue: 'Maths',
+    green: 'On track',
+    purple: 'SEN',
+    teal: 'EAL',
+    salmon: 'Pupil Premium',
+    yellow: 'Active',
+};
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
-    tags: ['autodocs'],
     title: 'Components/Tag',
     component: Tag,
+    tags: ['autodocs'],
     parameters: {
         docs: {
-            description: {
-                component: 'Displays compact tag content with optional start/end slots and removable actions. Removable tags keep their remove button in the tab order by default; composite parents such as Combobox can pass `removeButtonTabIndex={-1}` for roving tab focus.',
+            page: TagDocsPage,
+        },
+    },
+    argTypes: {
+        children: {
+            control: 'text',
+            description: [
+                'The label text rendered inside the Tag. Keep to **3 words or fewer** (Confluence spec) —',
+                'longer labels truncate with ellipsis when a max-width is applied.',
+                'Examples: `"Year 7"`, `"SEN"`, `"Pupil Premium"`, `"At risk"`, `"Autumn term"`.',
+            ].join(' '),
+            table: {
+                type: { summary: 'React.ReactNode' },
+            },
+        },
+        color: {
+            control: 'select',
+            options: allColours,
+            description: [
+                'The colour variant applied to the Tag background and border.',
+                '8 options: `neutral` (default), `orange`, `blue`, `green`, `purple`, `teal`, `salmon`, `yellow`.',
+                'Background colours are controlled by `--tag-category-{colour}-color-background` tokens (pale -050 washes).',
+                'Establish a semantic mapping in your app and apply it consistently — e.g. `salmon` = Pupil Premium,',
+                '`purple` = SEN. **Note:** when `selected` is `true`, this prop is visually overridden by the selected tokens.',
+            ].join(' '),
+            table: {
+                type: { summary: "'neutral' | 'orange' | 'blue' | 'green' | 'purple' | 'teal' | 'salmon' | 'yellow'" },
+                defaultValue: { summary: "'neutral'" },
+            },
+        },
+        selected: {
+            control: 'boolean',
+            description: [
+                'When `true`, overrides the `color` prop: background and border come from `--tag-selected-color-background`',
+                'and `--tag-selected-color-border`, and text reverts to neutral.',
+                'Selection is a higher-priority signal than categorical colour — use `selected` to indicate',
+                'that this tag represents the currently active category or chosen filter value.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        slotStart: {
+            control: false,
+            description: [
+                'Leading slot rendered before the label. Accepts any `ReactNode` — canonical use is',
+                '`slotStart={<Dot colour="purple" />}` for the dot-prefix pattern (replaces the old `dotColour` prop).',
+                'Also accepts `<Icon name="user" size={12} />` for an icon prefix.',
+                '`Dot` is `aria-hidden` when no `label` prop is passed.',
+            ].join(' '),
+            table: {
+                type: { summary: 'React.ReactNode' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        slotEnd: {
+            control: false,
+            description: [
+                'Trailing slot rendered after the label (and before the remove button when `onRemove` is set).',
+                'Accepts any `ReactNode` — common uses: a chevron icon for expandable tags, a count badge, a status dot.',
+                'Example: `slotEnd={<Icon name="chevron-down" size={12} />}`.',
+            ].join(' '),
+            table: {
+                type: { summary: 'React.ReactNode' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        onRemove: {
+            control: false,
+            description: [
+                'Callback fired when the remove button is clicked. When provided, renders a `<button>` with an X icon',
+                'at the end of the Tag. **For composite chip contexts only** (Combobox selection pills, multi-value inputs).',
+                'Do not use on standalone Tags in metadata lists — Confluence spec says regular Tags are non-interactive.',
+                'The click has `e.stopPropagation()` applied to prevent bubbling into composite parents.',
+            ].join(' '),
+            table: {
+                type: { summary: '() => void' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        removeLabel: {
+            control: 'text',
+            description: [
+                '`aria-label` applied to the remove button. Default is `"Remove"` — **always override this**',
+                'with something meaningful, e.g. `removeLabel="Remove Year 7"` or `removeLabel="Remove Alice Johnson"`.',
+                'The default alone is meaningless to screen reader users who cannot see which tag they are removing.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: '"Remove"' },
+            },
+        },
+        removeButtonTabIndex: {
+            control: 'select',
+            options: [0, -1],
+            description: [
+                'Tab index on the remove button.',
+                '`0` (default) — remove button is in the natural tab order. Correct for standalone removable tags.',
+                '`-1` — remove button is excluded from tab order; the parent manages focus via a roving tabindex.',
+                'Pass `-1` when the Tag lives inside a Combobox or other composite parent that manages keyboard',
+                'navigation, to avoid jarring tab-through of every individual X button.',
+            ].join(' '),
+            table: {
+                type: { summary: '0 | -1' },
+                defaultValue: { summary: '0' },
             },
         },
     },
 };
 export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
 const withDescription = (story, description) => ({
     ...story,
     parameters: {
@@ -28,34 +263,245 @@ const withDescription = (story, description) => ({
         },
     },
 });
+// ---------------------------------------------------------------------------
+// Template components for composition / stateful 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 AllColoursTemplate = () => (_jsx("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: 'var(--spacing-small)',
+        alignItems: 'center',
+    }, children: allColours.map(color => (_jsx(Tag, { color: color, children: colourLabels[color] }, color))) }));
+const RemovableInteractiveTemplate = () => {
+    const [tags, setTags] = useState(['Year 7', 'SEN', 'Pupil Premium', 'Active']);
+    return (_jsx("div", { style: {
+            padding: 'var(--spacing-xlarge)',
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: 'var(--spacing-small)',
+            alignItems: 'center',
+        }, children: tags.length === 0
+            ? (_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "All tags dismissed." }))
+            : (tags.map(tag => (_jsx(Tag, { onRemove: () => setTags(prev => prev.filter(t => t !== tag)), removeLabel: `Remove ${tag}`, children: tag }, tag)))) }));
+};
+const LongLabelTruncationTemplate = () => (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)' }, children: [_jsx("p", { className: "ds-text", style: { marginBottom: 'var(--spacing-small)', color: 'var(--color-grey-600)' }, children: "Container constrained to 12rem \u2014 label truncates with ellipsis:" }), _jsx("div", { style: { maxWidth: '12rem' }, children: _jsx(Tag, { children: "Currently being assessed for additional learning needs" }) })] }));
+const ContentGuidelinesTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Good (3 words or fewer)" }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)', alignItems: 'center' }, children: [_jsx(Tag, { children: "Maths" }), _jsx(Tag, { children: "Year 7" }), _jsx(Tag, { children: "Autumn term" }), _jsx(Tag, { children: "Assessed" }), _jsx(Tag, { children: "SEN" })] })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Too long (4 or more words)" }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)', alignItems: 'center' }, children: [_jsx(Tag, { children: "Currently being assessed" }), _jsx(Tag, { children: "Due for review next week" }), _jsx(Tag, { children: "Permission required from guardian" })] })] })] }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 export const Default = withDescription({
-    args: { children: 'Tag content' },
-}, 'Shows the default neutral Tag with plain text content.');
+    args: {
+        children: 'Year 7',
+        color: 'neutral',
+        selected: false,
+        removeLabel: 'Remove',
+        removeButtonTabIndex: 0,
+    },
+    render: args => _jsx(Tag, { ...args }),
+}, 'The interactive canvas story — every prop is wired to the **Controls** panel below. Use the controls to explore colours, selected state, and the remove button pattern. The `slotStart`, `slotEnd`, and `onRemove` props accept `ReactNode`/function values that cannot be set via controls; see the dedicated stories below for those patterns.');
 export const WithColour = withDescription({
-    args: { children: 'Blue tag', color: 'blue' },
-}, 'Applies one of the semantic colour variants to the Tag.');
+    args: {
+        children: 'Mathematics',
+        color: 'blue',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Tag } from '@arbor-education/design-system.components';
+
+function WithColourExample() {
+  return <Tag color="blue">Mathematics</Tag>;
+}
+export default WithColourExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Applies the `blue` colour variant. Each of the 8 colour options uses a distinct pale wash background from the `--tag-category-{colour}-color-background` token family. Establish a consistent semantic colour mapping in your app — for example `blue` = subject labels, `salmon` = Pupil Premium — and apply it everywhere.');
+export const AllColours = withDescription({
+    render: AllColoursTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Tag } from '@arbor-education/design-system.components';
+
+const colours = ['neutral', 'orange', 'blue', 'green', 'purple', 'teal', 'salmon', 'yellow'] as const;
+const labels: Record<typeof colours[number], string> = {
+  neutral: 'Year 7',
+  orange: 'At risk',
+  blue: 'Maths',
+  green: 'On track',
+  purple: 'SEN',
+  teal: 'EAL',
+  salmon: 'Pupil Premium',
+  yellow: 'Active',
+};
+
+function AllColoursExample() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+      {colours.map(color => (
+        <Tag key={color} color={color}>
+          {labels[color]}
+        </Tag>
+      ))}
+    </div>
+  );
+}
+export default AllColoursExample;
+`.trim(),
+            },
+        },
+    },
+}, 'All 8 colour variants side by side with realistic Arbor content for each colour. Confluence guidance: limit the number of distinct colours visible at once — colour variety hurts scannability. Use `neutral` as the default and reach for colour only when it adds genuine semantic value to the label.');
 export const Selected = withDescription({
-    args: { children: 'Selected tag', color: 'blue', selected: true },
-}, 'Shows the selected treatment, which intentionally prioritises selection styling over the base colour variant.');
+    args: {
+        children: 'Form 7B',
+        color: 'blue',
+        selected: true,
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Tag } from '@arbor-education/design-system.components';
+
+function SelectedExample() {
+  return <Tag color="blue" selected>Form 7B</Tag>;
+}
+export default SelectedExample;
+`.trim(),
+            },
+        },
+    },
+}, 'The `selected` prop overrides `color` — background and border come from `--tag-selected-color-background` and `--tag-selected-color-border`, and text reverts to neutral regardless of the `color` prop. Selection is a higher-priority signal than categorical colour; use it to indicate the currently active tag in a selectable cluster.');
 export const WithDot = withDescription({
     args: {
-        children: 'With dot',
-        slotStart: _jsx(Dot, { colour: "purple" }),
+        children: 'Pupil Premium',
+        slotStart: _jsx(Dot, { colour: "salmon" }),
     },
-}, 'Uses `slotStart` to render a decorative dot before the label.');
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Dot, Tag } from '@arbor-education/design-system.components';
+
+function WithDotExample() {
+  return <Tag slotStart={<Dot colour="salmon" />}>Pupil Premium</Tag>;
+}
+export default WithDotExample;
+`.trim(),
+            },
+        },
+    },
+}, 'The canonical dot-prefix pattern using `slotStart={<Dot colour="salmon" />}`. This replaces the old `dotColour` prop removed in v2. `Dot` renders as a decorative `<span aria-hidden="true">` when no `label` prop is passed — it adds no screen reader noise while providing a strong visual colour signal alongside the text.');
 export const WithIcon = withDescription({
     args: {
         children: 'Alice Johnson',
         slotStart: _jsx(Icon, { name: "user", size: 12 }),
     },
-}, 'Uses `slotStart` to show an icon before the Tag label.');
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Icon, Tag } from '@arbor-education/design-system.components';
+
+function WithIconExample() {
+  return <Tag slotStart={<Icon name="user" size={12} />}>Alice Johnson</Tag>;
+}
+export default WithIconExample;
+`.trim(),
+            },
+        },
+    },
+}, 'An icon prefix via `slotStart`. Size `12` matches the Tag label font size for optical balance. Icons in `slotStart` are presentational — add `screenReaderText` to `Icon` only if the icon conveys information not already present in the Tag label.');
+export const WithSlotEnd = withDescription({
+    args: {
+        children: 'Autumn term',
+        slotEnd: _jsx(Icon, { name: "chevron-down", size: 12 }),
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Icon, Tag } from '@arbor-education/design-system.components';
+
+function WithSlotEndExample() {
+  return <Tag slotEnd={<Icon name="chevron-down" size={12} />}>Autumn term</Tag>;
+}
+export default WithSlotEndExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A trailing slot via `slotEnd`. Common uses: a chevron icon for expandable Tag menus, a count indicator, or a secondary status dot. The slot renders between the label and the remove button (when present), so the remove button is always the last interactive element in the Tab sequence.');
+export const WithBothSlots = withDescription({
+    args: {
+        children: 'Form 7B',
+        slotStart: _jsx(Dot, { colour: "teal" }),
+        slotEnd: _jsx(Icon, { name: "chevron-down", size: 12 }),
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Dot, Icon, Tag } from '@arbor-education/design-system.components';
+
+function WithBothSlotsExample() {
+  return (
+    <Tag
+      slotStart={<Dot colour="teal" />}
+      slotEnd={<Icon name="chevron-down" size={12} />}
+    >
+      Form 7B
+    </Tag>
+  );
+}
+export default WithBothSlotsExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Both `slotStart` and `slotEnd` present simultaneously. The layout order is: `slotStart` | label | `slotEnd` | remove button (if `onRemove` is set). Slots are independently optional — compose freely based on the information density your context requires.');
 export const Removable = withDescription({
     args: {
-        children: 'Removable tag',
+        children: 'Year 7',
         onRemove: fn(),
-        removeLabel: 'Remove removable tag',
+        removeLabel: 'Remove Year 7',
+    },
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Tag } from '@arbor-education/design-system.components';
+
+function RemovableExample() {
+  return <Tag onRemove={() => {}} removeLabel="Remove Year 7">Year 7</Tag>;
+}
+export default RemovableExample;
+`.trim(),
+            },
+        },
     },
-}, 'Demonstrates a removable Tag with the default close affordance and a custom accessible remove label. The remove button is tabbable by default.');
+}, '`onRemove` renders a remove `<button>` with an X icon. **Use only in composite chip contexts** (Combobox selection pills, multi-value inputs) — Confluence spec says standalone Tags in metadata lists are non-interactive. The `removeLabel` prop sets the `aria-label` on the button; always override the default `"Remove"` with something specific like `"Remove Year 7"` so screen reader users know exactly what will be removed.');
 export const RemovableWithIcon = withDescription({
     args: {
         children: 'Alice Johnson',
@@ -63,15 +509,122 @@ export const RemovableWithIcon = withDescription({
         onRemove: fn(),
         removeLabel: 'Remove Alice Johnson',
     },
-}, 'Combines a leading icon with the removable Tag interaction.');
-export const WithSlotEnd = withDescription({
-    args: {
-        children: 'Custom end',
-        slotEnd: _jsx(Icon, { name: "chevron-down", size: 12 }),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Icon, Tag } from '@arbor-education/design-system.components';
+
+function RemovableWithIconExample() {
+  return (
+    <Tag
+      slotStart={<Icon name="user" size={12} />}
+      onRemove={() => {}}
+      removeLabel="Remove Alice Johnson"
+    >
+      Alice Johnson
+    </Tag>
+  );
+}
+export default RemovableWithIconExample;
+`.trim(),
+            },
+        },
     },
-}, 'Uses `slotEnd` to render trailing custom content.');
-const allColours = ['neutral', 'orange', 'blue', 'green', 'purple', 'teal', 'salmon', 'yellow'];
-export const AllColours = withDescription({
-    render: () => (_jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 8 }, children: allColours.map(color => (_jsx(Tag, { color: color, children: color }, color))) })),
-}, 'Displays every available Tag colour variant side by side.');
+}, 'Leading icon combined with a remove button — the chip-style composition pattern. The layout order is: icon slot | label | remove button. This pattern is common in people-picker Combobox components where selected individuals are shown as dismissible chips.');
+export const RemovableInteractive = withDescription({
+    render: RemovableInteractiveTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Tag } from '@arbor-education/design-system.components';
+
+function RemovableTags() {
+  const [tags, setTags] = useState(['Year 7', 'SEN', 'Pupil Premium', 'Active']);
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+      {tags.length === 0 ? (
+        <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>All tags dismissed.</p>
+      ) : (
+        tags.map(tag => (
+          <Tag
+            key={tag}
+            onRemove={() => setTags(prev => prev.filter(t => t !== tag))}
+            removeLabel={\`Remove \${tag}\`}
+          >
+            {tag}
+          </Tag>
+        ))
+      )}
+    </div>
+  );
+}
+export default RemovableTags;
+`.trim(),
+            },
+        },
+    },
+}, 'A live interactive example: click any X button to dismiss that Tag. When all tags are dismissed, a "All tags dismissed." message appears. This demonstrates the stateful chip pattern used inside Combobox and multi-select inputs. Each `removeLabel` is specific to the tag content — never leave it as the default `"Remove"`.');
+export const LongLabelTruncation = withDescription({
+    render: LongLabelTruncationTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Tag } from '@arbor-education/design-system.components';
+
+function LongLabelTruncationExample() {
+  return (
+    <div style={{ maxWidth: '12rem' }}>
+      <Tag>Currently being assessed for additional learning needs</Tag>
+    </div>
+  );
+}
+export default LongLabelTruncationExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Tag labels truncate with ellipsis when the available width is exceeded. This story demonstrates the behaviour in a container constrained to `12rem`. The ellipsis reinforces the Confluence design spec: keep Tag labels to **3 words or fewer**. If you find a label needing truncation, shorten it.');
+export const ContentGuidelines = withDescription({
+    render: ContentGuidelinesTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Tag } from '@arbor-education/design-system.components';
+
+function ContentGuidelinesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', padding: 'var(--spacing-xlarge)' }}>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+        {/* Good — 3 words or fewer (Confluence spec) */}
+        <Tag>Maths</Tag>
+        <Tag>Year 7</Tag>
+        <Tag>Autumn term</Tag>
+        <Tag>Assessed</Tag>
+        <Tag>SEN</Tag>
+      </div>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+        {/* Too long — 4 or more words. Use a tooltip or description instead. */}
+        <Tag>Currently being assessed</Tag>
+        <Tag>Due for review next week</Tag>
+        <Tag>Permission required from guardian</Tag>
+      </div>
+    </div>
+  );
+}
+export default ContentGuidelinesExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A side-by-side comparison of good (3 words or fewer) and too-long (4+ words) labels. The Confluence design spec is clear: Tags must be brief. Labels like "Due for review next week" belong in a tooltip or description, not a Tag. If you need more than 3 words to describe the attribute, reconsider the information architecture.');
 //# sourceMappingURL=Tag.stories.js.map