284 lines
14 KiB
Markdown
284 lines
14 KiB
Markdown
# Native theme migration plan
|
|
|
|
Integrate [`native-theme`](https://github.com/tiborgats/native-theme) (via the
|
|
`native-theme-gpui` connector) so the app follows the OS native theme on
|
|
macOS, Windows and Linux (KDE/GNOME), instead of only the bundled
|
|
`signed.json` themes.
|
|
|
|
Principles for this migration: plug the connector in, migrate what it
|
|
replaces, do not wrap it, and do not adopt its optional subsystems (icons,
|
|
theme-drawn widgets, presets UI) in this pass.
|
|
|
|
---
|
|
|
|
## 1. Current state
|
|
|
|
| Piece | Location | Notes |
|
|
| --- | --- | --- |
|
|
| Startup theme setup | `desktop/src/main.rs` | `gpui_component::init` + `theme::init`, loads `signed.json` into `ThemeRegistry`, sets `Theme::global_mut` fields (`radius`, `radius_lg`, `focus_ring`, `shadow`, `font_size`, `mono_font_size`, `light_theme`, `dark_theme`), then `Theme::change` / `Theme::sync_system_appearance` |
|
|
| Runtime theme application | `crates/workspace/src/views/sidebar/settings_dialog.rs` | `apply_theme()` re-reads settings into the global `Theme`; `apply_appearance()` maps `AppearanceMode` to `Theme::change` / `sync_system_appearance` |
|
|
| System appearance follow | `crates/workspace/src/workspace.rs` | `cx.observe_window_appearance` → `Theme::sync_system_appearance` when appearance is `System` |
|
|
| Theme settings | `crates/settings/src/settings.rs` (`ThemeSettings`) | `light_theme`, `dark_theme`, `font_size`, `mono_font_size`, `radius`, `radius_lg`, `focus_ring`, `shadow` |
|
|
| Bundled themes | `crates/assets/assets/themes/signed.json` | `Signed Light` / `Signed Dark` colors + a `highlight` section (editor/syntax colors) |
|
|
| Theme consumers | `dock`, `signed_ui`, `workspace` | ~50 `cx.theme()` call sites via `gpui_component::ActiveTheme` |
|
|
|
|
Dependencies today (branch `feat/native-theme`, commit `eb4fbb0`):
|
|
`gpui-pre` 0.3.9, `gpui-pre-platform` 0.3.9, `gpui-component` 0.8,
|
|
`gpui-base` 0.8, toolchain 1.96.
|
|
|
|
## 2. What the connector does
|
|
|
|
`native-theme-gpui` turns a `native_theme::ResolvedTheme` (read from the OS,
|
|
or from a bundled preset) into a fully configured `gpui_component::Theme` and
|
|
installs it:
|
|
|
|
- all 139 `ThemeColor` fields, fonts, `radius`, `shadow`, `focus_ring`,
|
|
scrollbar and base-layer values;
|
|
- a `ThemeConfig` per mode, so the app's existing
|
|
`Theme::change(mode, None, cx)` / `Theme::sync_system_appearance(..)`
|
|
switch between the native light and dark palettes unchanged;
|
|
- an internal observer that restores the native values gpui-component
|
|
overwrites on each rebuild;
|
|
- accessibility: the OS text-scaling factor scales fonts (through the window
|
|
rem), reduce-motion and reduce-transparency are forwarded.
|
|
|
|
Because the connector produces a regular gpui-component `Theme`, every
|
|
existing `cx.theme()` call site keeps working without modification. That is
|
|
the core reason this integration is small.
|
|
|
|
Key APIs: `SystemTheme::from_system()`, `apply_system_theme(&system, cx)`,
|
|
`apply(theme, &resolved, &prefs, cx)`, `from_preset(name, is_dark, &prefs)`,
|
|
`AccessibilityPreferences::from_system()`.
|
|
|
|
## 3. Gate 0 — version compatibility (blocking)
|
|
|
|
Verified against crates.io and the upstream repo on 2026-10-21:
|
|
|
|
| Fact | Value |
|
|
| --- | --- |
|
|
| Latest connector | `native-theme-gpui` 0.6.1 (2026-10-09); upstream `main` is the same |
|
|
| Connector requires | `gpui-component ^0.7.1`, `gpui-base ^0.7.1`, `gpui-pre ^0.3.8`, Rust ≥ 1.95 |
|
|
| `gpui-component`/`gpui-base` 0.7.1 pin | `gpui-pre =0.3.8` |
|
|
| `gpui-component`/`gpui-base` 0.7.3 pin | `gpui-pre =0.3.9` |
|
|
| `gpui-component` 0.8.0 pins | `gpui-pre =0.3.9` (0.8.0 published 2026-10-19) |
|
|
| This branch | moved 0.7.1 / 0.3.8 → 0.8 / 0.3.9 in `eb4fbb0` ("chore: update deps") |
|
|
|
|
The pins are mutually exclusive: with the app on `gpui-component` 0.8, cargo
|
|
cannot unify the graph — the connector would pull a second `gpui-pre` 0.3.8
|
|
and a second `gpui-component` 0.7.x, and `apply(.., cx)` would not even
|
|
type-check against the app's `App`. **The connector cannot be added on top of
|
|
gpui-component 0.8 today.**
|
|
|
|
### Decision
|
|
|
|
Revert the GPUI-side dependency bump on this branch and align with the
|
|
connector's supported closure (recommended):
|
|
|
|
```toml
|
|
# [workspace.dependencies]
|
|
gpui = { package = "gpui-pre", version = "0.3.8" }
|
|
gpui_platform = { package = "gpui-pre-platform", version = "0.3.8", features = ["font-kit", "x11", "wayland"] }
|
|
reqwest_client = { package = "gpui-pre-reqwest-client", version = "0.3.8" }
|
|
|
|
gpui-component = { version = "=0.7.1", features = ["tree-sitter-languages"] }
|
|
gpui-base = "=0.7.1"
|
|
|
|
native-theme-gpui = { version = "0.6.1", default-features = false, features = ["system-fonts"] }
|
|
```
|
|
|
|
- This is the state of `master` before `eb4fbb0`, the version set the
|
|
connector was verified against (2026-10-08 stamp). The exact `=0.7.1`
|
|
pins are required, not a style choice: a caret `"0.7.1"` resolves 0.7.3,
|
|
whose `gpui-pre =0.3.9` pin drags the graph onto 0.3.9, outside the
|
|
closure the connector is verified against. The three `gpui-pre-*` family
|
|
crates are published in lockstep; all three move back to 0.3.8 together.
|
|
- The connector re-exports the `native-theme` types that appear in its
|
|
public signatures (`SystemTheme`, `AccessibilityPreferences`, …), so the
|
|
app does **not** need `native-theme` as a direct dependency.
|
|
- The cost of the revert is the two one-line tweaks `eb4fbb0` made for 0.8
|
|
(the `Deref` removal in `crates/dock/src/dock_area.rs` is restored; the
|
|
0.7.1 `ResizeHandle::on_drag` hands the closure an `Rc<T>` and requires
|
|
`E: Render`). The nostr changes in that commit are unrelated and stay.
|
|
- When `native-theme-gpui` releases gpui-component 0.8 support (upstream has
|
|
bumped within days of each gpui-component release so far), bump both sides
|
|
together in one commit.
|
|
|
|
Alternative, rejected for now: staying on gpui-component 0.8 and waiting for
|
|
upstream 0.8 support. Nothing in this migration depends on 0.8-only APIs, and
|
|
0.8.0 shipped two days before this plan, so the revert is the cheaper path.
|
|
|
|
Note: the connector's README quick-start shows the `gpui-kit` facade crate;
|
|
this project depends on `gpui-component` + `gpui-base` directly, which is
|
|
equivalent — no `gpui-kit` dependency is needed.
|
|
|
|
## 4. Target design
|
|
|
|
### 4.1 Theme source
|
|
|
|
The native OS theme becomes the primary source. The bundled `signed.json`
|
|
registry stays as the fallback when the OS theme cannot be read (unsupported
|
|
Linux desktop, headless, etc.). This keeps the existing startup code as the
|
|
fallback branch instead of deleting a working safety net.
|
|
|
|
### 4.2 Startup flow (`desktop/src/main.rs`)
|
|
|
|
Order is load-bearing:
|
|
|
|
1. `gpui_component::init(cx)` and `theme::init(cx)` — must run before
|
|
`apply` (connector requirement).
|
|
2. `SettingsStore` load — already before any theme work.
|
|
3. `ThemeRegistry` load from `Assets.themes()` — kept, feeds the fallback.
|
|
4. Apply the native theme:
|
|
|
|
```rust
|
|
// native_theme_gpui re-exports SystemTheme from native-theme.
|
|
match native_theme_gpui::SystemTheme::from_system() {
|
|
Ok(system) => native_theme_gpui::apply_system_theme(&system, cx),
|
|
Err(error) => {
|
|
tracing::warn!("native theme unavailable ({error}); using bundled themes");
|
|
// existing path: registry lookups + Theme::global_mut field setup
|
|
}
|
|
}
|
|
// shared: the existing `match settings.appearance { .. }` block stays,
|
|
// now driving native palettes per mode on the native path.
|
|
```
|
|
|
|
`apply_system_theme` installs both the light and dark variants plus their
|
|
configs, so the subsequent `Theme::change` / `sync_system_appearance` for the
|
|
user's `AppearanceMode` picks the right native palette.
|
|
|
|
Sizing note: gpui-component derives the window rem from `theme.font_size`, so
|
|
every rem-relative element scales with it. The OS-reported UI font (13 on
|
|
macOS) is smaller than the 16 this app is designed around, so the native path
|
|
multiplies `system.accessibility.text_scaling_factor` by
|
|
`settings.theme.font_size / native_size` before applying — the connector's
|
|
supported scaling knob, which also preserves any OS accessibility scaling.
|
|
The same factor scales `mono_font_size`, so code text follows the UI size
|
|
(the pre-migration app used 13 for mono while the UI was 16).
|
|
|
|
On the native path, do **not** set `radius` / `font_size` / `light_theme` /
|
|
`dark_theme` etc. on `Theme::global_mut` — the connector owns those fields,
|
|
and overwriting them fights its observer.
|
|
|
|
### 4.3 Appearance switching (no changes)
|
|
|
|
- `AppearanceMode::System | Light | Dark` and `apply_appearance()` in
|
|
`settings_dialog.rs` work as-is.
|
|
- `workspace.rs`'s `observe_window_appearance` → `sync_system_appearance`
|
|
keeps following the OS while in `System` mode.
|
|
- `Theme::change(mode, None, cx)` reproduces the native palette for the mode
|
|
because the connector installed a `ThemeConfig` per variant.
|
|
|
|
Known gap (not addressed here): gpui-component's system-appearance follow is
|
|
driven by window-activation events. A live OS theme change while the window
|
|
is focused may not propagate on Linux until the window is re-focused;
|
|
native-theme's `watch` feature (a theme-change watcher) is a possible
|
|
follow-up, out of scope.
|
|
|
|
### 4.4 Settings dialog (`settings_dialog.rs`)
|
|
|
|
Keep:
|
|
|
|
- the **Appearance** row (`System` / `Light` / `Dark`) and its handler.
|
|
|
|
Remove (the native theme now owns all of these):
|
|
|
|
- **Light Theme** / **Dark Theme** pickers and `theme_options()` — colors are
|
|
chosen by the OS. This is also the only way to avoid the connector's
|
|
registry trap: selecting a registry theme would overwrite the connector's
|
|
per-mode configs on the next `Theme::change` and silently drop native
|
|
colors until restart.
|
|
- **Font size**, **Mono font size**, **Radius**, **Large radius**,
|
|
**Focus ring**, **Shadows** rows and their handlers — the resolved theme
|
|
provides geometry, and the connector already scales fonts by the OS text
|
|
size. Keeping manual overrides would require re-applying them after every
|
|
upstream rebuild, a permanent fight with the connector.
|
|
|
|
`apply_theme()` and `theme_options()` are deleted outright: with the pickers
|
|
and number fields gone they have no remaining callers. The fallback logic
|
|
lives only in `main.rs`'s `Err` branch; the Appearance handler keeps working
|
|
through `apply_appearance()` alone (`Theme::change` picks up whatever configs
|
|
are installed, bundled or native).
|
|
|
|
`ThemeSettings` keeps its fields and serde shape — the fallback branch still
|
|
reads them, existing settings files keep parsing, and the tests in
|
|
`settings.rs` stay valid. They become fallback-only tuning (editable via
|
|
`settings.json`). Deleting the fields is a possible follow-up cleanup if the
|
|
fallback ever moves to native-theme presets.
|
|
|
|
### 4.5 Syntax highlighting (known trade-off)
|
|
|
|
`signed.json` carries a `highlight` section (editor and syntax colors) used by
|
|
code and markdown rendering (`TextView` in the files view and elsewhere). The
|
|
connector's installed per-mode configs carry upstream's default highlighter
|
|
styles, so on the native path the active syntax palette is upstream's, not
|
|
Signed's.
|
|
|
|
Decision for this pass: accept upstream's defaults — zero code. If the Signed
|
|
syntax palette must be kept later, investigate whether gpui-component 0.7
|
|
exposes a syntax-theme setter that survives `Theme::change`; do not build an
|
|
override mechanism now.
|
|
|
|
### 4.6 Features
|
|
|
|
Use the connector with narrowed features; the app uses its own SVG icons and
|
|
gpui-component widgets:
|
|
|
|
```toml
|
|
native-theme-gpui = { version = "0.6.1", default-features = false, features = ["system-fonts"] }
|
|
```
|
|
|
|
`system-fonts` keeps a theme font family the system lacks drawing in the
|
|
platform's substitute. `widgets` (theme-drawn checkbox/switch/etc.),
|
|
`material-icons`, `lucide-icons`, `system-icons`, `svg-rasterize` are all
|
|
unused here and each carries build weight (the icon bundles are ~2 MB).
|
|
Adopting any of them is a separate, deliberate follow-up.
|
|
|
|
## 5. Change list
|
|
|
|
| File | Change |
|
|
| --- | --- |
|
|
| `Cargo.toml` | Revert gpui-side pins to 0.3.8 / `=0.7.1` (Gate 0); add the `native-theme-gpui` workspace dep |
|
|
| `desktop/Cargo.toml` | Add `native-theme-gpui` |
|
|
| `desktop/src/main.rs` | Native apply with bundled fallback (§4.2); move the settings-field setup into the fallback branch |
|
|
| `crates/workspace/src/views/sidebar/settings_dialog.rs` | Remove theme picker + font/radius/focus/shadow rows; shrink `apply_theme` to fallback-only (§4.4) |
|
|
| `CHANGELOG.md` | Added: native OS theme via `native-theme`; Removed: manual theme/font/radius settings |
|
|
|
|
Unchanged:
|
|
|
|
- every `cx.theme()` consumer in `dock`, `signed_ui`, `workspace` — including
|
|
the dock/tab skins and window controls, which keep reading tokens;
|
|
- `crates/workspace/src/workspace.rs` appearance observer;
|
|
- `crates/settings` (fields stay), `crates/assets` (`signed.json` stays as
|
|
the fallback), `crates/dock`.
|
|
|
|
## 6. Validation
|
|
|
|
1. `cargo check`, `cargo test --workspace`, `cargo clippy` across the workspace
|
|
(toolchain 1.96 satisfies the connector's 1.95 MSRV).
|
|
2. Manual matrix, per platform available (macOS first; KDE and GNOME Linux;
|
|
Windows):
|
|
- cold start matches the OS theme and accent; radius, fonts and controls
|
|
read as native;
|
|
- switching Appearance `System ↔ Light ↔ Dark` in settings switches native
|
|
palettes;
|
|
- with `System`, changing the OS theme and re-focusing the window updates
|
|
the app;
|
|
- settings dialog, dock tabs, diffs, files view, markdown rendering look
|
|
correct; the syntax palette difference from §4.5 is reviewed and
|
|
accepted;
|
|
- `cargo run` once with native detection forced to fail (e.g. temporarily
|
|
return early in the match) to prove the bundled fallback still works.
|
|
3. `cargo tree -i gpui-pre` and `cargo tree -i gpui-component` must each show
|
|
exactly one version — the whole point of Gate 0.
|
|
|
|
## 7. Explicitly out of scope
|
|
|
|
- native-theme icon sets / `CustomIconName` mapping — the app keeps its own
|
|
SVG assets.
|
|
- theme-drawn widgets (`widgets` feature).
|
|
- a preset-picker UI (`from_preset`) in settings.
|
|
- runtime OS-theme watching (`watch` feature).
|
|
- per-field user overrides layered on the native theme.
|
|
- migrating `signed.json` into a native-theme `Theme` definition.
|