# Icon names and lookup

> Page: https://docs.plotwork.dev/cloud-architecture/icon-names. Index of every page: https://docs.plotwork.dev/llms.txt

How a cloud product becomes an `icon=` name, how search finds it, and how to map the product names in a request to icons with the tools. It is for an AI agent first; a person can use the icon pages in the same way.

## TL;DR

| Question | Answer |
|---|---|
| What is the shape of a name? | `<provider>:<product>`, in lowercase words joined with hyphens, without the provider's name repeated: `aws:lambda`, `azure:cosmos-db`, `gcp:cloud-run`. |
| How do I get the icon for a group? | The provider itself is `<provider>:cloud`. Set `type=` and `provider=` on the group and it draws the right one. |
| How do I find the name of one product? | Call `search_icons` with the product name as the request writes it, and use the first result. |
| How do I find the names of many products? | Call `map_icons` once with up to 40 names and the provider. Each name comes back resolved, with a confidence, or with the candidates to choose from. |
| What if nothing matches? | The name is listed in `gaps` with a neutral fallback. Draw the service with its node type and put the product name in the label. |
| Where can I see the icons? | On the icon pages: [AWS](https://docs.plotwork.dev/cloud-icons/aws.md), [Azure](https://docs.plotwork.dev/cloud-icons/azure.md), [Google Cloud](https://docs.plotwork.dev/cloud-icons/google-cloud.md), [other providers](https://docs.plotwork.dev/cloud-icons/other-providers.md), and [generic and technology icons](https://docs.plotwork.dev/cloud-icons/generic.md). |
| Can I guess a name? | No. An unknown name is an error with the nearest valid names, so validation catches a guess, but a search is faster than a retry. A few everyday words are aliases that draw anyway: `lucide:cart` draws `lucide:shopping-cart` and comes back as note I122 with the real name. |

## 1. How a name resolves

An icon reference is a set, a colon, and a name. The set says where the artwork comes from, and the name says which one. The provider sets hold the products of one cloud each.

| Set | Holds | Example |
|---|---|---|
| `aws`, `azure`, `gcp` | The provider's products, one page of icons each | `aws:s3`, `azure:key-vault`, `gcp:bigquery` |
| `alibaba`, `oci`, `ibm`, `cloudflare`, `digitalocean`, `vercel` | Other providers, with fewer products, on [one page](https://docs.plotwork.dev/cloud-icons/other-providers.md) | `alibaba:oss`, `cloudflare:workers` |
| `simple` | Technology and brand logos | `simple:postgresql`, `simple:auth0`, `simple:angular` |
| `lucide` | General icons | `lucide:git-branch` |
| `status` | Colored outcome icons | `status:success` |

The names come from the product's own name, so they are stable.

A general icon is often guessed by an everyday word instead of its Lucide name. A hundred such words are aliases of a bundled icon: the diagram draws the icon, and validation returns note I122 in `notices`, which is information and never an error. Write the real name to clear it. A name that is neither bundled nor an alias is still error E122.

| Written | Draws |
|---|---|
| `lucide:cart`, `lucide:basket`, `lucide:checkout` | `lucide:shopping-cart` |
| `lucide:bank` | `lucide:landmark` |
| `lucide:support`, `lucide:helpdesk`, `lucide:customer-support` | `lucide:headset` |
| `lucide:edit`, `lucide:pen` | `lucide:pencil` |
| `lucide:delete`, `lucide:trash-2` | `lucide:trash` |
| `lucide:home` | `lucide:house` |
| `lucide:money`, `lucide:cash` | `lucide:banknote` |

`search_icons` and `map_icons` find each icon by the same words, so a search for `cart` or `bank` returns the icon first.

## 2. How search finds a product

`search_icons` understands how people name products. Relevance, best first:

| Rank | A query that is | Example |
|---|---|---|
| 1 | Exactly a product's name, title, or alias, with or without its provider | `lambda`, `aws lambda`, `s3 bucket`, `azure functions` |
| 2 | A provider followed by a kind of service | `azure object storage` |
| 3 | Two or more words inside a title or alias | `blob storage` |
| 4 | A phrase for a kind of service | `message queue` finds every provider's queue |
| 5 | Words that match a name, a concept phrase, or a tag | `token exchange`, `defect` |

A phrase for a kind of service wins over a product that happens to be named that, so `load balancer` lists every provider's load balancer, most used provider first. Some examples of what comes back:

| You search | You get | Why |
|---|---|---|
| `lambda`, `aws lambda`, `AWS Lambda` | `aws:lambda` | A product name, with or without the provider |
| `cosmos`, `cosmos db`, `cosmosdb` | `azure:cosmos-db` | An alias or abbreviation |
| `gke`, `google kubernetes engine` | `gcp:gke` | An abbreviation and the full title |
| `serverless function` | The function product of each provider, most used provider first | A kind of service |
| `azure message queue` | `azure:service-bus` | A provider followed by a kind of service |

## 3. Map the product names of a request

A request such as "a web app with a Postgres database, a queue for slow work, and a CDN, on AWS" names several products. Map them all at once.

1. **List the names.** Take each service as the request writes it: `Postgres`, `queue`, `CDN`, `web app`. Do not translate them first.
2. **Call `map_icons`.** Send the names and set `provider` to the cloud the architecture runs on, so that a generic name such as `queue` finds that cloud's product (`aws:sqs`) first.
3. **Read the confidence of each result.** Write the icon of a result whose `resolved` is true. For `ambiguous`, choose from `candidates`, or ask the user, because a kind of service several clouds offer, or a match by idea only, is not a decision for the tool.
4. **Handle the gaps.** A name in `gaps` matched nothing. Use the fallback, or leave `icon=` off so the node type draws its own, and put the name in the label.
5. **Validate.** Call `validate_diagram` or `draw_diagram`. A node whose label names a product but has no icon gets warning `W204` with the exact text to add.

| Confidence | Meaning | What to do |
|---|---|---|
| `exact` | The name is the icon or the product name | Use `icon` |
| `strong` | The name clearly points at this icon and no other provider competes | Use `icon` |
| `ambiguous` | Several icons fit, or the match is by idea only | Choose from `candidates`, or ask |

For one name, `search_icons` returns the matches best first, and the first is the answer. `map_icons` replaces up to 40 of those calls.

## 4. Read an icon page

Each icon page lists every icon of a set, grouped by the provider's own categories, with the same layout throughout.

| Part | What it shows |
|---|---|
| Category heading | The provider's category, such as Compute or Databases |
| Picture | The icons of the category as the renderer draws them, each above its product name |
| Table | The exact `icon=` for each product, its official name, and other names that find it. On the AWS, Azure, and Google Cloud pages it is folded under the picture. |

The pictures are extra: a table row holds everything an agent needs, and the picture lets a person see the icon before using it.

## 5. What an icon draws

Every cloud product draws one of three things, and the name, the search, and the validation are the same whichever it is, so a diagram means the same thing everywhere.

| Artwork | Where it comes from |
|---|---|
| The vendor's own icon | The official architecture icon of AWS, Azure, or Google Cloud, drawn as the vendor published it, in its original colors, on a light tile in both themes, next to the product name |
| A brand mark | A licensed mark, such as the mark of Cloudflare, drawn in the color of the node or group that holds it |
| The glyph of a kind of service | A function, a queue, or object storage looks the same on every cloud, and the label says whose it is |

See [Trademarks and icons](https://docs.plotwork.dev/trademarks-and-icons.md) for the terms the artwork is used under.

## See also

| Doc | Why |
|---|---|
| [Cloud architecture](https://docs.plotwork.dev/cloud-architecture.md) | The five-step recipe |
| [AWS icons](https://docs.plotwork.dev/cloud-icons/aws.md) | Every AWS icon, drawn |
| [Azure icons](https://docs.plotwork.dev/cloud-icons/azure.md) | Every Azure icon, drawn |
| [Google Cloud icons](https://docs.plotwork.dev/cloud-icons/google-cloud.md) | Every Google Cloud icon, drawn |
| [Trademarks and icons](https://docs.plotwork.dev/trademarks-and-icons.md) | The terms for the vendor artwork and the marks |
| [Icon reference](https://docs.plotwork.dev/reference/icons.md) | The compact catalog of every bundled icon |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | `map_icons`, `search_icons`, and `draw_diagram` |