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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.tsxindex 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 namesexport type XDSIconName =| 'close'| 'chevronDown'diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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',