# Icons: design playbook

> One set, one stroke, the weight of the words beside it, and only where an icon says something the text can't.

Checked 2026-10-29. Each value says where it came from: published, our reading, or our recipe.

## Pick a set

Our reading. Apple: match the weight of interface icons to the text beside them. Material: rounded icons go with curved, heavier type; sharp icons with rectangular details. Strokes below are measured at 24px from each set's own files.

Take the first row that matches the brand.

1. **The brand publishes an icon stroke** → the set whose stroke at 24px is closest to the published one, scaled to 24px. The brand's own number beats our table.
2. **Sharp corners: button radius 0–2px** → remix line. Square terminals and 90° interiors echo rectangular UI.
3. **Round brand: pill buttons** → lucide line, 2px. Round caps and joins everywhere, and a 2px stroke that holds up next to pill buttons.
4. **Light type: body weight 300 or less** → phosphor light. A 1.125px stroke at 24px matches thin stems.
5. **Heavy type: display weight 700 or more** → phosphor bold. A 2.25px stroke at 24px matches heavy stems.
6. **Medium type: display weight 500 or less** → heroicons outline, 1.5px. A 1.5px stroke sits with regular-weight type.
7. **Anything else** → lucide line, 2px. The most complete open set, with the most checkable spec.

## Rules

### 1. One icon set and one style per page.

- Value (published): Every icon on the page comes from the same set and style.
- Check: Every svg.ic carries the same data-lib and data-style.
- Sources: https://lucide.dev/how-to/icon-guide, https://developer.apple.com/design/human-interface-guidelines/icons, https://www.ibm.com/design/language/iconography/ui-icons/usage/

### 2. One stroke width per rendered size.

- Value (published): Effective stroke = stroke-width × rendered width ÷ viewBox width; all equal within a size.
- Check: Compute the effective stroke of every stroked icon at each size; fail if two differ.
- Sources: https://developer.apple.com/design/human-interface-guidelines/icons, https://lucide.dev/contribute/icons/specification

### 3. Don't blow a small icon up; above 32px, stop thickening the stroke.

- Value (our recipe): IBM thickens the stroke with size: 1px at 16, 1.25px at 20, 1.5px at 24, 2px at 32. Material's optical-size axis thins strokes at large sizes. Our recipe: above 32px, hold the stroke at the set's 32px value.
- Why: IBM's table stops at 32 and Material thins large icons; holding at 32 is the simplest rule that follows both.
- Check: Above 32px, effective stroke ≤ the set's stroke at 32px (its 24px stroke × 32 ÷ 24).
- Sources: https://www.ibm.com/design/language/iconography/ui-icons/design/, https://primer.style/octicons/usage-guidelines/

### 4. Match the icon's weight to the text beside it.

- Value (published): Use the pick table: it matches the set's stroke to the brand's type weight and corners.
- Check: The page's set and style equal the pick table's row for this brand.
- Sources: https://developer.apple.com/design/human-interface-guidelines/sf-symbols

### 5. Size the icon to the text it sits with.

- Value (published): IBM: a 16px icon with 14px text, a 20px icon with 16px text.
- Check: Icon height ÷ label font size is between 1.14 and 1.25 (IBM's two pairs).
- Sources: https://www.ibm.com/design/language/iconography/ui-icons/usage/

### 6. Center the icon on the text, don't sit it on the baseline.

- Value (published): Icon center equals the line's center, within 1px.
- Check: In a flex row, align-items is center; no inline-block icon has vertical-align baseline.
- Sources: https://carbondesignsystem.com/elements/icons/usage/

### 7. Draw icons in the text color, one color per icon.

- Value (published): fill or stroke is currentColor; a duotone back layer may be the accent.
- Check: Every non-none fill and stroke is currentColor, or the label's computed color.
- Sources: https://carbondesignsystem.com/elements/icons/usage/, https://fluent2.microsoft.design/iconography

### 8. Filled means selected. Outline means everything else.

- Value (published): In a nav, tab bar or toggle group, only the current item is filled.
- Check: At most one filled icon per single-select group, on the element with aria-current or aria-selected.
- Sources: https://fluent2.microsoft.design/iconography, https://developer.apple.com/design/human-interface-guidelines/sf-symbols, https://developers.google.com/fonts/docs/material_symbols

### 9. Make every icon button at least 44 × 44px to tap.

- Value (published): 44px hit area (Apple, IBM, Lucide; WCAG AAA). 24px is the legal floor (WCAG 2.5.8 AA). The glyph can stay 20–24px.
- Check: The nearest button or link around an icon measures at least 44 × 44.
- Sources: https://developer.apple.com/design/human-interface-guidelines/buttons, https://www.w3.org/TR/WCAG22/

### 10. Hide icons that repeat their label; name icon-only buttons.

- Value (published): Beside text: aria-hidden="true". Alone in a button: aria-label on the button.
- Check: An svg beside text has aria-hidden; a button with only an svg has a non-empty accessible name.
- Sources: https://lucide.dev/how-to/accessibility, https://primer.style/octicons/usage-guidelines/

### 11. Use icons only where they add meaning.

- Value (published): Never the same icon on three or more siblings; one meaning per icon, one icon per meaning.
- Check: Fail when 3+ siblings share an identical icon; fail when one icon name sits beside two different labels.
- Sources: https://lucide.dev/how-to/icon-guide, https://atlassian.design/foundations/iconography, https://www.ibm.com/design/language/iconography/ui-icons/usage/

### 12. No emoji standing in for icons.

- Value (our reading): Emoji are for what people type, not for the interface.
- Why: Primer reserves emoji for content people choose; we apply it to marketing pages.
- Check: No \p{Extended_Pictographic} in buttons, links, headings, list markers or icon slots.
- Sources: https://primer.style/octicons/usage-guidelines/

## What AI gets wrong

- **Mixing sets.** Heroicons in the nav, Lucide in the features, Font Awesome in the footer: strokes, caps and corners disagree. (rule: one-set)
- **Emoji as icons.** Multicolor, different on every phone, and blind to the brand's colors and weights. (rule: no-emoji)
- **Icon soup.** A check or sparkle on every bullet, adding nothing the words don't say. (rule: sparingly)
- **Stroke that fights the type.** A 2px stroke beside light type, or a 24px icon blown up to 64px with a 5px stroke. (rule: stroke-by-size)
- **Fill as decoration.** Filled icons used for emphasis, so nothing reads as selected. (rule: fill-is-state)
- **Tiny targets.** The 20px glyph is the whole button, sitting low on the baseline. (rule: target)

## Sets

### Lucide

- Package: `lucide-static@1.64.0`, ISC (https://github.com/lucide-icons/lucide/blob/main/LICENSE)
- Canvas 24px, drawn as stroke; styles: Line (2px)
- Files: search=search, arrow-right=arrow-right, check=check, close=x, user=user, calendar=calendar, chart=chart-column, mail=mail, lock=lock, settings=settings, home=house, heart=heart, bell=bell, download=download, play=play, spark=sparkles

### Phosphor

- Package: `@phosphor-icons/core@2.1.1`, MIT (https://github.com/phosphor-icons/core/blob/main/LICENSE)
- Canvas 24px, drawn as fill; styles: Thin (0.75px), Light (1.125px), Regular (1.5px), Bold (2.25px), Fill, Duotone
- Files: search=magnifying-glass, arrow-right=arrow-right, check=check, close=x, user=user, calendar=calendar, chart=chart-bar, mail=envelope, lock=lock, settings=gear, home=house, heart=heart, bell=bell, download=download, play=play, spark=sparkle

### Tabler

- Package: `@tabler/icons@3.50.0`, MIT (https://github.com/tabler/tabler-icons/blob/main/LICENSE)
- Canvas 24px, drawn as stroke; styles: Outline (2px)
- Files: search=search, arrow-right=arrow-right, check=check, close=x, user=user, calendar=calendar, chart=chart-bar, mail=mail, lock=lock, settings=settings, home=home, heart=heart, bell=bell, download=download, play=player-play, spark=sparkles

### Heroicons

- Package: `heroicons@2.2.0`, MIT (https://github.com/tailwindlabs/heroicons/blob/master/LICENSE)
- Canvas 24px, drawn as stroke; styles: Outline (1.5px), Solid (1.5px)
- Files: search=magnifying-glass, arrow-right=arrow-right, check=check, close=x-mark, user=user, calendar=calendar, chart=chart-bar, mail=envelope, lock=lock-closed, settings=cog-6-tooth, home=home, heart=heart, bell=bell, download=arrow-down-tray, play=play, spark=sparkles

### Iconoir

- Package: `iconoir@7.12.1`, MIT (https://github.com/iconoir-icons/iconoir/blob/main/LICENSE)
- Canvas 24px, drawn as stroke; styles: Regular (1.5px)
- Files: search=search, arrow-right=arrow-right, check=check, close=xmark, user=user, calendar=calendar, chart=stats-report, mail=mail, lock=lock, settings=settings, home=home, heart=heart, bell=bell, download=download, play=play, spark=sparks

### Remix Icon

- Package: `remixicon@4.9.1`, Apache-2.0 (https://github.com/Remix-Design/RemixIcon/blob/master/License)
- Canvas 24px, drawn as fill; styles: Line, Fill
- Files: search=search, arrow-right=arrow-right, check=check, close=close, user=user, calendar=calendar, chart=bar-chart, mail=mail, lock=lock, settings=settings-3, home=home, heart=heart, bell=notification-3, download=download, play=play, spark=sparkling

### Material Symbols

- Package: `@material-symbols/svg-400@0.48.2`, Apache-2.0 (https://github.com/google/material-design-icons/blob/master/LICENSE)
- Canvas 24px, drawn as fill; styles: Outlined, Rounded, Filled
- Files: search=search, arrow-right=arrow_forward, check=check, close=close, user=person, calendar=calendar_month, chart=bar_chart, mail=mail, lock=lock, settings=settings, home=home, heart=favorite, bell=notifications, download=download, play=play_arrow, spark=stars

## Not published anywhere we read

- No system publishes the gap between an icon and its label as a number; ours is 0.5em, our recipe.
- Material 3's icon pages render client-side and couldn't be read; Material values here are from Material 2 (2019) and the Material Symbols developer guide.
- Remix and Iconoir publish no craft guide; their strokes are measured from their files.
