Design note for user-facing theming. Written to be implemented against directly. Status: planned: Phase 0 (the selection-accent override seam) has shipped; Phases 1–4 are the work this note scopes.
← Back to Feature notes · Architecture · TODO
- 1. Goal and scope
- 2. Current state (what exists today)
- 3. What gpui-component already provides (verified)
- 4. Design principles / constraints
- 5. Data model & persistence
- 6. Phased plan
- 7. Settings UX (Appearance page, end state)
- 8. Integration points (files)
- 9. Open questions (resolve before Phase 1 build)
- 10. Risks & trade-offs
- 11. Testing & verification
Let users change how Ferail looks without touching code:
- Pick a theme from a small bundled set (beyond today's single light + dark palette).
- Drop in their own theme as a JSON file and have it appear in the picker, hot-reloading on save.
- Override individual accents (selection color today; a few more later) on top of whichever theme is active.
Non-goals for v1: a full in-app visual theme editor, importing other apps' theme formats, and per-window themes. They're noted as future work in §8.
- The app uses gpui-component's theme (
cx.theme()→ThemeColor): one light palette and one dark palette, both the library defaults. We never set a named theme. app_state.theme_prefholds the mode (light/dark/system).settings.rs(ThemePref,persist_theme_pref, the theme-tile strip) andmain.rs(Theme::change(mode, …)at init) drive it. A background→UI bridge inshell.rs(apply_pending_theme) exists because the worker thread has no&mut App.- Phase 0 shipped (2026-06-20): [
crate::selection_colors] adds aSelectionAccent(Option<Hsla>)global (override-or-theme.blue), seeded fromapp_state.selection_color, edited by aColorPickeron the Appearance page. The file list and icon grid both read its helpers, so selection is one hue across views and the user can recolor it live. This is the override seam the rest of this plan generalizes.
The gap: users can flip light/dark and recolor selection, but cannot pick a different palette or supply their own.
We do not need to build a theme engine: the library ships one. Verified in
the pinned checkout (crates/ui/src/theme/):
Themeglobal (Theme::global(cx)/global_mut): holdslight_theme: Rc<ThemeConfig>,dark_theme: Rc<ThemeConfig>, andmode.Theme::change(mode, window, cx)re-applies the registry's default light/dark for that mode. To use a named theme, setlight_theme/dark_themeto a registryThemeConfigand re-apply.ThemeRegistryglobal, installed bygpui_component::init(cx)(already called atmain.rs:360). It also installs a global observer that re-applies the active theme whenever the registry changes, so loading/adding themes repaints live. Key API:themes() -> HashMap<name, Rc<ThemeConfig>>,sorted_themes()default_light_theme()/default_dark_theme()load_themes_from_str(json): register themes from a JSON stringwatch_dir(dir, cx, on_load): background-load every theme file in a directory and hot-reload on change (off the UI thread)
ThemeConfig={ name, mode: Light|Dark, colors: ThemeConfigColors, highlight? }.ThemeSet={ name, themes: [ThemeConfig, …] }: one file bundles a light + a dark variant. Both are serde JSON; the token vocabulary is shadcn/Tailwind-style (background,foreground,accent,primary,table_active, base scales likeblue50–950, …).highlightrestyles the syntax-highlighted preview, so a theme can also recolor code.Colorizetrait onHsla:opacity,lighten,darken,mix,mix_oklab,hue,invert,to_hex,parse_hex. All the color math the override layer needs (Phase 0 already usesparse_hex/to_hex/opacity).ColorPicker/ColorPickerState: HSL sliders + palettes + hex input (already wired for the selection accent).Settingspages primitive, already hosts the Appearance page.
- Prime Directive (UI must never stop). Theme files are I/O, so all
reads happen off the paint path:
watch_dirbackground-loads; persisted choice is read once at startup (an existing I/O boundary); switching a theme at runtime only reads the in-memory registry, no disk touch in the gesture. - Light and dark are separate
ThemeConfigs. A user-facing "theme" is a pair. Model a picked theme as a set name that supplies both a light and a dark variant;mode(Light/Dark/System) selects which is active. (Allowing independent light/dark choices is a later refinement: see §8 / §9.) - Overrides are a layer on top of the theme, not theme edits. The selection accent (and future overrides) re-apply after a theme loads, so they survive theme switches. Each override is independently resettable to "follow theme."
- Keep it small (Slow AI default). Start with 2–3 curated bundled themes to
prove the path; don't ship a sprawl. No new state-management or plugin layer:
reuse the existing
app_statekey=value file and theGlobalpattern.
Add to app_state (flat key=value, unknown keys ignored: back/forward safe):
| Key | Type | Meaning |
|---|---|---|
theme_pref (exists) |
light|dark|system |
Active mode. |
theme_name (new) |
string | Chosen theme-set name. None/absent = library default. |
selection_color (exists) |
#RRGGBB(AA) |
Selection-accent override. |
Phase 3 may add more override keys (e.g. heat_tint, favorite_star), each
Option<hex>, all behind the same parse/validate guard selection_color
already uses. Independent light/dark theme names (theme_light_name /
theme_dark_name) are reserved for §9 if we adopt that model.
selection_colors module + SelectionAccent global + ColorPicker. Proves the
override → persist → live-repaint loop. See §2.
- Bundle 2–3 extra theme sets as JSON assets (alongside the existing asset
pipeline in
assets.rs). Each is aThemeSetwith a light + darkThemeConfig. Suggested starters: one warm/sepia, one high-contrast, one cool/solarized-like, enough to show range without bloat. - Register them right after
gpui_component::init(cx)inmain.rsviaThemeRegistry::global_mut(cx).load_themes_from_str(json)for each. - Apply persisted choice at startup: if
theme_nameis set and present in the registry, setTheme::global_mut(cx).{light,dark}_themeto that set's variants, thenTheme::change(mode, …). - Picker UI: an Appearance-page Theme dropdown listing
registry.sorted_themes()set names (the existing Light/Dark/System tiles stay : they choose mode; the dropdown chooses palette). On select: update theThemeglobals, persisttheme_name,cx.refresh_windows(). - Live + persistent; no relaunch. Mirrors the
persist_theme_pref+Theme::changeflow already insettings.rs.
- On startup call
ThemeRegistry::watch_dir(<config>/Ferail/themes, cx, on_load)(the sameconfig_dir()app_stateuses). Background-loads every theme file; user JSONs appear in the picker; saving a file hot-reloads it. - Affordances on the Appearance page: "Open themes folder" (reveal in Finder) and, since the watcher already reloads, an optional "Reload themes" fallback.
- Document the schema for authors: write a
README+ an annotated exampleThemeSetJSON into the folder on first run, and a short authoring section in this doc. Note the token vocabulary mirrors gpui-component'sThemeConfigColors. - Guard rails: a malformed file must not crash or block:
watch_diralready logs and skips on parse error; surface a quiet, non-blocking notification listing files that failed to load.
- Promote
selection_colorsinto a small appearance-overrides module that holds anOption<Hsla>per overridable role (selection accent now; candidates: Ant-Trail heat tint, favorite-star tint, both currently hard-coded). Each resolves to its theme-derived default when unset. - Re-apply order: after any theme switch, re-seed the override globals so overrides ride on top of the new palette (today only one global, trivially re-seeded; formalize it as theme switching lands in Phase 1).
- Settings: one
ColorPickerrow per role under an "Accents" group, each with a "follow theme" clear. Keep the set short: overrides are for the few colors the theme can't express well (see the selection rationale: the theme'stable_activeis alpha-capped ≤ 0.2 and desaturated, which is why selection needs an override rather than a theme field).
- In-app theme editor: live-edit roles with
ColorPickerrows over a workingThemeConfig, preview, export to JSON in the themes folder. - Import converters from popular external theme formats →
ThemeConfig. - Independent light/dark theme selection (see §9).
- Per-syntax highlight theme picker (reuse
ThemeConfig.highlight).
Theme
( ) Light ( ) Dark ( ) System ← mode (exists)
Theme: [ Ferail Default ▾ ] ← Phase 1 dropdown
Custom themes folder: [ Open ] [ Reload ] ← Phase 2
Accents
Selection color [■] (clear) ← Phase 0 (shipped); Phase 3 adds more
crates/ferail-gpui/src/main.rs(~360–410): register bundled themes aftergpui_component::init; apply persistedtheme_name; startwatch_dir.crates/ferail-gpui/src/settings.rs: Theme dropdown + persistence (mirrorpersist_theme_pref); the Appearance page already owns the selection picker.crates/ferail-gpui/src/shell.rs: extend theapply_pending_themebridge if a non-UI-thread path ever needs to switch themes (likely not for v1).crates/ferail-gpui/src/app_state.rs:theme_name(+ future override keys) field, parse arm, save line.crates/ferail-gpui/src/assets.rs: bundle the theme JSON assets.crates/ferail-gpui/src/selection_colors.rs: Phase 3 generalization.
- Pairing model: pick a set (one name → light+dark), or choose light and dark independently? Recommend set-based for v1 (simpler picker, matches how people think); independent is a Phase 4 refinement. The registry tracks light/dark names separately, so either is supportable.
- How many bundled themes, and which aesthetics? Recommend 2–3 curated.
- Highlight themes: do bundled themes also restyle the code preview
(
ThemeConfig.highlight), or keep syntax colors constant across themes? - Override breadth (Phase 3): which roles beyond selection are worth a picker (heat tint, favorite star, …) vs. left to full themes?
- Schema coupling: custom themes are pinned to gpui-component's
ThemeConfigschema; a dependency bump could rename/move tokens and break user files. Mitigation: document the pinned schema, fail soft (skip + notify), and treat a dep bump as a migration checkpoint. - Unreadable user themes: we don't validate contrast; a bad custom theme can make the UI illegible. Mitigation: the bundled/default theme is always present and one click away; never let a custom theme become unremovable.
- Watcher cost:
watch_diradds a filesystem watcher, but it's off the UI thread and only over a small user folder: negligible, and consistent with the Prime Directive.
- Extend the screenshot harness
--themeflag to accept a theme-set name (today it takeslight/dark); snapshot list + grid + Appearance under each bundled theme, light and dark. - Headless caveat (same as elsewhere): the
ColorPickerpopup and any dialog animate over multiple paints and render faint in single-frame captures: verify the popup interactively; the closed picker button + applied colors are captured fine. - Unit-test
app_stateround-trips fortheme_nameand override keys, and the hex validation guard.