> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Icons

> Give sources, skills, and statuses a visual identity with emoji, image files, or theme-aware SVGs.

Icons give the items in your workspace a quick visual identity. In Synti, three kinds of entities can carry an icon: **sources**, **skills**, and **statuses**. [Labels](/labels/overview) intentionally don't use icons — they render as colored dots instead, so the two systems stay visually distinct.

You can set an icon with a single emoji, drop an image file next to the entity, or point at a remote URL. SVGs get special treatment so they follow your [theme](/customisation/themes) and [entity color](/customisation/colors) automatically.

## Choosing an icon source

<Tabs>
  <Tab title="Emoji">
    The quickest option. Put any emoji directly in the entity's `config.json`, including multi-codepoint sequences like `👨‍💻`.

    ```json theme={null}
    { "icon": "🔧" }
    ```
  </Tab>

  <Tab title="Image file">
    Place an `SVG`, `PNG`, `JPG`, or `JPEG` in the entity's directory. Synti auto-discovers a file named `icon.svg`, `icon.png`, `icon.jpg`, or `icon.jpeg` — no config needed. When several are present, `icon.svg` wins.

    You can also point at a specific file with a relative path:

    ```json theme={null}
    { "icon": "./my-custom-icon.svg" }
    ```
  </Tab>

  <Tab title="Remote URL">
    Sources may reference a remote image by URL. Synti downloads and caches it locally on first use, so it keeps working offline. The download cap is **50 KB**.

    ```json theme={null}
    { "icon": "https://example.com/logo.png" }
    ```
  </Tab>
</Tabs>

## How Synti resolves an icon

For each entity, Synti checks in order:

1. An explicit `icon` value in `config.json` — emoji, relative path, or URL.
2. An auto-discovered `icon.*` file in the entity's directory (`svg` preferred).
3. For sources only, a favicon derived from the MCP server or REST API base URL.

The first match wins, so an explicit `icon` always overrides an auto-discovered file.

## Format guidance

| Format     | Best for                                                     |
| ---------- | ------------------------------------------------------------ |
| SVG        | Crisp icons that adapt to theme and color via `currentColor` |
| PNG        | Raster art that needs transparency                           |
| JPG / JPEG | Photographs or complex artwork                               |
| Emoji      | Instant identity with no files to manage                     |

### Theme-aware SVGs

SVGs are the only format that recolors itself. If your SVG uses `currentColor`, Synti tints it to match the entity's color and the active light or dark theme. If a path has no `fill` attribute, Synti injects the theme's foreground color. SVGs with hardcoded colors render exactly as authored — useful when you want a fixed brand mark.

<Tip>
  For a status or source icon that should blend into both light and dark mode, draw it with `stroke="currentColor"` (or `fill="currentColor"`), a 24×24 viewport, a stroke width of 2, and rounded caps and joins.
</Tip>

## Rendering sizes

Synti renders icons at five fixed sizes depending on context — 14 px, 16 px, 20 px, 24 px, and 28 px. Vector icons scale cleanly across all of them; if you use a raster format, author it at a comfortable multiple of the largest size (28 px) to avoid blur.

## Where files live

Icons sit inside each entity's directory under your workspace in `~/.synti`:

```text theme={null}
~/.synti/workspaces/{workspace-id}/sources/{slug}/icon.svg
~/.synti/workspaces/{workspace-id}/skills/{slug}/icon.svg
~/.synti/workspaces/{workspace-id}/statuses/icons/{status-id}.svg
```

<Note>
  The simplest way to set an icon is to ask the agent — for example, "give the GitHub source a black octocat icon." It writes the file and config for you. See [Customizing statuses](/statuses/customizing) for the same pattern applied to statuses.
</Note>