UI icon library

The library

Interaction-state variants

Same glyph, five interaction states. Stroke weight jumps from 1.75px to 2.25px on active. Fill mode is reserved for selection and toggles.

Rules the library ships with

• Every glyph fits inside 20×20 with a 2px optical margin. Nothing touches the bounding box.
• Arrow icons use one arrowhead style across the family. Mixing chevron and triangle arrows was the first thing I killed.
• Icons that pair with text sit at 16px or 20px. Icons that stand alone (toolbars, tab bars) sit at 24px minimum for touch targets.
• Right-facing arrows always go forward. Down-facing arrows always mean either dropdown or download. The direction is a semantic choice not a stylistic one.
• Filled variants are permitted only for selected states and destructive actions. Everything else stays stroked.

Delivery

Ships as an SVG sprite, a React component set, and an SF Symbols-style parity spec for the mobile team. Each glyph has a semantic name (chevron-right, not arrow-a), a stable ID, and a documented default size. The library is versioned in the design system package so a rename means a semver bump and everyone in the org knows what to update.

Accessibility rules

• Every icon shipped inside a button has an aria-label matching the icon’s semantic name. Icon-only buttons without labels are treated as bugs in code review.
• Contrast ratio for outline icons is measured against the actual background, not the theoretical one. Default gold on charcoal clears 7:1; muted gold on cream clears 5.5:1.
• Focus states use a 2px outline offset by 3px, drawn in the same gold as the icon fill. The outline is a separate SVG element so it does not distort the glyph geometry.
• Icons never carry meaning that a screen reader cannot recover from the label or surrounding text. If the whole meaning of a row depends on the icon, the row is redesigned.

What the library refuses to draw

There is a short list of concepts the library does not include, because a small icon cannot carry them without becoming a metaphor puzzle. Sync-to-cloud (draw the state, not the transport). Print (users on mobile do not have printers; users on desktop use the browser menu). Bookmark (star already carries the concept). Any face-shaped icon (faces are a genre of illustration, not an icon system). Every one of these has been pitched at some point and every one has been declined. Refusing icons is part of the discipline; the library is defined by the icons it will not draw as much as by the icons it will.