Skip to content

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

TypeScript

feat(cli): add 'npx xds docs icons' reference + update all icon prop descriptions (#1500)

Cindy Zhange3d8a41a42d5
diff --git a/packages/cli/docs/icons.doc.mjs b/packages/cli/docs/icons.doc.mjs
new file mode 100644
index 0000000000..c7a0cf4960
--- /dev/null
+++ b/packages/cli/docs/icons.doc.mjs
@@ -0,0 +1,114 @@
+/**
+ * @file Icons reference doc — semantic icon names available in XDS
+ */
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+export const docs = {
+ name: 'icons',
+ title: 'XDS Icons',
+ description:
+ "Semantic icon names available in XDS. These adapt to the active theme's icon registry.",
+
+ sections: [
+ {
+ title: 'Available Names',
+ content: [
+ {
+ type: 'prose',
+ text: 'Components that accept an icon prop use XDSIconType \u2014 either a semantic name string or a direct SVG component. The semantic names below are resolved through the global icon registry.',
+ },
+ {
+ type: 'table',
+ headers: ['Name', 'Usage'],
+ rows: [
+ ['close', 'Dismiss, close dialogs/panels'],
+ ['chevronDown', 'Dropdown triggers, expand/collapse'],
+ ['chevronLeft', 'Navigate back, previous'],
+ ['chevronRight', 'Navigate forward, next'],
+ ['check', 'Checkbox checked, confirm'],
+ ['checkCircle', 'Success status indicator'],
+ ['xCircle', 'Error status indicator'],
+ ['warning', 'Warning status indicator'],
+ ['info', 'Info status indicator, tooltips'],
+ ['calendar', 'Date pickers, scheduling'],
+ ['clock', 'Time pickers, timestamps'],
+ ['externalLink', 'Links opening in new tab'],
+ ['menu', 'Hamburger menu, navigation toggle'],
+ ['moreHorizontal', 'Overflow menu, additional actions'],
+ ['search', 'Search inputs, find'],
+ ['arrowUp', 'Sort ascending, move up'],
+ ['arrowDown', 'Sort descending, move down'],
+ ['arrowsUpDown', 'Sortable column indicator'],
+ ['funnel', 'Filter controls'],
+ ['eyeSlash', 'Hidden/visibility toggle'],
+ ['viewColumns', 'Column visibility settings'],
+ ['copy', 'Copy to clipboard'],
+ ['checkDouble', 'Copied confirmation'],
+ ['wrench', 'Settings, configuration'],
+ ['stop', 'Stop/cancel action'],
+ ['microphone', 'Voice input, audio recording'],
+ ],
+ },
+ ],
+ },
+ {
+ title: 'Custom Icons',
+ content: [
+ {
+ type: 'prose',
+ text: 'For icons not in the semantic list, pass an SVG component directly. Any ComponentType<SVGProps<SVGSVGElement>> works \u2014 XDSIcon applies size and color styling automatically.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Using custom SVG components',
+ code: `import { PhotoIcon } from '@heroicons/react/24/outline';
+import { HeartIcon } from 'lucide-react';
+
+<XDSIcon icon={PhotoIcon} size="lg" />
+<XDSIcon icon={HeartIcon} color="negative" />`,
+ },
+ ],
+ },
+ {
+ title: 'Theme Overrides',
+ content: [
+ {
+ type: 'prose',
+ text: 'Themes can replace the default SVGs for any semantic name using registerIcons(). This lets you swap the entire icon set (e.g. heroicons \u2192 lucide) without touching component code.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Registering theme icons',
+ code: `import { registerIcons } from '@xds/core';
+import { XMarkIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
+
+registerIcons({
+ close: <XMarkIcon />,
+ chevronDown: <ChevronDownIcon />,
+ // ... override as many as needed
+});`,
+ },
+ ],
+ },
+ {
+ title: 'Adding New Icons',
+ content: [
+ {
+ type: 'prose',
+ text: 'To add a new semantic icon name to XDS:',
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'Add the name to XDSIconName type in packages/core/src/Icon/globalIconRegistry.tsx',
+ 'Add the default SVG to packages/core/src/Icon/defaultIcons.tsx',
+ 'Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 950bc29e20..c28c8012d4 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -89,7 +89,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'XDSIconType',
- description: 'Icon to display before the label text.',
+ description: 'Icon to display before the label text. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'status',
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index 9dac00e435..d3d6b409bb 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -78,7 +78,7 @@ export const docs = {
{
name: 'icon',
type: 'XDSIconType',
- description: 'Icon to display before the label.',
+ description: 'Icon to display before the label. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'label',
@@ -129,7 +129,7 @@ export const docs = {
{
name: 'icon',
type: 'XDSIconType',
- description: 'Icon to display before the item label.',
+ description: 'Icon to display before the item label. See `npx xds docs icons` for valid semantic names.',
},
],
},
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index aa29305ec8..e9088cef04 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -84,7 +84,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'XDSIconType',
- description: 'Icon to display before the label text.',
+ description: 'Icon to display before the label text. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'labelTooltip',
@@ -174,7 +174,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'XDSIconType',
- description: 'Icon before the label text.',
+ description: 'Icon before the label text. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'labelTooltip',
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index abcecca8eb..ad646ad2e4 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
{
name: 'icon',
type: 'XDSIconName | ComponentType<SVGProps>',
- description: 'Semantic name or SVG icon component.',
+ description: 'Semantic icon name or SVG component. Run `npx xds docs icons` for valid names.',
required: true,
},
{
@@ -45,7 +45,7 @@ export const docsZh = {
{
name: 'icon',
type: 'XDSIconName | ComponentType<SVGProps>',
- description: '语义名称或 SVG 图标组件。',
+ description: '语义图标名称或 SVG 组件。运行 `npx xds docs icons` 查看可用名称。',
required: true,
},
{
@@ -89,7 +89,7 @@ export const docsDense = {
],
},
propDescriptions: {
- icon: 'Semantic name or SVG icon component.',
+ icon: 'Semantic icon name or SVG component. See `npx xds docs icons`.',
color: 'Color variant mapped to XDS icon color tokens.',
size: 'Icon size.',
},
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index b0a2c267cb..3a0e0af843 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -21,6 +21,7 @@ import {defaultIcons} from './defaultIcons';
* These represent the functional purpose of each icon, not a specific
* visual representation. Themes provide the actual icon components.
*/
+// SYNC: packages/cli/docs/icons.doc.mjs — update USAGE_HINTS when adding names
export type XDSIconName =
| 'close'
| 'chevronDown'
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index ccd3ec649e..32a1e84807 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -72,12 +72,12 @@ export const docs = {
{
name: 'startIcon',
type: 'XDSIconType',
- description: 'Icon to display at the start of the input.',
+ description: 'Icon to display at the start of the input. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'labelIcon',
type: 'XDSIconType',
- description: 'Icon to display before the label text.',
+ description: 'Icon to display before the label text. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'status',
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index b07d250ba0..0e76e7fbe9 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -113,7 +113,7 @@ export const docs = {
{
name: 'icon',
type: 'XDSIconType',
- description: 'Icon displayed before the label.',
+ description: 'Icon displayed before the label. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'description',
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index b8c6a464c9..cbbb343c96 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -128,13 +128,13 @@ export const docs = {
{
name: 'icon',
type: 'XDSIconType',
- description: 'Icon displayed in the outline (unselected) variant.',
+ description: 'Icon displayed in the outline (unselected) variant. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'selectedIcon',
type: 'XDSIconType',
description:
- 'Icon displayed when the item is selected (filled variant).',
+ 'Icon displayed when the item is selected (filled variant). See `npx xds docs icons` for valid semantic names.',
},
{
name: 'isSelected',
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index f9092f1edb..ed868aa485 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -91,7 +91,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'XDSIconType',
- description: 'Icon displayed before the label text.',
+ description: 'Icon displayed before the label text. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'labelTooltip',
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index f67a52a645..bd28038ef1 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -106,7 +106,7 @@ export const docs = {
name: 'startIcon',
type: 'XDSIconType',
description:
- 'Icon component rendered inside the leading edge of the textarea wrapper.',
+ 'Icon component rendered inside the leading edge of the textarea wrapper. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'hasSpellCheck',
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 3e996e473e..3aa7e526ad 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -96,7 +96,7 @@ export const docs = {
name: 'startIcon',
type: 'XDSIconType',
description:
- 'SVG icon component displayed at the start of the input (e.g. from heroicons or lucide).',
+ 'SVG icon component displayed at the start of the input. See `npx xds docs icons` for valid semantic names.',
},
{
name: 'status',