Skip to content

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

TypeScript

Improve Icon docs page and block examples (#1662)

Ted McDonaldbc625a627cc3
diff --git a/packages/cli/templates/blocks/components/Icon/IconNonSemanticColors.doc.mjs b/packages/cli/templates/blocks/components/Icon/IconNonSemanticColors.doc.mjs
index ff9be61060..360b5c9246 100644
--- a/packages/cli/templates/blocks/components/Icon/IconNonSemanticColors.doc.mjs
+++ b/packages/cli/templates/blocks/components/Icon/IconNonSemanticColors.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'Icon — Non-Semantic Colors',
description:
- 'Non-semantic color palette for icons including blue, red, green, teal, purple, and more.',
+ 'Non-semantic color palette for icons.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Icon', 'HStack', 'VStack', 'Text'],
diff --git a/packages/cli/templates/blocks/components/Icon/IconSemanticColors.doc.mjs b/packages/cli/templates/blocks/components/Icon/IconSemanticColors.doc.mjs
index 8dd0c13a79..ca6bc8df4b 100644
--- a/packages/cli/templates/blocks/components/Icon/IconSemanticColors.doc.mjs
+++ b/packages/cli/templates/blocks/components/Icon/IconSemanticColors.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'Icon — Semantic Colors',
description:
- 'All semantic icon color variants with labels, showing primary through warning states.',
+ 'All semantic icon color variants with labels.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Icon', 'HStack', 'VStack', 'Text'],
diff --git a/packages/cli/templates/blocks/components/Icon/IconSizes.doc.mjs b/packages/cli/templates/blocks/components/Icon/IconSizes.doc.mjs
index 9b1bd2fe72..d5a2ccd3e2 100644
--- a/packages/cli/templates/blocks/components/Icon/IconSizes.doc.mjs
+++ b/packages/cli/templates/blocks/components/Icon/IconSizes.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'Icon — Size Variants',
description:
- 'All icon size variants from extra-small to large, displayed side by side for comparison.',
+ 'All icon sizes from extra-small to large.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Icon', 'HStack', 'VStack', 'Text'],
diff --git a/packages/cli/templates/blocks/components/Icon/IconStatusIcons.doc.mjs b/packages/cli/templates/blocks/components/Icon/IconStatusIcons.doc.mjs
index 18e0a2a6df..045da7ba8c 100644
--- a/packages/cli/templates/blocks/components/Icon/IconStatusIcons.doc.mjs
+++ b/packages/cli/templates/blocks/components/Icon/IconStatusIcons.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'Icon — Status Indicators',
description:
- 'Real-world status list using semantic icons and colors for success, warning, error, and info states.',
+ 'Status list using semantic icons for success, warning, error, and info.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Icon', 'VStack', 'HStack', 'Text'],
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index d966fd5a63..7a473a04cc 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -29,11 +29,16 @@ export const docs = {
],
},
usage: {
- description: 'Renders icons using XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme. Use Icon wherever a visual symbol is needed to reinforce meaning or provide wayfinding.',
+ description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
bestPractices: [
- { guidance: true, description: 'Use semantic icon names when available — they automatically adapt to the active theme.' },
- { guidance: true, description: 'Pair standalone icons with an accessible label (aria-label) when they convey meaning beyond decoration.' },
- { guidance: false, description: 'Rely on an icon alone to communicate critical information — always pair with text or an accessible label.' },
+ { guidance: true, description: 'Use semantic icon names when available — they adapt to theme changes automatically.' },
+ { guidance: true, description: 'Pair icons with text labels for accessibility — icon-only elements need an accessible label.' },
+ { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
+ { guidance: true, description: 'Be mindful of context — decorative icons in compact components can distract rather than help.' },
+ { guidance: false, description: 'Use icons as the sole means of conveying meaning — always provide a text alternative.' },
+ { guidance: false, description: 'Resize icons with arbitrary pixel values — use the provided size props.' },
+ { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
+ { guidance: false, description: 'Render raw SVG elements — always wrap in Icon for consistent sizing and color.' },
],
},
};
@@ -67,11 +72,16 @@ export const docsZh = {
],
},
usage: {
- description: 'Renders icons using XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme. Use Icon wherever a visual symbol is needed to reinforce meaning or provide wayfinding.',
+ description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
bestPractices: [
- { guidance: true, description: 'Use semantic icon names when available — they automatically adapt to the active theme.' },
- { guidance: true, description: 'Pair standalone icons with an accessible label (aria-label) when they convey meaning beyond decoration.' },
- { guidance: false, description: 'Rely on an icon alone to communicate critical information — always pair with text or an accessible label.' },
+ { guidance: true, description: 'Use semantic icon names when available — they adapt to theme changes automatically.' },
+ { guidance: true, description: 'Pair icons with text labels for accessibility — icon-only elements need an accessible label.' },
+ { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
+ { guidance: true, description: 'Be mindful of context — decorative icons in compact components can distract rather than help.' },
+ { guidance: false, description: 'Use icons as the sole means of conveying meaning — always provide a text alternative.' },
+ { guidance: false, description: 'Resize icons with arbitrary pixel values — use the provided size props.' },
+ { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
+ { guidance: false, description: 'Render raw SVG elements — always wrap in Icon for consistent sizing and color.' },
],
},
};
@@ -81,11 +91,16 @@ export const docsDense = {
description:
'Renders icons w/ XDS design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
usage: {
- description: 'Renders icons using XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme. Use Icon wherever a visual symbol is needed to reinforce meaning or provide wayfinding.',
+ description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
bestPractices: [
- { guidance: true, description: 'Use semantic icon names when available — they automatically adapt to the active theme.' },
- { guidance: true, description: 'Pair standalone icons with an accessible label (aria-label) when they convey meaning beyond decoration.' },
- { guidance: false, description: 'Rely on an icon alone to communicate critical information — always pair with text or an accessible label.' },
+ { guidance: true, description: 'Use semantic icon names when available — they adapt to theme changes automatically.' },
+ { guidance: true, description: 'Pair icons with text labels for accessibility — icon-only elements need an accessible label.' },
+ { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
+ { guidance: true, description: 'Be mindful of context — decorative icons in compact components can distract rather than help.' },
+ { guidance: false, description: 'Use icons as the sole means of conveying meaning — always provide a text alternative.' },
+ { guidance: false, description: 'Resize icons with arbitrary pixel values — use the provided size props.' },
+ { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
+ { guidance: false, description: 'Render raw SVG elements — always wrap in Icon for consistent sizing and color.' },
],
},
propDescriptions: {