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

package/src/components/formField/FormField.tsx

@@ -1,16 +1,19 @@
 import classNames from 'classnames';
 import { Combobox } from 'Components/combobox/Combobox';
-import type { ComboboxProps } from 'Components/combobox/types';
-import { DatePicker, type DatePickerProps } from 'Components/datePicker/DatePicker';
-import { DateTimePicker, type DateTimePickerProps } from 'Components/dateTimePicker/DateTimePicker';
+import { DatePicker } from 'Components/datePicker/DatePicker';
+import { DateTimePicker } from 'Components/dateTimePicker/DateTimePicker';
 import { Icon } from '../icon/Icon.js';
-import { ColourPickerDropdown, type ColourPickerDropdownProps } from './inputs/colourPickerDropdown/ColourPickerDropdown.js';
-import { NumberInput, type NumberInputProps } from './inputs/number/NumberInput.js';
-import { SelectDropdown, type SelectDropdownInputProps } from './inputs/selectDropdown/SelectDropdown.js';
-import { TextInput, type TextInputProps } from './inputs/text/TextInput.js';
-import { TimeInput, type TimeInputProps } from './inputs/time/TimeInput.js';
-import { TextArea, type TextAreaProps } from './inputs/textArea/TextArea.js';
+import { ColourPickerDropdown } from './inputs/colourPickerDropdown/ColourPickerDropdown.js';
+import { NumberInput } from './inputs/number/NumberInput.js';
+import { SelectDropdown } from './inputs/selectDropdown/SelectDropdown.js';
+import { TextInput } from './inputs/text/TextInput.js';
+import { TimeInput } from './inputs/time/TimeInput.js';
+import { TextArea } from './inputs/textArea/TextArea.js';
 import { Label } from './label/Label.js';
+import { CheckboxInput } from './inputs/checkbox/CheckboxInput.js';
+import { CheckboxGroup } from './inputs/checkbox/CheckboxGroup.js';
+import { RadioButtonGroup } from './inputs/radio/RadioButtonGroup.js';
+import { Toggle } from 'Components/toggle/Toggle.js';
 
 export type FormFieldProps = {
   className?: string;
@@ -21,15 +24,19 @@ export type FormFieldProps = {
   helperLinkUrl?: string;
   errorText?: string;
 } & (
-  | { inputType?: 'text'; inputProps?: TextInputProps }
-  | { inputType?: 'textarea'; inputProps?: TextAreaProps }
-  | { inputType?: 'number'; inputProps?: NumberInputProps }
-  | { inputType?: 'time'; inputProps?: TimeInputProps }
-  | { inputType?: 'colourPicker'; inputProps?: ColourPickerDropdownProps }
-  | { inputType?: 'selectDropdown'; inputProps?: SelectDropdownInputProps }
-  | { inputType?: 'datePicker'; inputProps?: DatePickerProps }
-  | { inputType?: 'dateTimePicker'; inputProps?: DateTimePickerProps }
-  | { inputType?: 'combobox'; inputProps?: ComboboxProps }
+  | { inputType?: 'text'; inputProps?: TextInput.Props }
+  | { inputType?: 'textarea'; inputProps?: TextArea.Props }
+  | { inputType?: 'number'; inputProps?: NumberInput.Props }
+  | { inputType?: 'time'; inputProps?: TimeInput.Props }
+  | { inputType?: 'colourPicker'; inputProps?: ColourPickerDropdown.Props }
+  | { inputType?: 'selectDropdown'; inputProps?: SelectDropdown.Props }
+  | { inputType?: 'datePicker'; inputProps?: DatePicker.Props }
+  | { inputType?: 'dateTimePicker'; inputProps?: DateTimePicker.Props }
+  | { inputType?: 'combobox'; inputProps?: Combobox.Props }
+  | { inputType?: 'checkbox'; inputProps: CheckboxInput.Props }
+  | { inputType?: 'checkboxGroup'; inputProps: CheckboxGroup.Props }
+  | { inputType?: 'toggle'; inputProps: Toggle.Props }
+  | { inputType?: 'radio'; inputProps: RadioButtonGroup.Props }
 );
 
 export const FormField = (props: FormFieldProps) => {
@@ -61,31 +68,43 @@ export const FormField = (props: FormFieldProps) => {
         <span id={`${id}-description`} className="ds-form-field__description">{fieldDescription}</span>
       )}
       {inputType === 'text' && (
-        <TextInput {...sharedProps} {...(inputProps as TextInputProps)} />
+        <TextInput {...sharedProps} {...(inputProps as TextInput.Props)} />
       )}
       {inputType === 'textarea' && (
-        <TextArea {...sharedProps} {...(inputProps as TextAreaProps)} />
+        <TextArea {...sharedProps} {...(inputProps as TextArea.Props)} />
       )}
       {inputType === 'number' && (
-        <NumberInput {...sharedProps} {...(inputProps as NumberInputProps)} />
+        <NumberInput {...sharedProps} {...(inputProps as NumberInput.Props)} />
       )}
       {inputType === 'time' && (
-        <TimeInput {...sharedProps} {...(inputProps as TimeInputProps)} />
+        <TimeInput {...sharedProps} {...(inputProps as TimeInput.Props)} />
       )}
       {inputType === 'colourPicker' && (
-        <ColourPickerDropdown {...sharedProps} {...(inputProps as ColourPickerDropdownProps)} />
+        <ColourPickerDropdown {...sharedProps} {...(inputProps as ColourPickerDropdown.Props)} />
       )}
       {inputType === 'selectDropdown' && (
-        <SelectDropdown {...sharedProps} {...(inputProps as SelectDropdownInputProps)} />
+        <SelectDropdown {...sharedProps} {...(inputProps as SelectDropdown.Props)} />
       )}
       {inputType === 'datePicker' && (
-        <DatePicker {...sharedProps} {...(inputProps as DatePickerProps)} />
+        <DatePicker {...sharedProps} {...(inputProps as DatePicker.Props)} />
       )}
       {inputType === 'dateTimePicker' && (
-        <DateTimePicker {...sharedProps} {...(inputProps as DateTimePickerProps)} />
+        <DateTimePicker {...sharedProps} {...(inputProps as DateTimePicker.Props)} />
       )}
       {inputType === 'combobox' && (
-        <Combobox {...sharedProps} {...(inputProps as ComboboxProps)} />
+        <Combobox {...sharedProps} {...(inputProps as Combobox.Props)} />
+      )}
+      {inputType === 'checkbox' && (
+        <CheckboxInput {...sharedProps} {...(inputProps as CheckboxInput.Props)} />
+      )}
+      {inputType === 'checkboxGroup' && (
+        <CheckboxGroup {...sharedProps} {...(inputProps as CheckboxGroup.Props)} />
+      )}
+      {inputType === 'toggle' && (
+        <Toggle {...sharedProps} {...(inputProps as Toggle.Props)} />
+      )}
+      {inputType === 'radio' && (
+        <RadioButtonGroup {...sharedProps} {...(inputProps as RadioButtonGroup.Props)} />
       )}
       {((helperLinkText && helperLinkUrl) || errorText) && (
         <div className="ds-form-field__message">

package/src/components/formField/inputs/checkbox/CheckboxGroup.tsx

@@ -3,14 +3,15 @@ import { CheckboxInput, type CheckboxInputProps } from './CheckboxInput.js';
 
 export type CheckboxGroupProps = {
   options: (CheckboxInputProps & { id: string })[];
+  hasError?: boolean;
 } & FieldsetProps;
 
 export const CheckboxGroup = (props: CheckboxGroupProps) => {
-  const { options, ...rest } = props;
+  const { options, hasError, ...rest } = props;
   return (
     <Fieldset {...rest}>
       {options.map((option: CheckboxInputProps) => (
-        <CheckboxInput key={option.id} {...option} />
+        <CheckboxInput key={option.id} hasError={hasError} {...option} />
       ))}
     </Fieldset>
   );

package/src/components/formField/inputs/checkbox/CheckboxInput.tsx

@@ -5,6 +5,7 @@ import { Icon } from 'Components/icon/Icon';
 export type CheckboxInputProps = {
   indeterminate?: boolean;
   label?: string;
+  hasError?: boolean;
 } & InputHTMLAttributes<HTMLInputElement>;
 
 export const CheckboxInput = (props: CheckboxInputProps) => {
@@ -15,6 +16,7 @@ export const CheckboxInput = (props: CheckboxInputProps) => {
     checked = false,
     indeterminate = false,
     label,
+    hasError,
     ...rest
   } = props;
 
@@ -57,6 +59,7 @@ export const CheckboxInput = (props: CheckboxInputProps) => {
         checked={checked}
         onChange={onChange}
         aria-checked={indeterminate ? 'mixed' : checked}
+        aria-invalid={hasError}
         {...rest}
       />
       <span

package/src/components/formField/inputs/checkbox/checkboxInput.scss

@@ -64,6 +64,10 @@
     box-shadow: inset 0 0 0 var(--checkbox-input-control-unchecked-weight-border) var(--checkbox-input-control-unchecked-disabled-color-border);
   }
 
+  input[aria-invalid='true'] + .ds-checkbox-input {
+    box-shadow: inset 0 0 0 var(--checkbox-input-control-unchecked-weight-border) var(--form-field-text-error-color-border);
+  }
+
   input:checked:disabled + .ds-checkbox-input {
     background-color: var(--checkbox-input-control-checked-disabled-color-background);
   }

package/src/components/formField/inputs/radio/RadioButtonGroup.tsx

@@ -13,10 +13,19 @@ export type RadioButtonGroupProps = {
   options: RadioGroupOption[];
   checkedValue: string;
   onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  hasError?: boolean;
 } & Omit<FieldsetProps, 'onChange'>;
 
 export const RadioButtonGroup = (props: RadioButtonGroupProps) => {
-  const { legend, name, options, checkedValue, onChange, ...rest } = props;
+  const {
+    legend,
+    name,
+    options,
+    checkedValue,
+    onChange,
+    hasError,
+    ...rest
+  } = props;
 
   return (
     <Fieldset legend={legend} {...rest}>
@@ -28,6 +37,7 @@ export const RadioButtonGroup = (props: RadioButtonGroupProps) => {
           label={option.label}
           checked={checkedValue === option.value}
           onChange={onChange}
+          hasError={hasError}
         />
       ))}
     </Fieldset>

package/src/components/formField/inputs/radio/radioButtonInput.scss

@@ -75,6 +75,10 @@
     }
   }
 
+  .ds-radio-button-input__input[aria-invalid='true'] + .ds-radio-button-input__indicator {
+    border-color: var(--form-field-text-error-color-border);
+  }
+
   &:hover:not(:has(.ds-radio-button-input__input:disabled)) {
     .ds-radio-button-input__indicator {
       border-color: var(--checkbox-or-radio-button-group-hover-color-border);
@@ -93,6 +97,10 @@
         background-color: var(--checkbox-or-radio-button-group-selected-hover-color-check);
       }
     }
+
+    .ds-radio-button-input__input[aria-invalid='true'] + .ds-radio-button-input__indicator {
+      border-color: var(--form-field-text-error-color-border);
+    }
   }
 }
 

package/src/components/formField/inputs/selectDropdown/items/item/SelectDropdownItem.tsx

@@ -1,4 +1,4 @@
-import { allowedIcons } from 'Components/icon/allowedIcons';
+import type { IconName } from 'Components/icon/allowedIcons';
 import { Icon } from 'Components/icon/Icon';
 import { Dropdown } from 'Components/dropdown/Dropdown';
 import classNames from 'classnames';
@@ -12,7 +12,7 @@ export type SelectDropdownItemBaseProps = {
 export type SelectDropdownItemProps = {
   value: string;
   label?: string;
-  icon?: keyof typeof allowedIcons;
+  icon?: IconName;
   header?: string;
   group?: string;
   closeAfterSelection?: boolean;

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(' '),
+);