Tcl Improvement Proposals: TIP 767: Follow the desktop’s appearance on X11 through the XDG desktop portal

Author:         Serhiy Storchaka <[email protected]>
State:          Draft
Type:           Project
Created:        26-Oct-2026
Tcl-Version:    9.1
Tk-Branch:      x11-desktop-appearance
Keywords:       Tk, X11, dark mode, appearance, accent colour, portal
Vote:           Pending
Forum:          b9fecdc67c
Post-History:

Abstract

On X11, read the appearance the desktop asks for - its colour scheme, accent colour, contrast and reduced-motion preferences - from the org.freedesktop.appearance namespace of the XDG desktop portal; make the auto value of wm attributes window -appearance follow it; send the appearance events of TIP 750 when it changes; and report the settings through a new command. Builds on TIP 766, and is the companion of TIP 763.

Rationale

TIP 766 rests on the X resource database, which is how an X11 desktop has always told applications what colours to use. That channel is now largely historical: Plasma's krdb exported the colour scheme as X resources for KDE 3 and 4 and no longer does, and GNOME has never used X resources for this but XSETTINGS, which Tk does not read. So on a current GNOME or Plasma desktop a Tk application cannot discover the colour scheme at all, while the GTK and Qt applications beside it follow it.

What those applications read is the portal: GTK 4 and Qt 6 read it, GNOME and KDE serve it, standalone backends serve it under a bare window manager, and it is reachable from a sandbox. No build-time dependency is added, only D-Bus at run time, as in TIP 763.

XSETTINGS would reach GNOME without D-Bus, but carries a GTK theme name rather than a colour scheme, is not published by KDE, and says nothing of the accent colour.

Whether auto should follow the desktop by default is the question this TIP most needs answered. As specified, a dark desktop darkens existing applications; the other way round, nothing changes until each application is changed to ask. The first position is taken because TIP 750 already defines auto as the appearance being "determined by the system", and a desktop answering the portal is the system saying so.

Specification

tk appearance ?option?

Returns a dictionary of what the desktop asks for, or one value of it, and changes nothing:

colorScheme - light, dark, or empty where no preference is expressed.
accentColor - a colour in #rrggbb form, or empty where none is chosen.
contrast - normal or high.
reducedMotion - a boolean.

Where no portal answers, each value is empty or its neutral default. On Windows and macOS the command reports what those systems report and omits the rest.

wm attributes window -appearance auto

On X11 auto consults the portal as well as the option database, and the portal supplies only the colours the user has not chosen in X resources. An accent colour, where the portal reports one, becomes the selection colour.

light and dark continue to ignore the desktop.

On X11 the appearance events of TIP 750 are sent when the desktop changes its colour scheme, with light or dark as the data string. They are sent whatever the attribute's value, so that an application which colours itself can follow the desktop; the palette is re-derived only where the attribute is auto.

Reference Implementation

Branch x11-desktop-appearance, on top of x11-appearance. The settings are read with org.freedesktop.portal.Settings, whose SettingChanged signal drives the events. The D-Bus client is reached at run time, so a Tk built without it, or run where no portal answers, behaves as TIP 766 leaves it.

Compatibility

auto is the default, so on a desktop reporting a dark scheme an existing application which sets no colours of its own comes up dark. That is the purpose of the TIP, and what every GTK and Qt application on that desktop already does, but it is a change to applications that did not ask for one. A user's X resources outrank the desktop's scheme, and an application can set light.

Tk's own demos needed fixing for a dark palette ([042da6013e]), as does code outside the core which hardcodes light-palette colours.

Copyright

This document has been placed in the public domain.