XDS — Design System

Icon@xds/core · XDSIcon v0.0.13

Usage

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.

ts
import {XDSIcon} from '@xds/core/Icon'

Best practices

Guidance	Practices
Do	Use semantic icon names when available — they adapt to theme changes automatically.
Do	Pair icons with text labels for accessibility — icon-only elements need an accessible label.
Do	Use color tokens for icon colors, not hardcoded hex values.
Do	Be mindful of context — decorative icons in compact components can distract rather than help.
Don't	Use icons as the sole means of conveying meaning — always provide a text alternative.
Don't	Resize icons with arbitrary pixel values — use the provided size props.
Don't	Mix icon styles (e.g. outline and filled) within the same context.
Don't	Render raw SVG elements — always wrap in Icon for consistent sizing and color.

Examples

Common configurations, variations, and states.

Icon — Non-Semantic ColorsNon-semantic color palette for icons.

tsx
'use client';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack, XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
const colors = [
  'blue',
  'red',
  'green',
  'gray',
  'cyan',
  'teal',
  'yellow',
  'orange',
  'pink',
  'purple',
] as const;
export default function IconNonSemanticColors() {
  return (
    <XDSHStack gap={4} wrap="wrap">
      {colors.map((color) => (
        <XDSVStack key={color} gap={1} hAlign="center">
          <XDSIcon icon="search" color={color} />
          <XDSText type="supporting">{color}</XDSText>
        </XDSVStack>
      ))}
    </XDSHStack>
  );
}

Icon — Semantic ColorsAll semantic icon color variants with labels.

tsx
'use client';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack, XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function IconSemanticColors() {
  return (
    <XDSHStack gap={4} wrap="wrap">
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="search" color="primary" />
        <XDSText type="supporting">primary</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="menu" color="secondary" />
        <XDSText type="supporting">secondary</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="info" color="tertiary" />
        <XDSText type="supporting">tertiary</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="clock" color="disabled" />
        <XDSText type="supporting">disabled</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="calendar" color="accent" />
        <XDSText type="supporting">accent</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="success" color="positive" />
        <XDSText type="supporting">positive</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="error" color="negative" />
        <XDSText type="supporting">negative</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="warning" color="warning" />
        <XDSText type="supporting">warning</XDSText>
      </XDSVStack>
    </XDSHStack>
  );
}

Icon — Size VariantsAll icon sizes from extra-small to large.

tsx
'use client';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack, XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function IconSizes() {
  return (
    <XDSHStack gap={4}>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="search" size="xsm" />
        <XDSText type="supporting">xsm</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="search" size="sm" />
        <XDSText type="supporting">sm</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="search" size="md" />
        <XDSText type="supporting">md</XDSText>
      </XDSVStack>
      <XDSVStack gap={1} hAlign="center">
        <XDSIcon icon="search" size="lg" />
        <XDSText type="supporting">lg</XDSText>
      </XDSVStack>
    </XDSHStack>
  );
}

Icon — Status IndicatorsStatus list using semantic icons for success, warning, error, and info.

tsx
'use client';
import {XDSIcon} from '@xds/core/Icon';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
const statuses = [
  {icon: 'success' as const, color: 'positive' as const, label: 'Deployed successfully'},
  {icon: 'warning' as const, color: 'warning' as const, label: 'Build has warnings'},
  {icon: 'error' as const, color: 'negative' as const, label: 'Pipeline failed'},
  {icon: 'info' as const, color: 'accent' as const, label: 'New version available'},
] as const;
export default function IconStatusIcons() {
  return (
    <XDSVStack gap={3}>
      {statuses.map((status) => (
        <XDSHStack key={status.label} gap={2} vAlign="center">
          <XDSIcon icon={status.icon} color={status.color} size="sm" />
          <XDSText type="body">{status.label}</XDSText>
        </XDSHStack>
      ))}
    </XDSVStack>
  );
}

Showcase source

tsx
'use client';
import {XDSIcon} from '@xds/core/Icon';
export default function IconShowcase() {
  return <XDSIcon icon="search" color="primary" size="md" />;
}

Usage

import {XDSIcon} from '@xds/core/Icon'

Best practices

Guidance	Practices
Do	Use semantic icon names when available — they adapt to theme changes automatically.
Do	Pair icons with text labels for accessibility — icon-only elements need an accessible label.
Do	Use color tokens for icon colors, not hardcoded hex values.
Do	Be mindful of context — decorative icons in compact components can distract rather than help.
Don't	Use icons as the sole means of conveying meaning — always provide a text alternative.
Don't	Resize icons with arbitrary pixel values — use the provided size props.
Don't	Mix icon styles (e.g. outline and filled) within the same context.
Don't	Render raw SVG elements — always wrap in Icon for consistent sizing and color.

tsx

'use client'; import {XDSIcon} from '@xds/core/Icon'; import {XDSHStack, XDSVStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; const colors = [ 'blue', 'red', 'green', 'gray', 'cyan', 'teal', 'yellow', 'orange', 'pink', 'purple', ] as const; export default function IconNonSemanticColors() { return ( <XDSHStack gap={4} wrap="wrap"> {colors.map((color) => ( <XDSVStack key={color} gap={1} hAlign="center"> <XDSIcon icon="search" color={color} /> <XDSText type="supporting">{color}</XDSText> </XDSVStack> ))} </XDSHStack> ); }

tsx

'use client'; import {XDSIcon} from '@xds/core/Icon'; import {XDSHStack, XDSVStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; export default function IconSemanticColors() { return ( <XDSHStack gap={4} wrap="wrap"> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="search" color="primary" /> <XDSText type="supporting">primary</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="menu" color="secondary" /> <XDSText type="supporting">secondary</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="info" color="tertiary" /> <XDSText type="supporting">tertiary</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="clock" color="disabled" /> <XDSText type="supporting">disabled</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="calendar" color="accent" /> <XDSText type="supporting">accent</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="success" color="positive" /> <XDSText type="supporting">positive</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="error" color="negative" /> <XDSText type="supporting">negative</XDSText> </XDSVStack> <XDSVStack gap={1} hAlign="center"> <XDSIcon icon="warning" color="warning" /> <XDSText type="supporting">warning</XDSText> </XDSVStack> </XDSHStack> ); }

tsx

'use client'; import {XDSIcon} from '@xds/core/Icon'; import {XDSVStack, XDSHStack} from '@xds/core/Layout'; import {XDSText} from '@xds/core/Text'; const statuses = [ {icon: 'success' as const, color: 'positive' as const, label: 'Deployed successfully'}, {icon: 'warning' as const, color: 'warning' as const, label: 'Build has warnings'}, {icon: 'error' as const, color: 'negative' as const, label: 'Pipeline failed'}, {icon: 'info' as const, color: 'accent' as const, label: 'New version available'}, ] as const; export default function IconStatusIcons() { return ( <XDSVStack gap={3}> {statuses.map((status) => ( <XDSHStack key={status.label} gap={2} vAlign="center"> <XDSIcon icon={status.icon} color={status.color} size="sm" /> <XDSText type="body">{status.label}</XDSText> </XDSHStack> ))} </XDSVStack> ); }