---
name: icon-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Icon tokens or
Iconify classes with the library's supported size and semantic color props.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/atoms/icon.tsx libs/ui/src/tokens/components/atoms/_icon.css libs/ui/stories/atoms/icon.stories.tsx libs/ui/src/atoms/icon.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Icon Usage
Use Icon for decorative or component-adjacent icons. The Icon atom renders
`aria-hidden` by default, so it must not be the only accessible content for an action.
A meaningful standalone icon (a status glyph with no text beside it) takes `label`
and renders as `role="img"`.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Icon`.
**Use it when**
- Decorative icons that support adjacent text (status, list items, headings).
- Icons inside components that render them for you (Button `icon`, StatusText).
**Use something else when**
| Need | Use instead |
| --- | --- |
| A clickable icon | ActionIcon (with `aria-label`) or Button with `icon` |
| An icon that carries meaning without text | Icon with `label`, or visible status text |
**Do**
- Use one icon set and consistent size per context (the kit's icon tokens).
- Use the same icon for the same meaning everywhere (trash = delete, pencil = edit).
- Keep icons decorative — the text must carry the meaning.
**Don't**
- Use emoji as icons.
- Attach `onClick` to an Icon.
- Use colour-only icons to convey status.
**Copy and states**
- No text inside icons; meaning lives in the adjacent label.
**Behaviour (from the UX spec)**
- Classify every icon first: decorative (`aria-hidden`, the default), informative (`label`, or visible text), or inside a control (the control has the name).
- `size="current"` is 1em of the surrounding text in code but a fixed 16 px preview in Figma; don't read Figma sizes literally.
- Pick a `token-icon-*` glyph by its meaning in the host's slot. The glyph → meaning → host table, with what each glyph never means, is on the UX page.
**Figma → code**
| Figma | Code |
| --- | --- |
| `size=current` (16 px preview) | `size="current"` (1em) |
| `size=xs…2xl`, `severity=current…warning` | same prop names and values |
| `token-icon-cog`, `-filter`, `-sort-unfold`, `-drag-horizontal`, `-drag-vertical`, `-row-edit`, `-table-empty` | no token; DataTable uses `icon-[mdi--…]` classes |
| glyph doc "Vazba" (host) | ignore; the host is whichever component uses the token in code |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Icon → UX guidelines*.
## Setup
```tsx
import { Icon } from "@techsio/ui-kit/atoms/icon"
```
The component defaults to `size="current"` and `severity="current"`, inheriting
surrounding text. Choose an explicit size for standalone glyphs; the Playground
uses a recognizable Home icon at `lg` (the system's 24px step), not an error icon.
The Sizes story compares Small (`sm`), Medium (`md`) and Large (`lg`) in that order with the same icon. The `current`, `xs`, `xl` and `2xl` API sizes remain available for inherited, compact or decorative contexts; they are not canonical control sizes.
Explicit color props consume `--color-icon-fg-*` component aliases, so app token
overrides work without changing every icon call site.
The Storybook Gallery searches the curated common token glyphs and Iconify
examples by visible name, class name or category. Each result shows its exact
class for copying; clearing the search returns keyboard focus to the search field.
The gallery is not an exhaustive catalog of every component's private icon aliases. Iconify class names must be statically present in source
so the CSS generator can include them.
Supported props:
```text
icon: token-icon-${string} | icon-[${string}]
size: current | xs | sm | md | lg | xl | 2xl
color: current | primary | secondary | danger | success | warning
```
## Core Patterns
### Prefer token icons for UI-kit semantics
```tsx
```
Use `icon-[...]` for specific Iconify icons only when there is no token icon
for that component state.
### Match icon size to component size
```tsx
```
When a component has an `icon` prop, use that prop instead of placing a
separate Icon next to text.
### Provide accessible text outside Icon
```tsx
```
Icon itself is decorative. The parent action or surrounding text carries the
accessible name.
### Label a meaningful standalone icon
```tsx
```
Use `label` only when the icon is not inside a control and no text next to it
says the same thing. Never put `label` on an icon inside a labelled button.
## Common Mistakes
### HIGH Inline SVG instead of token/icon class
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/icon.tsx
### HIGH Icon-only button without accessible name
Wrong:
```tsx
```
Correct:
```tsx
```
The icon is `aria-hidden`.
Source: libs/ui/src/atoms/icon.tsx
### MEDIUM Arbitrary color class
Wrong:
```tsx
```
Correct:
```tsx
```
Change component or semantic tokens when the app needs different color mapping.
### MEDIUM Separate Icon beside Button text
Wrong:
```tsx
```
Correct:
```tsx
```
Use component icon props when they exist.
## Validation Commands
```sh
rg -n "