icon_design v1.0.0

name: icon_design description: Design a product icon set that reads at small sizes: grid and keyline use, stroke and corner rules, metaphor choice, consistency across a set, and export sizes for web and app use. Use when someone asks to design icons, build or extend an icon set, fix icons that look mismatched or blurry at small sizes, choose icon export sizes, or audit an existing set.

Icon Design

Purpose

Ship an icon set where every icon reads at the size users actually see it, usually 16 to 24 pixels, and where the whole set looks like one family. The method: one base grid with keylines, one stroke and corner system, one metaphor per action chosen for recognition, a redrawn small variant where detail would close up, and a two part consistency audit, script first, then eyes.

Workflow

1. Fix the set contract before drawing. Write down: base size (24 is the standard choice for product UI), style (outlined or filled), stroke width (2 on a 24 grid for an outlined set), linecap and linejoin (round and round is the common choice), corner radius, colour rule (currentColor for a monochrome UI set), and the smallest display size the set must survive. Every later icon is judged against this contract.

1. Generate the grid. Run python3 scripts/make_grid.py --size 24 --out grid-24.svg. Draw inside the live area: 20 by 20 on a 24 grid with 2 units of padding. Finished templates for 16, 24, and 48 ship in assets/grid-16.svg, assets/grid-24.svg, and assets/grid-48.svg. Full numbers are in references/grid-and-sizes.md.

1. Snap to a keyline. Fit a round icon to the circle keyline, a blocky icon to the slightly smaller square keyline, and a wide or tall icon to the matching rectangle keyline. Keylines give different shapes equal optical weight. Matching bounding boxes do not.

1. Choose the metaphor. Name the action in plain words, pick the object users already connect with it, and keep the silhouette to one main shape plus at most one identifying detail. Prefer learned conventions over clever new ones. Check that no two icons in the set could be confused at 16 pixels. The full method and the cultural traps list are in references/metaphor-and-consistency.md.

1. Draw to the contract. One stroke width everywhere, set on the root group. Gaps between strokes at least as wide as the stroke itself. Endpoints and centres on whole units where the shape allows it. No detail that only exists because it looked good at 800 percent zoom.

1. Test at real size early. Open assets/examples/preview.html for the pattern: every icon shown at 16, 24, and 48 pixels, plus a dark background check. Build the same sheet for the new set. Any icon that turns to mud at the smallest size gets a redrawn small variant with fewer lines and wider gaps. Filled forms read better than thin strokes at 16 pixels and below, so a filled small variant of an outlined icon is a normal move, as long as the rule is stated and applied to the whole set.

1. Audit the set. Run python3 scripts/audit_icons.py path/to/icons. Fix every FAIL before going further: mixed stroke widths or linecaps across the set, non square viewBoxes, embedded rasters or scripts. Then do the eye audit from references/metaphor-and-consistency.md: squint for equal weight, compare corners and detail levels, and have someone who did not draw the set name each icon at 16 pixels after a two second look.

1. Export for the target. For web UI: the SVG master per icon, named in lowercase kebab case, viewBox only, plus PNG at the sizes the stack needs. For favicons: an SVG, an ICO holding 16, 32, and 48, a 180 by 180 apple-touch-icon, and 192 and 512 PNGs for the web app manifest. For an app icon: a separate job, one focal object on a 1024 by 1024 flattened master with square corners and no transparency, because the platform applies its own mask. Size tables are in references/grid-and-sizes.md.

1. Study the worked set before starting a new one. assets/examples/ holds search, home, download, and bell drawn on the 24 grid with a 2 unit stroke, round caps and joins, no fill, and currentColor. Run the audit script on that folder for a known clean result, and on a folder with one stroke width changed for a known FAIL.

Output Contract

Every icon set delivery includes:

• One SVG file per icon, lowercase kebab case names, all sharing the base viewBox from the set contract.
• The set contract itself, in writing: base size, style, stroke, caps and joins, corner radius, colour rule, smallest display size.
• A preview sheet showing every icon at 16, 24, and 48 pixels and on a dark background.
• The audit output: script result plus the eye audit notes, including which icons a test viewer failed to name at 16 pixels.
• A list of icons that got a separate small size variant, so future additions match the treatment.
• Export files for the target platform, with sizes stated per file, when the job includes production exports.

Operating Rules

• Draw at the base size, test at the display size. An icon that only works large is not finished.
• One stroke width, one cap and join style, one corner logic for the whole set. A stated exception applied set wide is a rule. A silent exception in one icon is a defect.
• Keylines over bounding boxes. Optical size is what users see.
• Redraw small instead of shrinking blindly. Detail that closes up at 16 pixels comes out of the 16 pixel variant.
• Keep the gap rule: no space between strokes narrower than the stroke itself.
• Metaphors come from what users already recognise. If an icon needs its label to be understood in a two second test, change the metaphor or simplify the drawing.
• Vector only in production files. No rasters, fonts, scripts, or external links inside an icon SVG.
• Verify platform size requirements against the platform documentation at export time. Platform lists change, and the tables in references/grid-and-sizes.md are a checked starting point, not a guarantee.
• Never mix icons copied from other sets into a shipped set without redrawing them to the contract. Borrowed icons carry their old grid, stroke, and corners with them.