refactor: group stow packages into common, mac and kde

Split the packages by platform so each app stays an opt-in Stow package under common/, mac/ or kde/. KDE gets its own Fastfetch, Helium and Spectacle packages, and darwin-breeze becomes kde/theme. The READMEs document stowing a whole group as well as individual packages.
2026-10-30 21:57:15 +07:00
1 parent 1e99a15f6c
commit 34e978e84c
@@ -0,0 +1,123 @@
+# Darwin Breeze
+
+Breeze for KDE Plasma 6 in the macOS dark system colors, with Helium, T3 Code,
+VS Code and Telegram themed from the same colors.
+
+Only the colors change. Breeze still draws the widgets and the title bar, and
+the window buttons stay on the right.
+
+- Selection and focus rings use the macOS blue, `#007AFF`.
+- The title bar has the same color as the toolbar below it, so the two read as
+  one strip.
+- When a window loses focus, its selection turns gray, as on macOS.
+- Errors, warnings, success text and links use Apple's system red, orange,
+  green, blue and purple.
+
+## Install
+
+From `~/.dotfiles`:
+
+```sh
+stow -d kde -t "$HOME" theme
+./kde/theme/apply.sh
+```
+
+`apply.sh` regenerates the app themes, applies the global theme, hides the
+line under the title bar, turns off the wallpaper accent color and publishes
+the T3 Code theme and installs the VS Code extension. Restart Helium
+afterwards; T3 Code switches on its own. In VS Code, pick "Darwin Breeze Dark"
+once under Preferences → Color Theme; after later color changes, run Developer:
+Reload Window.
+
+Telegram has to import its theme by hand: Settings → Chat Settings → Chat
+background → Choose from file, then pick
+`kde/theme/telegram/DarwinBreezeDark.tdesktop-theme` and Apply. Import it
+again after the colors change.
+
+## Changing colors
+
+The color scheme is the only place colors are defined:
+
+```
+kde/theme/.local/share/color-schemes/DarwinBreezeDark.colors
+```
+
+Edit it, then run `./kde/theme/apply.sh` again. Everything else follows:
+
+| App                               | How it gets the colors                                                                                                            |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Qt / KDE apps                     | the color scheme itself                                                                                                           |
+| GTK apps                          | Breeze GTK, which `kde-gtk-config` syncs from the scheme                                                                          |
+| Tray icons in `kde/tray-icons/`   | `ColorScheme-Text`, recolored by Plasma                                                                                           |
+| Helium                            | `../helium/.local/share/helium-themes/`, generated by `build.py`                                                                  |
+| T3 Code                           | `t3/darwin-breeze.json`, generated by `build.py` and published with `t3 theme set`                                                |
+| VS Code                           | `vscode/package.json` and `vscode/themes/`, generated by `build.py`, packed into `darwin-breeze.vsix` and installed by `apply.sh` |
+| Telegram                          | `telegram/DarwinBreezeDark.tdesktop-theme`, built by `build.py` and imported by hand                                              |
+
+The generated text files are committed so that `stow` alone gives a working
+setup; the binary packages (Telegram's `.tdesktop-theme`, VS Code's `.vsix`)
+are built by `build.py` instead. Don't edit generated files by hand.
+
+## T3 Code notes
+
+- T3 Code ignores symlinked theme files, so the theme isn't stowed;
+  `apply.sh` publishes a copy into `~/.t3/userdata/themes/`.
+- Every slot of the T3 theme maps to a role in the color scheme (see `t3()` in
+  `build.py`), so a new slot or a different mapping is a change there, not a
+  hand-edited color.
+
+## VS Code notes
+
+- The workbench colors start from VS Code's own default dark theme, Dark 2026
+  (vendored in `vscode/base/` with the themes it includes). It already lays
+  out its grays as the scheme does: the editor darkest, the chrome around it
+  lighter, widgets lighter still. Each of those becomes the matching scheme
+  gray and the grays between them are interpolated. Other colors take the
+  hue of the matching Apple color and keep their lightness and saturation.
+  Keys with an exact role, such as buttons, badges, the active tab's top
+  border and the git colors, are set directly (`vscode()` in `build.py`).
+- Syntax colors are Pierre Dark's, the theme T3 Code highlights code with
+  (`vscode/base/pierre-dark.json`, taken from T3 Code). They are used as they
+  are, without gamma compensation, so code looks the same in both apps.
+- The terminal palette is generated from the color scheme.
+- VS Code is Electron, so its workbench colors get the same gamma
+  compensation as Helium and T3 Code.
+- The `.vsix` isn't committed; `build.py` packs it from `vscode/`.
+
+## Telegram notes
+
+- Telegram has some 600 color keys and the scheme has roles for only a few
+  dozen of them (`telegram()` in `build.py`). The rest start from Telegram's
+  own night theme, vendored as `telegram/night.tdesktop-palette`: its
+  blue-tinted grays become scheme grays of the same brightness and its blues
+  take the macOS blue's hue. Other colors, such as the reds, greens and name
+  colors, are kept as night has them.
+- The chat list, top bar and compose bar use the window color; the chat
+  behind the bubbles and the folder strip use the darker view color.
+- Telegram is a Qt app, so unlike Helium and T3 Code it needs no gamma
+  compensation.
+- The `.tdesktop-theme` is a zip, so it isn't committed; `build.py` builds it
+  from the night palette and the color scheme.
+
+## Helium notes
+
+- Helium loads the theme from `~/.local/share/helium-themes/darwinbreeze`
+  through `--load-extension` in `kde/helium/.config/helium-browser-flags.conf`.
+  Install it separately with `stow -d kde -t "$HOME" helium`.
+- In Helium's compact layout the active tab and the toolbar segments on either
+  side share one theme color, so the toolbar is the same color as the tab
+  strip and inactive tabs are drawn lighter, as Dolphin does.
+- Chromium tags its output as sRGB and KWin shows it with a gamma 2.2 curve,
+  which lifts dark grays (40 becomes 44). `build.py` writes pre-compensated
+  values for Helium and T3 Code (both Chromium), so the theme files say 35
+  where the screen shows 40.
+- Under Settings → Appearance the theme must be Classic, not GTK or QT.
+
+## When the colors don't show up
+
+- In System Settings → Colors, take the accent color from the color scheme. A
+  custom accent, or one taken from the wallpaper, replaces the blue.
+- Use the Plasma style called "Breeze". "Breeze Dark" and "Breeze Light" carry
+  their own colors, so panels and popups ignore the scheme.
+- GTK apps follow the scheme only with the Breeze GTK theme. Flatpak apps also
+  need `org.gtk.Gtk3theme.Breeze` installed.