Iconography

Icons name an action or an object where a word would take too much room. Use them only where they carry meaning, drawn from one family in the ink of the text beside them.

When an icon belongs

An icon earns its place in two cases. It is the only label on a control, such as Search or Close in a toolbar, or it marks an action that repeats down a dense list, such as the remove button at the end of each candidate row.

Remove the icon and read the screen again. If nothing is lost, leave it out. A pencil in front of the word Edit only repeats the word.

Menu rows, headings, empty states and notification cards carry no icon. A word reads faster there.

Light theme

Dark theme

One family, one grid

WerkOS draws its icons from Lucide: outlines on a 24 by 24 grid with round caps and joins. When a module needs a shape Lucide lacks, draw it on the same grid, at the same stroke, in one color.

Do not mix in a second icon set, an emoji or a brand logo. A different stroke or corner shows at once in a row of icons.

An icon takes the color of its label, so it needs no dark version. In navigation the current item's icon takes the full ink and the others a lighter one. Color on a glyph is kept for a verdict, such as a green check or a red cross.

Download CV

Light theme

Download CV

Dark theme

Grid: 24 by 24
Caps and joins: round
Color: the ink of its label; currentColor
Current item in navigation: full ink; --text
Other items in navigation: lighter ink; --text-muted

Sizes and stroke

12 px, stroke 2information only
14 px, stroke 2beside 12 and 13 px textSearch candidates
16 px, stroke 1.75beside 13 and 14 px text, the defaultSearch candidates
20 px, stroke 1.75beside 16 px textSearch candidates
24 px, stroke 1.5navigation rail and mobile bar
Current or pressedstroke 0.25 heavierRestPressed

Take the icon box from the line height of the text beside it, about 4 to 6 px less. The stroke gets lighter as the icon grows, so each size reads at the same weight.

A 12 px icon only informs, for example a small glyph beside a value. It is too small to press, so do not make it the target of a control.

Space between icon and label: 8 px; --space-2

One icon per action

Use the same icon for the same action on every screen, and do not give one icon two meanings. Sparkles belongs to WerkAI alone.

In one navigation group, neighbors must not share a silhouette. A clock beside a gauge reads as two clocks.

Closex
Confirm or selectedcheck
Addplus
Deletetrash-2
Editpencil
Searchsearch
Copycopy
Downloaddownload
Shareshare-2
More actionsellipsis
Open or expandchevron-down
Go tochevron-right
Open in a new tabexternal-link
Attachpaperclip
Undoundo-2
Retryrotate-ccw
Warningtriangle-alert
Loadingloader-circle
WerkAIsparkles

Names and contrast

Give an icon only control its name, for example an aria-label of Remove candidate, and show the same words in a tooltip. Hide an icon from screen readers when a visible label already says the same thing.

An icon that carries meaning outside a control, such as a warning beside a CV that did not upload, needs a text alternative. Show a state by shape as well as color, so it survives grayscale print and color blindness.

Keep 3 to 1 between an icon and its ground in both themes. On touch screens the target around an icon is 44 by 44 px, whatever the size of the icon.

Contrast of a glyph: at least 3 to 1
Lighter ink on white: 4.74 to 1; --text-muted
Touch target: 44 by 44 px

Permitted and not permitted

Permitted

An icon only button with a name
Search candidates and More actions in a toolbar, each announced and shown in a tooltip.
The same icon for the same action
The trash can means delete wherever it appears.
An icon in the ink of its label
It follows the theme with no second file.

Not permitted

An icon in a menu row
The word already names the action, and the icon slows the scan.
A colored or gradient icon in navigation
The current item shows as full ink, not as color.
An emoji in place of an icon
Emoji differ from one system to the next and break the stroke of the set.
A 12 px icon as the target of a button
Use 16 px or larger on anything a reader presses.

NextMotion

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

JSON

{
  "title": "Iconography",
  "path": "/foundations/iconography",
  "url": "https://design.werklist.com/foundations/iconography",
  "text": "https://design.werklist.com/agent/foundations/iconography",
  "summary": "Which icons to use, at what size and stroke, and when a word does the job better.",
  "version": "2.1.2",
  "kind": "foundation",
  "name": "Iconography",
  "purpose": "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.",
  "use": [
    "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."
  ],
  "avoid": [
    "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."
  ],
  "anatomy": [
    {
      "part": "Grid",
      "measure": "24 by 24"
    },
    {
      "part": "Caps and joins",
      "measure": "round"
    },
    {
      "part": "Stroke",
      "measure": "set by the size of the icon"
    },
    {
      "part": "Color",
      "measure": "the ink of its label",
      "token": "currentColor"
    }
  ],
  "sizes": [
    {
      "name": "12 px, information only",
      "height": "12 px, stroke 2"
    },
    {
      "name": "14 px, beside 12 and 13 px text",
      "height": "14 px, stroke 2"
    },
    {
      "name": "16 px, beside 13 and 14 px text, the default",
      "height": "16 px, stroke 1.75"
    },
    {
      "name": "20 px, beside 16 px text",
      "height": "20 px, stroke 1.75"
    },
    {
      "name": "24 px, navigation rail and mobile bar",
      "height": "24 px, stroke 1.5"
    }
  ],
  "states": [
    {
      "name": "At rest",
      "change": "the ink of its label",
      "tokens": [
        "--text"
      ]
    },
    {
      "name": "Other items in navigation",
      "change": "the lighter ink",
      "tokens": [
        "--text-muted"
      ]
    },
    {
      "name": "Current or pressed",
      "change": "the full ink and a stroke 0.25 heavier",
      "tokens": [
        "--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"
  ],
  "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."
  ]
}

Raw file: https://design.werklist.com/agent/foundations/iconography