Skip to content

Per-project Icons

Every project in Whittl's sidebar gets a distinct icon. The matcher picks from 125+ Phosphor Duotone SVGs based on keywords in the project's name and first prompt. If you don't like the auto-pick, override it manually from a curated picker.

How matching works

When Whittl creates or loads a project, it runs the project name + the first user message through a keyword matcher. The first matching rule wins; if nothing matches, the project gets the default app-window icon.

The matcher is regex-based — no AI call, no cost, instant. Examples from the built-in rules:

Project name contains Icon
weather, forecast, temperature cloud-sun
music, audio, song, playlist music-notes
game, puzzle, chess, snake game-controller
photo, image, gallery, camera camera
calc, calculator, math calculator
chat, messenger, discord chats
todo, tasks, checklist list-checks
book, ebook, reader, adventure book
terrain, mountain, landscape, hiking mountains
news, rss, feed, magazine newspaper
shop, shopping, cart, pos shopping-cart
password, vault, keychain, secure lock
database, sqlite, postgres database
map, location, gps, travel map-pin
budget, finance, money, crypto coin
recipe, cook, food, meal fork-knife
fitness, gym, workout barbell
space, planet, astronomy planet
terminal, console, shell terminal-window
chart, dashboard, analytics chart-bar

Full rule list: core/project_icons.py in the Whittl source.

Real-world examples

For concrete context, here's how the matcher picks for common project names:

  • "my weather app" → cloud-sun
  • "mobile weather" → cloud-sun (matches weather)
  • "Screen Recorder" → video-camera (matches screen.*recorder)
  • "todo list" → list-checks
  • "password manager" → lock
  • "Text Adventure" → book (matches adventure)
  • "The Deadlands" → game-controller (matches deadlands via the game rule's extended keyword list)
  • "collection" → app-window (no specific rule; falls through to default)
  • "random_thing_42" → app-window (default)

Overriding manually

Right-click a project in the sidebar → Change Icon. A picker dialog opens with ~30 curated options.

Pick one; it applies instantly and persists. The override is stored in project.json:

{
  "metadata": {
    "icon": "paint-brush"
  }
}

To clear the override and return to auto-matching, pick Use auto-match from the same menu.

The override picker

Rather than exposing all 125+ icons (which would be overwhelming), the override dialog shows a curated subset of the most visually distinctive choices:

  • Creative / media: music-notes, film-slate, video-camera, paint-brush, camera, image
  • Games / puzzles: game-controller, puzzle-piece
  • Utility: calculator, clock, cloud-sun, map-pin, mountains, list-checks, note-pencil, book
  • Communication: chats, envelope, newspaper
  • Data / work: chart-bar, database, terminal-window, file-py, folder-open
  • Life / personal: shopping-cart, coin, heart, fork-knife, barbell, leaf, planet
  • Security / AI: lock, brain, flask, rocket
  • Signature: knife (the Whittl mark — nice for "made with Whittl" projects)

Icon color

Icons inherit Whittl's theme:

  • Dark theme: muted cream for inactive projects, warm tan for the selected project
  • Light theme: muted navy for inactive, copper for selected

You don't configure this per-project. Whittl picks based on the current theme.

Collapsed sidebar view

When the Projects panel is collapsed (click the chevron), projects show as icon-only tiles. The per-project icons become the primary way to distinguish between them at a glance.

Hover over a collapsed tile to see the project name as a tooltip.

What happens when an SVG is missing

Whittl ships with 125+ Phosphor Duotone SVGs in assets/icons/. If a keyword rule somehow returns an icon name whose SVG isn't present (older versions had a few rules pointing at missing icons), Whittl falls back to app-window.

Why you can't see a project letter fallback anymore

Earlier versions would fall back to the project's first letter when the SVG was missing ("M" for "mobile weather"). That's gone in v2.3 — all rule targets are guaranteed to ship on disk, and the collapsed-sidebar fallback tries app-window before letters.

Regenerating matched icons

If you rename a project, the auto-match re-runs with the new name. If you had a manual override, the override wins (the rename doesn't clobber it).

To force a re-match after a rename, clear the override via right-click → Use auto-match.

What's next