Icon

When to use

Use Icon for small glyphs that support or replace text: button and field icons, status marks, menu items. All icons come from a single registry.

When not to use

• For decorative pictures or drawings: Icon draws only registry glyphs; use an image for illustrations and photos.
• For interaction: Icon is not clickable and takes no focus. To act on an icon, use IconButton.
• For a glyph that is not in the registry: An unknown name is a type error. Add the name to the registry first.

Anatomy

xssmmdlgxl

LightDark

Copy code

import { Icon } from '@bigbang/ui';

export default function Sizes() {
  return (
    <div className="flex items-end gap-lg">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <span key={size} className="flex flex-col items-center gap-xs">
          <Icon name="star" size={size} />
          <code className="type-body-sm text-fg-subtle">{size}</code>
        </span>
      ))}
    </div>
  );
}

1. Glyph: The SVG that matches the registry name; stroke width 2, focusable="false".
2. Box: A square from the icon-size-* token; xs 12 px up to xl 32 px.

Behaviour

• Icon is static: it does not change on hover, click or focus, and it is not in the tab order.
• name is a type error, not a runtime fallback: a name that is not in the registry does not compile.
• The default tone="current" takes the icon colour from the surrounding text; when the text colour changes, so does the icon.
• size="inherit" fits the icon to the box of the parent component (size-full). Button icon slots use it.
• arrow-left, arrow-right, chevron-left, chevron-right, external-link and log-out flip horizontally under dir="rtl".
• Without label, the icon carries aria-hidden="true"; with label, it gets role="img" and aria-label.

Guidelines

Use the icon with text

Icons alone can be unclear. With text, the icon is decoration; without text, give the icon a label.

Download

DoThe text names the action; the icon only supports it.

Don'tA lone icon with no name: its meaning is unclear.

Tone for meaning, meaning for tone

Use the danger, success, warning and info tones only for their meaning. For decoration, current or subtle is enough.

DoThe warning icon is in the warning tone and has a name.

Don'tThe danger tone on a decorative icon raises a false alarm.

Do not name an icon inside a control

An icon inside a Button stays decorative; the control carries the name. With a label on the icon, the name is announced twice.

Content

• label is one or two words and says what the icon means: “Warning”, “Information”.
• Write the meaning of the icon, not its look (“red triangle”).
• Give label only when the icon alone carries information; skip it when text next to it already says so.

Turkish	English	Icon and tone
Uyarı	Warning	triangle-alert, warning
Bilgi	Information	info, info
Başarılı	Success	circle-check, success
Hata	Error	circle-x, danger

Related components

• Button: startIcon and endIcon slots take an icon with size="inherit".
• Badge: Takes a 12 px decorative icon with startIcon.
• Provider: With direction="rtl", icons that follow the reading direction flip.