coop/docs/native-theme-migration.md

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

Status: Phase A is implemented (on the working tree, uncommitted). The app builds against gpui-kit (resolved 0.7.3 / gpui-pre 0.3.9), every UI element comes from the kit, and crates/theme is deleted.

Follow-up (this revision, also uncommitted): the last custom modules in crates/ui are gone — motion, typography, layout and styled were deleted and every call site now reads gpui-kit tokens directly (text_xs / text_sm, cx.theme().radius / radius_lg, gap_2, Separator). The dock wears the previous skin again, ported from the signed reference implementation onto the kit dock engine (workspace::dock: pill tabs, the 44px bar that doubles as the title bar, window controls, collapse buttons, chromeless sidebar group). The avatar with the pixel fallback is back (ui::Avatar): user image when set, deterministic pixel art from the profile/group seed otherwise, also as the image-load fallback. Desktop traffic lights recenter for the 44px bar (workspace::TAB_BAR_HEIGHT). Validation: cargo check, cargo clippy and cargo fmt are clean workspace-wide and the desktop binary builds; the wasm32 check fails identically before and after (pre-existing state → gpui_tokio and rustls blockers, verified at HEAD).

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.

Revision 2. Full replacement, no hybrids: no custom UI element is kept or maintained after Phase A. Earlier hybrid positions in this file (keep ui::message where it fits, possibly keep nav composites, keep an icon mapping shim) are dropped — kit elements are adopted outright, chat-specific composition moves into chat_ui, and the only coop-owned visuals left are brand SVG assets rendered through the kit Icon.

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. At the end of Phase A crates/ui contains no UI elements: every element comes from the kit, and only app utilities survive there (§4.4).

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 — animation utility, not an element; 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	message::{Message, Bubble, MessageGroup, MessageScroller} (avatar/header/content/footer slots); author grouping, date separators and receipts move into chat_ui as app code
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	kit Icon + IconName (Lucide) at every call site; the module and the coop enum are deleted (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, SidebarHeader, SidebarGroup, SidebarMenu, SidebarMenuItem, SidebarFooter}; the nav layout is adapted to the kit structure, not preserved
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::Marker / badge::Badge; the custom module is deleted either way
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.
• Register a combined AssetSource at app construction: coop's existing per-platform source for assets/brand and images, with gpui_kit::assets::Assets as the fallback for the component icon bundle (embedded on desktop; CDN-on-demand on wasm).
• 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 — rewrite every icon call site onto kit Icon/IconName and delete ui::icon in the same PR (see §4.3). Mechanical churn: one Lucide target per coop variant, Icon::path for brand marks; doing it early settles the imports for all later slices.
3. Small controls — Button, Switch, Kbd, GroupBox, Avatar, Tooltip, Popover; Indicator → Marker/Badge.
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 — port the nav onto sidebar::{Sidebar, SidebarGroup, SidebarMenu, …} and delete nav.rs/nav_item.rs in the same PR.
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; port chat rows onto Message/Bubble/MessageGroup + MessageScroller. Chat-specific composition (author grouping, date separators, receipts) is app code in chat_ui, built from kit elements — crates/ui keeps no message component.
12. Cleanup — delete the replaced modules; crates/ui ends as a utilities-only crate (see §4.4).

4.3 Icons

No mapping shim and no coop IconName enum: every call site uses the kit's Icon + IconName (Lucide) directly. During slice 2, give each of coop's 128 variants a Lucide target — exact equivalent where one exists, nearest match otherwise, accepting the visual difference. The only coop-owned SVGs that survive are true brand/product marks under assets/brand, rendered through the kit element with Icon::path("brand/….svg") (the kit Icon accepts any asset path). Delete assets/icons entirely once the last call site is mapped.

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;
  • the typography, layout, styled and motion modules were NOT kept: a follow-up revision removed them and adapted every call site to gpui-kit tokens — the TextStyle ladder collapsed to text_xs/text_sm (plus font_semibold/font_medium), the radius ladder to cx.theme().radius / cx.theme().radius_lg, SPACE to gap_2, divider to the kit Separator, and motion was deleted unused. geometry.rs and the CSD constants never carried over (the framework Root draws the window border); TAB_BAR_HEIGHT (44px, the dock tab bar that doubles as the title bar) now lives in workspace::dock and SIDEBAR_WIDTH in workspace;
  • end state: crates/ui is avatar.rs + window_drag.rs only — see the status note at the top of this file for the restored dock skin and avatar (the two deliberate exceptions to "no custom elements");
  • 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;
  • every icon renders from the kit Lucide bundle, and brand marks render via Icon::path on desktop and web (on wasm the kit bundle is fetched from CDN on demand; coop brand assets still come from coop's own source).
• 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, then shrinks to utilities (§4.4)
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; kit Message/Sidebar look replacing coop's chat/nav styling)	Accepted — requirement says the current palette need not survive; Phase B replaces it with native themes anyway
Icon gaps (coop 128 vs Lucide 106)	Nearest-Lucide target per variant in slice 2; only true brand marks stay as coop assets via Icon::path
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.