Getting an icon onto a page is easy. Getting one that themes correctly, carries\nthe right licence, matches the twelve icons beside it, and behaves for a screen\nreader is where the work actually is.
\nAn icon that won't change colour on hover, in dark mode, or when the theme\nswitches — almost always a hardcoded #000 in the file where currentColor\nshould be.
A UI where the icons \"look off\" without an obvious cause. Usually two icon sets\nmixed: different grid size, different stroke width, different corner language.\nIndividually fine, together visibly wrong.
\nChoosing an icon set at the start of a project, when the choice is cheap, rather\nthan after 60 icons are embedded.
\nUsing a brand logo — GitHub, Google, a client's mark — and needing to know\nwhether you actually may. The file licence does not answer this; trademark does.
\nNeeding a logo for an arbitrary company that no icon set carries. That is a\ndifferent category from icon sets — a runtime lookup by domain, not a committed\nglyph — with its own quota, caching and trademark consequences.
\nIcon-only buttons that a screen reader announces as \"button\", or announces\ntwice. Both come from putting the accessible name in the wrong place.
\nVendor SVGs carrying Inkscape/Figma metadata, fixed width/height that fights\nCSS, and inline styles that resist theming.
Deciding between inline SVG, a <symbol> sprite, framework components, and an\nicon font — and discovering too late that <img src=\"icon.svg\"> cannot be\nrecoloured at all.
A sprite that renders nothing in production but worked locally (the external\n<use> CORS trap).
Two inlined logos where the second one's gradient bleeds into the first. Both\nfiles declared id=\"a\"; the last definition in the document wins for the whole\npage. Brand marks hit this constantly because they carry gradients.
Needing a mark in grey, knocked out of a dark header, or in one brand ink — and\nwanting to know whether to generate it or use the owner's published variant.
\nA logo wall where one wide wordmark dominates because everything was set to the\nsame width.
Favicons and app icons — the modern four-file set, and why an Android maskable\nicon gets its edges cropped.
\nfill=\"currentColor\" is the whole game. An icon that inherits the CSS\ncolor of its context gets hover, focus, disabled, dark mode, and every future\ntheme for free, with no icon-specific CSS. An icon with a baked-in hex breaks all\nof them simultaneously, and each one gets \"fixed\" separately later.
Everything else in this skill exists to get icons into that state and keep them\nthere.
\nLock four decisions; they constrain every icon that follows:
\n| Decision | \nOptions | \n
|---|---|
| Grid | \n24 (most common) · 20 · 16 | \n
| Family | \nstroke · filled · both-as-matched-pair | \n
| Stroke width | \n1.5 · 2 — must be identical across the set | \n
| Corner language | \nround caps/joins · square | \n
Sensible defaults: Lucide (ISC, 24-grid, stroke 2) for a general UI,\nHeroicons (MIT) when you want matched outline/solid/mini tiers, Phosphor\n(MIT) when you need multiple weights in one family.
\nReach for a second set only when the first genuinely lacks the concept — then\nmatch grid and stroke width and expect to redraw. Prefer a near-neighbour\nconcept from your set over an exact match from a foreign one.
\nFull comparison table, licences, and the aggregator problem →\nreferences/icon-sources.md.
Brand marks are trademarks regardless of file licence. Simple Icons ships\nbrand logos under CC0, but the marks remain their owners' property. Nominative\nuse (\"Sign in with GitHub\") is fine; implying endorsement, recolouring a mark to\nyour palette, or putting it in your own logo is not. Quoting \"it's CC0\" as\nclearance is the wrong answer.
\nA company logo is not a UI icon. Three sources cover brand marks and they\ntrade off reach against commitment — Simple Icons (committed, monochrome,\nthemeable), theSVG (MIT, 6,500+ marks in brand colour via\nnpm i thesvg, an MCP server needing no key, or npx skills add glincker/thesvg), and Brandfetch (runtime lookup by domain, any company, nothing\ncommitted; free key at developers.brandfetch.com/dashboard, hotlink-only URLs\nthat expire in ~24h, and two free tiers that differ by 10,000x). All three carry\nthe identical trademark position — see\nBrand marks.\nThey resolve the mark for you; none of them clears it.
Aggregators hide the licence. Iconify, and any icon-search MCP or plugin,\nresolve across 150+ sets each keeping its own terms. Record the originating\nset and its licence when the icon enters the repo — one line in LICENSES.md\nor atop the sprite. That single line is the difference between an answerable\nquestion and an audit.
Vendor output is not shippable. scripts/normalize-icon.py strips editor cruft,\nnamespaces internal ids so two inlined SVGs cannot clobber each other's\ngradients, drops fixed width/height so CSS controls size, and applies the\ncorrect accessibility attributes.
Colour is never guessed. A single-colour source rebinds to currentColor. A\nmulti-colour source is refused (exit 11) until you name the treatment,\nbecause flattening a mark to a silhouette is lossy and counts as modifying it:
| Flag | \nResult | \n
|---|---|
| (default) | \nmono source → currentColor | \n
--keep-colour | \ncolours untouched — the right default for someone else's mark | \n
--greyscale | \nRec.709 luminance-mapped grey | \n
--tint '#fff' | \nflatten to one colour; white = knockout / reverse-out | \n
--flatten | \nyes, really collapse a multi-colour source to currentColor | \n
It also sanitises. An inlined SVG runs script in your page's origin; an\n<img src=\"x.svg\"> does not. Since this skill tells you to inline third-party\nSVGs, the normalizer strips <script>, <foreignObject>, every on* handler\nand javascript:/data:text hrefs. Treat any SVG you did not author as\nuntrusted input, and never inline one that has not been through this.
# Would this file change? exit 10 = yes, 0 = already clean\nscripts/normalize-icon.py --check vendor.svg\n\n# Normalize a filled icon into the repo (atomic write)\nscripts/normalize-icon.py vendor.svg -o src/icons/search.svg\n\n# A brand mark: keep its colours, just clean and namespace it\nscripts/normalize-icon.py --keep-colour acme.svg -o src/logos/acme.svg\n\n# Stroke icon: forces fill=none, stroke=currentColor, consistent caps/joins\nscripts/normalize-icon.py --stroke vendor.svg -o src/icons/search.svg\n\n# Append to a sprite as a <symbol>\nscripts/normalize-icon.py --symbol --id i-search vendor.svg >> src/sprite.svg\n\n# Machine-readable result (what changed, and why)\nscripts/normalize-icon.py --json vendor.svg | jq '.data[0]'\nExit codes: 0 ok · 2 usage · 3 no such file · 4 not a usable SVG ·\n10 (--check only) normalization would change the file · 11 multi-colour\nsource refused. The --check mode is a CI gate — run it over src/icons/ to\nkeep un-normalized icons out.
For byte-level path optimisation, run SVGO after normalizing, never before:
\nscripts/normalize-icon.py raw.svg -o icon.svg && npx svgo --multipass icon.svg\n| Mechanism | \nThemeable | \nUse when | \n
|---|---|---|
<symbol> sprite + <use> | \nYes | \nDefault for a real UI — many icons, reused | \n
Inline <svg> | \nYes | \nFew icons, or per-path styling/animation | \n
| Framework component | \nYes | \nComponent stack already in play; tree-shakes | \n
<img src=\"icon.svg\"> | \nNo | \nNever for UI icons | \n
| Icon font | \nColour only | \nLegacy only — migrate, don't extend | \n
Start a sprite from assets/sprite-template.svg,\nwhich carries the hiding pattern that survives Safari, per-symbol viewBox so\nmixed grids scale correctly, and the sizing rule.
Size in em, never px:
![assets/sprite-template.svg](\"assets/sprite-template.svg\"){kind=link}
.icon { width: 1em; height: 1em; flex: none; }\n1em keeps the icon optically matched to its label at every type scale.\nflex: none stops a flex parent squashing it into an ellipse — the most common\nicon layout bug there is.
The trap that only shows in production: an external\n<use href=\"/sprite.svg#id\"> is CORS-blocked cross-origin and renders nothing,\nsometimes with no console error. Inline the sprite into the document.
Decision detail, icon-font failure modes, and optimisation order →\nreferences/inline-delivery.md.
Every icon is decorative or meaningful. Leaving it undecided is the defect.
\n<!-- Decorative: text beside it already names the control -->\n<button>\n <svg class=\"icon\" aria-hidden=\"true\" focusable=\"false\"><use href=\"#i-trash\"/></svg>\n Delete\n</button>\n\n<!-- Meaningful: the icon IS the label -->\n<button aria-label=\"Delete item\">\n <svg class=\"icon\" aria-hidden=\"true\" focusable=\"false\"><use href=\"#i-trash\"/></svg>\n</button>\nName the control, not the icon. The counter-intuitive part is that the SVG\nstays aria-hidden in both cases — a name on the icon and on the button\nproduces a double announcement. role=\"img\" + <title> is for standalone\ngraphics, not for the contents of a control.
Also: icon-only controls need a 24×24 CSS px minimum interactive area (WCAG\n2.2 §2.5.8) — pad the control, don't grow the glyph. Never let colour alone carry\nmeaning: pair it with a distinct shape.
\nA mark rarely ships in one treatment. Use the owner's published mono/reversed/\ngreyscale asset when one exists — theirs is drawn, yours is computed, and a\ndesigner already fixed the hairline that vanishes when knocked out. Generate\nonly when they publish none.
\nscripts/normalize-icon.py --tint '#fff' acme.svg -o src/logos/acme-knockout.svg\nscripts/normalize-icon.py --greyscale acme.svg -o src/logos/acme-grey.svg\nfilter: grayscale(1) is right for a hover-reveal effect and wrong for a\ncanonical asset. filter: invert(1) is never a knockout — it inverts hue\ntoo, so a blue mark comes back orange.
Logo walls: constrain both axes. width: 120px on everything makes a wide\nwordmark occupy ~3x the visual area of a square badge. Use max-width and\nmax-height in a fixed box, then correct optically by eye.
Favicons are a different mark, not your logo scaled down — four files\n(favicon.ico, icon.svg, apple-touch-icon.png 180x180, and a separate\n512x512 maskable PNG whose content sits inside the centre 80%-diameter circle).
Variant production, light/dark pairs, logo-wall sizing and logo alt conventions\n→ references/brand-variants.md. The favicon set,\nthe theme-aware SVG favicon, and maskable safe zones →\nreferences/favicons-and-app-icons.md.
svg-brand-tint-ops. This skill produces flat\nvariants (mono, grey, knockout) of a single mark; that one does tonal\nre-mapping and vectorising.color-opsgenart-ops, isometric-ops| When | \nUse | \n
|---|---|
| The icons are right but the palette isn't | \ncolor-ops | \n
| A whole set needs brand recolouring or a logo needs vectorising | \nsvg-brand-tint-ops | \n
| Building the surrounding component styles | \ntailwind-ops | \n
references/icon-sources.md — the set comparison\ntable (licence, grid, family, notes) for the eleven sets worth knowing; the\ntrademark-vs-file-licence distinction for brand marks; the aggregator licence\ntrap; MCP/plugin sourcing discipline; what each licence class actually\nrequires by way of attribution; and brand marks — Simple Icons vs theSVG\nvs Brandfetch compared on shape, coverage, colour and offline behaviour, plus\nBrandfetch's key setup, its two very different free tiers, hotlink/expiry\nconstraints, and both MCP servers. Load when choosing a set, sourcing a\ncompany logo, or before shipping any brand mark.
references/inline-delivery.md — delivery\nmechanism comparison and why icon fonts fail; the external-<use> CORS trap;\nem sizing and optical alignment; currentColor theming; the full\naccessibility checklist (both cases, target size, contrast, reduced motion);\nand SVGO ordering. Load when wiring icons into a page or debugging one that\nwon't theme.
references/brand-variants.md — producing mono,\ngreyscale, knockout and single-ink variants of a mark; why Rec.709 luminance\nbeats an RGB average; when a CSS filter is right and when it is a lie; the three\nlight/dark approaches and why the internal-media-query one usually breaks;\nlogo-wall sizing by area rather than width; and logo alt conventions. Load\nwhen a mark needs a treatment it did not ship with.
references/favicons-and-app-icons.md —\nthe modern four-file set and the head block that serves it, why rel=\"shortcut icon\" is meaningless, the theme-aware SVG favicon, Android maskable safe zones,\nand designing a mark down to 16px. Load for favicons, PWA icons or app icons.
scripts/normalize-icon.py — normalize a vendor SVG for inline themeable use.\n--check for a CI gate, --stroke for stroke families, --symbol --id for\nsprite assembly, --json for a machine-readable diff summary. Idempotent:\nre-running on a normalized file reports clean.assets/sprite-template.svg — commented <symbol> sprite scaffold to copy\ninto a project, carrying the Safari-safe hiding pattern, per-symbol viewBox,\ncurrentColor defaults, and both filled and stroke examples.