Expose browser UI theme (read-only + change event)

[chrmod]

Summary
Standardize a minimal, cross-browser way for extensions to read the browser’s current UI theme (effective light/dark + accent/seed color, plus a few optional flags) and get notified when it changes—so extension UIs can match the browser without shipping full themes.

Motivation: this is inspired by Helmut Januschka’s Omarchy work on coherent browser theming: https://www.januschka.com/chromium-omarchy.html

---

API proposal

declare namespace browser.theme {
  // Enumerations (list of all values)
  type ColorScheme = "light" | "dark" | "system";
  type ThemeVariant = "neutral" | "tonal_spot" | "vibrant" | "expressive" | "none";
  type Source = "system" | "browser" | "extension";

  interface Theme {
    // Effective scheme in use
    colorScheme: ColorScheme;                    // "light" | "dark" | "system"

    // Accent / seed color used by the browser UI
    // Value: sRGB hex "#RRGGBB" (optionally "#RRGGBBAA"); null/undefined if not supported
    accentColor?: string | null;

    // Optional vendor-mapped variant of the theme palette
    variant?: ThemeVariant;                      // "neutral" | "tonal_spot" | "vibrant" | "expressive" | "none"

    // Whether the UI is rendered in grayscale
    grayscale?: boolean;                         // true | false

    // Present if per-window theming exists; omitted otherwise
    windowId?: number;
  }

  // Query once (optionally for a specific window)
  function query(options?: { windowId?: number }): Promise<Theme>;

  // Fire when any property above changes
  const onChanged: browser.Events.Event<(info: Theme) => void>;
}

Example

const apply = async () => {
  const theme = await browser.theme.query();
  document.documentElement.dataset.scheme = theme.colorScheme;
  document.documentElement.style.setProperty("--accent", env.accentColor ?? "#666666");
};
browser.theme.onChanged.addListener(apply);

Why this helps (brief)

• Consistent theming for popups/side panels/options without hacks.
• Works in service workers (no DOM/CSS media queries needed).

[carlosjeurissen]

Some previous discussion:
Issue 680: Extensions API to query the current browser theme
Issue 242: Inconsistency: extension popup's prefered color scheme
Issue 229: Extension Icons for Light/Dark/Custom Theme
Issue 585: action.getIconVariables()

Ideally querying the browser theme should not be needed by resorting to declarative approaches by using APIs like:

• The color-scheme meta tag
• The css AccentColor system color
• The new webExtension icon_variants API

These do not currently cover all cases though. First of all, many of these are not available in a ServiceWorker, and AccentColor is not supported in Chrome for example. While being unreliable on Safari (From my own testing, it renders as blue even tho my macOS accent color is set to green).

[oliverdunk]

We discussed this issue in the last public meeting (minutes).

Currently, Firefox implements an API that exposes themes, however this is only the case for explicit themes installed from the addons store. The browser theme is not exposed as it is hard to represent with the same JSON schema. Chrome does not have current plans to implement this API.

There was general agreement that some theming capabilities would be useful, in particular:

• Being able to respond to light / dark preferences, including in service workers where the matchMedia API is not available.
• Being able to have the extension's action icon respond to theme changes. This is done automatically in Safari and will be possible in the future everywhere with the icon_variants proposal.

We don't think the API proposed here is the right solution for this problem, and the other solutions would be better discussed in their own issues. Therefore, closing this.