@arbor-education/design-system.components 0.21.0 → 0.22.0

package/src/components/articleCard/ArticleCard.stories.tsx

@@ -37,7 +37,7 @@ const USAGE_GUIDANCE = [
   '|---|---|',
   '| Displaying a metric or statistic | [`KPICard`](?path=/docs/components-card-kpicard--docs) |',
   '| Full control over interior layout | [`Card`](?path=/docs/components-card--docs) directly |',
-  '| Icon + text without a card shell | [`IcoText`](?path=/docs/components-icotext--docs) |',
+  '| Icon + text without a card shell | [`IconText`](?path=/docs/components-icontext--docs) |',
   '| Selecting from a list (radio/checkbox semantics) | `RadioGroup` or selection list pattern |',
 ].join('\n');
 
@@ -64,7 +64,7 @@ const DEVELOPER_NOTES = [
   '### Accessibility',
   '',
   '- **Linked mode**: the `<a>` wrapping `title` is the accessible link target.',
-  '  If the title text is not self-descriptive, use `aria-label` to override the accessible name.',
+  '  Use self-descriptive link text in `title`, because the outer `aria-label` does not rename the inner link.',
   '- **Shell mode**: `aria-label` or `aria-labelledby` is required when `onClick` is provided.',
   '- **Decorative icons**: omit `iconScreenReaderText` — the icon is `aria-hidden="true"` automatically.',
   '',
@@ -81,7 +81,7 @@ const DEVELOPER_NOTES = [
 const RELATED_COMPONENTS = [
   '## Related components',
   '',
-  '[Card](?path=/docs/components-card--docs) · [KPICard](?path=/docs/components-card-kpicard--docs) · [IcoText](?path=/docs/components-icotext--docs) · [Tag](?path=/docs/components-tag--docs)',
+  '[Card](?path=/docs/components-card--docs) · [KPICard](?path=/docs/components-card-kpicard--docs) · [IconText](?path=/docs/components-icontext--docs) · [Tag](?path=/docs/components-tag--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.';
@@ -137,7 +137,7 @@ const meta = {
     'icon': {
       control: { type: 'select' },
       options: [undefined, 'eye', 'guardians', 'date', 'book-open', 'file', 'settings', 'info', 'triangle-alert'],
-      description: 'Icon displayed in the left rail via `IcoText.Icon`. Omit for icon-free layout.',
+      description: 'Icon displayed in the left rail via `IconText.Icon`. Omit for icon-free layout.',
       table: { type: { summary: 'IconName' } },
     },
     'iconColor': {
@@ -176,8 +176,13 @@ const meta = {
       description: 'Accessible name. Required on interactive shell cards (when `onClick` is provided).',
       table: { type: { summary: 'string' } },
     },
-    'href': {
+    'aria-labelledby': {
       control: 'text',
+      description: 'Alternative accessible name for interactive shell cards when a visible label already exists in the card content.',
+      table: { type: { summary: 'string' } },
+    },
+    'href': {
+      control: false,
       description: 'URL. Mutually exclusive with `onClick`. When provided with `title` + `!disabled`, the title renders as a navigable `<a>`.',
       table: { type: { summary: 'string' } },
     },
@@ -190,7 +195,7 @@ const meta = {
 } satisfies Meta<typeof ArticleCard>;
 
 export default meta;
-type Story = StoryObj<typeof ArticleCard>;
+type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
 // Helper: attach a per-story description to docs
@@ -356,7 +361,7 @@ function FullCompositionExample() {
       iconColor="var(--color-semantic-warning-600)"
       tagText="Pending review"
       tagColor="yellow"
-      onClick={() => console.log('navigate to report')}
+      onClick={() => {}}
       aria-label="Spring term behaviour report"
     />
   );
@@ -375,7 +380,7 @@ export default FullCompositionExample;
           iconColor="var(--color-semantic-warning-600)"
           tagText="Pending review"
           tagColor="yellow"
-          onClick={fn()}
+          onClick={() => {}}
           aria-label="Spring term behaviour report"
         />
       </div>
@@ -440,7 +445,7 @@ import { ArticleCard } from '@arbor-education/design-system.components';
 function InteractiveShellExample() {
   return (
     <ArticleCard
-      onClick={() => console.log('card clicked')}
+      onClick={() => {}}
       aria-label="Year 10 progress report"
       title="Year 10 progress report"
       paragraph="Mid-year review — targets, attainment, and next steps."
@@ -456,7 +461,7 @@ export default InteractiveShellExample;
     render: () => (
       <div style={{ maxWidth: '400px' }}>
         <ArticleCard
-          onClick={fn()}
+          onClick={() => {}}
           aria-label="Year 10 progress report"
           title="Year 10 progress report"
           paragraph="Mid-year review — targets, attainment, and next steps."
@@ -498,7 +503,7 @@ export default DisabledExample;
     render: () => (
       <div style={{ maxWidth: '400px' }}>
         <ArticleCard
-          onClick={fn()}
+          onClick={() => {}}
           aria-label="Summer term report — not yet available"
           title="Summer term report"
           paragraph="This report will be available at the end of term."
@@ -508,7 +513,7 @@ export default DisabledExample;
       </div>
     ),
   },
-  '`disabled=true` dims the card and suppresses all interaction. In interactive shell mode, `onClick` does not fire. The card is removed from the tab order.',
+  '`disabled=true` dims the card and suppresses activation. In interactive shell mode, `onClick` no longer fires, but the card still renders with `role="button"`, `tabIndex={0}`, and `aria-disabled={true}`.',
 );
 
 export const LinkedDisabled: Story = withDescription(

package/src/components/articleCard/ArticleCard.tsx

@@ -1,16 +1,16 @@
 import classNames from 'classnames';
-import type { IcoTextIconProps } from 'Components/icoText/IcoText';
+import type { IconTextIconProps } from 'Components/iconText/IconText';
 import type { TagColor } from 'Components/tag/Tag';
 import { Tag } from 'Components/tag/Tag';
 import type { IconName } from 'Components/icon/allowedIcons';
 import { Card, getCardInteractionProps } from 'Components/card/Card';
-import { IcoText } from 'Components/icoText/IcoText';
+import { IconText } from 'Components/iconText/IconText';
 
 type ArticleCardBaseProps = {
   className?: string;
   paragraph?: React.ReactNode;
   icon?: IconName;
-  iconColor?: IcoTextIconProps['color'];
+  iconColor?: IconTextIconProps['color'];
   disabled?: boolean;
   tagText?: string;
   tagColor?: TagColor;
@@ -62,16 +62,16 @@ export const ArticleCard = (props: ArticleCardProps): React.JSX.Element => {
 
   const content = (
     <article className="ds-article-card">
-      <IcoText>
+      <IconText>
         {icon && (
-          <IcoText.Icon
+          <IconText.Icon
             color={iconColor}
             name={icon}
             screenReaderText={iconScreenReaderText}
           />
         )}
         {title && (
-          <IcoText.Heading>
+          <IconText.Heading>
             {hasPrimaryLink
               ? (
                   <a className="ds-article-card__primary-link" href={href}>
@@ -79,11 +79,11 @@ export const ArticleCard = (props: ArticleCardProps): React.JSX.Element => {
                   </a>
                 )
               : title}
-          </IcoText.Heading>
+          </IconText.Heading>
         )}
-        {paragraph && <IcoText.Paragraph>{paragraph}</IcoText.Paragraph>}
+        {paragraph && <IconText.Paragraph>{paragraph}</IconText.Paragraph>}
         {tagText && <Tag color={tagColor}>{tagText}</Tag>}
-      </IcoText>
+      </IconText>
     </article>
   );
 

package/src/components/{icoText/IcoText.stories.tsx → iconText/IconText.stories.tsx}

@@ -1,21 +1,21 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Controls,
   Heading as DocHeading,
-  Markdown,
   Primary as DocPrimary,
+  Markdown,
   Stories,
   Subtitle,
   Title,
 } from '@storybook/addon-docs/blocks';
-import { IcoText } from './IcoText.js';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { IconText } from './IconText.js';
 
 // ---------------------------------------------------------------------------
 // Docs page content
 // ---------------------------------------------------------------------------
 
 const DESCRIPTION_INTRO = [
-  '`IcoText` is a compound layout component that pairs an icon in a left rail with a heading and/or paragraph.',
+  '`IconText` is a compound layout component that pairs an icon in a left rail with a heading and/or paragraph.',
   'It is the canonical icon-plus-text primitive in this design system — used internally by `ArticleCard`',
   'and available for direct use in any context that needs an icon anchoring labelled content.',
 ].join(' ');
@@ -60,26 +60,26 @@ const USAGE_GUIDANCE = [
   '| Content inside a navigable card | [`ArticleCard`](?path=/docs/components-card-articlecard--docs) |',
   '| Icon with no text | [`Icon`](?path=/docs/components-icon--docs) directly |',
   '| Long-form prose | Semantic HTML `<p>` with a separate heading |',
-  '| Interactive element | Wrap `IcoText` inside a `Card` or `Button` — never add `onClick` to `IcoText` itself |',
+  '| Interactive element | Wrap `IconText` inside a `Card` or `Button` — never add `onClick` to `IconText` itself |',
 ].join('\n');
 
 const DEVELOPER_NOTES = [
   '### Critical usage patterns',
   '',
-  '**`IcoText.Icon` is automatically hoisted to the left rail** regardless of position in JSX.',
-  'The root inspects `children`, pulls out any `IcoText.Icon` elements into a flex-shrink-0 left column,',
+  '**`IconText.Icon` is automatically hoisted to the left rail** regardless of position in JSX.',
+  'The root inspects `children`, pulls out any `IconText.Icon` elements into a flex-shrink-0 left column,',
   'and places all other children (Heading, Paragraph) in the content column.',
   '',
   '```tsx',
-  '<IcoText>',
-  '  <IcoText.Icon name="guardians" />',
-  '  <IcoText.Heading>Year 9 Attendance</IcoText.Heading>',
-  '  <IcoText.Paragraph>28 pupils · 94.2% this term</IcoText.Paragraph>',
-  '</IcoText>',
+  '<IconText>',
+  '  <IconText.Icon name="guardians" />',
+  '  <IconText.Heading>Year 9 Attendance</IconText.Heading>',
+  '  <IconText.Paragraph>28 pupils · 94.2% this term</IconText.Paragraph>',
+  '</IconText>',
   '```',
   '',
-  '**`IcoText.Heading` always renders as `<h4>`.** There is no `level` prop. Verify your document',
-  'heading hierarchy is correct before using `IcoText` as a standalone heading.',
+  '**`IconText.Heading` always renders as `<h4>`.** There is no `level` prop. Verify your document',
+  'heading hierarchy is correct before using `IconText` as a standalone heading.',
   '',
   '**Omit `screenReaderText` for decorative icons.** The icon is rendered with `aria-hidden="true"`',
   'when `screenReaderText` is absent. The heading or surrounding text should carry the accessible meaning.',
@@ -90,16 +90,16 @@ const DEVELOPER_NOTES = [
   '',
   '- Decorative icons (no `screenReaderText`): `aria-hidden="true"` — screen readers skip them',
   '- Meaningful icons: provide `screenReaderText` so the icon has an accessible label',
-  '- `IcoText.Heading` renders `<h4>` — verify your document heading hierarchy',
-  '- `IcoText.Paragraph` renders `<p>` — semantically appropriate for supporting text',
+  '- `IconText.Heading` renders `<h4>` — verify your document heading hierarchy',
+  '- `IconText.Paragraph` renders `<p>` — semantically appropriate for supporting text',
   '',
   '---',
   '',
   '### TypeScript types',
   '',
   '```ts',
-  "import { IcoText } from '@arbor-education/design-system.components';",
-  "import type { IcoTextProps, IcoTextIconProps, IcoTextHeadingProps, IcoTextParagraphProps } from '@arbor-education/design-system.components';",
+  "import { IconText } from '@arbor-education/design-system.components';",
+  "import type { IconTextProps, IconTextIconProps, IconTextHeadingProps, IconTextParagraphProps } from '@arbor-education/design-system.components';",
   '```',
 ].join('\n');
 
@@ -115,7 +115,7 @@ const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tw
 // Custom DocsPage
 // ---------------------------------------------------------------------------
 
-function IcoTextDocsPage() {
+function IconTextDocsPage() {
   return (
     <>
       <Title />
@@ -125,11 +125,11 @@ function IcoTextDocsPage() {
       <Markdown>{PROPS_INTRO}</Markdown>
       <DocPrimary />
       <Controls />
-      <DocHeading>IcoText.Icon props</DocHeading>
+      <DocHeading>IconText.Icon props</DocHeading>
       <Markdown>{ICON_PROPS}</Markdown>
-      <DocHeading>IcoText.Heading props</DocHeading>
+      <DocHeading>IconText.Heading props</DocHeading>
       <Markdown>{HEADING_PROPS}</Markdown>
-      <DocHeading>IcoText.Paragraph props</DocHeading>
+      <DocHeading>IconText.Paragraph props</DocHeading>
       <Markdown>{PARAGRAPH_PROPS}</Markdown>
       <DocHeading>Usage guidance</DocHeading>
       <Markdown>{USAGE_GUIDANCE}</Markdown>
@@ -147,12 +147,12 @@ function IcoTextDocsPage() {
 // ---------------------------------------------------------------------------
 
 const meta = {
-  title: 'Components/IcoText',
-  component: IcoText,
+  title: 'Components/IconText',
+  component: IconText,
   tags: ['autodocs'],
   parameters: {
     layout: 'padded',
-    docs: { page: IcoTextDocsPage },
+    docs: { page: IconTextDocsPage },
   },
   argTypes: {
     className: {
@@ -162,14 +162,14 @@ const meta = {
     },
     children: {
       control: false,
-      description: 'Compose using `IcoText.Icon`, `IcoText.Heading`, and `IcoText.Paragraph` sub-components.',
+      description: 'Compose using `IconText.Icon`, `IconText.Heading`, and `IconText.Paragraph` sub-components.',
       table: { type: { summary: 'ReactNode' } },
     },
   },
-} satisfies Meta<typeof IcoText>;
+} satisfies Meta<typeof IconText>;
 
 export default meta;
-type Story = StoryObj<typeof IcoText>;
+type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
 // Helper: attach a per-story description to docs
@@ -194,11 +194,11 @@ const IconSizesTemplate = () => (
         <p className="ds-text" style={{ margin: '0 0 var(--spacing-small)', color: 'var(--color-grey-600)' }}>
           {`size={${size}}`}
         </p>
-        <IcoText>
-          <IcoText.Icon name="guardians" size={size} />
-          <IcoText.Heading>Year 9 Attendance</IcoText.Heading>
-          <IcoText.Paragraph>28 pupils · 94.2% average this term</IcoText.Paragraph>
-        </IcoText>
+        <IconText>
+          <IconText.Icon name="guardians" size={size} />
+          <IconText.Heading>Year 9 Attendance</IconText.Heading>
+          <IconText.Paragraph>28 pupils · 94.2% average this term</IconText.Paragraph>
+        </IconText>
       </div>
     ))}
   </div>
@@ -216,23 +216,23 @@ const IconColorsTemplate = () => (
         <p className="ds-text" style={{ margin: '0 0 var(--spacing-small)', color: 'var(--color-grey-600)' }}>
           {label}
         </p>
-        <IcoText>
-          <IcoText.Icon name="triangle-alert" color={color} />
-          <IcoText.Heading>Attendance alert</IcoText.Heading>
-          <IcoText.Paragraph>3 pupils below 90% this half-term</IcoText.Paragraph>
-        </IcoText>
+        <IconText>
+          <IconText.Icon name="triangle-alert" color={color} />
+          <IconText.Heading>Attendance alert</IconText.Heading>
+          <IconText.Paragraph>3 pupils below 90% this half-term</IconText.Paragraph>
+        </IconText>
       </div>
     ))}
   </div>
 );
 
 const MultipleParagraphsTemplate = () => (
-  <IcoText>
-    <IcoText.Icon name="date" />
-    <IcoText.Heading>Parents&apos; evening — Tuesday 14 May</IcoText.Heading>
-    <IcoText.Paragraph>4:00 pm – 7:00 pm · Main Hall</IcoText.Paragraph>
-    <IcoText.Paragraph>Appointments available every 10 minutes. Please arrive 5 minutes early.</IcoText.Paragraph>
-  </IcoText>
+  <IconText>
+    <IconText.Icon name="date" />
+    <IconText.Heading>Parents&apos; evening — Tuesday 14 May</IconText.Heading>
+    <IconText.Paragraph>4:00 pm – 7:00 pm · Main Hall</IconText.Paragraph>
+    <IconText.Paragraph>Appointments available every 10 minutes. Please arrive 5 minutes early.</IconText.Paragraph>
+  </IconText>
 );
 
 // ---------------------------------------------------------------------------
@@ -242,14 +242,14 @@ const MultipleParagraphsTemplate = () => (
 export const Default: Story = withDescription(
   {
     render: () => (
-      <IcoText>
-        <IcoText.Icon name="guardians" />
-        <IcoText.Heading>Year 9 Attendance</IcoText.Heading>
-        <IcoText.Paragraph>28 pupils · 94.2% average this term</IcoText.Paragraph>
-      </IcoText>
+      <IconText>
+        <IconText.Icon name="guardians" />
+        <IconText.Heading>Year 9 Attendance</IconText.Heading>
+        <IconText.Paragraph>28 pupils · 94.2% average this term</IconText.Paragraph>
+      </IconText>
     ),
   },
-  'The full canonical composition — `IcoText.Icon` in the left rail, `IcoText.Heading` and `IcoText.Paragraph` in the content column.',
+  'The full canonical composition — `IconText.Icon` in the left rail, `IconText.Heading` and `IconText.Paragraph` in the content column.',
 );
 
 export const HeadingOnly: Story = withDescription(
@@ -260,14 +260,14 @@ export const HeadingOnly: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { IcoText } from '@arbor-education/design-system.components';
+import { IconText } from '@arbor-education/design-system.components';
 
 function HeadingOnlyExample() {
   return (
-    <IcoText>
-      <IcoText.Icon name="book-open" />
-      <IcoText.Heading>Assessment policy</IcoText.Heading>
-    </IcoText>
+    <IconText>
+      <IconText.Icon name="book-open" />
+      <IconText.Heading>Assessment policy</IconText.Heading>
+    </IconText>
   );
 }
 export default HeadingOnlyExample;
@@ -276,10 +276,10 @@ export default HeadingOnlyExample;
       },
     },
     render: () => (
-      <IcoText>
-        <IcoText.Icon name="book-open" />
-        <IcoText.Heading>Assessment policy</IcoText.Heading>
-      </IcoText>
+      <IconText>
+        <IconText.Icon name="book-open" />
+        <IconText.Heading>Assessment policy</IconText.Heading>
+      </IconText>
     ),
   },
   'Icon + Heading with no Paragraph — the compact pattern for short navigational labels.',
@@ -293,14 +293,14 @@ export const WithoutIcon: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { IcoText } from '@arbor-education/design-system.components';
+import { IconText } from '@arbor-education/design-system.components';
 
 function WithoutIconExample() {
   return (
-    <IcoText>
-      <IcoText.Heading>Behaviour report</IcoText.Heading>
-      <IcoText.Paragraph>No incidents recorded this week. All targets met.</IcoText.Paragraph>
-    </IcoText>
+    <IconText>
+      <IconText.Heading>Behaviour report</IconText.Heading>
+      <IconText.Paragraph>No incidents recorded this week. All targets met.</IconText.Paragraph>
+    </IconText>
   );
 }
 export default WithoutIconExample;
@@ -309,13 +309,13 @@ export default WithoutIconExample;
       },
     },
     render: () => (
-      <IcoText>
-        <IcoText.Heading>Behaviour report</IcoText.Heading>
-        <IcoText.Paragraph>No incidents recorded this week. All targets met.</IcoText.Paragraph>
-      </IcoText>
+      <IconText>
+        <IconText.Heading>Behaviour report</IconText.Heading>
+        <IconText.Paragraph>No incidents recorded this week. All targets met.</IconText.Paragraph>
+      </IconText>
     ),
   },
-  'Heading + Paragraph with no icon. The left rail disappears cleanly — `IcoText.Icon` is entirely optional.',
+  'Heading + Paragraph with no icon. The left rail disappears cleanly — `IconText.Icon` is entirely optional.',
 );
 
 export const IconWithScreenReaderText: Story = withDescription(
@@ -326,19 +326,19 @@ export const IconWithScreenReaderText: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { IcoText } from '@arbor-education/design-system.components';
+import { IconText } from '@arbor-education/design-system.components';
 
 function IconWithScreenReaderTextExample() {
   return (
-    <IcoText>
-      <IcoText.Icon
+    <IconText>
+      <IconText.Icon
         name="triangle-alert"
         color="var(--color-semantic-warning-600)"
         screenReaderText="Warning"
       />
-      <IcoText.Heading>Attendance below target</IcoText.Heading>
-      <IcoText.Paragraph>Alice Johnson — 78.4% this term. Intervention recommended.</IcoText.Paragraph>
-    </IcoText>
+      <IconText.Heading>Attendance below target</IconText.Heading>
+      <IconText.Paragraph>Alice Johnson — 78.4% this term. Intervention recommended.</IconText.Paragraph>
+    </IconText>
   );
 }
 export default IconWithScreenReaderTextExample;
@@ -347,11 +347,11 @@ export default IconWithScreenReaderTextExample;
       },
     },
     render: () => (
-      <IcoText>
-        <IcoText.Icon name="triangle-alert" color="var(--color-semantic-warning-600)" screenReaderText="Warning" />
-        <IcoText.Heading>Attendance below target</IcoText.Heading>
-        <IcoText.Paragraph>Alice Johnson — 78.4% this term. Intervention recommended.</IcoText.Paragraph>
-      </IcoText>
+      <IconText>
+        <IconText.Icon name="triangle-alert" color="var(--color-semantic-warning-600)" screenReaderText="Warning" />
+        <IconText.Heading>Attendance below target</IconText.Heading>
+        <IconText.Paragraph>Alice Johnson — 78.4% this term. Intervention recommended.</IconText.Paragraph>
+      </IconText>
     ),
   },
   'When the icon carries meaning not conveyed by the heading text, provide `screenReaderText`. Without it the icon is `aria-hidden="true"`. Here the warning triangle conveys severity — screen readers announce "Warning, Attendance below target".',
@@ -365,26 +365,26 @@ export const IconSizes: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { IcoText } from '@arbor-education/design-system.components';
+import { IconText } from '@arbor-education/design-system.components';
 
 function IconSizesExample() {
   return (
     <>
-      <IcoText>
-        <IcoText.Icon name="guardians" size={12} />
-        <IcoText.Heading>size 12</IcoText.Heading>
-        <IcoText.Paragraph>Use in very compact contexts</IcoText.Paragraph>
-      </IcoText>
-      <IcoText>
-        <IcoText.Icon name="guardians" size={16} />
-        <IcoText.Heading>size 16</IcoText.Heading>
-        <IcoText.Paragraph>Use in moderately compact contexts</IcoText.Paragraph>
-      </IcoText>
-      <IcoText>
-        <IcoText.Icon name="guardians" size={24} />
-        <IcoText.Heading>size 24 (default)</IcoText.Heading>
-        <IcoText.Paragraph>Standard — aligns best with h4 line-height</IcoText.Paragraph>
-      </IcoText>
+      <IconText>
+        <IconText.Icon name="guardians" size={12} />
+        <IconText.Heading>size 12</IconText.Heading>
+        <IconText.Paragraph>Use in very compact contexts</IconText.Paragraph>
+      </IconText>
+      <IconText>
+        <IconText.Icon name="guardians" size={16} />
+        <IconText.Heading>size 16</IconText.Heading>
+        <IconText.Paragraph>Use in moderately compact contexts</IconText.Paragraph>
+      </IconText>
+      <IconText>
+        <IconText.Icon name="guardians" size={24} />
+        <IconText.Heading>size 24 (default)</IconText.Heading>
+        <IconText.Paragraph>Standard — aligns best with h4 line-height</IconText.Paragraph>
+      </IconText>
     </>
   );
 }
@@ -395,7 +395,7 @@ export default IconSizesExample;
     },
     render: IconSizesTemplate,
   },
-  'All three supported icon sizes — 12, 16, and 24 (default). Use smaller sizes only in compact contexts such as table cells or dense lists. The `24` default aligns best with `IcoText.Heading`\'s h4 line-height.',
+  'All three supported icon sizes — 12, 16, and 24 (default). Use smaller sizes only in compact contexts such as table cells or dense lists. The `24` default aligns best with `IconText.Heading`\'s h4 line-height.',
 );
 
 export const IconColors: Story = withDescription(
@@ -406,15 +406,15 @@ export const IconColors: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { IcoText } from '@arbor-education/design-system.components';
+import { IconText } from '@arbor-education/design-system.components';
 
 function IconColorsExample() {
   return (
-    <IcoText>
-      <IcoText.Icon name="triangle-alert" color="var(--color-semantic-warning-600)" />
-      <IcoText.Heading>Attendance alert</IcoText.Heading>
-      <IcoText.Paragraph>3 pupils below 90% this half-term</IcoText.Paragraph>
-    </IcoText>
+    <IconText>
+      <IconText.Icon name="triangle-alert" color="var(--color-semantic-warning-600)" />
+      <IconText.Heading>Attendance alert</IconText.Heading>
+      <IconText.Paragraph>3 pupils below 90% this half-term</IconText.Paragraph>
+    </IconText>
   );
 }
 export default IconColorsExample;
@@ -424,7 +424,7 @@ export default IconColorsExample;
     },
     render: IconColorsTemplate,
   },
-  'The `color` prop on `IcoText.Icon` accepts any CSS value — always use design token variables, never hardcoded hex. Semantic tokens (`--color-semantic-*`) are most appropriate for status-indicating icons.',
+  'The `color` prop on `IconText.Icon` accepts any CSS value — always use design token variables, never hardcoded hex. Semantic tokens (`--color-semantic-*`) are most appropriate for status-indicating icons.',
 );
 
 export const MultipleParagraphs: Story = withDescription(
@@ -435,16 +435,16 @@ export const MultipleParagraphs: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { IcoText } from '@arbor-education/design-system.components';
+import { IconText } from '@arbor-education/design-system.components';
 
 function MultipleParagraphsExample() {
   return (
-    <IcoText>
-      <IcoText.Icon name="calendar" />
-      <IcoText.Heading>Parents' evening — Tuesday 14 May</IcoText.Heading>
-      <IcoText.Paragraph>4:00 pm – 7:00 pm · Main Hall</IcoText.Paragraph>
-      <IcoText.Paragraph>Appointments every 10 minutes. Please arrive 5 minutes early.</IcoText.Paragraph>
-    </IcoText>
+    <IconText>
+      <IconText.Icon name="date" />
+      <IconText.Heading>Parents' evening — Tuesday 14 May</IconText.Heading>
+      <IconText.Paragraph>4:00 pm – 7:00 pm · Main Hall</IconText.Paragraph>
+      <IconText.Paragraph>Appointments every 10 minutes. Please arrive 5 minutes early.</IconText.Paragraph>
+    </IconText>
   );
 }
 export default MultipleParagraphsExample;
@@ -454,5 +454,5 @@ export default MultipleParagraphsExample;
     },
     render: MultipleParagraphsTemplate,
   },
-  'Multiple `IcoText.Paragraph` sub-components stack vertically in the content column. Use for supplementary detail lines below the primary heading.',
+  'Multiple `IconText.Paragraph` sub-components stack vertically in the content column. Use for supplementary detail lines below the primary heading.',
 );

package/src/components/{icoText/IcoText.test.tsx → iconText/IconText.test.tsx}

@@ -1,25 +1,25 @@
-import { render, screen, within } from '@testing-library/react';
 import '@testing-library/jest-dom/vitest';
+import { render, screen, within } from '@testing-library/react';
 import { describe, expect, test } from 'vitest';
-import { IcoText } from './IcoText.js';
+import { IconText } from './IconText.js';
 
-describe('IcoText', () => {
+describe('IconText', () => {
   test('renders icon children before content children and keeps content in the content wrapper', () => {
     const { container } = render(
-      <IcoText>
-        <IcoText.Heading>Article title</IcoText.Heading>
-        <IcoText.Icon name="eye" screenReaderText="Views" />
-        <IcoText.Paragraph>Helpful supporting copy</IcoText.Paragraph>
+      <IconText>
+        <IconText.Heading>Article title</IconText.Heading>
+        <IconText.Icon name="eye" screenReaderText="Views" />
+        <IconText.Paragraph>Helpful supporting copy</IconText.Paragraph>
         <span>Metadata</span>
-        <IcoText.Icon name="eye" screenReaderText="More views" />
-      </IcoText>,
+        <IconText.Icon name="eye" screenReaderText="More views" />
+      </IconText>,
     );
 
     const root = container.querySelector<HTMLDivElement>('.ds-ico-text');
     const content = container.querySelector<HTMLDivElement>('.ds-ico-text__content');
 
     if (!content) {
-      throw new Error('Expected IcoText content wrapper to exist');
+      throw new Error('Expected IconText content wrapper to exist');
     }
 
     const iconElements = Array.from(root?.querySelectorAll(':scope > .ds-ico-text__icon') ?? []);