# Semantic Icons

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

Semantic Icons is a curated set of 3000 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 3000 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 3000 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

- [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.