.dotfiles/darwin-breeze/README.md

# Darwin Breeze

Breeze for KDE Plasma 6 in the macOS dark system colors, with Helium, T3 Code,
Ghostty, 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 darwin-breeze helium
./darwin-breeze/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
`darwin-breeze/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:

```
.local/share/color-schemes/DarwinBreezeDark.colors
```

Edit it, then run `./darwin-breeze/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 `tray-icons/` | `ColorScheme-Text`, recolored by Plasma |
| 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` |
| Ghostty | `.config/ghostty/themes/`, generated by `build.py` |
| 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 uses the same 16 colors as Ghostty.
- 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 `helium/.config/helium-browser-flags.conf`.
- 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.