From 9198fae30e42b338dc22a41c4ffc2cab3a8d7172 Mon Sep 17 00:00:00 2001
From: skylar taylor-barrick <hi@skylar.cc>
Date: Fri, 9 Oct 2026 13:14:03 -0600
Subject: [PATCH] UI.4: share widget-state theme application

---
 NOTICE                       |   5 ++
 README.md                    |   4 +-
 crates/ui/README.md          |  25 +++++-
 crates/ui/src/lib.rs         |   1 +
 crates/ui/src/theme/mod.rs   |  97 +++++++++++++++++++++
 docs/theme-infrastructure.md | 162 +++++++++++++++++++++++++++++++++++
 docs/ui-components-audit.md  |   2 +
 7 files changed, 294 insertions(+), 2 deletions(-)
 create mode 100644 crates/ui/src/theme/mod.rs
 create mode 100644 docs/theme-infrastructure.md

diff --git a/NOTICE b/NOTICE
index 83bd778..7774abe 100644
--- a/NOTICE
+++ b/NOTICE
@@ -32,4 +32,9 @@ The pane sizing and resize boundaries in crates/ui/src/layout draw on:
 - EffectCraft, crates/ui-egui/src/dock.rs, revision 2a460986ee7a4b32656a3d434849693904b486bc.
   https://github.com/storytold/effectcraft
   Copyright (c) 2026 ArtCraft Team and the EffectCraft contributors.
+The widget-state styling in crates/ui/src/theme is adapted from VectorCraft (above),
+crates/ui-egui/src/theme.rs, and:
+- DesignCraft, crates/ui-egui/src/theme.rs, revision 66c7ce7e96ec286a091878cc2541ee8369aa79d6.
+  https://github.com/storytold/designcraft
+  Copyright (c) 2026 ArtCraft Team and the DesignCraft contributors.
 All sources listed above are licensed MIT OR Apache-2.0. No icon artwork is copied here.
diff --git a/README.md b/README.md
index 9dd3a37..e0e78b7 100644
--- a/README.md
+++ b/README.md
@@ -23,10 +23,12 @@ craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit
 
 ## Libraries
 
-- [`craft-ui`](crates/ui/README.md): SVG catalogs, icon buttons, tabs and pane controls for egui frontends;
+- [`craft-ui`](crates/ui/README.md): SVG catalogs, icon buttons, tabs, pane controls and theme helpers for egui frontends;
   assets, themes, localization and command handling stay in each app. Requires Rust 1.95 or later.
 - [Shared UI component audit](docs/ui-components-audit.md): source inventory, extraction priorities
   and compatibility boundaries across the Craft suite.
+- [Theme infrastructure](docs/theme-infrastructure.md): eight-app comparison and the small shared
+  widget-state styling boundary.
 
 ## License and credits
 
diff --git a/crates/ui/README.md b/crates/ui/README.md
index 8cdee6f..3025703 100644
--- a/crates/ui/README.md
+++ b/crates/ui/README.md
@@ -2,7 +2,7 @@
 
 `craft-ui` provides small egui components with application-supplied styles. `icons` prepares
 embedded SVG catalogs; `buttons` paints accessible icon buttons; `tabs` handles tab fitting and
-interaction; `layout` provides split geometry and resize handles. Components have adapters in
+interaction; `layout` provides split geometry and resize handles; `theme` shares widget-state styling. Components have adapters in
 PhotoCraft, VectorCraft, PdfCraft, DesignCraft, FilmCraft and EffectCraft. Assets, complete themes, localization and command
 handling remain in each application. No icons, fonts or application engines are bundled.
 
@@ -148,6 +148,29 @@ or use an application-specific adapter. The library does not persist geometry, d
 or create panes. Apps keep their existing dock trees, stacked panels, layout files, pane contents,
 cameras, document focus and native windows. Shared controls do not constitute a dock-tree migration.
 
+## Theme mechanisms
+
+`theme::WidgetPalette` applies background colors to egui's five widget states, with a supplied
+corner radius and foreground stroke. VectorCraft and DesignCraft construct it from their existing
+local tokens. It updates each state's strong/weak background fill, radius and foreground; borders,
+expansion and all other visual settings are retained.
+
+```rust
+use craft_ui::theme::WidgetPalette;
+use egui::{Color32, CornerRadius, Stroke};
+
+fn style_widgets(visuals: &mut egui::Visuals, palette: WidgetPalette, text: Color32) {
+    palette.apply_to(&mut visuals.widgets, CornerRadius::same(4), Stroke::new(1.0, text));
+    // Optional app-specific exceptions belong after the shared operation.
+    visuals.widgets.inactive.weak_bg_fill = Color32::TRANSPARENT;
+}
+```
+
+This is a mechanism for coloring widgets, not a shared theme schema. Fonts, complete palettes,
+selection colors, shadows, spacing, context storage and preference serialization remain in each
+application. See the [eight-app comparison](../../docs/theme-infrastructure.md) for the exact
+common operation and the differences preserved by the adapters.
+
 ## Compatibility and checks
 
 The crate uses egui 0.36 and Rust 1.95 or later. Its production dependency disables egui's default
diff --git a/crates/ui/src/lib.rs b/crates/ui/src/lib.rs
index 585b388..b54cc84 100644
--- a/crates/ui/src/lib.rs
+++ b/crates/ui/src/lib.rs
@@ -9,3 +9,4 @@ pub mod buttons;
 pub mod icons;
 pub mod layout;
 pub mod tabs;
+pub mod theme;
diff --git a/crates/ui/src/theme/mod.rs b/crates/ui/src/theme/mod.rs
new file mode 100644
index 0000000..26f9e9d
--- /dev/null
+++ b/crates/ui/src/theme/mod.rs
@@ -0,0 +1,97 @@
+//! Theme mechanisms for egui widgets, with palettes and theme selection owned by applications.
+//!
+//! This module does not install fonts, store a theme, or change global visuals. Applications
+//! decide their colors, borders, typography, spacing and saved preferences independently.
+
+use egui::{Color32, CornerRadius, Stroke, style::Widgets};
+
+/// Background colors for egui's five widget interaction states.
+///
+/// These are rendering inputs, not a theme schema: applications construct them from their own
+/// tokens. In particular, `noninteractive` describes egui's noninteractive widget state, not a
+/// disabled control palette. egui and the application retain their disabled-state behavior.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct WidgetPalette {
+    pub noninteractive: Color32,
+    pub inactive: Color32,
+    pub hovered: Color32,
+    pub active: Color32,
+    pub open: Color32,
+}
+
+impl WidgetPalette {
+    /// Set each state's strong and weak background fill, with a common radius and foreground.
+    ///
+    /// Borders, expansion and every other widget property are retained. Apply per-state
+    /// exceptions afterward, e.g. transparent weak fill for outline-only inactive buttons.
+    /// This deliberately does not choose selection colors, surfaces, shadows or text styles.
+    pub fn apply_to(self, widgets: &mut Widgets, radius: CornerRadius, foreground: Stroke) {
+        for (widget, fill) in [
+            (&mut widgets.noninteractive, self.noninteractive),
+            (&mut widgets.inactive, self.inactive),
+            (&mut widgets.hovered, self.hovered),
+            (&mut widgets.active, self.active),
+            (&mut widgets.open, self.open),
+        ] {
+            widget.bg_fill = fill;
+            widget.weak_bg_fill = fill;
+            widget.corner_radius = radius;
+            widget.fg_stroke = foreground;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn switching_palette_retains_custom_borders_and_expansion() {
+        let mut widgets = egui::Visuals::light().widgets;
+        widgets.active.bg_stroke = Stroke::new(3.0, Color32::YELLOW);
+        widgets.hovered.expansion = 7.0;
+        let original_borders = [
+            widgets.noninteractive.bg_stroke,
+            widgets.inactive.bg_stroke,
+            widgets.hovered.bg_stroke,
+            widgets.active.bg_stroke,
+            widgets.open.bg_stroke,
+        ];
+        let palette = WidgetPalette {
+            noninteractive: Color32::BLACK,
+            inactive: Color32::RED,
+            hovered: Color32::GREEN,
+            active: Color32::BLUE,
+            open: Color32::TRANSPARENT,
+        };
+        let foreground = Stroke::new(2.0, Color32::WHITE);
+        palette.apply_to(&mut widgets, CornerRadius::same(4), foreground);
+        assert_eq!(widgets.noninteractive.bg_fill, Color32::BLACK);
+        assert_eq!(widgets.inactive.bg_fill, Color32::RED);
+        assert_eq!(widgets.hovered.bg_fill, Color32::GREEN);
+        assert_eq!(widgets.active.bg_fill, Color32::BLUE);
+        assert_eq!(widgets.open.bg_fill, Color32::TRANSPARENT);
+        for widget in [&widgets.noninteractive, &widgets.inactive, &widgets.hovered, &widgets.active, &widgets.open] {
+            assert_eq!(widget.weak_bg_fill, widget.bg_fill);
+            assert_eq!(widget.corner_radius, CornerRadius::same(4));
+            assert_eq!(widget.fg_stroke, foreground);
+        }
+        assert_eq!(widgets.hovered.expansion, 7.0);
+        assert_eq!(
+            [
+                widgets.noninteractive.bg_stroke,
+                widgets.inactive.bg_stroke,
+                widgets.hovered.bg_stroke,
+                widgets.active.bg_stroke,
+                widgets.open.bg_stroke
+            ],
+            original_borders
+        );
+        // A second theme application replaces prior fills, including an app's outline override.
+        widgets.inactive.weak_bg_fill = Color32::TRANSPARENT;
+        WidgetPalette { inactive: Color32::GRAY, ..palette }.apply_to(&mut widgets, CornerRadius::ZERO, foreground);
+        assert_eq!(widgets.inactive.bg_fill, Color32::GRAY);
+        assert_eq!(widgets.inactive.weak_bg_fill, Color32::GRAY);
+        assert_eq!(widgets.active.bg_stroke, Stroke::new(3.0, Color32::YELLOW));
+    }
+}
diff --git a/docs/theme-infrastructure.md b/docs/theme-infrastructure.md
new file mode 100644
index 0000000..d2c31cd
--- /dev/null
+++ b/docs/theme-infrastructure.md
@@ -0,0 +1,162 @@
+# Shared theme infrastructure
+
+The first shared mechanism is `craft-ui::theme::WidgetPalette`: it applies colors to egui's five
+widget states, with a supplied foreground stroke and corner radius. VectorCraft and DesignCraft
+use the same operation today. Their complete palettes, theme choices, fonts and preferences
+remain in their frontends. This boundary also has a compatible future consumer in LightCraft.
+
+This follows the reusable-UI workstream of [craft-libs issue 2](https://github.com/storytold/craft-libs/issues/2).
+The [cross-app architecture discussion](https://github.com/storytold/vectorcraft/issues/647) and
+[base-crate request](https://github.com/storytold/photocraft/issues/1217) provide context; this change
+keeps the existing repository, document and release boundaries.
+
+## Source comparison
+
+Reviewed 2026-10-09 at the revisions below. All links point to
+`crates/ui-egui/src/theme.rs`. The 3,454-line total includes font setup, specialized helpers and
+tests; it is not a count of duplicate theme code. Token-field counts include non-color fields.
+
+| App | Source revision | Lines | Token fields | Theme model |
+| --- | --- | ---: | ---: | --- |
+| PhotoCraft | [`e7a83ca342cd`](https://github.com/storytold/photocraft/blob/e7a83ca342cdff568254f85f442b9cc8afb08066/crates/ui-egui/src/theme.rs) | 832 | 37 | Five presets; per-preset metrics and Classic bevels |
+| VectorCraft | [`825d4fdb8b52`](https://github.com/storytold/vectorcraft/blob/825d4fdb8b527c597855d273fb4bcc1971855b6a/crates/ui-egui/src/theme.rs) | 345 | 38 | Four brightness presets |
+| DesignCraft | [`66c7ce7e96ec`](https://github.com/storytold/designcraft/blob/66c7ce7e96ec286a091878cc2541ee8369aa79d6/crates/ui-egui/src/theme.rs) | 426 | 33 | Four brightness presets plus High Contrast |
+| WordCraft | [`d7d9702bda1f`](https://github.com/storytold/wordcraft/blob/d7d9702bda1fe626952024dc37fd2624323dad0f/crates/ui-egui/src/theme.rs) | 231 | 32 | Light/dark, ribbon and page colors |
+| PdfCraft | [`f626db25cca2`](https://github.com/storytold/pdfcraft/blob/f626db25cca2c89f8fa3f7e30d22bf59faea65ec/crates/ui-egui/src/theme.rs) | 314 | 22 | System/light/dark preference |
+| LightCraft | [`88ea1a804b35`](https://github.com/storytold/lightcraft/blob/88ea1a804b35709e1fe436e3792adf0428b97daa/crates/ui-egui/src/theme.rs) | 345 | 35 | Dark photo workflow palette |
+| FilmCraft | [`7b6c13447228`](https://github.com/storytold/filmcraft/blob/7b6c134472287db4367fca80bcb498240ba36567/crates/ui-egui/src/theme.rs) | 447 | 43 | Three presets, custom accent and accessible contrast |
+| EffectCraft | [`2a460986ee7a`](https://github.com/storytold/effectcraft/blob/2a460986ee7a4b32656a3d434849693904b486bc/crates/ui-egui/src/theme.rs) | 514 | 44 | Three presets, brightness and label colors |
+
+The matching widget-state operation is visible in [VectorCraft lines 299–312][vector-loop],
+[DesignCraft lines 336–348][design-loop] and [LightCraft lines 235–247][light-loop]. It assigns
+`bg_fill`, `weak_bg_fill`, `corner_radius` and `fg_stroke` across noninteractive, inactive, hovered,
+active and open states. The state colors differ, but the assignments and their meaning agree.
+
+The surrounding `Visuals` operations differ materially:
+
+| App | Differences that remain local |
+| --- | --- |
+| VectorCraft | Selection uses accent at 0.55 gamma with an accent stroke. Popup/window radius is 6; shadows vary with light/dark. Inactive border is absent, hover uses input border and active uses accent. Body/button text is 13 pt. |
+| DesignCraft | Selection uses strong accent and strong-text stroke. Radius is 4; window shadow stays egui's default. Interactive borders use field border. Inactive buttons get transparent weak fill and input background after the shared operation. Body/button text is 11 pt. High Contrast keeps black/white/yellow colors. |
+| LightCraft | The matching loop uses `text_label`, intentionally dimmer than the app's main text, and a fixed dark palette. Catalog label helpers depend on its own model. |
+| FilmCraft | Custom highlight and contrast preferences feed its palette. Widget states use ordinary text for inactive/noninteractive and brighter text for hovered/active; open foreground remains inherited. |
+| EffectCraft | Its widget assignment block matches FilmCraft's, but brightness adjustment, label/gradient helpers, popup radius, shadows, spacing and solid scrollbars differ. |
+| PhotoCraft | Noninteractive text is dimmer; interactive states have separate border and expansion policies. Classic styling includes bevels, and font size is preference-driven. |
+| PdfCraft | System theme resolution and named context storage are local. Its foreground loop preserves each inherited stroke width; a blanket full-stroke assignment would change that contract. Light text and font subpixel settings differ. |
+| WordCraft | Tokens derive from egui's current dark mode. Only three interactive states get explicit radii; other states inherit egui defaults. Ribbon/document colors have separate meaning. |
+
+FilmCraft and EffectCraft's separate matching block is a useful second extraction candidate, but
+it has a different foreground-state contract. Extending the first helper to cover it immediately
+would obscure the small invariant being shared. There is no single cleanest complete theme:
+the first pair offers the clearest common operation, and the other apps preserve different
+requirements rather than providing interchangeable replacements.
+
+## Boundary and API
+
+```rust
+pub struct WidgetPalette {
+    pub noninteractive: egui::Color32,
+    pub inactive: egui::Color32,
+    pub hovered: egui::Color32,
+    pub active: egui::Color32,
+    pub open: egui::Color32,
+}
+
+impl WidgetPalette {
+    pub fn apply_to(
+        self,
+        widgets: &mut egui::style::Widgets,
+        radius: egui::CornerRadius,
+        foreground: egui::Stroke,
+    );
+}
+```
+
+The implementation lives in [`crates/ui/src/theme`](../crates/ui/src/theme/mod.rs). It changes only
+those four properties. Borders, expansion, selection, shadows and the rest of egui's visuals
+stay untouched. Apps apply their state-specific exceptions afterward. `noninteractive` names
+egui's state, not a new disabled-control policy.
+
+A separate `craft-theme` crate adds no useful boundary: this mechanism already depends on egui
+and belongs beside the controls it styles. A universal token structure, theme enum, application
+identifier or global context key is unnecessary. Constructing another large visual-options
+object would mostly rename `egui::Visuals` fields without simplifying their use. Context lookup
+and storage are already small and retain different fallback themes.
+
+The identical packed-RGB helper in VectorCraft and DesignCraft is only a few casts; it remains
+local in this extraction. A contrast API also needs a second runtime consumer before extraction.
+
+## Fonts and styling outside theme modules
+
+Font setup occupies hundreds of the audited lines. It depends on app-specific font catalogs,
+locale handling and fallback order: PhotoCraft uses its text and preference crates; VectorCraft
+uses `vectorcraft_text`; DesignCraft and WordCraft use their font crates; PdfCraft adds script
+and system fallback; LightCraft uses its engine catalog; FilmCraft and EffectCraft use their text
+crates and local font discovery. DesignCraft also configures named Arabic shaping families.
+These dependencies and font assets stay outside `craft-ui`.
+
+Theme references occur throughout panels, menus and tools, with local visual/spacing overrides
+in every app. A source search alone cannot turn this into a percentage of correctly themed UI:
+many literal colors are document content, swatches, previews or intentional contrast choices.
+A search of UI source files outside `theme.rs` found the following. The columns count files,
+including tests, containing token/theme references, local visual/spacing mutation, or literal
+`Color32` construction. They are navigation aids, not counts of defective controls.
+
+| App | Theme references | Local overrides | Literal colors |
+| --- | ---: | ---: | ---: |
+| PhotoCraft | 115 | 37 | 59 |
+| VectorCraft | 149 | 40 | 41 |
+| DesignCraft | 26 | 8 | 19 |
+| WordCraft | 10 | 4 | 9 |
+| PdfCraft | 40 | 11 | 30 |
+| LightCraft | 40 | 20 | 27 |
+| FilmCraft | 53 | 4 | 46 |
+| EffectCraft | 61 | 1 | 55 |
+
+Examples worth preserving or reviewing separately:
+
+- PhotoCraft's `widgets.rs` draws fixed light/dark Classic bevels and removes field chrome;
+  `menus.rs` supplies its own menu styling.
+- VectorCraft's `widgets.rs` uses white primary-button labels and contrasting fill/stroke wells.
+- DesignCraft's `widgets.rs:147` sets focused numeric-field colors independently of High Contrast;
+  fixed dialog warning/error colors also merit a later accessibility review.
+- WordCraft's ribbon Share control uses white; PdfCraft's notification surfaces and dialog
+  widgets have local light/dark styling.
+- LightCraft's dialog download errors use a fixed hue, while its color helpers also draw actual
+  photo-workflow values.
+- FilmCraft's header customizes menu chrome; EffectCraft's effect widgets and ScriptUI controls
+  customize backgrounds and slider widths.
+
+This extraction preserves those choices. It does not certify whole-app accessibility or theme
+consistency, and it does not move font installation into the shared crate.
+
+## Migration and validation
+
+1. Capture VectorCraft's four themes and DesignCraft's five, including High Contrast, before
+   replacing either loop. Use synthetic documents, panels/inspectors, menus and preferences at
+   1× and 2× scales. Save the complete egui Style and app Tokens for comparison.
+2. Add the shared helper with a test that preserves custom borders and expansion while replacing
+   all state fills, including reapplying a theme after a local override.
+3. Replace only each app's five-state loop. Keep its existing colors, strokes, post-loop
+   exceptions, fonts, spacing, context state, commands and saved preference schema.
+4. Repeat the renders and compare complete styles/tokens and images. Exercise theme commands,
+   menu check states and an in-memory saved-preference round trip. A process restart or native
+   display acceptance remains a separate check.
+5. Run shared fmt, strict Clippy, tests and wasm, then each app's own gates. Each app pins the
+   shared revision independently and can revert its adapter/pin without migrating preferences.
+
+The main risks are accidentally resetting inherited egui fields, losing DesignCraft's inactive
+outline exception or High Contrast colors, and confusing font/locale behavior with theme
+application. Exact style comparison plus visual checks covers the first two; keeping font code
+unchanged limits the third. Shared code depends only on egui, and layer checks keep it above
+engines and document models.
+
+Next candidates are LightCraft's identical loop, FilmCraft/EffectCraft's widget-state matrix,
+app-owned theme adapters for shared tabs/buttons/resize handles, and consistent focused numeric
+fields. Each should have two real consumers and its own visual/interaction checks before adoption.
+
+[vector-loop]: https://github.com/storytold/vectorcraft/blob/825d4fdb8b527c597855d273fb4bcc1971855b6a/crates/ui-egui/src/theme.rs#L299-L312
+
+[design-loop]: https://github.com/storytold/designcraft/blob/66c7ce7e96ec286a091878cc2541ee8369aa79d6/crates/ui-egui/src/theme.rs#L336-L348
+
+[light-loop]: https://github.com/storytold/lightcraft/blob/88ea1a804b35709e1fe436e3792adf0428b97daa/crates/ui-egui/src/theme.rs#L235-L247
diff --git a/docs/ui-components-audit.md b/docs/ui-components-audit.md
index 1f68c09..4ed1a5e 100644
--- a/docs/ui-components-audit.md
+++ b/docs/ui-components-audit.md
@@ -45,6 +45,8 @@ These are proposed boundaries and adoption pairs, not a commitment to build a fr
 | 6 | Ruler tick layout and painting | Standardize a primitive API | VectorCraft and DesignCraft, then PhotoCraft/WordCraft/DeckCraft | Share bounded tick placement and painting with caller-supplied labels and coordinates. Keep units, guide commands and paragraph markers outside. |
 | 7 | Pane controls | Share geometry and interactions; keep layout models in apps | PhotoCraft, VectorCraft, DesignCraft, FilmCraft, EffectCraft | Tabs, bounded splits and resize handles are implemented. A shared dock tree or persisted-layout migration remains separate work. |
 
+The [theme comparison](theme-infrastructure.md) verifies all eight principal theme modules and extracts their first common mechanism: `theme::WidgetPalette`, used by VectorCraft and DesignCraft to style egui widget states while retaining their full palettes.
+
 Theme roles belong beside the components that consume them. `IconButtonStyle` contains fills, borders, icon and focus colors for the implemented button. That does not require all apps to replace their `Tokens` structs or serialize the same theme enum. Panels, inspectors and dialogs can then reuse those controls while retaining their application-specific contents.
 
 ## Icons and the first extraction