# Iconography

Icons from the Tempo catalog, and how to size, color, and label them.

## Overview

Icons support a label rather than replace it. Every icon in the catalog shares one grid and stroke weight, so any group of icons reads as one family.



* **Grid (16 by 16):** Every icon draws on the same square grid.
* **Size (1em):** An icon matches the font size of its text.
* **Color (currentColor):** An icon fills with the color of its text.
* **Imports (one module each):** A build carries only the icons it imports.

```tsx
import { Send } from '@tempoxyz/ds/icons'

export function SendButton() {
  return (
    <Button>
      <Send />
      Send payment
    </Button>
  )
}
```

## Size and Color

Components size and color their own icons, so inside a [Button](/docs/components/button) you add only the icon as a child.

### Size

* **Beside Text (1em):** The default in buttons, links, and running text.
* **Beside Titles (20px):** A larger icon beside a section or card title.
* **Status Icons (20px):** A status icon beside a message, as in a [Toast](/docs/components/toast).
* **Alert Indicator (16px):** An [Alert](/docs/components/alert) marks its tone with a square in a 16px box.
* **Modal Icons (24px):** An [IconTile](/docs/components/icon-tile) frames the icon above a modal title.
* **Standalone Icons (fontSize):** Set its font size, not its width and height.

### Color

Set the color on the icon or its parent, with the same roles as text.

* **Primary (content.primary):** The default, beside primary labels and text.
* **Secondary (content.secondary):** Beside metadata, such as an update time.
* **Status (content.warning):** Only for an icon that reports a status.

## Guidelines

### Pair Icons With Text

Drop the label only for actions that are familiar without words, such as Close, Copy, and More. Don't give an icon to only one of several buttons, since it draws attention to that action.

**Do:** Use icon-only buttons for actions with a universal icon.

```tsx
<Button aria-label="Copy address" shape="icon" variant="secondary">
  <Copy />
</Button>
<Button aria-label="Delete contact" shape="icon" variant="secondary">
  <Delete />
</Button>
```

**Don't:** Drop the label from actions that have no universal icon.

```tsx
<Button aria-label="Wallets" shape="icon" variant="secondary">
  <Wallet />
</Button>
<Button aria-label="Access keys" shape="icon" variant="secondary">
  <Key />
</Button>
```

### Match Icons to Their Text

An icon that inherits from its label scales with the type and stays aligned. Any other color reads as a status.

**Do:** Let an inline icon inherit the size and color of its label.

```tsx
/**
 * Do example for "Match Icons to Their Text" on the Iconography page.
 * Let an inline icon inherit the size and color of its label.
 * @module
 */
import { Copy } from '@tempoxyz/ds/icons'
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <span {...styles.label()}>
      <Copy />
      Copy address
    </span>
  )
}

namespace styles {
  export const label = style({
    alignItems: 'center',
    color: 'content.primary',
    display: 'inline-flex',
    gap: '4',
    typography: 'body.b2Strong',
  })
}
```

**Don't:** Enlarge or recolor an inline icon apart from its text.

```tsx
/**
 * Don't example for "Match Icons to Their Text" on the Iconography page.
 * Don't enlarge or recolor an inline icon apart from its text.
 * @module
 */
import { Copy } from '@tempoxyz/ds/icons'
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <span {...styles.label()}>
      <Copy {...styles.icon()} />
      Copy address
    </span>
  )
}

namespace styles {
  export const icon = style({ color: 'accent.blue.background', fontSize: '30' })

  export const label = style({
    alignItems: 'center',
    color: 'content.primary',
    display: 'inline-flex',
    gap: '4',
    typography: 'body.b2Strong',
  })
}
```

### Use Catalog Icons Only

Icons from another set break the shared grid and stroke weight. If the catalog lacks an icon, propose one with its use case in the Design System project.

**Do:** Draw every icon in a group from the catalog.

```tsx
/**
 * Do example for "Use Catalog Icons Only" on the Iconography page.
 * Draw every icon in a group from the catalog.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { ArrowDownLeft, Send, SwapHorizontal } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button size="small" variant="secondary">
        <Send />
        Send
      </Button>
      <Button size="small" variant="secondary">
        <ArrowDownLeft />
        Receive
      </Button>
      <Button size="small" variant="secondary">
        <SwapHorizontal />
        Swap
      </Button>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

**Don't:** Mix in an icon from another set.

```tsx
/**
 * Don't example for "Use Catalog Icons Only" on the Iconography page.
 * Don't mix in an icon from another set.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { ArrowDownLeft, Send } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Button size="small" variant="secondary">
        <Send />
        Send
      </Button>
      <Button size="small" variant="secondary">
        <ArrowDownLeft />
        Receive
      </Button>
      <Button size="small" variant="secondary">
        {/* A heavier, rounded stroke on a 24 by 24 grid, as another icon set draws it. */}
        <svg
          aria-hidden="true"
          fill="none"
          stroke="currentColor"
          strokeLinecap="round"
          strokeLinejoin="round"
          strokeWidth="3"
          viewBox="0 0 24 24"
          {...styles.icon()}
        >
          <path d="M4 8h14l-4-4M20 16H6l4 4" />
        </svg>
        Swap
      </Button>
    </div>
  )
}

namespace styles {
  export const icon = style({ height: '1.25em !custom', width: '1.25em !custom' })

  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

* **Token Logos (TokenLogo):** Render token and network logos with [TokenLogo](/docs/components/token-logo).
* **Account Images (Identicon):** Render accounts with [Avatar](/docs/components/avatar) or [Identicon](/docs/components/identicon).

## Accessibility

* **Decorative by Default (aria-hidden):** An icon without `aria-label` or `aria-labelledby` is hidden, so screen readers skip it.
* **Meaningful Icons (role=img):** Add `aria-label` only if no nearby text states its meaning, such as a lone status icon.
* **Icon-Only Buttons (aria-label):** Label the button, not the icon. Name the action, such as Close dialog rather than X.
* **Tooltips (Tooltip):** Pair an icon-only button with a [Tooltip](/docs/components/tooltip) that repeats its label for sighted mouse users.
* **Contrast (3:1):** Applies to meaningful icons. Both `content.primary` and `content.secondary` pass.
* **Forced Colors (currentColor):** Icons follow the system text color in forced colors mode, with no extra styles.

## Catalog

* **Names (PascalCase):** Names match the design, such as `QRCode`.
* **Reserved Names (InfinityIcon):** Avoids the JavaScript global `Infinity`.
* **Shared Names (2):** A second icon with a taken name ends in `2`.
* **Component Names (as):** Rename on import, such as `TableIcon`.
* **Raw SVGs (.svg):** The original exports, for use outside React.

```tsx
import { Table } from '@tempoxyz/ds'
import { Table as TableIcon } from '@tempoxyz/ds/icons'
import copyUrl from '@tempoxyz/ds/icons/Copy.svg'
```



## Related

[Button](/docs/components/button)

Use for icon buttons and icons beside labels.

[IconTile](/docs/components/icon-tile)

Use for framed icons in headers and lists.

[Tooltip](/docs/components/tooltip)

Use for labelling icon buttons.

[Color](/docs/foundations/color)

Covers icon colors.
