Iconography

Drawing and Choosing Icons

Default posture: one icon set for the whole product, one effective stroke weight per surface, matched to the weight of the text it sits beside, and a label on anything whose metaphor the platform has not already taught. Icons change size by changing cut, not by scaling a single drawing — a 24px outline mark shrunk with CSS keeps detail that was never meant to survive at 12px, and its stroke lands off the pixel grid. This skill owns the structural constraint that makes one icon able to become another — matched primitive counts, the three-line budget, rotation groups — while the duration, curve and interruption behaviour of that morph belong to transitions, and whether it animates at all is decided by the frequency gate before either skill is loaded. Photographs, illustration, avatars and device frames are imagery.

Read which set the project already installs before drawing or importing anything. Check package.json for lucide-react, @radix-ui/react-icons, @phosphor-icons/react, @heroicons/react, material-symbols, or a local components/icons directory, and stay inside it. Adding a second set is the fastest way to make an interface look assembled rather than designed: two sets differ in grid, stroke, corner radius and terminal style, and those differences compound across a card grid until every row reads slightly wrong for a reason nobody can name.

Quick Reference

Core Principles

1. One set per product, and it is the set already installed. Stroke weight, terminal style and corner radius are set-wide decisions; mixing two sets re-litigates all three on every surface. Import from the existing package. Exception: the product's own logo and third-party brand marks (GitHub, Google, Slack) are never part of the icon set, are never restyled to match it, and are never redrawn.
2. Match the effective stroke to the adjacent text weight. A hairline icon beside semibold text reads as a mistake, and the number that matters is the rendered stroke, not the declared one: effective px = stroke-width × (rendered px ÷ viewBox units). Lucide's default stroke-width: 2 in a 24 box renders 1.33px at 16px. House default: text at weight 400–500 wants a 1.5px effective stroke; 600 and above wants 2px. Exception: filled sets such as Radix carry no stroke — match those by visual mass against a sample, since there is no number to compute.
3. Change the cut when the size changes; do not scale one drawing. Detail drawn for 24px turns to mush at 12px, and a 1px stroke disappears into antialiasing. Below roughly 12px, switch to the filled variant — Heroicons ships separate 20×20 and 16×16 solid sets for exactly this reason. Exception: variable icon fonts retune themselves; set Material Symbols' opsz axis (20–48) instead of swapping files.
4. Snap the drawn geometry to whole pixels at the size it will actually render. Half-pixel coordinates blur on 1× screens, and the blur reads as low quality without ever being identifiable. Radix Icons are drawn on a 15 grid, so they are half a pixel off at 16px — render them at 15px. Exception: icons only ever shown at 32px and above, or icons that are always in motion, where subpixel movement defeats hinting anyway.
5. Optical size is not box size — align by mass, not by box. A play triangle centred mathematically in a circle sits visibly left-heavy because its mass is on the left; nudge it about 1px toward the point. Exception: a row or grid of icons from one set already shares padding and alignment by construction; per-icon nudges there create the misalignment they were meant to fix.
6. An icon may stand alone only if the mark is already learned, the action is repeated, and the control is named to assistive tech. The floppy disk means nothing to anyone under thirty. Give the label to everything else, and give every icon-only control an aria-label naming the action: aria-label="Search", never aria-label="icon". Exception: the marks the platform has already taught — close, search, menu, back, add, overflow — which carry meaning without text.
7. Give an icon-plus-label pair a 6–8px gap. With no breathing room the two collide into one blob; with too much they read as separate controls. Exception: a compact density mode may drop to 4px, but only when the whole row's rhythm drops with it — spacing owns the density scale.
8. One icon, one meaning, product-wide. If a chevron means both "expand this accordion" and "go to the next page", users reliably learn neither; if a star means both "favourite" and "rating", the state is ambiguous. Pick a distinct mark for the second meaning. Exception: rotation groups — a chevron at 0deg, 90deg, 180deg and 270deg is one meaning (disclosure) pointed four ways, and that is a legitimate reuse.
9. Icons that will ever morph share a primitive budget from the moment they are drawn. Benji Taylor's icon set gives every icon exactly three SVG lines, collapsing the spares to invisible points where an icon needs fewer, which is what makes any icon in the set able to become any other. Retrofitting that onto arbitrary paths does not work. Exception: shapes that cannot be reconciled — play to pause — crossfade or swap; forcing a morph there produces a smear.
10. Union multipath icons into one path with one fill, coloured by currentColor. Multiple fills mean multiple things to theme, to invert for dark mode, and to break. Exception: duotone and two-tone sets, where the second layer is the design — declare both layers as currentColor with an opacity rather than hardcoding a grey that will not survive a theme change.

Smell / Fix

Output Format

When handing back a drawn or corrected icon, ship the SVG itself with viewBox, stroke-width, stroke-linecap and stroke-linejoin explicit, fill="none" and stroke="currentColor" for outline sets, no width/height attributes (the consumer sizes it), and one line stating which render sizes it is cut for and its effective stroke at each. When auditing a set rather than drawing one, report per surface: which set each icon came from, its effective stroke, and the adjacent text weight.

Checklist

• Every icon on the surface comes from one set
• Effective stroke computed and matched to adjacent text weight
• Small sizes use the small cut or the filled variant, not a scaled-down drawing
• Geometry lands on whole pixels at the intended render size
• Optically centred where the mark's mass is off-centre
• Every icon-only control has an aria-label naming the action
• Icon-plus-label gap is 6–8px
• No mark carries two meanings
• currentColor, single path, single fill; no hardcoded hex
• viewBox present, width/height absent
• Any morphing pair shares a primitive count; timing deferred to transitions