coop/docs/native-theme-migration.md

Migrate the UI to GPUI-Kit, then native-theme

Plan to move coop's custom UI elements onto GPUI-Kit (gpui-kit 0.7.1), delete the custom theme implementation (crates/theme), and then integrate native-theme through its official native-theme-gpui connector.

Revision. This supersedes the earlier approach in this file (depend on the native-theme core crate and hand-write a ResolvedTheme → coop token mapping). Going through GPUI-Kit first makes that mapping unnecessary: the connector already projects native themes onto gpui-component's Theme, and every call site reads cx.theme() from gpui-component directly.

1. What the git history shows

• 516eb0e — move gpui-components to ui crate: the UI crate was the upstream component library, vendored into crates/ui. Call sites used library components and its theme vocabulary (cx.theme().elevated_surface_background, surface_background, border_variant, …).
• 0c1c23f — migrate to gpui-base (#51): the vendored library was deleted and replaced by the gpui-base crate plus hand-written wrappers (Button, Switch, Dialog, Input, Dock, Menu, Notification, …) and the custom crates/theme.

"Migrate like before" therefore means: go back to the upstream component library — this time as a dependency (gpui-kit), not vendored — and let it own the theme.

2. Strategy

graph LR
    A[Phase A: GPUI-Kit] --> B[Phase B: native-theme-gpui]
    A1[A1 Bootstrap<br/>init + open_window + Root] --> A2[A2 Component swap<br/>~20 custom modules]
    A2 --> A3[A3 Theme removal<br/>cx.theme = gpui-component]
    A3 --> B1[B1 Connector<br/>apply_system_theme]
    B1 --> B2[B2 Appearance + presets<br/>settings wiring]

Phase A replaces the custom elements with gpui_kit::component components and moves all color reads onto gpui-component's Theme (ThemeColor, 139 semantic fields). The app runs on gpui-component's built-in light/dark palettes at the end of Phase A; crates/theme is gone.

Phase B adds native-theme-gpui, which installs native OS themes (or any of 16 bundled presets) into that same Theme. No call site changes — the connector is verified against exactly the versions Phase A pins.

Target dependency set (exact versions)

Crate	Version	Note
gpui-kit	0.7.1	facade: gpui_kit::* = GPUI (gpui-pre), gpui_kit::component (gpui-component 0.7.1), gpui_kit::base (gpui-base 0.7.1), gpui_kit::assets
gpui-pre	=0.3.8	already pinned; gpui-kit 0.7.1 requires it
native-theme-gpui	0.6	Phase B; verified against gpui-kit 0.7.1 / gpui-pre 0.3.8; needs Rust ≥ 1.95 (toolchain is 1.98)

Do not jump to gpui-kit 0.8: native-theme-gpui 0.6.1 pins 0.7.1, and a gpui-component patch release has broken the connector before.

3. Current custom UI inventory

crates/ui is ~8,700 lines across 34 files. Consumers import it at ~138 sites (workspace 14 files, chat_ui, nip29_ui, nip4e, settings, desktop, web); theme tokens are read at ~340 sites across the same crates.

Custom module	Lines	GPUI-Kit replacement
menu/ (popup, dropdown, item)	983	menu::{PopupMenu, PopupMenuItem, DropdownMenu, ContextMenu}
dock/ (mod, panel)	1,032	dock (entity-backed DockArea / panels)
motion.rs	668	keep — app-level animation, no theme dependency
notification.rs	594	notification::Notification + WindowExt::push_notification; placement via Theme.notification
button.rs	581	button::{Button, ButtonGroup, Toggle, DropdownButton}
message.rs	553	evaluate message::{Message, Bubble, Attachment, MessageScroller}; keep as app composite where it fits better
avatar.rs	445	avatar::Avatar
root.rs	430	framework Root via gpui_kit::open_window (owns dialogs, notifications, tooltip/menu layers, focus traps)
dialog.rs	394	WindowExt::open_dialog / AlertDialog; custom footer buttons → Dialog's footer API
input/	~290	input::{Input, InputState, Textarea, NumberInput}; delete the custom styling (its input_bg/selection/caret reads die with it)
icon.rs	274	Icon + IconName (Lucide); keep ui::icon as a thin mapping shim (see §4.3)
kbd.rs	270	Kbd
tab/	385	tab::{Tab, TabBar, Tabs}
title_bar.rs	218	TitleBar (keep the client-side-decoration constants)
popover.rs	170	popover::Popover
styled.rs	161	h_flex/v_flex/StyledExt from the kit; drop coop-specific helpers as their users migrate
switch.rs	157	switch::Switch
markdown.rs	146	text::TextView::markdown (code styling via Theme.highlight_theme)
nav.rs + nav_item.rs	268	sidebar::{Sidebar, SidebarMenu, …}; if the coop layout doesn't fit, keep as an app composite on top of kit primitives — decide during the slice
group_box.rs	126	group_box::GroupBox
scroll/	~124	scroll::{Scrollbar, Scrollable}
resizable/	31	resizable::{h_resizable, v_resizable, resizable_panel}
tooltip.rs	34	.tooltip()
indicator.rs	59	Marker/Badge, or keep if neither fits
window_ext.rs	90	gpui_kit::component::WindowExt

4. Phase A — GPUI-Kit migration

4.1 Bootstrap

• desktop/main.rs and web/lib.rs: gpui_kit::init(cx) first, then open the window with gpui_kit::open_window(opts, cx, |window, cx| …), which installs the framework Root (dialog, sheet, notification and tooltip layers). Delete ui::Root and its layers; workspace::init stays as the window's content view.
• TitlebarOptions / client-side decoration setup stays coop's (CLIENT_SIDE_DECORATION_*, TABBAR_HEIGHT move to ui).
• Keep bind_keys before set_menus (guide rule); coop already does.

4.2 Component slices (each PR compiles)

Replace one family at a time; consumers update in the same PR:

1. Deps + bootstrap (above). Custom components still work alongside the framework Root.
2. Icons — introduce the ui::icon shim so later slices see kit icons through the old call sites (see §4.3).
3. Small controls — Button, Switch, Kbd, GroupBox, Avatar, Tooltip, Indicator, Popover.
4. Menu — PopupMenu/DropdownMenu/ContextMenu (+ the popup-menu actions already imported from gpui_base::actions).
5. Input — Input/InputState/Textarea; port the chat composer, dialog fields, relay editor; drop the clear-button and input-styling modules.
6. Dialog + Notification — open_dialog/AlertDialog/ push_notification; port the settings, relays, profile, new-chat, import… dialogs; the custom footers move to the Dialog footer API.
7. Scroll + Resizable + Tab — panels and the workspace tab strip.
8. Sidebar/Nav — Sidebar family (or keep composites, per the table).
9. Title bar — kit TitleBar + traffic-light handling.
10. Dock — the biggest single item (805 + 205 lines, dock::add registry, DockPlacement). Port panels onto DockArea; do it last so the panels it hosts are already kit-based.
11. Message + Markdown — TextView::markdown; Message/Bubble where they fit, otherwise keep ui::message as an app composite (it is domain layout, allowed by the guides' app-component layer).
12. Cleanup — delete the replaced modules; decide what crates/ui still is (see §4.4).

4.3 Icons

coop's IconName has 128 variants backed by assets/icons/*.svg; the kit's IconName (Lucide) has 106. Keep ui::icon as a mapping module: a coop-IconName enum (same variant names) that resolves to the kit IconName where a Lucide equivalent exists, and to a custom asset path (coop's bundled SVGs) where it doesn't (brand marks, a few specials). Most Icon::new(...) call sites then keep compiling with import changes only. Delete assets/icons entries that get Lucide equivalents; keep assets/brand.

4.4 Theme removal

• Call sites: theme::ActiveTheme → gpui_kit::component's ActiveTheme (cx.theme() -> &Theme). Rewrite the ~340 token reads with the mapping below (done per consumer crate, one slice each: ui, workspace, chat_ui, nip29_ui, settings + nip4e).

coop token (cx.theme().x)	gpui-component ThemeColor
bg	background
surface	sidebar
surface_raised	secondary
surface_card	muted
surface_dialog, surface_overlay	popover
element_hover	accent (gpui-component's accent is the item highlight)
element_active	list_active
border	border
border_faint, border_strong	border (one border token; faintness loss accepted)
ring	ring
text	foreground
text_muted, text_faint, text_dim	muted_foreground
cursor, caret	caret
selection	selection
solid / on_solid	primary / primary_foreground
accent, accent_strong	primary (emphasis ink)
danger / danger_muted	danger
danger_strong	button_danger
warning / warning_muted	warning / warning.alpha(≈0.15) at the call site
success	success
input_bg, selection, caret inside the custom input	die with the custom Input (§3)
code_text, code_wash	die with ui::markdown → TextView
drop_line / drop_target	drag_border / drop_target

• Non-color fields move to Theme directly: font_sans/font_mono → theme.font_family/mono_font_family; shadow → theme.shadow; scrollbar_mode → theme.scrollbar_mode; notification placement → theme.notification (gpui-component ships the same NotificationSettings coop's was modeled on); is_dark() → theme.mode.
• crates/theme disposition:
  • delete: lib.rs (Theme global, AppExt, sync_base, PaletteBuilder), colors.rs, palette.rs, brand.rs, appearance.rs, paint.rs, color.rs, syntax.rs, notification.rs, scrollbar_mode.rs, platform_kind.rs;
  • move to crates/ui unchanged: typography.rs (TextStyle/Typeset, ~200 call sites — retained deliberately as coop's type ladder), layout.rs (spacing constants, radius accessors), geometry.rs (Edges/Side/AxisExt), and the three CLIENT_SIDE_DECORATION_* constants;
  • AppearanceMode (System/Light/Dark, serde-persisted) moves into crates/settings.
• The gpui-base projection coop did in sync_base is now the framework's job (Theme::update / Theme::change keep colors, tokens and the base layer in step per the coding guides).

4.5 Appearance handling (end of Phase A)

• settings::apply_theme → Theme::change(mode, None, cx) for a pinned Light/Dark, Theme::sync_system_appearance(None, cx) for System.
• workspace's Theme::sync_system_appearance(Some(window), cx) call stays, now against the kit's Theme; window-appearance observation comes with the framework Root/theme (verify; if not, keep the existing observe_window_appearance wiring).

5. Phase B — native-theme-gpui

1. Add native-theme-gpui = "0.6" (pulls native-theme; keep default features or trim icon features coop doesn't use).

2. Boot, after gpui_kit::init and before opening the window:

   match native_theme::SystemTheme::from_system() {
       Ok(sys) => native_theme_gpui::apply_system_theme(&sys, cx),
       Err(error) => {
           log::warn!("system theme unavailable: {error}");
           // per-platform fallback preset: macos-sonoma / kde-breeze / windows-11
           let prefs = native_theme_gpui::AccessibilityPreferences::default();
           if let Ok((theme, resolved)) = native_theme_gpui::from_preset("macos-sonoma", true, &prefs) {
               native_theme_gpui::apply(theme, &resolved, &prefs, cx);
           }
       }
   }
   

   apply_system_theme stores both variants and a ThemeConfig per mode; afterwards the Phase A controls keep working unchanged: Theme::sync_system_appearance / Theme::change switch between the native palettes.

3. Optional preset picker (the same one proposed in the superseded plan): settings.theme_preset: Option<String>, a dropdown in Preferences → Appearance; selecting one calls from_preset(name, is_dark, &prefs) + apply for both variants.

4. Fonts, radius, scrollbar geometry and the base layer are written by the connector (it also re-asserts them after each upstream rebuild via its observer). Coop writes nothing theme-related itself.

wasm: SystemTheme::from_system is unavailable on wasm32 — cfg-gate step 2 to native targets; on web, apply the fallback preset (or extend native-theme with a web story later; presets need no OS reader).

6. Testing and QA

• Per slice: cargo check workspace, cargo clippy, cargo fmt --check, plus the affected crate's tests; UI behavior verified by hand in the desktop app.
• Early spike (before slice 2): cargo check -p web --target wasm32-unknown-unknown with the gpui-kit dependency added. The vendored library was wasm-capable; confirm the published crates are too before committing to the migration. If they are not, stop and reassess — the web target is a launch blocker.
• End of Phase A:
  • all dialogs open/close, focus trap and restore works; nested popover-in-dialog works (framework Root owns the layers);
  • notifications stack and auto-hide; settings' appearance dropdown switches Light/Dark/System with a full repaint;
  • dock panels move, split and zoom; sidebar resizes; scrollbars behave in Hover/Always/Scrolling modes;
  • markdown code blocks render through TextView with syntax colors from Theme.highlight_theme.
• End of Phase B:
  • macOS: OS light/dark follows; pinned modes; accent changes picked up at next launch (documented limitation — no watch feature);
  • Linux (KDE + GNOME/portal) and Windows: theme reads work or fall back to the platform preset with a logged warning;
  • preset switch renders in both modes; inputs/menus/dialogs/tooltips/ scrollbars all paint from the native palette;
  • startup shows no wrong-palette flash (apply before the first window).

7. Risks

Risk	Mitigation
Scale: ~8.7k lines of custom UI, ~140 ui:: imports, ~340 token reads	Slices in §4.2 each compile; crates/ui acts as the facade during the migration so consumer churn is incremental
Dock port (largest, most stateful)	Scheduled last; panels are kit-based by then; DockArea owns layout state coop currently hand-rolls
gpui-component on wasm	Spike in §6 before committing; fallback would be staying on 0.7.1 desktop-only and parking the web target
Visual identity changes (shadcn-style stock palette in Phase A)	Accepted — requirement says the current palette need not survive; Phase B replaces it with native themes anyway
Icon gaps (coop 128 vs Lucide 106)	Mapping shim keeps coop names; unmatched variants fall back to bundled SVGs
API drift between coop's wrappers and the kit (e.g. Sizable, Disableable, callback shapes)	Per the coding guides: never invent APIs; verify each component page / source signature during its slice
TextStyle ladder is a deliberate holdout from rem-based text	Documented exception; sizes are absolute points and don't claim to zoom. Revisit only if the kit's text scale is adopted later
native-theme-gpui version coupling	Pin gpui-kit = "=0.7.1"-era set (0.7.1, gpui-pre =0.3.8) matching the connector's verified table; bump all together

8. Out of scope

• Migrating motion.rs or the panel-background image feature.
• Accessibility text scaling / reduce-motion plumbing (connector supports it; adopt after Phase B if wanted).
• Replacing coop's composited panels (chat, screening, backup…) with kit Sheet/Settings — revisit after the migration settles.