# Semantic Icons

> Ask for an icon the way you would say it.

Semantic Icons is a curated set of 3006 SVG icons drawn to one contract: a 24 by 24 view box, a 2 unit stroke, and `currentColor` so an icon follows the surrounding text colour. Every icon carries a phrase, a category and about seventeen keywords, so the set can be searched with plain prose rather than by file name.

## Site

- [Icon set and search](https://semanticicons.com/): search 3006 icons with a sentence. The ranking runs in the page.
- [Custom sets](https://semanticicons.com/#house-style): a set drawn to your own grid and stroke width.
- [Writing](https://semanticicons.com/blog): notes on icon design, SVG and search retrieval.
- [Full text of every post](https://semanticicons.com/llms-full.txt): the complete articles in one file.

## What is free and what is paid

Free, and MIT licensed:

- The 3006 icon set. Use it in anything, change it, redistribute it, sell what you build. No credit is needed in your interface.
- The prose search. It runs in the page over a static index, with no request, no key and no server.
- The SDK, which needs no framework, and the MCP server, which gives a coding agent five tools.

Paid:

- The hosted API, but only when it draws an icon that does not exist yet. That is the one stage that calls a model.
- A custom set drawn in your own house style, as a fixed price service.

## How the API charges

A request has four possible answers and only one of them costs anything.

| How it answered | Cost |
| --- | --- |
| The phrase was already in the cache | free |
| The phrase named a curated icon | free |
| A vector search found a close curated icon | free |
| A model drew something new | one credit |

Facts a reader should not have to infer:

- Charging is per generated icon, never per request or per search.
- Credits are prepaid. There is no invoice and no metered bill.
- At a zero balance the three free stages keep working. Only a new drawing is refused, with HTTP 402.
- A drawing that fails, and a phrase the model reports as too complex, are both refunded. The caller received no icon.
- Every icon a customer generates is kept in their own library, with the SVG copied in rather than referenced.
- The API needs a key on every route. The key is stored only as a SHA-256 hash.
- The search needs no key, because it never reaches a server.

## Writing

- [How many icons does a product actually need?](https://semanticicons.com/blog/how-many-icons-does-a-product-need): Most products use fewer than 120 icons. Here is the coverage checklist that finds the gaps, and why a large set still helps even when you ship a small one.
- [Stroke or fill: which icon style should you choose?](https://semanticicons.com/blog/stroke-or-fill-icons): Stroke icons stay light and legible on any background. Fill icons read faster at small sizes and carry state. Here is how to pick one, and how to mix them safely.
- [Inline, sprite or component: how to ship SVG icons](https://semanticicons.com/blog/how-to-ship-svg-icons): Four ways to deliver an SVG icon set, and the one property that decides between them. Includes what each costs in bytes, caching and colour control.
- [Should icon search use embeddings or keywords?](https://semanticicons.com/blog/embeddings-or-keywords-for-icon-search): Keywords answer fast and offline but fail on unfamiliar words. Embeddings catch meaning but cost a request. Run words first and vectors second.
- [When an icon needs a label, and when it must not have one](https://semanticicons.com/blog/accessible-icons): An icon beside a word needs no name. An icon alone needs one. Getting this backwards makes a screen reader repeat itself, or leaves a button silent.
- [Make an SVG icon follow your text colour with currentColor](https://semanticicons.com/blog/svg-currentcolor-icons): One keyword removes the need for colour variants, dark mode icons and inline fill overrides. Here is how currentColor works and the three places it breaks.
- [How many keywords does an icon need?](https://semanticicons.com/blog/how-many-keywords-does-an-icon-need): Four keywords per icon makes a set searchable by synonym. Fifteen makes it searchable by sentence. Here is what to write, what to leave out, and how to measure it.
- [What the 24 by 24 icon grid is actually for](https://semanticicons.com/blog/the-24x24-icon-grid): The 24 unit grid is not a size. It is a shared coordinate space that makes stroke width, gaps and optical weight consistent across a whole icon set.
- [Charge for the stage that costs you money](https://semanticicons.com/blog/charge-only-when-the-model-runs): An icon API has four ways to answer a request and only one of them calls a model. Metering the request instead of the model call overcharges almost everybody.
- [Icon naming conventions that survive a redesign](https://semanticicons.com/blog/icon-naming-conventions): Name an icon for what it draws, not for where you first used it. Here is the rule, the three name types to avoid, and how to keep names stable as a product changes.
- [Why icon search returns the wrong icon](https://semanticicons.com/blog/why-icon-search-returns-the-wrong-icon): One icon with a long tag list can shadow every other icon in the set. Here are the four scoring faults that cause it, and the structural fix.
- [The stroke width that keeps an SVG icon legible at 16px](https://semanticicons.com/blog/svg-icon-stroke-width-legible-at-16px): A 24px icon drawn with a 2 unit stroke stays readable down to 16px. Here is why that ratio works, and the four geometry rules that matter more than the number.
- [How to find an icon without knowing its name](https://semanticicons.com/blog/find-an-icon-without-knowing-its-name): Most icon libraries make you guess a file name. Prose search matches what you mean instead. Here is how it works and what to check before you adopt a set.

## Notes for machine readers

- Every post is also served as Markdown at `/blog/<slug>.md`.
- Posts dated in the future return 404 and are absent from the sitemap until their publish day.
- This file lists only published posts.
- Prices are not stated here on purpose. Ask, rather than quote a number that may be out of date.