Skip to content

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

TypeScript

Improve Token docs page and block examples (#1609)

Kenton Quatmanf7a763373dea
diff --git a/packages/cli/templates/blocks/components/Token/TokenClickable.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenClickable.doc.mjs
index 1d6eb6c939..2b4b9ea103 100644
--- a/packages/cli/templates/blocks/components/Token/TokenClickable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Token/TokenClickable.doc.mjs
@@ -2,8 +2,8 @@
export const doc = {
type: 'block',
name: 'Token — Clickable',
- description: 'Interactive tokens that respond to click events.',
+ description: 'Interactive tokens that respond to clicks. Use for toggleable filters or tokens that open a detail view when selected.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Token'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Token', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Token/TokenClickable.tsx b/packages/cli/templates/blocks/components/Token/TokenClickable.tsx
index b2bada209e..724bb4d1e6 100644
--- a/packages/cli/templates/blocks/components/Token/TokenClickable.tsx
+++ b/packages/cli/templates/blocks/components/Token/TokenClickable.tsx
@@ -1,12 +1,21 @@
'use client';
import {XDSToken} from '@xds/core/Token';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function TokenClickable() {
return (
- <div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSToken label="Click me" onClick={() => {}} />
- <XDSToken label="Green action" color="green" onClick={() => {}} />
- </div>
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Click a token to view details
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSToken label="Bug" color="red" onClick={() => {}} />
+ <XDSToken label="Feature" color="blue" onClick={() => {}} />
+ <XDSToken label="Enhancement" color="green" onClick={() => {}} />
+ <XDSToken label="Documentation" color="gray" onClick={() => {}} />
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Token/TokenColors.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenColors.doc.mjs
new file mode 100644
index 0000000000..45b7197bb9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenColors.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Token — Colors',
+ description: 'All 11 color variants in default and disabled states. Use color to categorize entities or convey status at a glance.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Token', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Token/TokenColors.tsx b/packages/cli/templates/blocks/components/Token/TokenColors.tsx
new file mode 100644
index 0000000000..f7c1c40a32
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenColors.tsx
@@ -0,0 +1,46 @@
+'use client';
+
+import {XDSToken} from '@xds/core/Token';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const COLORS = [
+ {color: 'default' as const, label: 'Default'},
+ {color: 'red' as const, label: 'Red'},
+ {color: 'orange' as const, label: 'Orange'},
+ {color: 'yellow' as const, label: 'Yellow'},
+ {color: 'green' as const, label: 'Green'},
+ {color: 'teal' as const, label: 'Teal'},
+ {color: 'cyan' as const, label: 'Cyan'},
+ {color: 'blue' as const, label: 'Blue'},
+ {color: 'purple' as const, label: 'Purple'},
+ {color: 'pink' as const, label: 'Pink'},
+ {color: 'gray' as const, label: 'Gray'},
+];
+
+export default function TokenColors() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Default
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ {COLORS.map(({color, label}) => (
+ <XDSToken key={color} label={label} color={color} />
+ ))}
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Disabled
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ {COLORS.map(({color, label}) => (
+ <XDSToken key={color} label={label} color={color} isDisabled />
+ ))}
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Token/TokenEndContent.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenEndContent.doc.mjs
new file mode 100644
index 0000000000..8e4c094dc1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenEndContent.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Token — End Content',
+ description: 'Tokens with trailing content like a count badge or status indicator after the label. Use for notification counts, item quantities, or compact status info.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Token', 'Badge', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Token/TokenEndContent.tsx b/packages/cli/templates/blocks/components/Token/TokenEndContent.tsx
new file mode 100644
index 0000000000..628359b7a3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenEndContent.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import {XDSToken} from '@xds/core/Token';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function TokenEndContent() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Trailing badges for counts or status
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSToken
+ label="Inbox"
+ color="blue"
+ endContent={<XDSBadge variant="info" label={12} />}
+ />
+ <XDSToken
+ label="Reviews"
+ color="purple"
+ endContent={<XDSBadge variant="purple" label={3} />}
+ />
+ <XDSToken
+ label="Resolved"
+ color="green"
+ endContent={<XDSBadge variant="success" label="Done" />}
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Token/TokenIcon.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenIcon.doc.mjs
new file mode 100644
index 0000000000..a2d5ed7529
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenIcon.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Token — Icon',
+ description: 'Tokens with a leading icon that identifies the entity type. Use when the icon helps users recognize the token category faster, like a user icon for people or a tag icon for labels.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Token', 'Icon', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Token/TokenIcon.tsx b/packages/cli/templates/blocks/components/Token/TokenIcon.tsx
new file mode 100644
index 0000000000..a0f553c0cd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenIcon.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import {XDSToken} from '@xds/core/Token';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {
+ StarIcon,
+ TagIcon,
+ UserIcon,
+ ShieldCheckIcon,
+} from '@heroicons/react/24/outline';
+
+export default function TokenIcon() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Icons identify the token category
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSToken
+ label="Sarah Chen"
+ color="blue"
+ icon={<XDSIcon icon={UserIcon} size="sm" color="inherit" />}
+ />
+ <XDSToken
+ label="Featured"
+ color="yellow"
+ icon={<XDSIcon icon={StarIcon} size="sm" color="inherit" />}
+ />
+ <XDSToken
+ label="Design"
+ color="purple"
+ icon={<XDSIcon icon={TagIcon} size="sm" color="inherit" />}
+ />
+ <XDSToken
+ label="Verified"
+ color="green"
+ icon={<XDSIcon icon={ShieldCheckIcon} size="sm" color="inherit" />}
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Token/TokenRemovable.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenRemovable.doc.mjs
new file mode 100644
index 0000000000..43ea01a246
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenRemovable.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Token — Removable',
+ description: 'Tokens with a dismiss button for selections the user can undo. Use in multi-select fields, active filters, or any list of user-chosen items.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Token', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Token/TokenRemovable.tsx b/packages/cli/templates/blocks/components/Token/TokenRemovable.tsx
new file mode 100644
index 0000000000..bca9d3b6f9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Token/TokenRemovable.tsx
@@ -0,0 +1,32 @@
+'use client';
+
+import {XDSToken} from '@xds/core/Token';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function TokenRemovable() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Active filters
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSToken label="Status: Open" color="green" onRemove={() => {}} />
+ <XDSToken label="Priority: High" color="red" onRemove={() => {}} />
+ <XDSToken label="Team: Design" color="purple" onRemove={() => {}} />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Selected recipients
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSToken label="Sarah Chen" color="blue" onRemove={() => {}} />
+ <XDSToken label="Alex Rivera" color="blue" onRemove={() => {}} />
+ <XDSToken label="Jordan Lee" color="blue" onRemove={() => {}} />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Token/TokenShowcase.tsx b/packages/cli/templates/blocks/components/Token/TokenShowcase.tsx
index 79a402cb12..e820aa4682 100644
--- a/packages/cli/templates/blocks/components/Token/TokenShowcase.tsx
+++ b/packages/cli/templates/blocks/components/Token/TokenShowcase.tsx
@@ -1,7 +1,20 @@
'use client';
import {XDSToken} from '@xds/core/Token';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSStack} from '@xds/core/Layout';
+import {TagIcon} from '@heroicons/react/24/outline';
export default function TokenShowcase() {
- return <XDSToken label="Token" />;
+ return (
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ <XDSToken label="Default" />
+ <XDSToken label="Removable" color="blue" onRemove={() => {}} />
+ <XDSToken
+ label="Design"
+ color="purple"
+ icon={<XDSIcon icon={TagIcon} size="sm" color="inherit" />}
+ />
+ </XDSStack>
+ );
}
diff --git a/packages/cli/templates/blocks/components/Token/TokenWithEndContent.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenWithEndContent.doc.mjs
deleted file mode 100644
index e3a3c41513..0000000000
--- a/packages/cli/templates/blocks/components/Token/TokenWithEndContent.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Token — End Content',
- description: 'Tokens with trailing content such as counts or status indicators.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Token'],
-};
diff --git a/packages/cli/templates/blocks/components/Token/TokenWithEndContent.tsx b/packages/cli/templates/blocks/components/Token/TokenWithEndContent.tsx
deleted file mode 100644
index 15cb170af3..0000000000
--- a/packages/cli/templates/blocks/components/Token/TokenWithEndContent.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-'use client';
-
-import {XDSToken} from '@xds/core/Token';
-
-export default function TokenWithEndContent() {
- return (
- <div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSToken
- label="Count"
- endContent={
- <span
- style={{
- fontSize: '10px',
- opacity: 0.7,
- marginInlineStart: '2px',
- }}>
- (3)
- </span>
- }
- />
- <XDSToken
- label="Status"
- color="green"
- endContent={
- <span
- style={{
- width: '6px',
- height: '6px',
- borderRadius: '50%',
- backgroundColor: 'currentColor',
- marginInlineStart: '2px',
- }}
- />
- }
- />
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Token/TokenWithIcon.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenWithIcon.doc.mjs
deleted file mode 100644
index f38d9c9806..0000000000
--- a/packages/cli/templates/blocks/components/Token/TokenWithIcon.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Token — With Icon',
- description: 'Tokens with leading icon elements for visual context.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Token'],
-};
diff --git a/packages/cli/templates/blocks/components/Token/TokenWithIcon.tsx b/packages/cli/templates/blocks/components/Token/TokenWithIcon.tsx
deleted file mode 100644
index 8ae9946492..0000000000
--- a/packages/cli/templates/blocks/components/Token/TokenWithIcon.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-'use client';
-
-import {XDSToken} from '@xds/core/Token';
-
-export default function TokenWithIcon() {
- return (
- <div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSToken
- label="Star"
- icon={
- <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
- <path d="M6 0l1.8 3.6L12 4.2 8.9 7.1l.7 4.1L6 9.2 2.4 11.2l.7-4.1L0 4.2l4.2-.6z" />
- </svg>
- }
- />
- <XDSToken
- label="Info"
- color="blue"
- icon={
- <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
- <circle
- cx="6"
- cy="6"
- r="5"
- fill="none"
- stroke="currentColor"
- strokeWidth="1.5"
- />
- <text
- x="6"
- y="9"
- textAnchor="middle"
- fontSize="8"
- fill="currentColor">
- i
- </text>
- </svg>
- }
- />
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Token/TokenWithRemove.doc.mjs b/packages/cli/templates/blocks/components/Token/TokenWithRemove.doc.mjs
deleted file mode 100644
index 93f8f05dbf..0000000000
--- a/packages/cli/templates/blocks/components/Token/TokenWithRemove.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Token — Removable',
- description: 'Tokens with a remove button for dismissible tags and filters.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Token'],
-};
diff --git a/packages/cli/templates/blocks/components/Token/TokenWithRemove.tsx b/packages/cli/templates/blocks/components/Token/TokenWithRemove.tsx
deleted file mode 100644
index 5bf0f82f5d..0000000000
--- a/packages/cli/templates/blocks/components/Token/TokenWithRemove.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-'use client';
-
-import {XDSToken} from '@xds/core/Token';
-
-export default function TokenWithRemove() {
- return (
- <div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSToken label="Removable" onRemove={() => {}} />
- <XDSToken label="Red tag" color="red" onRemove={() => {}} />
- <XDSToken label="Blue tag" color="blue" onRemove={() => {}} />
- </div>
- );
-}
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
index 79a44dbe71..bf57456e3d 100644
--- a/packages/core/src/Token/Token.doc.mjs
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -84,19 +84,21 @@ export const docs = {
},
usage: {
description:
- 'Token is a compact chip component for displaying entities like tags, names, or status indicators inline within content. Use a Token to represent metadata, categorization, or removable selections. For static status indicators without interaction, use Badge instead.',
+ 'Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.',
bestPractices: [
- {guidance: true, description: 'Use color variants to distinguish different categories or entity types at a glance.'},
- {guidance: true, description: 'Provide an onRemove callback when users need the ability to dismiss or deselect a token.'},
- {guidance: false, description: 'Avoid using tokens for primary actions or navigation — use Button or Link instead.'},
- {guidance: false, description: 'Avoid hiding the label unless an icon provides sufficient visual meaning on its own.'},
+ {guidance: true, description: 'Use color to distinguish categories — for example, green for "Active", red for "Blocked", blue for "In Review" — so users can scan status at a glance.'},
+ {guidance: true, description: 'Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.'},
+ {guidance: true, description: 'Add a leading icon when it helps identify the token type faster, like a person icon for user tokens or a tag icon for labels.'},
+ {guidance: true, description: 'Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows.'},
+ {guidance: false, description: 'Don\'t use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.'},
+ {guidance: false, description: 'Don\'t hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.'},
+ {guidance: false, description: 'Don\'t mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.'},
],
anatomy: [
- {name: 'Color', required: false, description: 'Background color indicator.'},
- {name: 'Label', required: true, description: 'Text label for the token.'},
- {name: 'Icon', required: false, description: '16px icon displayed in the token.'},
- {name: 'Remove button', required: false, description: 'Shown when onRemove is provided.'},
- {name: 'Description', required: false, description: 'Additional descriptive text.'},
+ {name: 'Icon', required: false, description: 'A leading icon that identifies the token type, like a user avatar or category symbol.'},
+ {name: 'Label', required: true, description: 'The visible text. Also used as the accessible name when isLabelHidden is true.'},
+ {name: 'End content', required: false, description: 'Trailing content after the label, like a count badge or status dot.'},
+ {name: 'Remove button', required: false, description: 'An X button that appears when onRemove is provided, letting users dismiss the token.'},
],
},
};
@@ -186,41 +188,39 @@ export const docsZh = {
},
usage: {
description:
- 'Token is a compact chip component for displaying entities like tags, names, or status indicators inline within content. Use a Token to represent metadata, categorization, or removable selections. For static status indicators without interaction, use Badge instead.',
+ 'Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.',
bestPractices: [
- {guidance: true, description: 'Use color variants to distinguish different categories or entity types at a glance.'},
- {guidance: true, description: 'Provide an onRemove callback when users need the ability to dismiss or deselect a token.'},
- {guidance: false, description: 'Avoid using tokens for primary actions or navigation — use Button or Link instead.'},
- {guidance: false, description: 'Avoid hiding the label unless an icon provides sufficient visual meaning on its own.'},
+ {guidance: true, description: 'Use color to distinguish categories — for example, green for "Active", red for "Blocked", blue for "In Review" — so users can scan status at a glance.'},
+ {guidance: true, description: 'Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.'},
+ {guidance: true, description: 'Add a leading icon when it helps identify the token type faster, like a person icon for user tokens or a tag icon for labels.'},
+ {guidance: true, description: 'Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows.'},
+ {guidance: false, description: 'Don\'t use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.'},
+ {guidance: false, description: 'Don\'t hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.'},
+ {guidance: false, description: 'Don\'t mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.'},
],
anatomy: [
- {name: 'Color', required: false, description: 'Background color indicator.'},
- {name: 'Label', required: true, description: 'Text label for the token.'},
- {name: 'Icon', required: false, description: '16px icon displayed in the token.'},
- {name: 'Remove button', required: false, description: 'Shown when onRemove is provided.'},
- {name: 'Description', required: false, description: 'Additional descriptive text.'},
+ {name: 'Icon', required: false, description: 'A leading icon that identifies the token type, like a user avatar or category symbol.'},
+ {name: 'Label', required: true, description: 'The visible text. Also used as the accessible name when isLabelHidden is true.'},
+ {name: 'End content', required: false, description: 'Trailing content after the label, like a count badge or status dot.'},
+ {name: 'Remove button', required: false, description: 'An X button that appears when onRemove is provided, letting users dismiss the token.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'Chip/tag for displaying entities inline. Renders as <span> default, <a> w/ href, or <span> w/ invisible <button> when onClick provided.',
+ description: 'compact chip/tag for inline metadata, filters, selections. 11 colors, 2 sizes, removable, clickable, linkable.',
usage: {
description:
- 'Token is a compact chip component for displaying entities like tags, names, or status indicators inline within content. Use a Token to represent metadata, categorization, or removable selections. For static status indicators without interaction, use Badge instead.',
+ 'Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use for labeling content, showing active filters, or representing removable items.',
bestPractices: [
- {guidance: true, description: 'Use color variants to distinguish different categories or entity types at a glance.'},
- {guidance: true, description: 'Provide an onRemove callback when users need the ability to dismiss or deselect a token.'},
- {guidance: false, description: 'Avoid using tokens for primary actions or navigation — use Button or Link instead.'},
- {guidance: false, description: 'Avoid hiding the label unless an icon provides sufficient visual meaning on its own.'},
- ],
- anatomy: [
- {name: 'Color', required: false, description: 'Background color indicator.'},
- {name: 'Label', required: true, description: 'Text label for the token.'},
- {name: 'Icon', required: false, description: '16px icon displayed in the token.'},
- {name: 'Remove button', required: false, description: 'Shown when onRemove is provided.'},
- {name: 'Description', required: false, description: 'Additional descriptive text.'},
+ {guidance: true, description: 'Color-code categories — green for active, red for blocked, blue for review — for fast scanning.'},
+ {guidance: true, description: 'Provide onRemove when tokens represent dismissible user selections like filters or multi-select values.'},
+ {guidance: true, description: 'Add a leading icon when it helps identify the token type — person icon for users, tag icon for labels.'},
+ {guidance: true, description: 'Keep labels to one to three words. Tokens truncate with ellipsis on overflow.'},
+ {guidance: false, description: 'Don\'t use tokens for actions or navigation — use Button or Link. Tokens display metadata, not trigger workflows.'},
+ {guidance: false, description: 'Don\'t hide the label unless the icon alone is universally clear.'},
+ {guidance: false, description: 'Don\'t mix too many colors in one group. Two or three meaningful colors keeps it scannable.'},
],
},
propDescriptions: {