# Iconography

Icons name an action or an object where a word would take too much room. They come from one family, Lucide, on one grid, with a stroke set by their size.

* Kind: foundation
* Page: https://design.werklist.com/foundations/iconography
* Version: 2.1.2

## When to use it

* As the only label of an icon button, with a name and a tooltip, such as Search in a toolbar.
* To mark an action that repeats down a dense list, such as the remove button at the end of each candidate row.

## When not to use it

* Menu rows, headings, empty states and notification cards.
* An icon beside a word that says the same thing, such as a pencil before Edit.
* A second icon set, an emoji or a brand logo.
* A colored or gradient icon in navigation.
* A 12 px icon as the target of a button.

## Rules

* Icons come from Lucide. A shape Lucide lacks is drawn on the same grid, at the same stroke, in one color.
* The icon box is 4 to 6 px smaller than the line height of the text beside it.
* Between an icon and its label: 8 px.
* The stroke gets lighter as the icon grows, so each size reads at the same weight.
* One icon per action on every screen, by its Lucide name: Close is x, Confirm or selected is check, Add is plus, Delete is trash-2, Edit is pencil, Search is search, Copy is copy, Download is download, Share is share-2, More actions is ellipsis, Open or expand is chevron-down, Go to is chevron-right, Open in a new tab is external-link, Attach is paperclip, Undo is undo-2, Retry is rotate-ccw, Warning is triangle-alert, Loading is loader-circle, WerkAI is sparkles.
* Sparkles belongs to WerkAI alone.
* In one navigation group, neighbors do not share a silhouette.
* In navigation the current item takes the full ink and the others the lighter ink. Color on a glyph is kept for a verdict, such as a green check or a red cross.

## Anatomy

* Grid: 24 by 24
* Caps and joins: round
* Stroke: set by the size of the icon
* Color: the ink of its label (currentColor)

## Sizes

* 12 px, information only: height 12 px, stroke 2
* 14 px, beside 12 and 13 px text: height 14 px, stroke 2
* 16 px, beside 13 and 14 px text, the default: height 16 px, stroke 1.75
* 20 px, beside 16 px text: height 20 px, stroke 1.75
* 24 px, navigation rail and mobile bar: height 24 px, stroke 1.5

## States

* At rest: the ink of its label (--text)
* Other items in navigation: the lighter ink (--text-muted)
* Current or pressed: the full ink and a stroke 0.25 heavier (--text)

## Accessibility

* An icon only control has a name, such as Remove candidate, and shows the same words in a tooltip.
* An icon beside a label that says the same thing is hidden from screen readers.
* An icon that carries meaning outside a control, such as a warning beside a CV that did not upload, has a text alternative.
* An icon keeps 3 to 1 against its ground in both themes. The lighter ink measures 4.74 to 1 on white.
* A state shows by shape as well as color.
* On touch screens the target around an icon is 44 by 44 px, whatever the size of the icon.

## Tokens

* --text
* --text-muted
* --space-2