Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: add XDSIconButton component (#1323)

Cindy Zhangf0583357fdee
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
index 26a6a1a44d..4e117ba46e 100644
--- a/.claude/commands/create-component.md
+++ b/.claude/commands/create-component.md
@@ -23,7 +23,6 @@ Follow the full component lifecycle documented on the XDS wiki:
- `XDS{ComponentName}.test.tsx` — unit tests
- `{ComponentName}.doc.mjs` — typed docs (ComponentDoc)
- `index.ts` — public exports
- - `README.md` — directory README (see Tokenizer/README.md for the format)
- Create `apps/storybook/stories/{ComponentName}.stories.tsx`
- Wire up: add to `packages/core/src/index.ts`
- Run `node scripts/sync-exports.js` to update package.json exports
diff --git a/CLAUDE.md b/CLAUDE.md
index 9c083fa9b3..594718c149 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,19 +61,12 @@ For component-specific documentation, see the `{Name}.doc.mjs` file in each comp
## Documentation Standard
-This project uses **Fractal Documentation** — a self-referential pattern where documentation exists at three levels:
+Documentation lives in two places:
-1. **Project Root** (`README.md`) — Project-wide architecture and directory overview
-2. **Directory READMEs** — Each directory contains a `README.md` with file manifests
-3. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`
+1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`
+2. **Component Docs** — `{Name}.doc.mjs` files in each component directory (props, features, examples)
-**Update Protocol**: When modifying code, update:
-
-1. The file's header comment
-2. The directory's README.md
-3. Parent documentation if architecture changes
-
-Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.
+**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.
## Quick Reference
diff --git a/apps/storybook/stories/IconButton.stories.tsx b/apps/storybook/stories/IconButton.stories.tsx
new file mode 100644
index 0000000000..89e1c54b51
--- /dev/null
+++ b/apps/storybook/stories/IconButton.stories.tsx
@@ -0,0 +1,127 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {
+ Cog6ToothIcon,
+ TrashIcon,
+ PlusIcon,
+ XMarkIcon,
+ PencilIcon,
+ HeartIcon,
+ BellIcon,
+} from '@heroicons/react/24/outline';
+
+const meta: Meta<typeof XDSIconButton> = {
+ title: 'Core/XDSIconButton',
+ component: XDSIconButton,
+ tags: ['autodocs'],
+ argTypes: {
+ label: {
+ control: 'text',
+ description: 'Accessible label (aria-label)',
+ },
+ variant: {
+ control: 'select',
+ options: ['primary', 'secondary', 'ghost', 'destructive'],
+ description: 'Visual style variant',
+ },
+ size: {
+ control: 'select',
+ options: ['sm', 'md', 'lg'],
+ description: 'Size variant',
+ },
+ isLoading: {
+ control: 'boolean',
+ description: 'Loading state',
+ },
+ isDisabled: {
+ control: 'boolean',
+ description: 'Disabled state',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSIconButton>;
+
+export const Default: Story = {
+ args: {
+ label: 'Settings',
+ icon: <Cog6ToothIcon />,
+ },
+};
+
+export const Ghost: Story = {
+ args: {
+ label: 'Settings',
+ icon: <Cog6ToothIcon />,
+ variant: 'ghost',
+ },
+};
+
+export const Primary: Story = {
+ args: {
+ label: 'Add item',
+ icon: <PlusIcon />,
+ variant: 'primary',
+ },
+};
+
+export const Destructive: Story = {
+ args: {
+ label: 'Delete',
+ icon: <TrashIcon />,
+ variant: 'destructive',
+ },
+};
+
+export const Small: Story = {
+ args: {
+ label: 'Close',
+ icon: <XMarkIcon />,
+ variant: 'ghost',
+ size: 'sm',
+ },
+};
+
+export const Large: Story = {
+ args: {
+ label: 'Edit',
+ icon: <PencilIcon />,
+ size: 'lg',
+ },
+};
+
+export const WithTooltip: Story = {
+ args: {
+ label: 'Notifications',
+ icon: <BellIcon />,
+ variant: 'ghost',
+ tooltip: 'View notifications',
+ },
+};
+
+export const Loading: Story = {
+ args: {
+ label: 'Saving',
+ icon: <HeartIcon />,
+ variant: 'primary',
+ isLoading: true,
+ },
+};
+
+export const Disabled: Story = {
+ args: {
+ label: 'Edit',
+ icon: <PencilIcon />,
+ isDisabled: true,
+ },
+};
+
+export const EmojiIcon: Story = {
+ args: {
+ label: 'React with rocket',
+ icon: <span>🚀</span>,
+ variant: 'ghost',
+ size: 'sm',
+ },
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index 993a32eef9..e1863c44ea 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -196,6 +196,12 @@
"import": "./dist/Icon/index.mjs",
"require": "./dist/Icon/index.js"
},
+ "./IconButton": {
+ "source": "./src/IconButton/index.ts",
+ "types": "./dist/IconButton/index.d.ts",
+ "import": "./dist/IconButton/index.mjs",
+ "require": "./dist/IconButton/index.js"
+ },
"./Kbd": {
"source": "./src/Kbd/index.ts",
"types": "./dist/Kbd/index.d.ts",
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
new file mode 100644
index 0000000000..3d03848d44
--- /dev/null
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -0,0 +1,102 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'IconButton',
+ description:
+ 'An icon-only button. Thin wrapper around XDSButton with isIconOnly always true.',
+
+ keywords: ['icon-button', 'icon', 'button', 'toolbar', 'action', 'compact'],
+ features: [
+ 'Composition wrapper — delegates all behavior to XDSButton with isIconOnly=true',
+ 'Explicit component name — greppable, codemod-safe, import-level detection',
+ 'Same variants, sizes, and states as XDSButton',
+ 'label prop becomes aria-label for accessibility',
+ 'icon prop is required (enforced by TypeScript)',
+ ],
+
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label. Used as aria-label (not rendered as visible text).',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon element rendered inside the button.',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "\'primary\' | \'secondary\' | \'ghost\' | \'destructive\'",
+ description: 'Visual style variant.',
+ default: "\'secondary\'",
+ },
+ {
+ name: 'size',
+ type: "\'sm\' | \'md\' | \'lg\'",
+ description: 'Size variant.',
+ default: "\'md\'",
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'Shows a loading spinner and disables interaction.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the button.',
+ default: 'false',
+ },
+ {
+ name: 'tooltip',
+ type: 'string',
+ description: 'Tooltip text shown on hover.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Standard click handler.',
+ },
+ {
+ name: 'onClickAction',
+ type: '(e: MouseEvent) => void | Promise<void>',
+ description: 'Async click handler with automatic loading state.',
+ },
+ ],
+
+ examples: [
+ {
+ label: 'Ghost icon button',
+ code: '<XDSIconButton label="Settings" icon={<GearIcon />} variant="ghost" />',
+ },
+ {
+ label: 'Destructive icon button',
+ code: '<XDSIconButton label="Delete" icon={<TrashIcon />} variant="destructive" />',
+ },
+ {
+ label: 'Small emoji icon button',
+ code: '<XDSIconButton label="Emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />',
+ },
+ {
+ label: 'Primary icon button with tooltip',
+ code: '<XDSIconButton label="Add item" icon={<PlusIcon />} variant="primary" tooltip="Add a new item" />',
+ },
+ ],
+
+ notes: [
+ 'Prefer XDSIconButton over <XDSButton isIconOnly> for explicit intent',
+ 'The label prop is always used as aria-label — required for accessibility',
+ 'children and endContent are not accepted (omitted from props type)',
+ 'All other XDSButton props (variant, size, onClick, etc.) are forwarded',
+ ],
+
+ accessibility: [
+ 'Uses aria-label from the label prop for screen reader accessibility',
+ 'Same keyboard and screen reader behavior as XDSButton with isIconOnly',
+ ],
+};
diff --git a/packages/core/src/IconButton/XDSIconButton.test.tsx b/packages/core/src/IconButton/XDSIconButton.test.tsx
new file mode 100644
index 0000000000..3c1a622bc3
--- /dev/null
+++ b/packages/core/src/IconButton/XDSIconButton.test.tsx
@@ -0,0 +1,106 @@
+/**
+ * @file XDSIconButton.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSIconButton component
+ * @output Unit tests for XDSIconButton component behavior
+ * @position Testing; validates XDSIconButton.tsx implementation
+ *
+ * SYNC: When XDSIconButton.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSIconButton} from './XDSIconButton';
+
+describe('XDSIconButton', () => {
+ it('renders as an icon-only button with aria-label', () => {
+ render(
+ <XDSIconButton
+ label="Settings"
+ icon={<span data-testid="icon">⚙</span>}
+ />,
+ );
+ const button = screen.getByRole('button', {name: 'Settings'});
+ expect(button).toHaveAttribute('aria-label', 'Settings');
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ });
+
+ it('does not render label as visible text', () => {
+ render(
+ <XDSIconButton
+ label="Settings"
+ icon={<span data-testid="icon">⚙</span>}
+ />,
+ );
+ const button = screen.getByRole('button');
+ // The label text should not appear as visible content
+ const visibleText = button.textContent;
+ expect(visibleText).not.toContain('Settings');
+ });
+
+ it('forwards variant prop', () => {
+ render(
+ <XDSIconButton
+ label="Delete"
+ icon={<span>🗑</span>}
+ variant="destructive"
+ />,
+ );
+ expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();
+ });
+
+ it('forwards size prop', () => {
+ render(<XDSIconButton label="Add" icon={<span>+</span>} size="sm" />);
+ expect(screen.getByRole('button', {name: 'Add'})).toBeInTheDocument();
+ });
+
+ it('handles click events', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <XDSIconButton
+ label="Close"
+ icon={<span>✕</span>}
+ onClick={handleClick}
+ />,
+ );
+
+ await user.click(screen.getByRole('button'));
+ expect(handleClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('is disabled when isDisabled is true', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <XDSIconButton
+ label="Close"
+ icon={<span>✕</span>}
+ isDisabled
+ onClick={handleClick}
+ />,
+ );
+
+ const button = screen.getByRole('button');
+ expect(button).toBeDisabled();
+ await user.click(button);
+ expect(handleClick).not.toHaveBeenCalled();
+ });
+
+ it('shows loading state', () => {
+ render(<XDSIconButton label="Save" icon={<span>💾</span>} isLoading />);
+ const button = screen.getByRole('button');
+ expect(button).toBeDisabled();
+ });
+
+ it('forwards ref correctly', () => {
+ const ref = vi.fn();
+ render(<XDSIconButton label="Action" icon={<span>⚡</span>} ref={ref} />);
+ expect(ref).toHaveBeenCalled();
+ expect(ref.mock.calls[0][0]).toBeInstanceOf(HTMLButtonElement);
+ });
+
+ it('has displayName set', () => {
+ expect(XDSIconButton.displayName).toBe('XDSIconButton');
+ });
+});
diff --git a/packages/core/src/IconButton/XDSIconButton.tsx b/packages/core/src/IconButton/XDSIconButton.tsx
new file mode 100644
index 0000000000..abaa63df2e
--- /dev/null
+++ b/packages/core/src/IconButton/XDSIconButton.tsx
@@ -0,0 +1,52 @@
+'use client';
+
+/**
+ * @file XDSIconButton.tsx
+ * @input Uses XDSButton, XDSButtonProps
+ * @output Exports XDSIconButton component, XDSIconButtonProps type
+ * @position Composition wrapper over XDSButton for icon-only buttons
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/IconButton/IconButton.doc.mjs (props table, features)
+ * - /packages/core/src/IconButton/XDSIconButton.test.tsx (tests)
+ * - /packages/core/src/IconButton/index.ts (exports if types change)
+ * - /apps/storybook/stories/IconButton.stories.tsx (storybook stories)
+ */
+
+import type {ReactNode} from 'react';
+import {XDSButton} from '../Button/XDSButton';
+import type {XDSButtonProps} from '../Button/XDSButton';
+
+/**
+ * Props for XDSIconButton.
+ *
+ * Omits `isIconOnly` (always true), `children` and `endContent` (not applicable
+ * for icon-only buttons). `icon` is required.
+ */
+export interface XDSIconButtonProps extends Omit<
+ XDSButtonProps,
+ 'isIconOnly' | 'children' | 'endContent'
+> {
+ /** Icon element rendered inside the button (required). */
+ icon: ReactNode;
+}
+
+/**
+ * An icon-only button — a thin wrapper around XDSButton with `isIconOnly`
+ * always set to true.
+ *
+ * Use this instead of `<XDSButton isIconOnly>` for explicit, greppable,
+ * and codemod-safe icon-only button usage.
+ *
+ * @example
+ * ```
+ * <XDSIconButton label="Settings" icon={<GearIcon />} variant="ghost" />
+ * <XDSIconButton label="Delete" icon={<TrashIcon />} variant="destructive" />
+ * <XDSIconButton label="Emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />
+ * ```
+ */
+export function XDSIconButton({icon, ...props}: XDSIconButtonProps): ReactNode {
+ return <XDSButton {...props} icon={icon} isIconOnly />;
+}
+
+XDSIconButton.displayName = 'XDSIconButton';
diff --git a/packages/core/src/IconButton/index.ts b/packages/core/src/IconButton/index.ts
new file mode 100644
index 0000000000..a473369de1
--- /dev/null
+++ b/packages/core/src/IconButton/index.ts
@@ -0,0 +1,13 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports XDSIconButton component and types from XDSIconButton.tsx
+ * @output Exports XDSIconButton, XDSIconButtonProps
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/IconButton/IconButton.doc.mjs
+ */
+
+export {XDSIconButton} from './XDSIconButton';
+export type {XDSIconButtonProps} from './XDSIconButton';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index c2814f5b54..df1aff7df4 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -20,6 +20,7 @@ export * from './Badge';
export * from './Banner';
export * from './Breadcrumbs';
export * from './Button';
+export * from './IconButton';
export * from './Card';
export * from './Carousel';
export * from './Calendar';