Skip to content

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

TypeScript

Improve IconButton docs page and block examples (#1675)

Ted McDonald75964656d127
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.doc.mjs b/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.doc.mjs
index e791030d0b..0e2da0b94a 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.doc.mjs
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'IconButton — Action Bar',
- description:
- 'A toolbar row of ghost icon buttons for common actions like search, copy, info, and close.',
+ description: 'Row of ghost icon buttons for a compact action toolbar',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['IconButton', 'Icon', 'HStack'],
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx b/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx
index 171bb422f8..93681bd61b 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx
@@ -2,7 +2,7 @@
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
-import {XDSHStack} from '@xds/core/Layout';
+import {XDSHStack} from '@xds/core/Stack';
export default function IconButtonActionBar() {
return (
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.doc.mjs b/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.doc.mjs
index 23e62f4ca8..612449307d 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.doc.mjs
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'IconButton — Loading State',
- description:
- 'Icon buttons that show a loading spinner on click, demonstrating async action feedback.',
+ description: 'Icon buttons that show a loading spinner on click for async feedback',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['IconButton', 'Icon', 'HStack'],
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.tsx b/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.tsx
index 2f6d9c2b42..bf346c2829 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.tsx
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonLoadingToggle.tsx
@@ -3,7 +3,7 @@
import {useState} from 'react';
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
-import {XDSHStack} from '@xds/core/Layout';
+import {XDSHStack} from '@xds/core/Stack';
export default function IconButtonLoadingToggle() {
const [loadingId, setLoadingId] = useState<string | null>(null);
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.doc.mjs b/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.doc.mjs
index 1e1a514ea8..209607d683 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.doc.mjs
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'IconButton — With Tooltips',
- description:
- 'Icon buttons with tooltip hints that appear on hover, providing context for icon-only controls.',
+ description: 'Icon buttons with tooltips that explain each action on hover',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['IconButton', 'Icon', 'HStack'],
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.tsx b/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.tsx
index 3f4ed4270c..8dfe901808 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.tsx
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonTooltipIconButton.tsx
@@ -2,7 +2,7 @@
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
-import {XDSHStack} from '@xds/core/Layout';
+import {XDSHStack} from '@xds/core/Stack';
export default function IconButtonTooltipIconButton() {
return (
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index f83d48d260..3a4dc52009 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -61,11 +61,13 @@ export const docs = {
],
usage: {
- description: 'An icon-only button for compact actions that can be clearly represented by a single icon. Use IconButton in toolbars, table rows, and dense UI areas where space is limited and the icon meaning is universally understood.',
+ description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
bestPractices: [
- { guidance: true, description: 'Always provide a descriptive label prop — it becomes the aria-label for screen reader users.' },
- { guidance: true, description: 'Add a tooltip to clarify the action for sighted users who may not recognize the icon.' },
- { guidance: false, description: 'Use an icon-only button when the action is ambiguous — add visible text or use a standard Button instead.' },
+ { guidance: true, description: 'Make the aria-label specific — a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
+ { guidance: true, description: 'Add a tooltip — even a gear icon can mean Settings, Preferences, or Configure.' },
+ { guidance: true, description: 'Use ghost in toolbars and dense areas to reduce visual clutter.' },
+ { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone — use Button with text.' },
+ { guidance: false, description: 'Skip the tooltip — label only reaches screen readers, sighted users need the hover hint.' },
],
},
};