# IconTile

An icon in a tinted tile: a stat's category, an empty state, a step in a
list. Avatar's sibling. Avatar is a person, drawn from their name; IconTile
is a thing, coloured by meaning (a theme). They share one size ladder so
they line up in the same list.

Decorative by default: the text beside it says what it means. Give it a
`label` when it stands alone. Not interactive: wrap it in a Button to act.

```tsx
import { IconTile } from '@tangible/ui';
```

Interactive docs and examples: [IconTile in Storybook](https://design.tangible.one/?path=/docs/primitives-icontile--docs).

## IconTile props

| Prop | Type | Default | Description |
| - | - | - | - |
| `icon` | `IconSource` | | The icon, by registry name (`"system/folder"`) or as an imported icon component |
| `label?` | `string` | | Names the tile as an image. Leave it out when the text beside the tile already says what it means (the usual case): the tile is then decorative and hidden from assistive tech. Don't repeat text that's already beside it, or it's read twice. Blank or whitespace-only counts as no label. |
| `shape?` | `"circle" \| "square"` | `"square"` | Default `square` (radius-md) |
| `size?` | `"lg" \| "md" \| "sm" \| "xl" \| "xs" \| "xxl"` | `"md"` | Default `md` (40px). The same ladder as Avatar, so the two line up in a list. |
| `theme?` | `"danger" \| "info" \| "primary" \| "secondary" \| "success" \| "warning"` | `"primary"` | Default `primary`. Meaning, not identity: the tint and icon colour follow the theme. |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

## Examples

- [Default](https://design.tangible.one/?path=/story/primitives-icontile--default): A 40px square in the primary tint

- [Sizes](https://design.tangible.one/?path=/story/primitives-icontile--sizes): Avatar's ladder: xs 24, sm 32, md 40, lg 48, xl 64, xxl 80. The icon is half the box.

- [Themes](https://design.tangible.one/?path=/story/primitives-icontile--themes): Colour is meaning, not identity: each theme's -subtlest tint with its -strong icon

- [Shapes](https://design.tangible.one/?path=/story/primitives-icontile--shapes): Square (radius-md) by default; circle for a softer mark, as in empty states

- [Beside Avatar](https://design.tangible.one/?path=/story/primitives-icontile--beside-avatar): The same box ladder as Avatar: a tile and an avatar line up in one list.

- [Labelled](https://design.tangible.one/?path=/story/primitives-icontile--labelled): Standing alone, with no text beside it: named, so it isn't silent.

- [Themes Dark](https://design.tangible.one/?path=/story/primitives-icontile--themes-dark): Dark mode: the tints and icon colours follow the dark palette, still 3:1 or better

- [Custom Tokens](https://design.tangible.one/?path=/story/primitives-icontile--custom-tokens): Restyled through its tokens: --tui-icon-tile-bg, -fg, -radius and -size

- [Empty State](https://design.tangible.one/?path=/story/primitives-icontile--empty-state): An empty state: the tile is decorative because the heading beside it says
  what's happening. Labelling it too would make a screen reader say it twice.

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-icon-tile-size`
- `--tui-icon-tile-radius`
- `--tui-icon-tile-bg`
- `--tui-icon-tile-fg`

---

Interactive version: https://design.tangible.one/?path=/docs/primitives-icontile--docs
