Theme System

What is it?

The theme system decides every colour, material and shadow on screen, so that switching between dark and light mode, or choosing an accent colour, changes the whole desktop at once. This roadmap builds it: a theme_t structure of named colour tokens behind theme_get(), built-in Dark and Light presets, settings saved in the Registry, accent variants computed from one colour, a pass that removes hard-coded colours from the desktop code, theme-aware shadows, live reloading, and a token corpus generated from Microsoft's Fluent design data. None of its nine sections has started. The design tokens themselves already exist and are generated into C.

How does it work?

The tokens exist. docs/design/tokens.json is the single source for the shell's colours, frosted materials, sizes, corner radii, spacing, elevation (shadow) and motion timings. gen_theme_header.py generates theme_tokens.h from it, and the site check (python3 scripts/site/build.py --check, lint Check 30) fails a commit when the header drifts from the JSON. Each theme carries 74 colour tokens (THEME_DARK_* and THEME_LIGHT_*), including accent, text, fills, strokes, status colours, the terminal palette and taskbar attention colours. Materials carry blur, luminosity, noise, tint and tint opacity for the taskbar, Start, flyouts and menus, plus the Mica window tint. Motion includes THEME_MOTION_FAST_MS (83), NORMAL (167) and SLOW (250). The easing curves in the JSON are not emitted yet, because the generator skips list values.

Nothing uses them yet. No C file includes theme_tokens.h. The desktop draws with fixed colours instead: WM_COLOR_* in wm.h, CTRL_COLOR_* in the control library, and literal values in the desktop, terminal and gallery code. Window shadows use their own radius and alpha rather than the elevation tokens, and the Mica title bar tint is computed inside wm.c instead of calling gfx_mica().

Settings. registry_populate_defaults() in registry.c seeds a theme key: HKLM\SYSTEM\Theme holds DarkMode (1), AccentColor (the string #0078D4), Font, FontSize, CornerRadius, Wallpaper, WallpaperMode and EnableAnimations. Only the wallpaper values are read by anything today. A kernel Registry change notification, reg_notify_register(), exists and is what a live theme reload would listen on.

flowchart LR
    J[docs/design/tokens.json] --> G[gen_theme_header.py] --> H[theme_tokens.h]
    H -. planned .-> T[theme_t presets + theme_get]
    R[Registry theme key] -. planned .-> T
    T -. planned .-> D[desktop, WM, controls]
    L[fixed colours in wm.h, controls.h, desktop.c] --> D

What are its interfaces?

How do I use it?

To change a design value, edit tokens.json, run python3 scripts/site/gen_theme_header.py, and commit both files; the process is described in How do I change the design?. The change reaches the screen only once the migration section moves the desktop onto the tokens.

What is not implemented yet?

• Engine: theme_t Struct, theme_get() Singleton and Built-in Presets.
• Settings: Registry Load and Custom Accent Color.
• Adoption: Migration Pass and Theme-Aware Shadow Rendering.
• Live change: Hot-Reload. The window manager has no message system yet, so the broadcast this section describes needs one first.
• Windows compatibility: Fluent Token Corpus and Win11 Personalization Contract, which adds Microsoft's personalisation Registry keys.

How does it compare with Windows 11 and Linux?

Windows 11 stores light or dark mode and the accent colour under HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize, exposes WinUI resource brushes and redraws every window live when you change them. GNOME keeps the colour scheme in GSettings and GTK and libadwaita apps reload named colours live. Impossible OS already has a generated, drift-checked token set shared by the website and the kernel headers, which neither of the others has, but nothing on screen reads it yet.

See also

• Theme System roadmap
• Design system and the theme system
• Shell design: materials
• Animation Engine
• Core Widgets