Icons

Configure icons for sources, skills, and statuses

xiantong supports icons on sources, skills, and statuses. Icons can be emojis, SVG files, or raster images (PNG, JPG).

Labels do not use icons — they display as colored circles. See Colors for label color configuration.

Supported Formats#

Setting Icons#

Emoji#

Set the icon field in your entity’s config.json to any Unicode emoji:

{
"icon": "🔧"
}

Multi-codepoint emojis and ZWJ sequences are supported (e.g. 👨‍💻, 🇭🇺).

Icon Files#

Place an icon file in your entity’s directory. xiantong auto-discovers files named icon.{svg,png,jpg,jpeg}:

sources/
linear/
config.json
icon.svg        ← auto-discovered

Priority order when multiple formats exist: SVG > PNG > JPG > JPEG.

Explicit Path#

Point to a specific file using a relative path in config.json:

{
"icon": "./my-custom-icon.svg"
}

URL (Sources Only)#

For sources with a URL-based icon field, xiantong downloads the image to a local icon.{ext} file (max 50KB). After download, the local file is used for rendering.

Resolution Priority#

When rendering an entity’s icon, xiantong resolves it in this order:

1. Emoji — if icon field is an emoji string, render as text
2. Explicit path — if icon is a relative path (e.g. ./icon.svg), load that file
3. Auto-discovery — probe for icon.svg, icon.png, icon.jpg in the entity directory
4. Favicon fallback (sources only) — resolve from the service URL (MCP url or API baseUrl)
5. Fallback icon — a generic placeholder icon is shown

SVG Theming#

SVGs that use currentColor automatically adapt to the current theme:

<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12 2L2 7l10 5 10-5-10-5z" fill="currentColor"/>
</svg>

How it works:

• SVGs with currentColor are detected as colorable — they inherit color from their parent context (e.g. a status icon takes its status color)
• SVGs without currentColor render with their hardcoded colors
• SVGs with no fill attribute on the root <svg> element get the theme foreground color injected automatically

Use currentColor in your SVGs for icons that should match the entity’s color (e.g. statuses) or adapt to light/dark mode.

Entity-Specific Details#

Sources#

~/.xiantong/workspaces/{id}/sources/{slug}/
config.json     ← "icon": "🔧" or "./icon.svg"
icon.svg        ← auto-discovered

Sources have favicon fallback: if no local icon exists, xiantong resolves one from the MCP URL or API base URL.

Skills#

~/.xiantong/workspaces/{id}/skills/{slug}/
SKILL.md
icon.svg        ← auto-discovered

Skills use the same auto-discovery pattern. The resolved icon path is stored in the skill’s metadata as iconPath.

Statuses#

~/.xiantong/workspaces/{id}/statuses/
config.json     ← status definitions with optional "icon" field
{status-id}.svg ← icon file named after the status ID

Status icons use the status ID as the filename instead of icon:

statuses/
config.json
in-progress.svg   ← discovered for status id "in-progress"
done.svg          ← discovered for status id "done"

Icon Sizes#

Icons render at standard sizes across the UI:

Tips#

Use SVG for best results

SVGs scale perfectly at all sizes and can adapt to theme colors via currentColor. They’re the recommended format for custom icons.

Keep SVGs simple

Remove unnecessary metadata, editor artifacts, and inline styles. A clean viewBox, paths with fill="currentColor", and no width/height attributes work best.

Emoji for quick setup

Emojis require no files and render natively. They’re perfect for getting started or when a file icon isn’t needed.

Icon not showing?

• Check the file is in the correct directory for your entity type
• Verify the filename matches (icon.svg for sources/skills, {id}.svg for statuses)
• Ensure SVG content is valid XML
• For URL icons, check the file was downloaded (look for icon.{ext} in the entity directory)