@arbor-education/design-system.components 1.0.5 → 2.0.1

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

@@ -624,7 +624,8 @@ const DecorativeVsMeaningfulTemplate = () => (
         Decorative — icon accompanies visible button text. No screenReaderText needed.
         Screen reader announces "Edit" from the button text.
       </p>
-      <Button variant="secondary" type="button" iconRightName="pencil">
+      <Button variant="secondary" type="button">
+        <Icon name="pencil" />
         Edit
       </Button>
       <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
@@ -639,15 +640,16 @@ const DecorativeVsMeaningfulTemplate = () => (
       }}
     >
       <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
-        Meaningful — icon-only button. Accessible name via iconRightScreenReaderText.
-        No screenReaderText needed on Icon itself.
+        Meaningful — icon-only button. Accessible name via screenReaderText on the Icon,
+        since Button no longer supplies a fallback.
       </p>
       <Button
         variant="tertiary"
         type="button"
-        iconRightName="pencil"
-        iconRightScreenReaderText="Edit student record"
-      />
+        isRound
+      >
+        <Icon name="pencil" screenReaderText="Edit student record" />
+      </Button>
       <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
         Screen reader: "Edit student record, button"
       </p>
@@ -892,30 +894,28 @@ const InButtonContextTemplate = () => (
     }}
   >
     <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
-      Button manages Icon internally — use iconLeftName/iconRightName, not
-      {' '}
-      {'<Icon>'}
-      {' '}
-      as a child
+      Button renders Icon as a plain child — there are no separate icon-name props.
     </p>
     <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap', alignItems: 'center' }}>
-      <Button variant="primary" type="button" iconLeftName="plus">
+      <Button variant="primary" type="button">
+        <Icon name="plus" />
         Add student
       </Button>
       <Button
         variant="secondary"
         type="button"
-        iconRightName="chevron-down"
       >
         Select year group
+        <Icon name="chevron-down" />
       </Button>
       {/* Icon-only tertiary — in production, wrap in TooltipWrapper for hover/focus affordance */}
       <Button
         variant="tertiary"
         type="button"
-        iconRightName="3-dot"
-        iconRightScreenReaderText="More actions"
-      />
+        isRound
+      >
+        <Icon name="3-dot" screenReaderText="More actions" />
+      </Button>
     </div>
     <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
       The icon-only tertiary button above should be wrapped in a TooltipWrapper in production
@@ -1215,22 +1215,20 @@ export const DecorativeVsMeaningful: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Button } from '@arbor-education/design-system.components';
+import { Button, Icon } from '@arbor-education/design-system.components';
 
 function DecorativeVsMeaningfulExample() {
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)', padding: 'var(--spacing-xlarge)' }}>
       {/* Decorative — icon accompanies visible button text. Screen reader: "Edit, button" */}
-      <Button variant="secondary" type="button" iconRightName="pencil">
+      <Button variant="secondary" type="button">
+        <Icon name="pencil" />
         Edit
       </Button>
-      {/* Meaningful — icon-only button. iconRightScreenReaderText provides accessible name. */}
-      <Button
-        variant="tertiary"
-        type="button"
-        iconRightName="pencil"
-        iconRightScreenReaderText="Edit student record"
-      />
+      {/* Meaningful — icon-only button. screenReaderText on the Icon provides the accessible name. */}
+      <Button variant="tertiary" type="button" isRound>
+        <Icon name="pencil" screenReaderText="Edit student record" />
+      </Button>
     </div>
   );
 }
@@ -1247,9 +1245,9 @@ export default DecorativeVsMeaningfulExample;
     'No `screenReaderText` on the Icon. The button\'s accessible name is "Edit" — from the visible text.',
     'Adding SR text here would cause "Edit pencil" duplication.',
     '',
-    '**Meaningful (bottom):** an icon-only button with no visible text.',
-    '`aria-label="Edit student record"` on the `<button>` element provides the accessible name.',
-    'No `screenReaderText` needed on the Icon — the button already has one accessible name.',
+    '**Meaningful (bottom):** an icon-only button (`isRound`) with no visible text.',
+    '`screenReaderText="Edit student record"` on the `Icon` provides the button\'s only accessible name —',
+    'unlike before, Button will not fall back to the icon name for you.',
     '',
     'The rule is: **one accessible name per interactive element**. Choose where to put it, but never',
     'duplicate it. For icon-only buttons in production, also add a TooltipWrapper for sighted mouse users.',
@@ -1318,24 +1316,23 @@ export const InButtonContext: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Button } from '@arbor-education/design-system.components';
+import { Button, Icon } from '@arbor-education/design-system.components';
 
 function InButtonContextExample() {
   return (
     <div style={{ display: 'flex', gap: 'var(--spacing-large)', flexWrap: 'wrap', alignItems: 'center' }}>
-      <Button variant="primary" type="button" iconLeftName="plus">
+      <Button variant="primary" type="button">
+        <Icon name="plus" />
         Add student
       </Button>
-      <Button variant="secondary" type="button" iconRightName="chevron-down">
+      <Button variant="secondary" type="button">
         Select year group
+        <Icon name="chevron-down" />
       </Button>
       {/* Icon-only — wrap in TooltipWrapper in production for hover/focus affordance */}
-      <Button
-        variant="tertiary"
-        type="button"
-        iconRightName="3-dot"
-        iconRightScreenReaderText="More actions"
-      />
+      <Button variant="tertiary" type="button" isRound>
+        <Icon name="3-dot" screenReaderText="More actions" />
+      </Button>
     </div>
   );
 }
@@ -1348,16 +1345,18 @@ export default InButtonContextExample;
   [
     'How Icon appears in real Button usage.',
     '',
-    '**Do not** render `<Icon>` as a child of `<Button>` directly. The `Button` component manages',
-    'its own icon rendering internally via `iconLeftName` and `iconRightName` props.',
+    '`Button` renders `children` as-is — render an `Icon` before and/or after the label text yourself.',
+    'There are no separate icon-name props on `Button`.',
     '',
-    '`iconLeftName="plus"` — icon before label (the default icon+label pattern for action buttons).',
+    'A leading `<Icon name="plus" />` before the label is the default icon+label pattern for action buttons.',
     '',
-    '`iconRightName="chevron-down"` — trailing action-indicator icon (communicates "opens a menu").',
+    'A trailing `<Icon name="chevron-down" />` after the label is a trailing action-indicator',
+    '(communicates "opens a menu"). Both are decorative here since the label already conveys the action,',
+    'so neither Icon needs `screenReaderText`.',
     '',
-    'Icon-only tertiary with `iconRightScreenReaderText="More actions"` — in production, this should',
-    'be wrapped in a `TooltipWrapper` to provide a hover/focus label for sighted users per Confluence',
-    'guidance on icon-only interactive elements.',
+    'Icon-only tertiary: `isRound` on the `Button` plus `screenReaderText="More actions"` on the `Icon` —',
+    'in production, this should also be wrapped in a `TooltipWrapper` to provide a hover/focus label for',
+    'sighted users per Confluence guidance on icon-only interactive elements.',
   ].join(' '),
 );
 

package/src/components/modal/ModalCloseButton.tsx

@@ -1,6 +1,7 @@
 import { useContext, useEffect } from 'react';
 import { ModalContext } from './Modal.js';
 import { Button, type ButtonProps } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import classNames from 'classnames';
 
 export const ModalCloseButon = (props: ButtonProps) => {
@@ -29,11 +30,12 @@ export const ModalCloseButon = (props: ButtonProps) => {
       size="S"
       onClick={closeHandler}
       variant="secondary"
-      iconRightName="x"
-      iconRightScreenReaderText="Close"
+      isRound
       borderless
       className={classNames('ds-modal__close-button', className)}
       {...rest}
-    />
+    >
+      <Icon name="x" screenReaderText="Close" />
+    </Button>
   );
 };

package/src/components/section/Section.stories.tsx

@@ -11,6 +11,7 @@ import {
 import { fn } from 'storybook/test';
 
 import { Row } from 'Components/row/Row';
+import { Icon } from 'Components/icon/Icon';
 import { Section } from './Section.js';
 
 // ---------------------------------------------------------------------------
@@ -409,7 +410,7 @@ export const WithActionButton: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Section } from '@arbor-education/design-system.components';
+import { Section, Icon } from '@arbor-education/design-system.components';
 
 function PersonalDetailsSection() {
   return (
@@ -417,8 +418,12 @@ function PersonalDetailsSection() {
       title="Personal Details"
       headingLevel={2}
       headerButtonProps={{
-        children: 'Edit',
-        iconLeftName: 'pencil',
+        children: (
+          <>
+            <Icon name="pencil" />
+            Edit
+          </>
+        ),
         onClick: () => openEditModal(),
         variant: 'secondary',
         size: 'S',
@@ -438,21 +443,25 @@ export default PersonalDetailsSection;
         title="Personal Details"
         headingLevel={2}
         headerButtonProps={{
-          children: 'Edit',
-          iconLeftName: 'pencil',
+          children: (
+            <>
+              <Icon name="pencil" />
+              Edit
+            </>
+          ),
           onClick: fn(),
           variant: 'secondary',
           size: 'S',
         }}
       >
         <p>
-          The action button appears in the heading row. Use
-          <code>iconLeftName</code>
+          The action button appears in the heading row. Render an
+          <code>Icon</code>
           {' '}
-          or
-          <code>iconRightName</code>
+          as part of the
+          <code>children</code>
           {' '}
-          inside
+          passed to
           <code>headerButtonProps</code>
           {' '}
           to add an icon alongside the label.
@@ -460,7 +469,7 @@ export default PersonalDetailsSection;
       </Section>
     ),
   },
-  'Pass `headerButtonProps` to render an action button in the section heading. Icons can be added via `iconLeftName` or `iconRightName`. Use `size: "S"` to keep it visually lightweight alongside the title.',
+  'Pass `headerButtonProps` to render an action button in the section heading. Icons are added by rendering an `Icon` inside `headerButtonProps.children`, before or after the label text. Use `size: "S"` to keep it visually lightweight alongside the title.',
 );
 
 export const WithActionButtonVariants: Story = withDescription(
@@ -471,35 +480,62 @@ export const WithActionButtonVariants: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Section } from '@arbor-education/design-system.components';
+import { Section, Icon } from '@arbor-education/design-system.components';
 
 // Icon on the left
 <Section title="Documents" headingLevel={2}
-  headerButtonProps={{ children: 'Upload', iconLeftName: 'upload', onClick: () => {}, variant: 'secondary', size: 'S' }}>
+  headerButtonProps={{
+    children: <><Icon name="upload" />Upload</>,
+    onClick: () => {},
+    variant: 'secondary',
+    size: 'S',
+  }}>
   <p>...</p>
 </Section>
 
 // Icon on the right
 <Section title="External Link" headingLevel={2}
-  headerButtonProps={{ children: 'Open', iconRightName: 'external-link', onClick: () => {}, variant: 'tertiary', size: 'S' }}>
+  headerButtonProps={{
+    children: <>Open<Icon name="external-link" /></>,
+    onClick: () => {},
+    variant: 'tertiary',
+    size: 'S',
+  }}>
   <p>...</p>
 </Section>
 
-// Icon-only (no children — button renders in icon-only mode)
+// Icon-only (isRound + no label text — button renders in icon-only mode)
 <Section title="Attachments" headingLevel={2}
-  headerButtonProps={{ iconLeftName: 'plus', iconLeftScreenReaderText: 'Add attachment', onClick: () => {}, variant: 'secondary', size: 'S' }}>
+  headerButtonProps={{
+    isRound: true,
+    children: <Icon name="plus" screenReaderText="Add attachment" />,
+    onClick: () => {},
+    variant: 'secondary',
+    size: 'S',
+  }}>
   <p>...</p>
 </Section>
 
 // Destructive
 <Section title="Danger Zone" headingLevel={2}
-  headerButtonProps={{ children: 'Delete', iconLeftName: 'trash', onClick: () => {}, variant: 'primary-destructive', size: 'S' }}>
+  headerButtonProps={{
+    children: <><Icon name="trash" />Delete</>,
+    onClick: () => {},
+    variant: 'primary-destructive',
+    size: 'S',
+  }}>
   <p>...</p>
 </Section>
 
 // Disabled
 <Section title="Locked Section" headingLevel={2}
-  headerButtonProps={{ children: 'Edit', iconLeftName: 'pencil', onClick: () => {}, variant: 'secondary', size: 'S', disabled: true }}>
+  headerButtonProps={{
+    children: <><Icon name="pencil" />Edit</>,
+    onClick: () => {},
+    variant: 'secondary',
+    size: 'S',
+    disabled: true,
+  }}>
   <p>...</p>
 </Section>
 `.trim(),
@@ -512,8 +548,12 @@ import { Section } from '@arbor-education/design-system.components';
           title="Documents"
           headingLevel={2}
           headerButtonProps={{
-            children: 'Upload',
-            iconLeftName: 'upload',
+            children: (
+              <>
+                <Icon name="upload" />
+                Upload
+              </>
+            ),
             onClick: fn(),
             variant: 'secondary',
             size: 'S',
@@ -525,8 +565,12 @@ import { Section } from '@arbor-education/design-system.components';
           title="External Link"
           headingLevel={2}
           headerButtonProps={{
-            children: 'Open',
-            iconRightName: 'external-link',
+            children: (
+              <>
+                Open
+                <Icon name="external-link" />
+              </>
+            ),
             onClick: fn(),
             variant: 'tertiary',
             size: 'S',
@@ -538,19 +582,22 @@ import { Section } from '@arbor-education/design-system.components';
           title="Attachments"
           headingLevel={2}
           headerButtonProps={{
-            iconLeftName: 'plus',
-            iconLeftScreenReaderText: 'Add attachment',
+            isRound: true,
+            children: <Icon name="plus" screenReaderText="Add attachment" />,
             onClick: fn(),
             variant: 'secondary',
             size: 'S',
           }}
         >
           <p>
-            Icon-only — omit
-            <code>children</code>
+            Icon-only — set
+            <code>isRound: true</code>
             {' '}
             and the button renders in compact icon-only mode. Always supply
-            <code>iconLeftScreenReaderText</code>
+            <code>screenReaderText</code>
+            {' '}
+            on the child
+            <code>Icon</code>
             {' '}
             for accessibility.
           </p>
@@ -559,8 +606,12 @@ import { Section } from '@arbor-education/design-system.components';
           title="Danger Zone"
           headingLevel={2}
           headerButtonProps={{
-            children: 'Delete',
-            iconLeftName: 'trash',
+            children: (
+              <>
+                <Icon name="trash" />
+                Delete
+              </>
+            ),
             onClick: fn(),
             variant: 'primary-destructive',
             size: 'S',
@@ -580,8 +631,12 @@ import { Section } from '@arbor-education/design-system.components';
           title="Locked Section"
           headingLevel={2}
           headerButtonProps={{
-            children: 'Edit',
-            iconLeftName: 'pencil',
+            children: (
+              <>
+                <Icon name="pencil" />
+                Edit
+              </>
+            ),
             onClick: fn(),
             variant: 'secondary',
             size: 'S',

package/src/components/table/Table.stories.tsx

@@ -12,6 +12,7 @@ import {
 import { type Column, type ColDef, type ColGroupDef } from 'ag-grid-enterprise';
 import { Table } from './Table.js';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 
 import { useState, type ComponentProps } from 'react';
 import { RowCountInfo } from './pagination/RowCountInfo.js';
@@ -1115,8 +1116,12 @@ const sampleDataWithButtonCellRenderer = [
   {
     id: 5,
     name: {
-      children: 'Ethan Hunt',
-      iconLeftName: 'download',
+      children: (
+        <>
+          <Icon name="download" />
+          Ethan Hunt
+        </>
+      ),
       value: 'Ethan Hunt',
       onClick: handleClick,
     },
@@ -1215,8 +1220,12 @@ export const WithButtonCellRendererThatOpensAModalWithModalManager: StoryObj<Tab
         {
           id: 5,
           name: {
-            children: 'Ethan Hunt',
-            iconLeftName: 'download',
+            children: (
+              <>
+                <Icon name="download" />
+                Ethan Hunt
+              </>
+            ),
             value: 'Ethan Hunt',
             onClick: () =>
               ModalUtils.addModal({ children: ModalContent('Ethan Hunt') }),
@@ -1315,8 +1324,12 @@ export const WithButtonCellRendererThatOpensAModalWithComposableModal: StoryObj<
         {
           id: 5,
           name: {
-            children: 'Ethan Hunt',
-            iconLeftName: 'download',
+            children: (
+              <>
+                <Icon name="download" />
+                Ethan Hunt
+              </>
+            ),
             value: 'Ethan Hunt',
             onClick: () => {
               setActivePersonId(5);

package/src/components/table/pagination/PageSizeSelector.tsx

@@ -1,4 +1,5 @@
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { Dropdown } from 'Components/dropdown/Dropdown';
 import { useEffect, useState } from 'react';
 import { useGridApi } from 'Utils/hooks/useGridApi';
@@ -58,8 +59,9 @@ export const PageSizeSelector = (props: PageSizeSelectorProps) => {
   return (
     <Dropdown>
       <Dropdown.Trigger>
-        <Button variant="dropdown" iconRightName="chevron-down" aria-label="Select page size">
+        <Button variant="dropdown" aria-label="Select page size">
           {selectedPageSize}
+          <Icon name="chevron-down" />
         </Button>
       </Dropdown.Trigger>
       <Dropdown.Content>

package/src/components/table/pagination/PaginationControls.tsx

@@ -1,4 +1,5 @@
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { NumberInput } from 'Components/formField/inputs/number/NumberInput';
 import { useEffect, useState } from 'react';
 import { useGridApi } from 'Utils/hooks/useGridApi';
@@ -54,21 +55,23 @@ export const PaginationControls = (props: PaginationControlsProps) => {
         borderless
         size="S"
         color="black"
-        iconLeftName="chevrons-left"
-        iconLeftScreenReaderText="Go to first page"
+        isRound
         onClick={() => goToPage(1)}
         disabled={inputValue === 1}
-      />
+      >
+        <Icon name="chevrons-left" screenReaderText="Go to first page" />
+      </Button>
       <Button
         variant="secondary"
         borderless
         size="S"
         color="black"
-        iconLeftName="chevron-left"
+        isRound
         onClick={() => goToPage(inputValue - 1)}
-        iconLeftScreenReaderText="Go to previous page"
         disabled={inputValue === 1}
-      />
+      >
+        <Icon name="chevron-left" screenReaderText="Go to previous page" />
+      </Button>
       <span>
         Page
         {' '}
@@ -97,20 +100,22 @@ export const PaginationControls = (props: PaginationControlsProps) => {
         variant="secondary"
         borderless
         color="black"
-        iconLeftName="chevron-right"
+        isRound
         onClick={() => goToPage(inputValue + 1)}
         disabled={inputValue === totalPages}
-        iconLeftScreenReaderText="Go to next page"
-      />
+      >
+        <Icon name="chevron-right" screenReaderText="Go to next page" />
+      </Button>
       <Button
         variant="secondary"
         borderless
         color="black"
-        iconLeftName="chevrons-right"
+        isRound
         onClick={() => goToPage(totalPages)}
         disabled={inputValue === totalPages}
-        iconLeftScreenReaderText="Go to last page"
-      />
+      >
+        <Icon name="chevrons-right" screenReaderText="Go to last page" />
+      </Button>
     </div>
   );
 };

package/src/components/table/tableControls/BulkActionsDropdown.tsx

@@ -2,6 +2,7 @@ import { useContext } from 'react';
 import { GridApiContext } from '../GridApiContext.js';
 import type { GridApi } from 'ag-grid-community';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { Dropdown } from 'Components/dropdown/Dropdown';
 
 export type BulkAction = {
@@ -21,10 +22,11 @@ export const BulkActionsDropdown = (props: BulkActionsDropdownProps) => {
   return (
     <Dropdown>
       <Dropdown.Trigger>
-        <Button variant="dropdown" iconRightName="chevron-down">
+        <Button variant="dropdown">
           Actions (
           {actions.length}
           )
+          <Icon name="chevron-down" />
         </Button>
       </Dropdown.Trigger>
       <Dropdown.Content>