XDS — Design System

Token@xds/core · XDSToken v0.0.13

Usage

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.

ts
import {XDSToken} from '@xds/core/Token'

Best practices

Guidance	Practices
Do	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.
Do	Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.
Do	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.
Do	Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows.
Don't	Don't use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.
Don't	Don't hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.
Don't	Don't mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.

Examples

Common configurations, variations, and states.

Token — ClickableInteractive tokens that respond to clicks. Use for toggleable filters or tokens that open a detail view when selected.

tsx
'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 (
    <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>
  );
}

Token — ColorsAll 11 color variants in default and disabled states. Use color to categorize entities or convey status at a glance.

tsx
'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>
  );
}

Token — End ContentTokens with trailing content like a count badge or status indicator after the label. Use for notification counts, item quantities, or compact status info.

tsx
'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>
  );
}

Token — IconTokens 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.

tsx
'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>
  );
}

Token — RemovableTokens with a dismiss button for selections the user can undo. Use in multi-select fields, active filters, or any list of user-chosen items.

tsx
'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>
  );
}

Showcase source

tsx
'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 (
    <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>
  );
}

Usage

import {XDSToken} from '@xds/core/Token'

Best practices

Guidance	Practices
Do	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.
Do	Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.
Do	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.
Do	Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows.
Don't	Don't use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.
Don't	Don't hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.
Don't	Don't mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.

tsx

'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 ( <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> ); }

tsx

'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> ); }

tsx

'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> ); }

tsx

'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> ); }

tsx

'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> ); }

tsx

'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 ( <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> ); }