---
name: gentleface-icons
description: Pick and add icons to an app's UI with the Gentleface icon set (free, MIT, pixel-aligned at 16 px, 6 styles), keeping one meaning per icon across the project. Use whenever a UI you build or change needs icons (buttons, menus, tabs, toolbars, status, empty states), on the web (React, Vue, Svelte, HTML and CSS) or native (SwiftUI, Jetpack Compose, Android views, Flutter).
---

# Gentleface icons

Gentleface is a free icon set (MIT) drawn on the 16 px pixel grid, in 6 styles: line or solid, with round, soft or sharp corners. Every icon documents what it means, which icons to use instead and what it is confused with. Use that to pick the right icon for a meaning, not just a shape that looks close.

## Tools

- **MCP server `gentleface`** (`https://gentleface.com/mcp`): `search_icons`, `get_icon`, `get_icons`, `list_categories`, `get_category`. Prefer it when it is connected.
- **Without MCP**, fetch:
  - `https://gentleface.com/icons.txt`: one line per icon, `name: meanings (category)`;
  - `https://gentleface.com/icons/<name>.md`: the icon's code in every format, with its guidance;
  - `https://gentleface.com/llms.txt`: the overview and URL patterns.

## Workflow

1. **Read the project's manifest**, `icons.manifest.json` at the repo root, if there is one. A concept it already maps keeps its icon.
2. **Plan before you pick.** List every meaning the feature needs (settings, sign out, invite member, delete, unread notifications…), with the obvious siblings: "add member" usually comes with "remove member".
3. **Search each new meaning** with `search_icons`, in plain words. Take the top result unless its notes name a better owner for that meaning.
4. **Check collisions.** `get_icon` returns `dont_confuse_with`, `not_for` and `motif`. In one project, one motif means one thing: if the manifest's `motifs` already uses a motif for another concept, take the documented alternative.
5. **Ask only when conventions really differ** and the codebase shows no precedent: share (iOS box-and-arrow or Android nodes), favorite (star or heart). Show 2 or 3 options in a small table. Otherwise use the library's choice.
6. **Fetch every chosen icon in one `get_icons` call**, in the project's style and format.
7. **Record each decision** in the manifest, with a one-line why.

## Style and size

- **One style for the whole project.** The default is `line-round`. A common exception is the solid variant for an active state (the selected tab); note it in the manifest.
- **Render at 16, 32 or 48 px**, the exact multiples of the 16 px master, on whole pixels.
  - Avoid 18, 20 or 24 px, and sizes in rem.
  - Don't centre a 16 px icon in an odd-sized box: it lands on half pixels and blurs.
- **Color:** the SVG uses `currentColor`, so set the color on the parent.

## Code

- **Format by stack:**
  - web: `react` (TSX components), `vue`, `svelte`, `svg` (inline HTML), `css` (a mask, for icons in stylesheets);
  - native: `swiftui` (a `Shape`), `compose` (an `ImageVector`), `android` (a vector drawable), `flutter` (a widget);
  - `img` only where the color doesn't matter.
- **Put components where the project keeps components**, for example `src/components/icons/BellIcon.tsx`, one file per icon, or one `icons.tsx` if that's the project's habit. Names are PascalCase plus `Icon`: `bell` becomes `BellIcon`.
- **Keep the header comment** each snippet carries (name, style, license link). It credits the set.
- **Accessibility:** the snippets are decorative (`aria-hidden`). An icon-only button needs an accessible name on the button (`aria-label`, `accessibilityLabel`, `contentDescription`), not on the icon.

## Manifest

`icons.manifest.json` at the repo root:

```json
{
  "library": "gentleface",
  "style": "line-round",
  "sizes": [16],
  "concepts": {
    "api-key": { "icon": "key-code", "why": "key means credentials in this app", "by": "user" },
    "license": { "icon": "certificate", "why": "key is taken by API keys", "by": "agent" }
  },
  "motifs": { "key": ["api-key"], "certificate": ["license"] }
}
```

- `concepts`: each meaning, the icon chosen, why, and who chose it (`user` or `agent`).
- `motifs`: each motif (from `get_icon`) and the concepts that use it, so one motif never means two things.

## When nothing fits

Say so. Name the closest icon and the gap. Don't draw a replacement, or take one from another set, without telling the user. Missing icons can be requested at https://gentleface.com/feedback.