docs: describe the shell-driven light/dark theming

ARCHITECTURE.md

@@ -295,38 +295,24 @@ image.
 
 ## Theming
 
-St's CSS engine has no custom properties (`var()`) and no reliable
+Light and dark are handled by GNOME Shell's built-in per-variant stylesheet
-`!important`, so the light theme is not a runtime-generated stylesheet.
+loading, not by any code in the extension. When it enables an extension the
-Instead `stylesheet.css` is the dark theme (default, auto-loaded by GNOME),
+Shell loads `stylesheet-<variant>.css`, where the variant comes from
-and `light.css` carries light overrides with every rule scoped under a
+`Main.getStyleVariant()` (the shell's own light/dark), and falls back to
-`.strata-theme-light` ancestor class -- e.g. dark `.strata-panel { ... }` is
+`stylesheet.css`; it reloads that sheet when the color scheme changes.
-overridden by `.strata-panel.strata-theme-light { ... }`. That scoping makes
-each light rule strictly more specific than its dark counterpart, so it wins
-deterministically regardless of stylesheet load order.
 
-The switch between themes is a single class. `extension.js` loads `light.css`
+Strata ships two sheets and no `stylesheet.css`:
-into the St theme context once at `enable()` (and unloads it on `disable()`),
-but loading it changes nothing on screen: its rules are present in the engine
-yet match no actors, because nothing carries `.strata-theme-light` yet. The
-panel resolves the effective theme from the `theme` setting (`auto` consults
-`org.gnome.desktop.interface color-scheme`) and adds or removes that one class
-on its root box. With the class present the more-specific light rules win and
-the panel is light; with it absent only the base dark rules apply. So
-switching is one class toggle on an existing subtree -- instant, off the
-ingest/render hot paths, and needing no reload.
 
-`light.css` is loaded exactly once and the theme context's `changed` signal is
+- `stylesheet-dark.css` is the full dark theme (the base).
-deliberately not used: `load_stylesheet` itself emits `changed`, so reloading
+- `stylesheet-light.css` does `@import url("stylesheet-dark.css")` and then
-on it feeds back into itself and hits "too much recursion" (it fired on screen
+  overrides the colors for a light panel. Its rules follow the import, so they
-unlock, which restyles widgets). The one caveat of loading once is a full
+  win by load order.
-GNOME Shell *theme* switch (the User Themes extension swapping the whole Shell
+
-theme), which replaces the theme object and drops every dynamically loaded
+This is the structure the built-in `window-list` extension uses. Because the
-sheet, including `light.css`. After that, light mode falls back to the dark
+variant tracks the *shell* style, the panel matches the shell chrome: a normal
-base rules until the extension is re-enabled; dark mode is unaffected because
+session prefers dark, so the panel is dark, and it turns light only when the
-GNOME re-loads `stylesheet.css` itself. This is rare and recoverable, and far
+shell itself is light (a `prefer-light` color scheme, the Classic session, or
-preferable to re-subscribing to `changed`. The ordinary light/dark switch
+high contrast). There is no theme setting and no manual stylesheet loading.
-(including the system Settings light/dark that `auto` follows) is just the
-class toggle and is unaffected.
 
 ## Wayland clipboard monitor
 

README.md

@@ -34,8 +34,8 @@ Unknown MIME types are ignored (a strict allowlist).
 
 **Appearance.**
 
-- Automatic light/dark theme: `Auto` follows the system color scheme; `Light`
+- Light and dark styling follows the GNOME Shell automatically, matching the
-  and `Dark` force one.
+  rest of the shell UI.
 - Configurable panel position (top/center/bottom by left/center/right), width,
   and maximum height.
 - Optional "move an item to the top" when you paste it.