icon-ops

Files (8)

• SKILL.md
• sprite-template.svg · assets/
• brand-variants.md · references/
• favicons-and-app-icons.md · references/
• icon-sources.md · references/
• inline-delivery.md · references/
• normalize-icon.py · scripts/
• run.sh · tests/

SKILL.md (first lines)

# icon-ops

Getting an icon onto a page is easy. Getting one that themes correctly, carries
the right licence, matches the twelve icons beside it, and behaves for a screen
reader is where the work actually is.

## Helps with

An icon that won't change colour on hover, in dark mode, or when the theme
switches — almost always a hardcoded `#000` in the file where `currentColor`
should be.

A UI where the icons "look off" without an obvious cause. Usually two icon sets
mixed: different grid size, different stroke width, different corner language.
Individually fine, together visibly wrong.

Choosing an icon set at the start of a project, when the choice is cheap, rather
than after 60 icons are embedded.

Using a brand logo — GitHub, Google, a client's mark — and needing to know
whether you actually may. The file licence does not answer this; trademark does.

Needing a logo for an arbitrary company that no icon set carries. That is a
different category from icon sets — a runtime lookup by domain, not a committed
glyph — with its own quota, caching and trademark consequences.

Icon-only buttons that a screen reader announces as "button", or announces
twice. Both come from putting the accessible name in the wrong place.

Vendor SVGs carrying Inkscape/Figma metadata, fixed `width`/`height` that fights
CSS, and inline styles that resist theming.

Deciding between inline SVG, a `<symbol>` sprite, framework components, and an
icon font — and discovering too late that `<img src="icon.svg">` cannot be
recoloured at all.

A sprite that renders nothing in production but worked locally (the external
`<use>` CORS trap).

Two inlined logos where the second one's gradient bleeds into the first. Both
files declared `id="a"`; the last definition in the document wins for the whole
page. 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
wanting to know whether to generate it or use the owner's published variant.

A logo wall where one wide wordmark dominates because everything was set to the
same `width`.

Favicons and app icons — the modern four-file set, and why an Android maskable
icon gets its edges cropped.

## The core technique

**`fill="currentColor"` is the whole game.** An icon that inherits the CSS
`color` of its context gets hover, focus, disabled, dark mode, and every future
theme for free, with no icon-specific CSS. An icon with a baked-in hex breaks all
of them simultaneously, and each one gets "fixed" separately later.

Everything else in this skill exists to get icons into that state and keep them
there.

## Workflow

### 1. Choose the set before sourcing anything

Lock four decisions; they constrain every icon that follows:

| Decision | Options |
|---|---|
| Grid | 24 (most common) · 20 · 16 |
| Family | stroke · filled · both-as-matched-pair |
| Stroke width | 1.5 · 2 — **must be identical across the set** |
| Corner language | round caps/joins · square |

Sensible defaults: **Lucide** (ISC, 24-grid, stroke 2) for a general UI,
**Heroicons** (MIT) when you want matched outline/solid/mini tiers, **Phosphor**
(MIT) when you need multiple weights in one family.

Reach for a second set only when the first genuinely lacks the concept — then
match grid and stroke width and expect to redraw. Prefer a near-neighbour
concept from your set over an exact match from a foreign one.

Full comparison table, licences, and the aggregator problem →
[`references/icon-sources.md`](references/icon-sources.md).

### 2. Vet the licence — two traps

**Brand marks are trademarks regardless of file licence.** Simple Icons ships
brand logos under CC0, but the marks remain their owners' property. Nominative
use ("Sign in with GitHub") is fine; implying endorsement, recolouring a mark to
your palette, or putting it in your own logo is not. Quoting "it's CC0" as
clearance is the wrong answer.

**A company logo is not a UI icon.** Three sources cover brand marks and they
trade off reach against commitment — **Simple Icons** (committed, monochrome,
themeable), **theSVG** (MIT, 6,500+ marks in brand colour via
`npm i thesvg`, an MCP server needing no key, or `npx skills add glincker/thesvg`), and **Brandfetch** (runtime lookup by *domain*, any company, nothing
committed; free key at developers.brandfetch.com/dashboard, hotlink-only URLs
that expire in ~24h, and two free tiers that differ by 10,000x). All three carry
the identical trademark position — see
[Brand marks](references/icon-sources.md#brand-marks--three-sources-one-trademark-position).
They resolve the mark for you; none of them clears it.

**Aggregators hide the licence.** Iconify, and any icon-search MCP or plugin,
resolve across 150+ sets each keeping its own terms. Record the *originating
set* and its licence when the icon enters the repo — one line in `LICENSES.md`
or atop the sprite. That single line is the difference between an answerable
question and an audit.

### 3. Normalize before it enters the repo

Vendor output is not shippable. `scripts/normalize-icon.py` strips editor cruft,
**namespaces internal ids** so two inlined SVGs cannot clobber each other's
gradients, drops fixed `width`/`height` so CSS controls size, and applies the
correct accessibility attributes.

**Colour is never guessed.** A single-colour source rebinds to `currentColor`. A
multi-colour source is **refused (exit 11)** until you name the treatment,

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods