Skip to content

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

TypeScript

Improve Badge docs page and block examples (#1551)

rubyycheung750286d411e5
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.doc.mjs b/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.doc.mjs
index 7f74272ae3..2aed3dab0f 100644
--- a/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.doc.mjs
+++ b/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Badge — Category Tags',
- description: 'Non-semantic color badges used as category or team tags.',
+ name: 'Badge — Colors',
+ description: 'Tag items with color-coded categories like teams, priorities, or topics. Use the 9 non-semantic color variants when you need to distinguish groups visually.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Badge'],
+ componentsUsed: ['Badge', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.tsx b/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.tsx
index 6552e5e8f0..0aee91e8a3 100644
--- a/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.tsx
+++ b/packages/cli/templates/blocks/components/Badge/BadgeCategoryTags.tsx
@@ -1,19 +1,35 @@
'use client';
import {XDSBadge} from '@xds/core/Badge';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function BadgeCategoryTags() {
return (
- <div style={{display: 'flex', gap: 8, flexWrap: 'wrap'}}>
- <XDSBadge variant="blue" label="Design" />
- <XDSBadge variant="cyan" label="DevOps" />
- <XDSBadge variant="green" label="Backend" />
- <XDSBadge variant="orange" label="Urgent" />
- <XDSBadge variant="pink" label="Marketing" />
- <XDSBadge variant="purple" label="Engineering" />
- <XDSBadge variant="red" label="Critical" />
- <XDSBadge variant="teal" label="Research" />
- <XDSBadge variant="yellow" label="Review" />
- </div>
+ <XDSStack direction="vertical" gap={6}>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Teams
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} style={{flexWrap: 'wrap'}}>
+ <XDSBadge variant="blue" label="Design" />
+ <XDSBadge variant="cyan" label="DevOps" />
+ <XDSBadge variant="green" label="Backend" />
+ <XDSBadge variant="pink" label="Marketing" />
+ <XDSBadge variant="purple" label="Engineering" />
+ <XDSBadge variant="teal" label="Research" />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Priority
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2}>
+ <XDSBadge variant="orange" label="Urgent" />
+ <XDSBadge variant="red" label="Critical" />
+ <XDSBadge variant="yellow" label="Review" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.doc.mjs b/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.doc.mjs
index 31ce24603e..4124c53c09 100644
--- a/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.doc.mjs
+++ b/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Badge — Count Badges',
- description: 'Badges used as numeric counters for notifications or item counts.',
+ name: 'Badge — Counts',
+ description: 'Show a number inside a badge for notification counts, unread messages, or task totals. Use next to icons, nav items, or list labels.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Badge'],
+ componentsUsed: ['Badge', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.tsx b/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.tsx
index 1baad64894..b5aa3c3b29 100644
--- a/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.tsx
+++ b/packages/cli/templates/blocks/components/Badge/BadgeCountBadges.tsx
@@ -1,13 +1,27 @@
'use client';
import {XDSBadge} from '@xds/core/Badge';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const COUNTS = [
+ {variant: 'info' as const, label: '3', note: 'Messages'},
+ {variant: 'error' as const, label: '99+', note: 'Alerts'},
+ {variant: 'success' as const, label: '12', note: 'Completed'},
+ {variant: 'warning' as const, label: '5', note: 'Pending'},
+];
export default function BadgeCountBadges() {
return (
- <div style={{display: 'flex', gap: 8, alignItems: 'center'}}>
- <XDSBadge variant="info" label={3} />
- <XDSBadge variant="error" label="99+" />
- <XDSBadge variant="success" label={12} />
- </div>
+ <XDSStack direction="horizontal" gap={8} hAlign="center" vAlign="center">
+ {COUNTS.map(({variant, label, note}) => (
+ <XDSStack key={note} direction="vertical" gap={2} hAlign="center">
+ <XDSBadge variant={variant} label={label} />
+ <XDSText type="supporting" color="secondary">
+ {note}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeSemanticVariants.doc.mjs b/packages/cli/templates/blocks/components/Badge/BadgeSemanticVariants.doc.mjs
deleted file mode 100644
index 8a38ef2b39..0000000000
--- a/packages/cli/templates/blocks/components/Badge/BadgeSemanticVariants.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Badge — Semantic Variants',
- description: 'All five semantic badge variants: neutral, info, success, warning, and error.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Badge'],
-};
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeSemanticVariants.tsx b/packages/cli/templates/blocks/components/Badge/BadgeSemanticVariants.tsx
deleted file mode 100644
index cd954367dc..0000000000
--- a/packages/cli/templates/blocks/components/Badge/BadgeSemanticVariants.tsx
+++ /dev/null
@@ -1,15 +0,0 @@
-'use client';
-
-import {XDSBadge} from '@xds/core/Badge';
-
-export default function BadgeSemanticVariants() {
- return (
- <div style={{display: 'flex', gap: 8, alignItems: 'center'}}>
- <XDSBadge variant="neutral" label="Neutral" />
- <XDSBadge variant="info" label="Info" />
- <XDSBadge variant="success" label="Success" />
- <XDSBadge variant="warning" label="Warning" />
- <XDSBadge variant="error" label="Error" />
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.doc.mjs b/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.doc.mjs
index 4b11e36a03..d7b89bffaa 100644
--- a/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.doc.mjs
+++ b/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Badge — Status Labels',
- description: 'Badges as status indicators showing active, pending, failed, and draft states.',
+ name: 'Badge — Status',
+ description: 'Show the state of an item like Active, Pending, or Failed. Use in table rows, list items, or detail pages where users need to see status at a glance.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Badge'],
+ componentsUsed: ['Badge', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.tsx b/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.tsx
index b92735cfc5..01a4b94fa0 100644
--- a/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.tsx
+++ b/packages/cli/templates/blocks/components/Badge/BadgeStatusLabels.tsx
@@ -1,14 +1,31 @@
'use client';
import {XDSBadge} from '@xds/core/Badge';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function BadgeStatusLabels() {
return (
- <div style={{display: 'flex', gap: 8, alignItems: 'center'}}>
- <XDSBadge variant="success" label="Active" />
- <XDSBadge variant="warning" label="Pending" />
- <XDSBadge variant="error" label="Failed" />
- <XDSBadge variant="neutral" label="Draft" />
- </div>
+ <XDSStack direction="vertical" gap={6}>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ System status
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ <XDSBadge variant="success" label="Active" />
+ <XDSBadge variant="warning" label="Pending" />
+ <XDSBadge variant="error" label="Failed" />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Workflow
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ <XDSBadge variant="neutral" label="Draft" />
+ <XDSBadge variant="info" label="In Review" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
index c3b64c0a1f..f6779cc2fb 100644
--- a/packages/core/src/Badge/Badge.doc.mjs
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -29,15 +29,16 @@ export const docs = {
},
usage: {
description:
- 'Badge displays system or categorical information such as status indicators, counts, or labels. Use semantic color variants for system status and non-semantic colors for categorization and tagging.',
+ 'Badge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.',
bestPractices: [
- {guidance: true, description: 'Use semantic variants (success, warning, error) to communicate system status and non-semantic colors for categorization.'},
- {guidance: true, description: 'Keep badge labels concise — ideally one or two words — and always pair icons with a text label.'},
- {guidance: false, description: 'Use badges as interactive elements — they are informational only and should not be clickable.'},
+ {guidance: true, description: 'Use success, warning, and error variants for system status like "Active", "Pending", or "Failed". Use color variants like blue, purple, or teal for categories and tags.'},
+ {guidance: true, description: 'Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge.'},
+ {guidance: true, description: 'Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.'},
+ {guidance: false, description: 'Make badges clickable — they are read-only indicators. Use a button or link if the user needs to take action.'},
],
anatomy: [
- {name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
- {name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
+ {name: 'Icon', required: false, description: 'An optional leading icon that helps identify the badge type at a glance.'},
+ {name: 'Label', required: true, description: 'The text or number shown inside the badge.'},
],
},
};
@@ -47,15 +48,16 @@ export const docsZh = {
name: 'Badge',
usage: {
description:
- 'Badge displays system or categorical information such as status indicators, counts, or labels. Use semantic color variants for system status and non-semantic colors for categorization and tagging.',
+ 'Badge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.',
bestPractices: [
- {guidance: true, description: 'Use semantic variants (success, warning, error) to communicate system status and non-semantic colors for categorization.'},
- {guidance: true, description: 'Keep badge labels concise — ideally one or two words — and always pair icons with a text label.'},
- {guidance: false, description: 'Use badges as interactive elements — they are informational only and should not be clickable.'},
+ {guidance: true, description: 'Use success, warning, and error variants for system status like "Active", "Pending", or "Failed". Use color variants like blue, purple, or teal for categories and tags.'},
+ {guidance: true, description: 'Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge.'},
+ {guidance: true, description: 'Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.'},
+ {guidance: false, description: 'Make badges clickable — they are read-only indicators. Use a button or link if the user needs to take action.'},
],
anatomy: [
- {name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
- {name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
+ {name: 'Icon', required: false, description: 'An optional leading icon that helps identify the badge type at a glance.'},
+ {name: 'Label', required: true, description: 'The text or number shown inside the badge.'},
],
},
props: [
@@ -83,18 +85,18 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'badge for status indicators, counts, or labels',
+ description: 'short label for status, counts, or categories',
usage: {
description:
- 'Badge displays system or categorical information such as status indicators, counts, or labels. Use semantic color variants for system status and non-semantic colors for categorization and tagging.',
+ 'Badge shows a short label like a status, count, or category. Use in table rows, list items, navigation, or anywhere you need to call out a state or group.',
bestPractices: [
- {guidance: true, description: 'Use semantic variants (success, warning, error) to communicate system status and non-semantic colors for categorization.'},
- {guidance: true, description: 'Keep badge labels concise — ideally one or two words — and always pair icons with a text label.'},
- {guidance: false, description: 'Use badges as interactive elements — they are informational only and should not be clickable.'},
+ {guidance: true, description: 'Use success/warning/error for system status. Use color variants for categories and tags.'},
+ {guidance: true, description: 'Keep labels to one or two words. Add an icon only when it helps identify the badge type.'},
+ {guidance: false, description: 'Make badges clickable — they are read-only. Use a button or link for actions.'},
],
anatomy: [
- {name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
- {name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
+ {name: 'Icon', required: false, description: 'Optional leading icon.'},
+ {name: 'Label', required: true, description: 'Text or number shown inside the badge.'},
],
},
propDescriptions: {