Use Light/Dark system completely from JavaFX

[Maran23]

Related issues and pull requests

Closes: #15039
Closes: #15560

PR Description

Since JavaFX 25, we can use the new JavaFX Theme system.
JavaFX CSS now offers media queries (just like normal CSS) and on all OS, the header bar (frame) will change to light or dark automatically as well.

Concrete changes:

• Remove Dark.css
• Use CSS media queries in Base.css
• Remove com.pixelduke:fxthemes as we don't need the functionality anymore
• Special handling of some styles is inside the media queries. Note that we should eventually remove them all, so that we only contain the same Set of variables in the light and dark CSS sections and all styles just use those variables.
• Added a 'Use System Preference' inside the 'Change visual theme' dialog, which works the same as in the JabRef Visual Theme settings
  • As default, JabRef now follows the system theme (when launched the very first time)

I'm confused about the .search-dialog styles in Dark.css. This seems to be related to cayw.css, which is a single standalone CSS and not used inside the main application?

JabRef

Aufzeichnung.2026-04-13.230021.mp4

Aufzeichnung.2026-04-13.230551.mp4

CAYW

Will now automatically use the OS theme.

What we can do in the Future:

• Custom Stylesheets from Users can also be Light/Dark aware. So it might make sense to rather have:
  • A Theme (Default: JabRef, can be a custom one)
  • A color scheme (System, Light or Dark)
• So you can use the Stylesheet you want and change the color scheme for it. As of now, you can only switch between: System, Light, Dark, Custom. But don't have a combination of it.

• Remove the custom rules inside the media queries
• Completely remove any hardcoded colors, using variables everywhere (beside transparent color)
• Remove unused colors, unify same colors
• We could probably remove the windowsListener and the whole Window CSS logic, as normally or sub Windows will derive the main CSS style

Steps to test

Open JabRef, change the OS theme setting or change the theme manually in JabRef.

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• I manually tested my changes in running JabRef (always required)
• [/] I added JUnit tests for changes (if applicable)
• I added screenshots in the PR description (if change is visible to the user)
• [/] I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
• [/] I described the change in CHANGELOG.md in a way that can be understood by the average user (if change is visible to the user)
• [/] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Migrate to JavaFX 25 native light/dark theme system

✨ Enhancement

Walkthroughs

Description

• Migrate to JavaFX 25 native light/dark theme system
• Remove dependency on external FXThemes library
• Consolidate dark theme into Base.css using CSS media queries
• Add system preference synchronization option to UI

Diagram

flowchart LR
  A["FXThemes Library"] -->|Remove| B["JavaFX 25 Native System"]
  C["Dark.css File"] -->|Merge| D["Base.css with Media Queries"]
  E["Theme Type Enum"] -->|Refactor| F["SYSTEM/LIGHT/DARK/CUSTOM"]
  B -->|Apply| G["ColorScheme API"]
  D -->|Support| G
  H["Theme Dialog UI"] -->|Add| I["System Preference Checkbox"]

Loading

File Changes

1. jabgui/src/main/java/module-info.java Dependencies +0/-1

Remove FXThemes library dependency

jabgui/src/main/java/module-info.java

---

2. jabgui/src/main/java/org/jabref/gui/theme/Theme.java ✨ Enhancement +32/-20

Refactor theme types and add system theme support

jabgui/src/main/java/org/jabref/gui/theme/Theme.java

---

3. jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java ✨ Enhancement +31/-32

Replace FXThemes with JavaFX ColorScheme API

jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java

---

View more (11)

4. jabgui/src/main/java/org/jabref/gui/WorkspacePreferences.java ⚙️ Configuration changes +2/-2

Change default theme to system with sync enabled

jabgui/src/main/java/org/jabref/gui/WorkspacePreferences.java

---

5. jabgui/src/main/java/org/jabref/gui/preferences/JabRefGuiPreferences.java ⚙️ Configuration changes +1/-1

Update theme default constant to SYSTEM

jabgui/src/main/java/org/jabref/gui/preferences/JabRefGuiPreferences.java

---

6. jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java ✨ Enhancement +5/-7

Update theme type mapping and store sync setting

jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java

---

7. jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/ThemeDialog.java ✨ Enhancement +21/-3

Add system preference checkbox and update visibility logic

jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/ThemeDialog.java

---

8. jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/viewmodel/ThemeDialogViewModel.java ✨ Enhancement +17/-4

Add theme sync OS property and update initialization

jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/viewmodel/ThemeDialogViewModel.java

---

9. jabgui/src/main/resources/org/jabref/gui/Base.css ✨ Enhancement +469/-226

Consolidate light and dark themes using media queries

jabgui/src/main/resources/org/jabref/gui/Base.css

---

10. jabgui/src/main/resources/org/jabref/gui/Dark.css ✨ Enhancement +0/-251

Remove Dark.css file completely

jabgui/src/main/resources/org/jabref/gui/Dark.css

---

11. jabgui/src/main/resources/org/jabref/gui/welcome/quicksettings/ThemeDialog.fxml ✨ Enhancement +8/-5

Add system preference checkbox and disable theme options

jabgui/src/main/resources/org/jabref/gui/welcome/quicksettings/ThemeDialog.fxml

---

12. jabgui/src/test/java/org/jabref/gui/theme/ThemeTest.java 🧪 Tests +12/-13

Update tests for new theme type enum values

jabgui/src/test/java/org/jabref/gui/theme/ThemeTest.java

---

13. build-logic/src/main/kotlin/org.jabref.gradle.base.dependency-rules.gradle.kts ⚙️ Configuration changes +0/-2

Remove FXThemes module configuration

build-logic/src/main/kotlin/org.jabref.gradle.base.dependency-rules.gradle.kts

---

14. versions/build.gradle.kts Dependencies +0/-1

Remove FXThemes library version constraint

versions/build.gradle.kts

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (3)   📘 Rule violations (3)   📎 Requirement gaps (0)

🐞\ ≡ Correctness (3)

📘\ ☼ Reliability (1) ⚙ Maintainability (2)

1. Non-localized theme radio texts 📘 ⚙

Description

The modified ThemeDialog.fxml still hardcodes user-facing strings (Light Theme, Dark Theme,
Custom Theme) instead of using localized %... keys. This breaks localization requirements for
FXML UI text.

Code

jabgui/src/main/resources/org/jabref/gui/welcome/quicksettings/ThemeDialog.fxml[R31-34]

+                    <RadioButton fx:id="lightRadio" text="Light Theme" disable="${themeSyncOs.selected}">
                        <toggleGroup>
                            <ToggleGroup fx:id="themeGroup"/>
                        </toggleGroup>

Evidence

PR Compliance ID 20 requires all user-facing FXML text to be localized using % keys. The updated
radio button nodes still contain hardcoded text= values.

AGENTS.md
jabgui/src/main/resources/org/jabref/gui/welcome/quicksettings/ThemeDialog.fxml[31-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ThemeDialog.fxml` contains hardcoded user-facing strings for theme selection, which should be localized using `%...` keys.

## Issue Context
The PR already introduced a localized checkbox (`%Use System Preference`), but the theme radio buttons remain hardcoded even though they were modified in this PR.

## Fix Focus Areas
- jabgui/src/main/resources/org/jabref/gui/welcome/quicksettings/ThemeDialog.fxml[31-47]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Prefs save NPE 🐞 ≡

Description

GeneralTabViewModel leaves selectedThemeProperty unset for Theme.Type.SYSTEM, but storeSettings()
switches on selectedThemeProperty.get(), which can throw a NullPointerException when saving
preferences. This can happen with the new defaults (Theme.system + sync with OS), because
validateSettings() does not reject a null theme selection.

Code

jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[R248-254]

        workspacePreferences.setShouldOverrideDefaultFontSize(fontOverrideProperty.getValue());
        workspacePreferences.setMainFontSize(Integer.parseInt(fontSizeProperty.getValue()));

+        workspacePreferences.setThemeSyncOs(themeSyncOsProperty.getValue());
        switch (selectedThemeProperty.get()) {
            case LIGHT ->
                    workspacePreferences.setTheme(Theme.light());

Evidence

WorkspacePreferences now defaults to Theme.system() (Type.SYSTEM), but
GeneralTabViewModel.setValues() does not handle SYSTEM, so selectedThemeProperty remains null.
PreferencesDialogViewModel.storeAllSettings() calls each tab’s storeSettings() as long as
validateSettings() returns true; GeneralTabViewModel.validateSettings() does not validate
selectedThemeProperty != null unless CUSTOM is selected, so the null flows into the switch in
storeSettings().

jabgui/src/main/java/org/jabref/gui/WorkspacePreferences.java[52-66]
jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[193-207]
jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[239-260]
jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[338-369]
jabgui/src/main/java/org/jabref/gui/preferences/PreferencesDialogViewModel.java[166-189]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`GeneralTabViewModel` does not map `Theme.Type.SYSTEM` into a non-null `selectedThemeProperty`, but later `storeSettings()` switches on `selectedThemeProperty.get()` which can be null and crash.

### Issue Context
- `WorkspacePreferences` defaults to `Theme.system()`.
- `ThemeTypes` has no `SYSTEM` entry, so the view model must map SYSTEM to a safe fallback (e.g., LIGHT) and/or avoid switching on null.

### Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[193-207]
- jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[239-260]
- jabgui/src/main/java/org/jabref/gui/preferences/general/GeneralTabViewModel.java[338-369]

### Suggested fix
- In `setValues()`, add a `case SYSTEM -> selectedThemeProperty.setValue(ThemeTypes.LIGHT);` (or another defined default), and consider aligning with `themeSyncOsProperty`.
- In `storeSettings()`, defensively handle `selectedThemeProperty.get() == null` (e.g., treat as LIGHT) to prevent NPE.
- Optionally, add validation to fail `validateSettings()` if the selection is null (when needed).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Legacy theme not applied 🐞 ≡

Description

ThemeManager.applyModeToWindow decides light/dark by comparing theme.getName() to "light"/"dark",
but Theme accepts legacy stored names ("Base.css", "Dark.css") without normalizing Theme.name. Users
upgrading with stored legacy names will not get the intended forced light/dark ColorScheme and will
fall back to system.

Code

jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java[R196-202]

+        if (Objects.equals(theme.getName(), Theme.light().getName())) {
+            scene.getPreferences().setColorScheme(ColorScheme.LIGHT);
+        } else if (Objects.equals(theme.getName(), Theme.dark().getName())) {
+            scene.getPreferences().setColorScheme(ColorScheme.DARK);
+        } else {
+            scene.getPreferences().setColorScheme(null);
        }

Evidence

Theme.java explicitly treats "Base.css" as LIGHT and "Dark.css" as DARK (legacy), but it preserves
the raw name string. JabRefGuiPreferences persists the theme preference using Theme.getName(),
so existing installs can have "Dark.css" stored; ThemeManager then compares that string to
Theme.dark().getName() ("dark"), fails, and sets ColorScheme to null (system).

jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java[182-203]
jabgui/src/main/java/org/jabref/gui/theme/Theme.java[18-52]
jabgui/src/main/java/org/jabref/gui/preferences/JabRefGuiPreferences.java[564-567]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Legacy stored theme names (e.g., "Dark.css") are recognized for `Theme.type` but not for `Theme.name`, and `ThemeManager` uses `name` equality to set `Scene` color scheme. This breaks forced dark/light for upgraded users.

### Issue Context
- `Theme` already classifies legacy names into `Type.LIGHT`/`Type.DARK`.
- `ThemeManager.applyModeToWindow` should rely on `Theme.getType()` (or normalize `Theme.name`) rather than comparing `name` against "light"/"dark".

### Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java[182-203]
- jabgui/src/main/java/org/jabref/gui/theme/Theme.java[18-52]

### Suggested fix
- In `ThemeManager.applyModeToWindow`, replace `theme.getName()` comparisons with `switch (theme.getType()) { case LIGHT -> ...; case DARK -> ...; case SYSTEM -> setColorScheme(null); }`.
- Alternatively (or additionally), normalize legacy inputs in `Theme` by setting `this.name` to the canonical "light"/"dark" when `BASE_CSS`/`DARK_CSS` are provided, so persistence converges to the new values.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. setThemeSyncOs(boolean) public flag 📘 ⚙

Description

A new public method setThemeSyncOs(boolean selected) introduces a boolean flag parameter, which
reduces API clarity. Public APIs should use intention-revealing methods instead of boolean
parameters.

Code

jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/viewmodel/ThemeDialogViewModel.java[R106-112]

+    public void setThemeSyncOs(boolean selected) {
+        this.shouldThemeSyncOs = selected;
+    }
+
+    public boolean shouldThemeSyncOs() {
+        return shouldThemeSyncOs;
+    }

Evidence

PR Compliance ID 11 forbids boolean parameters in public methods because they obscure behavior. The
PR adds setThemeSyncOs(boolean selected) as a public API.

AGENTS.md
jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/viewmodel/ThemeDialogViewModel.java[106-112]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new public method uses a boolean flag parameter (`setThemeSyncOs(boolean)`), which makes the API less intention-revealing.

## Issue Context
This is a view model API and can be refactored to `enableThemeSyncOs()` / `disableThemeSyncOs()` (or a small enum) while keeping internal state the same.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/viewmodel/ThemeDialogViewModel.java[106-112]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. getBaseStyleSheet() unchecked throw 📘 ☼

Description

Theme.getBaseStyleSheet() uses orElseThrow() and can crash with an unchecked exception if
Base.css is not found/loaded. This is brittle for runtime theme/CSS initialization paths.

Code

jabgui/src/main/java/org/jabref/gui/theme/Theme.java[R120-122]

+    public static StyleSheet getBaseStyleSheet() {
+        return StyleSheet.create(BASE_CSS).orElseThrow();
+    }

Evidence

PR Compliance ID 14 requires avoiding unchecked throws for error handling and keeping exception
behavior robust. The added method calls StyleSheet.create(BASE_CSS).orElseThrow(), which will
throw an unchecked exception if stylesheet resolution fails.

AGENTS.md
jabgui/src/main/java/org/jabref/gui/theme/Theme.java[120-122]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`Theme.getBaseStyleSheet()` can throw an unchecked exception when `Base.css` cannot be resolved, which can crash theme initialization.

## Issue Context
Even if `Base.css` should always exist, packaging/classpath issues can occur; a safer failure mode is to log and fall back to an empty/no-op stylesheet or a known-safe default.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/theme/Theme.java[120-122]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Custom keeps old scheme 🐞 ≡

Description

ThemeManager skips applyModeToAllWindows/applyModeToWindow for CUSTOM themes, so a previously forced
Scene ColorScheme (LIGHT/DARK) is never cleared when switching to CUSTOM. This can cause Base.css
media queries to keep applying the old scheme on already-open windows until restart.

Code

jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java[R182-215]

+    private void applyModeToWindow(Stage stage) {
+        if (theme.getType() == Theme.Type.CUSTOM) {
            return;
        }
-        try {
-            themeWindowManager.setDarkModeForWindowFrame(stage, isDarkMode);
-            LOGGER.debug("Applied {} mode to window: {}", isDarkMode ? "dark" : "light", stage);
-        } catch (NoClassDefFoundError | UnsatisfiedLinkError e) {
-            // We need to handle these exceptions because the native library may not be available on all platforms (e.g., x86).
-            // See https://github.com/dukke/FXThemes/issues/13 for details.
-            LOGGER.debug("Failed to set dark mode for window frame (likely due to native library compatibility issues on intel)", e);
+
+        if (stage == null) {
+            return;
+        }
+
+        Scene scene = stage.getScene();
+        if (scene == null) {
+            return;
+        }
+
+        if (Objects.equals(theme.getName(), Theme.light().getName())) {
+            scene.getPreferences().setColorScheme(ColorScheme.LIGHT);
+        } else if (Objects.equals(theme.getName(), Theme.dark().getName())) {
+            scene.getPreferences().setColorScheme(ColorScheme.DARK);
+        } else {
+            scene.getPreferences().setColorScheme(null);
        }
    }

-    private void applyDarkModeToAllWindows() {
+    private void applyModeToAllWindows() {
+        if (theme.getType() == Theme.Type.CUSTOM) {
+            return;
+        }
+
        Window.getWindows().stream()
              .filter(Window::isShowing)
              .filter(window -> window instanceof Stage)
              .map(window -> (Stage) window)
-              .forEach(this::applyDarkModeToWindow);
+              .forEach(this::applyModeToWindow);
    }

Evidence

The only place that mutates scene.getPreferences().setColorScheme(...) is applyModeToWindow, but
both applyModeToWindow and applyModeToAllWindows return early for CUSTOM. Therefore, if a Scene
previously had ColorScheme.LIGHT/DARK forced, switching to a custom theme will not reset it to
system (null).

jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java[182-215]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Switching to `Theme.Type.CUSTOM` does not clear a previously forced `Scene` color scheme, because `applyModeToWindow`/`applyModeToAllWindows` early-return for custom themes.

### Issue Context
Base.css now uses `@media (prefers-color-scheme: ...)`, so the `Scene` color scheme directly affects which variable set is active.

### Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/theme/ThemeManager.java[182-215]

### Suggested fix
- Do not early-return for CUSTOM; instead set `scene.getPreferences().setColorScheme(null)` for CUSTOM (system-driven) unless you explicitly want custom themes to force a particular scheme.
- Ensure the transition path (e.g., from DARK -> CUSTOM) clears any previous LIGHT/DARK forcing on all open windows.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[subhramit]

I'm confused about the .search-dialog styles in Dark.css. This seems to be related to cayw.css, which is a single standalone CSS and not used inside the main application?

Relates to #15508

[calixtus]

I totally love your changes. Simplifies dependencies and theming system a lot. I think Qodo already mentioned most important issues.
Migration issue about selected theme can be ignored imho.

[Maran23]

Relates to #15508

I see. What I'm wondering is why we have a separate cayw.css with the .search-dialog styles (that are not included in Base.css) but the former Dark.css included cayw .search-dialog related CSS.
Can we integrate cayw.css into Base.css? So that we only have one CSS file?

[subhramit]

Relates to #15508

I see. What I'm wondering is why we have a separate cayw.css with the .search-dialog styles (that are not included in Base.css) but the former Dark.css included cayw .search-dialog related CSS.
Can we integrate cayw.css into Base.css? So that we only have one CSS file?

cc @palukku @calixtus

[palukku]

Relates to #15508

I see. What I'm wondering is why we have a separate cayw.css with the .search-dialog styles (that are not included in Base.css) but the former Dark.css included cayw .search-dialog related CSS.
Can we integrate cayw.css into Base.css? So that we only have one CSS file?

cc @palukku @calixtus

We need the extra css to be able to style the popup when running jabsrv standalone and not through the gui, that's also why it worked using standalone and not when running along with the gui but if there's a good solution to that I'm fine with removing or making it the "correct" way.

[Maran23]

We need the extra css to be able to style the popup when running jabsrv standalone and not through the gui, that's also why it worked using standalone and not when running along with the gui but if there's a good solution to that I'm fine with removing or making it the "correct" way.

Ok, so then I can just rewrite cayw.css to also handle the dark mode probably.
Thanks, makes sense, will change.

[Maran23]

Note: I'm forcepushing until everything is fixed - to keep the diff managable (for me - mostly, as I compare very often the previous CSS with the current one, so I don't miss anything).

[Maran23]

CAYW looks good now as well - but I just tested the standalone version for now. Not sure how I can call it from within the JabRef GUI. Otherwise, this should be good. I removed some unused variables as well and left a TODO I want to resolve after (in Base.css).

[koppor]

Ok, so then I can just rewrite cayw.css to also handle the dark mode probably.
Thanks, makes sense, will change.

Maybe, we should add this as comment into cayw.css (jabsrv/src/main/resources/cayw.css)

[Siedlerchr]

Regarding the future base for custom theme, there is a related issue #12352

[Maran23]

Regarding the future base for custom theme, there is a related issue #12352

Right now, there is unfortunately not really a way to really override modena as theme. There are ongoing improvements by other contributors, so this might be possible at a future version. With the recent CSS split, we are very well prepared for that!

EDIT:
see: https://bugs.openjdk.org/browse/JDK-8374824
see: https://bugs.openjdk.org/browse/JDK-8267546

[calixtus]

btw., i think we probably need a line on usage of split css files in the devdocs, maybe somewhere here https://devdocs.jabref.org/architecture-and-components.html#theming