Design

1. Apps that didn't have their own appearance preference (e.g. Contacts or Clocks) should normally be light and become dark if the system prefers that.
   • Apps that synchronized their appearance with the system night light mode (e.g. Calendar or Builder), should stop doing that, this will be done system-wide instead.
2. Apps that didn't have a preference but used dark appearance by default (e.g. Photos or Videos) should be dark unless the system prefers light appearance, such as for the high contrast mode. If it's not possible to support light appearance, they can be always dark.
3. Apps that had provided a preference, but only because there wasn't a system-wide one (e.g. Shortwave or dconf-editor) should drop their preference for GNOME 42. They can still show it when running on older systems.
4. Apps that had provided a prominent preference and want to keep it going forward (e.g. Apostrophe, Text Editor or Builder) should add a state where the application follows the system preference, for example like on this mockup. That state may be omitted when running on older systems.
5. Apps that use completely custom styles (e.g. Contrast) shouldn't try to follow the preference at all if it doesn't make sense for them.
6. Libraries that provide widgets should try to follow the app's appearance if possible and makes sense - for example, WebKitGTK should use dark color scheme for pages that support it when the application it's embedded into is dark — either automatically, or via API that the app would use. They should not follow the system preference directly, as there's no guarantee the application follows it.

Implementation

GTK4 + libadwaita

Applications follow the preference by default, so design 1 doesn't require any changes.

To implement design 2 can use the following snippet to request dark variant and still support light appearance:

adw_style_manager_set_color_scheme (adw_style_manager_get_default (),
                                    ADW_COLOR_SCHEME_PREFER_DARK);

or the following one otherwise:

adw_style_manager_set_color_scheme (adw_style_manager_get_default (),
                                    ADW_COLOR_SCHEME_FORCE_DARK);

A good place to do that would be the startup() handler of your GApplication.

Applications that provide color scheme preferences as per designs 3 and 4 should use ADW_COLOR_SCHEME_FORCE_LIGHT and ADW_COLOR_SCHEME_FORCE_DARK color schemes, as they will ignore the system preference. The "follow system" state can be implemented as ADW_COLOR_SCHEME_PREFER_LIGHT.

See AdwStyleManager:color-scheme for more details.

Important: Don't use GtkSettings:gtk-application-prefer-dark-theme or GtkSettings:gtk-theme-name for checking if the application is currently using dark appearance! Neither of them will change in this case.

Instead, if you need to vary other aspects of the UI (e.g. the GtkSourceView color scheme), use the AdwStyleManager:dark property, and to check for the high contrast mode, use AdwStyleManager:high-contrast.

To only show a switch when running on an system without a system-wide preference, the AdwStyleManager:system-supports-color-schemes property can be used; libadwaita demo has an example.

If the application bundles custom CSS which needs changes for dark appearance or vice versa, AdwApplication provides an easy way to do that via style.css and style-dark.css resoures.

GTK3 + libhandy

If possible, consider porting to GTK4 and libadwaita first. libadwaita has a significant amount of changes in its stylesheet, aimed to improve the contrast in dark variant. For example:

GTK3	GTK4 + libadwaita

Cases like this will need custom styles in the application.

Other than that, the steps mostly match libadwaita, with one exception: applications don't follow the preference by default, so design 1 requires apps to opt in using the following snippet:

hdy_style_manager_set_color_scheme (hdy_style_manager_get_default (),
                                    HDY_COLOR_SCHEME_PREFER_LIGHT);

Additionally, since AdwApplication is not available, loading a CSS snippet only for dark appearance is instead done as follows:

struct _MyApplication
{
  ...

  GtkStyleProvider *dark_provider;
};

...

static void
update_dark_style (MyApplication *self)
{
  HdyStyleManager *manager = hdy_style_manager_get_default ();
  GdkScreen *screen = gdk_screen_get_default ();

  if (hdy_style_manager_get_dark (manager))
    gtk_style_context_add_provider_for_screen (screen,
                                               self->dark_provider,
                                               GTK_STYLE_PROVIDER_PRIORITY_APPLICATION + 1);
  else
    gtk_style_context_remove_provider_for_screen (screen,
                                                  self->dark_provider);
}

...

static void
my_application_dispose (GObject *self)
{
  ...

  g_clear_object (&self->dark_provider);
}

...

static void
my_application_startup (MyApplication *self)
{
  ...

  self->dark_provider = GTK_STYLE_PROVIDER (gtk_css_provider_new ());

  gtk_css_provider_load_from_resource (GTK_CSS_PROVIDER (self->dark_provider),
                                       "/my/application/style-dark.css");

  update_dark_style (self);

  g_signal_connect_object (hdy_style_manager_get_default (),
                           "notify::dark",
                           G_CALLBACK (update_dark_style),
                           self,
                           G_CONNECT_SWAPPED);
}

Other

If it's not possible to use libadwaita or libhandy, use DBus to manually access the settings portal and fetch the preference.

Do not use the gsettings key backing the settings portal implementation other than as a fallback if the portal isn't present: that key only exists on GNOME and is an implementation detail.

Don't add any animation for the transition; the whole screen will be animated on the compositor side instead.

A self-contained SDL+GDBus example that supports the dark style preference: hello.c

Building: gcc $(pkg-config --libs --cflags sdl2 gio-2.0) hello.c -o hello"

Screenshots:

Testing

GNOME 42

If you have a GNOME 42 system, for example a jhbuild session or a GNOME OS VM, use dconf-editor or gsettings CLI to edit the following preference: org.gnome.desktop.interface.color-scheme.

libadwaita

Libadwaita provides a GtkInspector page. If libadwaita is present in the SDK, it should work out of the box, and for apps that bundle libadwaita, it can be enabled via "--env=GTK_PATH=/app/lib/gtk-4.0" in finish-args in their manifest.

If it's set up correctly, open inspector with Ctrl+Shift+D and there should be a libadwaita page providing toggles for the system color scheme, high contrast and emulating an older system without color schemes.

Other

The following project can be used to test the preference: https://gitlab.gnome.org/exalm/color-scheme-simulator

If you're on Fedora, a copr repository is available.

It provides a settings portal implementation (providing color-scheme and nothing else) that can run on older GNOME versions together with xdg-desktop-portal-gnome/gtk, and a simple GUI for changing the preference.