@arbor-education/design-system.components 3.1.0 → 3.2.0

package/src/components/icon/Icon.stories.tsx

@@ -1,3 +1,4 @@
+import { useMemo, useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Controls,
@@ -10,7 +11,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { Button } from 'Components/button/Button';
 import { Icon } from './Icon.js';
-import { allowedIcons } from './allowedIcons.js';
+import { iconNames, type IconName } from './allowedIcons.js';
 import { iconSizes } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -189,7 +190,7 @@ const DEVELOPER_NOTES = [
   '- **Status icons** — must be paired with visible text where possible (WCAG 1.4.1: use of colour).',
   '  Do not rely on icon colour alone to communicate success, warning, or error.',
   '- **Icon-only interactions** — must have accessible label + tooltip on hover/focus.',
-  '- **Avoid `title` attributes** — Lucide SVGs sometimes include `<title>` elements; Arbor\'s `allowedIcons`',
+  '- **Avoid `title` attributes** — Lucide SVGs sometimes include `<title>` elements; Arbor\'s `Icon`',
   '  wrapper suppresses these via `aria-hidden`. Do not rely on SVG `title` for accessible names.',
   '- **"Opens in new tab"** — communicate this in text (`<span class="sr-only">opens in new tab</span>`),',
   '  not only via the `external-link` icon.',
@@ -207,7 +208,7 @@ const DEVELOPER_NOTES = [
   '| Type | Description |',
   '|---|---|',
   '| `Icon.Props` | Full props interface |',
-  '| `Icon.Name` | Union of all icon name strings — see argTypes for full list |',
+  '| `Icon.Name` | Union of every valid name: the whole Lucide set, plus Arbor aliases and custom icons |',
   '| `Icon.Size` | `12 \\| 16 \\| 24` |',
   '| `Icon.CustomProps` | Props for custom SVG icons |',
 ].join('\n');
@@ -218,6 +219,11 @@ const RELATED_COMPONENTS = [
   '[Button](?path=/docs/components-button--docs) · [Banner](?path=/docs/components-banner--docs) · [Badge](?path=/docs/components-badge--docs) · [Dot](?path=/docs/components-dot--docs) · [Tag](?path=/docs/components-tag--docs)',
 ].join('\n');
 
+const CATALOGUE_INTRO = [
+  'The Arbor-curated names are grouped below. Every [Lucide](https://lucide.dev/icons) icon name is',
+  'also valid — use the **Icon search** story above to find one by name.',
+].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 IconDocsPage() {
@@ -237,12 +243,101 @@ function IconDocsPage() {
       <DocHeading>Examples</DocHeading>
       <Stories title="" />
       <DocHeading>Icon catalogue</DocHeading>
+      <Markdown>{CATALOGUE_INTRO}</Markdown>
       <IconGalleryTemplate />
       <Markdown>{RELATED_COMPONENTS}</Markdown>
     </>
   );
 }
 
+type IconCategory = {
+  heading: string;
+  icons: IconName[];
+};
+
+const ICON_CATEGORIES: IconCategory[] = [
+  {
+    heading: 'Navigation',
+    icons: [
+      'arrow-up', 'arrow-down', 'arrow-left', 'arrow-right',
+      'arrow-right-from-line', 'arrow-up-right',
+      'chevron-up', 'chevron-down', 'chevron-left', 'chevron-right',
+      'chevrons-left', 'chevrons-right',
+      'corner-down-left', 'menu',
+      'ellipsis', 'ellipsis-vertical', '3-dot', 'grab',
+    ],
+  },
+  {
+    heading: 'Actions',
+    icons: [
+      'pencil', 'trash', 'save', 'copy', 'download', 'upload',
+      'share', 'send', 'redo', 'undo', 'plus', 'minus',
+      'circle-plus', 'iteration-ccw', 'switch-camera',
+    ],
+  },
+  {
+    heading: 'Status / severity',
+    icons: [
+      'info', 'circle-alert', 'triangle-alert',
+      'circle-check', 'circle-check-big', 'circle-x',
+      'circle-help', 'check', 'check-solid', 'x', 'x-solid',
+    ],
+  },
+  {
+    heading: 'Content / media',
+    icons: [
+      'file', 'files', 'clipboard', 'clipboard-list',
+      'book-open', 'camera', 'mic', 'paperclip',
+      'sheet', 'table',
+      'sparkles', 'party-popper', 'lightbulb',
+      'favourite-outline', 'favourite-filled',
+    ],
+  },
+  {
+    heading: 'Charts / data',
+    icons: [
+      'chart-column-increasing', 'chart-spline',
+      'trending-up', 'trending-down',
+      'percent', 'circle-percent',
+      'sorting', 'funnel', 'sliders-horizontal', 'list-filter-plus',
+    ],
+  },
+  {
+    heading: 'People / org',
+    icons: [
+      'user', 'guardians', 'group', 'staff', 'graduation-cap',
+    ],
+  },
+  {
+    heading: 'System / state',
+    icons: [
+      'eye', 'eye-off', 'lock', 'lock-open', 'loader',
+      'pin', 'flag', 'house', 'history', 'clock-3', 'date',
+      'settings', 'expand', 'shrink', 'link', 'external-link',
+      'log-out', 'search', 'mail', 'phone', 'smartphone',
+      'monitor', 'projector', 'archive',
+    ],
+  },
+  {
+    heading: 'Other / misc',
+    icons: [
+      'dot', 'layout-list', 'list', 'grid-3x3',
+      'paint-bucket', 'message-square-more',
+    ],
+  },
+  {
+    heading: 'Custom / brand',
+    icons: ['ask-arbor', 'google'],
+  },
+];
+
+/**
+ * The Arbor-curated names, used for the Controls select. The `name` prop accepts every Lucide icon
+ * too, but ~1,900 options in a dropdown is not a usable control — use the Icon search story to
+ * explore the full set.
+ */
+const CURATED_ICON_NAMES: IconName[] = ICON_CATEGORIES.flatMap(category => category.icons);
+
 // ---------------------------------------------------------------------------
 // Meta
 // ---------------------------------------------------------------------------
@@ -260,12 +355,12 @@ const meta = {
   argTypes: {
     name: {
       control: 'select',
-      options: Object.keys(allowedIcons),
+      options: CURATED_ICON_NAMES,
       description: [
         'Kebab-case key identifying the icon to render. Required.',
-        'Maps to an entry in `allowedIcons` — TypeScript errors on any unknown value.',
-        'There are currently 106 valid options covering navigation, actions, status,',
-        'content, data, people, and system contexts.',
+        'Every [Lucide](https://lucide.dev) icon name is valid, plus Arbor\'s own aliases and custom',
+        'icons — TypeScript errors on any unknown value. The dropdown below lists the Arbor-curated',
+        'names only; use the **Icon search** story to browse the full set.',
         'Commonly used: `pencil` (edit), `trash` (delete), `plus` (add), `x` (close/remove),',
         '`check` (confirm), `3-dot` (more actions), `chevron-down` (expand), `triangle-alert` (warning).',
       ].join(' '),
@@ -739,86 +834,39 @@ const CustomSolidVariantsTemplate = () => (
 // IconGallery — all icons grouped by semantic category
 // ---------------------------------------------------------------------------
 
-type IconCategory = {
-  heading: string;
-  icons: Array<keyof typeof allowedIcons>;
-};
+const ICON_CARD_GRID_STYLE = {
+  display: 'grid',
+  gridTemplateColumns: 'repeat(auto-fill, minmax(7rem, 1fr))',
+  gap: 'var(--spacing-small)',
+} as const;
 
-const ICON_CATEGORIES: IconCategory[] = [
-  {
-    heading: 'Navigation',
-    icons: [
-      'arrow-up', 'arrow-down', 'arrow-left', 'arrow-right',
-      'arrow-right-from-line', 'arrow-up-right',
-      'chevron-up', 'chevron-down', 'chevron-left', 'chevron-right',
-      'chevrons-left', 'chevrons-right',
-      'corner-down-left', 'menu',
-      'ellipsis', 'ellipsis-vertical', '3-dot', 'grab',
-    ],
-  },
-  {
-    heading: 'Actions',
-    icons: [
-      'pencil', 'trash', 'save', 'copy', 'download', 'upload',
-      'share', 'send', 'redo', 'undo', 'plus', 'minus',
-      'circle-plus', 'iteration-ccw', 'switch-camera',
-    ],
-  },
-  {
-    heading: 'Status / severity',
-    icons: [
-      'info', 'circle-alert', 'triangle-alert',
-      'circle-check', 'circle-check-big', 'circle-x',
-      'circle-help', 'check', 'check-solid', 'x', 'x-solid',
-    ],
-  },
-  {
-    heading: 'Content / media',
-    icons: [
-      'file', 'files', 'clipboard', 'clipboard-list',
-      'book-open', 'camera', 'mic', 'paperclip',
-      'sheet', 'table',
-      'sparkles', 'party-popper', 'lightbulb',
-      'favourite-outline', 'favourite-filled',
-    ],
-  },
-  {
-    heading: 'Charts / data',
-    icons: [
-      'chart-column-increasing', 'chart-spline',
-      'trending-up', 'trending-down',
-      'percent', 'circle-percent',
-      'sorting', 'funnel', 'sliders-horizontal', 'list-filter-plus',
-    ],
-  },
-  {
-    heading: 'People / org',
-    icons: [
-      'user', 'guardians', 'group', 'staff', 'graduation-cap',
-    ],
-  },
-  {
-    heading: 'System / state',
-    icons: [
-      'eye', 'eye-off', 'lock', 'lock-open', 'loader',
-      'pin', 'flag', 'house', 'history', 'clock-3', 'date',
-      'settings', 'expand', 'shrink', 'link', 'external-link',
-      'log-out', 'search', 'mail', 'phone', 'smartphone',
-      'monitor', 'projector', 'archive',
-    ],
-  },
-  {
-    heading: 'Other / misc',
-    icons: [
-      'dot', 'layout-list', 'list', 'grid-3x3',
-      'paint-bucket', 'message-square-more',
-    ],
-  },
-  {
-    heading: 'Custom / brand',
-    icons: ['ask-arbor', 'google'],
-  },
-];
+const IconCard = ({ name }: { name: IconName }) => (
+  <div
+    style={{
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      gap: 'var(--spacing-xsmall)',
+      padding: 'var(--spacing-medium)',
+      borderRadius: 'var(--border-radius-small)',
+      border: '1px solid var(--color-grey-200)',
+      background: 'var(--color-grey-100)',
+    }}
+  >
+    <Icon name={name} size={16} />
+    <span
+      className="ds-text"
+      style={{
+        color: 'var(--color-grey-600)',
+        wordBreak: 'break-word',
+        textAlign: 'center',
+        fontSize: 'var(--font-size-1-11)',
+      }}
+    >
+      {name}
+    </span>
+  </div>
+);
 
 const IconGalleryTemplate = () => (
   <div
@@ -843,40 +891,9 @@ const IconGalleryTemplate = () => (
         >
           {category.heading}
         </p>
-        <div
-          style={{
-            display: 'grid',
-            gridTemplateColumns: 'repeat(auto-fill, minmax(7rem, 1fr))',
-            gap: 'var(--spacing-small)',
-          }}
-        >
+        <div style={ICON_CARD_GRID_STYLE}>
           {category.icons.map(name => (
-            <div
-              key={name}
-              style={{
-                display: 'flex',
-                flexDirection: 'column',
-                alignItems: 'center',
-                gap: 'var(--spacing-xsmall)',
-                padding: 'var(--spacing-medium)',
-                borderRadius: 'var(--border-radius-small)',
-                border: '1px solid var(--color-grey-200)',
-                background: 'var(--color-grey-100)',
-              }}
-            >
-              <Icon name={name} size={16} />
-              <span
-                className="ds-text"
-                style={{
-                  color: 'var(--color-grey-600)',
-                  wordBreak: 'break-word',
-                  textAlign: 'center',
-                  fontSize: 'var(--font-size-1-11)',
-                }}
-              >
-                {name}
-              </span>
-            </div>
+            <IconCard key={name} name={name} />
           ))}
         </div>
       </div>
@@ -884,6 +901,83 @@ const IconGalleryTemplate = () => (
   </div>
 );
 
+// ---------------------------------------------------------------------------
+// IconSearch — search the whole Lucide set without rendering ~1,900 SVGs at once
+// ---------------------------------------------------------------------------
+
+const SEARCH_RESULT_LIMIT = 120;
+
+const IconSearchTemplate = () => {
+  const [query, setQuery] = useState('');
+  const searchTerm = query.trim().toLowerCase();
+  const matches = useMemo(
+    () => (searchTerm
+      ? iconNames.filter(name => name.includes(searchTerm))
+      : CURATED_ICON_NAMES),
+    [searchTerm],
+  );
+  const visible = matches.slice(0, SEARCH_RESULT_LIMIT);
+
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', width: '100%', maxWidth: '900px' }}>
+      <label
+        className="ds-text"
+        htmlFor="ds-icon-search"
+        style={{
+          display: 'block',
+          marginBottom: 'var(--spacing-xsmall)',
+          fontWeight: 'var(--font-weight-semi-bold)',
+        }}
+      >
+        Search
+        {' '}
+        {iconNames.length}
+        {' '}
+        icon names
+      </label>
+      <input
+        id="ds-icon-search"
+        type="search"
+        value={query}
+        onChange={event => setQuery(event.target.value)}
+        placeholder="e.g. calendar, arrow, user"
+        style={{
+          width: '100%',
+          padding: 'var(--spacing-small)',
+          marginBottom: 'var(--spacing-small)',
+          borderRadius: 'var(--border-radius-small)',
+          border: '1px solid var(--color-grey-300)',
+        }}
+      />
+      <p
+        className="ds-text"
+        style={{ margin: '0 0 var(--spacing-large) 0', color: 'var(--color-grey-600)' }}
+      >
+        {searchTerm
+          ? `${matches.length} match${matches.length === 1 ? '' : 'es'}${
+            matches.length > visible.length ? ` — showing the first ${visible.length}` : ''
+          }`
+          : `Showing the ${visible.length} Arbor-curated names — type to search the full set.`}
+      </p>
+      <div style={ICON_CARD_GRID_STYLE}>
+        {visible.map(name => (
+          <IconCard key={name} name={name} />
+        ))}
+      </div>
+      {searchTerm && matches.length === 0 && (
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+          No icon name contains &ldquo;
+          {searchTerm}
+          &rdquo;. Browse the full set at
+          {' '}
+          <a href="https://lucide.dev/icons" target="_blank" rel="noreferrer">lucide.dev/icons</a>
+          .
+        </p>
+      )}
+    </div>
+  );
+};
+
 const InButtonContextTemplate = () => (
   <div
     style={{
@@ -1461,3 +1555,14 @@ export default InEmptyStateContextExample;
     'full-area statements like this one.',
   ].join(' '),
 );
+
+export const IconSearch: Story = withDescription(
+  {
+    render: () => <IconSearchTemplate />,
+    parameters: { layout: 'fullscreen' },
+  },
+  [
+    'Every Lucide icon name is a valid `name`, which is far too many to render at once — search',
+    'instead. Icons load on demand, so only the ones you actually render are downloaded.',
+  ].join(' '),
+);

package/src/components/icon/Icon.test.tsx

@@ -1,14 +1,186 @@
-import { describe, expect, test } from 'vitest';
-import { render, screen } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
 import { Icon } from './Icon.js';
 import '@testing-library/jest-dom/vitest';
-import { allowedIcons, type IconName } from './allowedIcons.js';
+import {
+  allowedIcons,
+  customIcons,
+  iconAliases,
+  isIconName,
+  type IconName,
+} from './allowedIcons.js';
+import { lucideIconNames } from './LucideIcon.js';
+
+/**
+ * Every name the design system supported before the whole Lucide set was exposed. Kept as a literal
+ * list so that removing a name from `iconAliases`, or Lucide dropping one, fails here rather than
+ * in a consumer.
+ */
+const PREVIOUSLY_SUPPORTED_NAMES = [
+  '3-dot', 'archive', 'arrow-down', 'arrow-left', 'arrow-right-from-line', 'arrow-right',
+  'arrow-up-right', 'arrow-up', 'ask-arbor', 'book-open', 'camera', 'chart-column-increasing',
+  'chart-spline', 'check', 'check-solid', 'chevron-down', 'chevron-left', 'chevron-right',
+  'chevron-up', 'chevrons-left', 'chevrons-right', 'circle-alert', 'circle-check-big',
+  'circle-check', 'circle-help', 'circle-percent', 'circle-plus', 'circle-x', 'clipboard-list',
+  'clipboard', 'clock-3', 'cloud-upload', 'copy', 'corner-down-left', 'date', 'dot', 'download',
+  'ellipsis-vertical', 'ellipsis', 'expand', 'external-link', 'eye-off', 'eye', 'favourite-filled',
+  'favourite-outline', 'file', 'files', 'flag', 'funnel', 'google', 'grab', 'graduation-cap',
+  'grid-3x3', 'group', 'guardians', 'history', 'house', 'info', 'iteration-ccw', 'layout-list',
+  'lightbulb', 'link', 'list-filter-plus', 'list', 'list-tree', 'loader', 'lock-open', 'lock',
+  'log-out', 'mail', 'menu', 'message-square-more', 'mic', 'minus', 'monitor', 'paint-bucket',
+  'paperclip', 'party-popper', 'pencil', 'percent', 'phone', 'pin', 'plus', 'projector', 'redo',
+  'save', 'search', 'send', 'settings', 'share', 'sheet', 'shrink', 'sliders-horizontal',
+  'smartphone', 'sorting', 'sparkles', 'staff', 'switch-camera', 'table', 'trash', 'trending-down',
+  'trending-up', 'triangle-alert', 'undo', 'upload', 'user', 'x', 'x-solid', 'zap',
+] as const satisfies readonly IconName[];
+
+/**
+ * A spread of plain Lucide names rather than all ~1,900 — enough to cover the naming shapes that
+ * kebab-casing tends to break on (leading single letters, digits, repeated digits, letter pairs)
+ * plus Lucide's own deprecated aliases.
+ */
+const SAMPLED_LUCIDE_NAMES = [
+  'ban', 'shopping-cart', 'a-arrow-down', 'a-large-small', 'align-center', 'arrow-down-a-z',
+  'arrow-down-0-1', 'axis-3d', 'bluetooth-connected', 'building-2', 'circle-slash-2', 'clock-12',
+  'columns-3', 'file-json-2', 'git-pull-request-arrow', 'square-dashed-mouse-pointer', 'test-tube',
+  'volume-2', 'wifi-off', 'zoom-out',
+  // Lucide's deprecated aliases still resolve, so they are supported too
+  'sort-desc', 'area-chart',
+] as const satisfies readonly IconName[];
+
+/**
+ * Waits for the loaded glyph rather than the placeholder. Both carry `role="img"`, so they are told
+ * apart by their contents: the placeholder is an empty SVG until the icon's chunk resolves.
+ */
+const findLoadedIcon = async () => waitFor(() => {
+  const icon = screen.getByRole('img', { hidden: true });
+  expect(icon.childElementCount).toBeGreaterThan(0);
+  return icon;
+});
+
+const renderedIcon = async (name: IconName) => {
+  const { unmount } = render(<Icon name={name} />);
+  const icon = await findLoadedIcon();
+  const classes = icon.getAttribute('class') ?? '';
+  unmount();
+  return { tagName: icon.tagName.toLowerCase(), classes };
+};
 
 describe('Icon', () => {
-  Object.keys(allowedIcons).forEach((icon) => {
-    test(`Icon ${icon} renders`, () => {
-      render(<Icon name={icon as IconName} />);
+  describe('name allow-list', () => {
+    test('every previously supported name is still accepted', () => {
+      const rejected = PREVIOUSLY_SUPPORTED_NAMES.filter(name => !isIconName(name));
+      expect(rejected).toEqual([]);
+    });
+
+    test('the whole Lucide set is accepted', () => {
+      const rejected = lucideIconNames.filter(name => !isIconName(name));
+      expect(rejected).toEqual([]);
+      expect(lucideIconNames.length).toBeGreaterThan(1500);
+    });
+
+    test('every alias target is a real Lucide icon', () => {
+      const lucideNames = new Set<string>(lucideIconNames);
+      const unresolved = Object.entries(iconAliases)
+        .filter(([, target]) => !lucideNames.has(target));
+      expect(unresolved).toEqual([]);
+    });
+
+    test('isIconName rejects names that are not icons', () => {
+      expect(isIconName('behaviour')).toBe(false);
+      expect(isIconName('not-an-icon')).toBe(false);
+      expect(isIconName('')).toBe(false);
+      expect(isIconName('toString')).toBe(false);
+    });
+
+    test('allowedIcons supports hasOwnProperty membership checks', () => {
+      // arbor-fe-library validates backend-supplied names this way, so the shape has to hold.
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'ban')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'shopping-cart')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, '3-dot')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'ask-arbor')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'not-an-icon')).toBe(false);
+    });
+  });
+
+  describe('rendering', () => {
+    test.each(Object.keys(iconAliases) as Array<keyof typeof iconAliases>)(
+      'alias %s renders its target glyph',
+      async (name) => {
+        const { tagName, classes } = await renderedIcon(name);
+        expect(tagName).toBe('svg');
+        // Lucide tags each glyph with its own name, which proves the alias resolved correctly.
+        expect(classes.split(' ')).toContain(`lucide-${iconAliases[name]}`);
+        expect(classes.split(' ')).toContain(`ds-icon-${name}`);
+      },
+    );
+
+    test.each(Object.keys(customIcons) as Array<keyof typeof customIcons>)(
+      'custom icon %s renders',
+      async (name) => {
+        const { tagName, classes } = await renderedIcon(name);
+        expect(tagName).toBe('svg');
+        expect(classes.split(' ')).toContain(`ds-icon-${name}`);
+      },
+    );
+
+    test.each(SAMPLED_LUCIDE_NAMES)('lucide icon %s renders', async (name) => {
+      const { tagName, classes } = await renderedIcon(name);
+      expect(tagName).toBe('svg');
+      expect(classes.split(' ')).toContain(`ds-icon-${name}`);
+    });
+
+    test('an Arbor alias wins over the Lucide icon it shadows', async () => {
+      const { classes } = await renderedIcon('trash');
+      expect(classes.split(' ')).toContain('lucide-trash-2');
+      expect(classes.split(' ')).not.toContain('lucide-trash');
+    });
+
+    test('favourite-filled fills the star with the icon colour', async () => {
+      render(<Icon name="favourite-filled" color="rebeccapurple" />);
+      const icon = await findLoadedIcon();
+      expect(icon).toHaveAttribute('fill', 'rebeccapurple');
+      expect(icon.getAttribute('class')).toContain('lucide-star');
+    });
+
+    test('a placeholder of the right size holds the icon\'s place while it loads', () => {
+      // `not-yet-loaded` is only true on the very first render of an icon in this file's module
+      // registry, so pick one no other test touches.
+      render(<Icon name="microscope" size={24} className="custom-class" />);
+      const placeholder = screen.getByRole('img', { hidden: true });
+      expect(placeholder).toHaveAttribute('width', '24');
+      expect(placeholder).toHaveAttribute('height', '24');
+      expect(placeholder).toHaveClass('custom-class', 'ds-icon', 'ds-icon-microscope');
+      expect(placeholder).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    test('a loaded icon renders synchronously on later mounts', async () => {
+      const { unmount } = render(<Icon name="rocket" />);
+      await findLoadedIcon();
+      unmount();
+
+      render(<Icon name="rocket" />);
+      // No `await` — the module-level cache means no second placeholder frame.
+      expect(screen.getByRole('img', { hidden: true }).getAttribute('class'))
+        .toContain('lucide-rocket');
+    });
+
+    test.each([12, 16, 24] as const)('renders at size %i', async (size) => {
+      render(<Icon name="ban" size={size} />);
+      const icon = await findLoadedIcon();
+      expect(icon).toHaveAttribute('width', String(size));
+      expect(icon).toHaveAttribute('height', String(size));
+    });
+
+    test('an unrecognised name renders the placeholder and reports the problem', () => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+      // Consumers passing backend data can defeat the type, so this must not throw.
+      render(<Icon name={'definitely-not-an-icon' as IconName} />);
       expect(screen.getByRole('img', { hidden: true })).toBeInTheDocument();
+      expect(consoleError).toHaveBeenCalledWith(
+        '[design-system] "definitely-not-an-icon" is not a known icon name.',
+      );
+      consoleError.mockRestore();
     });
   });
 

package/src/components/icon/Icon.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
-import { allowedIcons, type IconName } from './allowedIcons.js';
+import { customIcons, iconAliases, type IconName } from './allowedIcons.js';
+import { LucideIcon, type LucideIconName } from './LucideIcon.js';
 import type { CustomIconProps, IconSize } from './types.js';
 
 type IconProps = {
@@ -10,14 +11,35 @@ type IconProps = {
   className?: string;
 };
 
+const isCustomIconName = (name: IconName): name is keyof typeof customIcons =>
+  Object.prototype.hasOwnProperty.call(customIcons, name);
+
+const isAliasedIconName = (name: IconName): name is keyof typeof iconAliases =>
+  Object.prototype.hasOwnProperty.call(iconAliases, name);
+
+const resolveLucideName = (name: Exclude<IconName, keyof typeof customIcons>): LucideIconName =>
+  isAliasedIconName(name) ? iconAliases[name] : name;
+
+/**
+ * Arbor's custom icons and aliases are resolved before the Lucide set, so an Arbor name always wins
+ * over the Lucide icon it shadows.
+ */
+const IconGlyph = (props: CustomIconProps & { name: IconName }) => {
+  const { name, ...glyphProps } = props;
+  if (isCustomIconName(name)) {
+    const CustomIcon = customIcons[name];
+    return <CustomIcon {...glyphProps} />;
+  }
+  return <LucideIcon name={resolveLucideName(name)} {...glyphProps} />;
+};
+
 export const Icon = (props: IconProps) => {
   const { size = 16, color = 'currentColor', name, screenReaderText, className } = props;
-  const Component = allowedIcons[name];
   const classes = classNames(className, `ds-icon ds-icon-${name}`);
   return (
     <>
       {/* why aria-hidden? https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/ */}
-      <Component size={size} color={color} className={classes} role="img" aria-hidden />
+      <IconGlyph name={name} size={size} color={color} className={classes} role="img" aria-hidden />
       {!!screenReaderText && (
         <span className="sr-only">{screenReaderText}</span>
       )}