# Visuals

## Icon

Unified icon wrapper that resolves to the correct sub-component based on the icon category.

```tsx
import { Icon } from '@theorchard/suite-components';
```

Use `Icon` as a single import when you need to render any icon type. Use the specific sub-components (`GlyphIcon`, `AppIcon`, `BrandIcon`, `StoreIcon`) when you know the category.

---

## GlyphIcon

Graphic symbol from the Orchard glyph set. Used for UI actions, status indicators, and decorative marks.

```tsx
import { GlyphIcon } from '@theorchard/suite-icons';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `name` | `GlyphName` | Glyph identifier (typed union) |
| `size` | `12 \| 16 \| 24` | Icon size in px |
| `className` | string | Additional CSS classes |

### Size Guidance

| Size | Usage |
|---|---|
| 12px | Compact / small controls (table cells, small badges) |
| 16px | Default — inline with text, form controls |
| 24px | Large buttons, section headers |

### Example

```tsx
<GlyphIcon name="edit" size={16} />
<GlyphIcon name="warning" size={24} />
```

Do NOT use arbitrary sizes — only 12, 16, or 24 are supported.

---

## AppIcon

Visual identifier for an application. Shows a gradient icon that represents the app.

```tsx
import { AppIcon } from '@theorchard/suite-icons';
```

The gradient colours (`app-icon-gradient-color-0` → `app-icon-gradient-color-1`) are controlled by the active theme.

---

## BrandIcon

External brand logo provided by business units.

```tsx
import { BrandIcon } from '@theorchard/suite-components';
```

Use for displaying partner brand logos in dropdowns, tables, or detail pages.

---

## NavIcon

App-section icon used inside navigation items to communicate the scope of each section.

```tsx
import { NavIcon } from '@theorchard/suite-components';
```

Use only inside `MainNav.NavLink` — not as a standalone decorative element.

---

## StoreIcon

Visual identifier for a music distribution store (Spotify, Apple Music, etc.).

```tsx
import { StoreIcon } from '@theorchard/suite-components';
```

Used in tables, dropdowns, and detail pages to represent distribution channels.

---

## CountryFlag

Country flag glyph for representing countries in compact contexts.

```tsx
import { CountryFlag } from '@theorchard/suite-components';
```

Used in `CountrySelect`, table cells, and tag displays to represent countries visually.

---

## CoverArt

Container for product, artist, or video cover images with standardised sizes and a placeholder.

```tsx
import { CoverArt } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `src` | string | Image URL |
| `size` | string | Standardised size key |
| `alt` | string | Accessible alt text |

Use `CoverArt` for all product/artist images — never use a raw `<img>` or the deprecated `Image` component.

---

## UserThumb

User profile picture with initials-based colour placeholder.

```tsx
import { UserThumb } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `src` | string | Profile image URL (optional — falls back to initials) |
| `name` | string | User display name (used for initials and alt text) |
| `size` | string | Standardised size key |

Use `UserThumb` anywhere a user avatar is displayed. Do NOT render a raw `<img>` for profile pictures.

---

## Illustration

Generic product illustration for empty or error states.

```tsx
import { Illustration } from '@theorchard/suite-components';
```

Use alongside `InfoMessage` or `ErrorMessage` to add a visual element to empty/error states.

## Decision Tree: Choosing an Icon Component

```
Displaying a UI action or status symbol? → GlyphIcon
Displaying an app identity? → AppIcon
Displaying a brand logo? → BrandIcon
Displaying a nav section icon? → NavIcon
Displaying a store / DSP? → StoreIcon
Displaying a country? → CountryFlag
Displaying a product/artist image? → CoverArt
Displaying a user avatar? → UserThumb
Don't know which type? → Icon (auto-resolves)
```

## Common Mistakes

- Do NOT use raw `<img>` for cover art — use `CoverArt`.
- Do NOT use the deprecated `Image` component.
- Do NOT use non-standard glyph sizes — only 12, 16, 24 are supported.
- Do NOT use `NavIcon` outside of navigation context.