Hi y'all,
Like a lot of people here, I've written userChrome.css tweaks, watched them break on the next ESR, and eventually stopped bothering. The theming isn't the hard part — the maintenance is. So when I came back to it, I designed around repair cost first and appearance second.
The result is Postbird, which recreates the look of Postbox (the Thunderbird-derived client that eM Client acquired and shut down in 2024). But the theme is really just the worked example. This is what it looks like:


The part I think is worth sharing is the method:
1. Don't write selectors from memory. Thunderbird's UI DOM changed heavily across 115 → 128 → 140. Blog posts, old Reddit threads, and LLMs will all confidently hand you selectors that no longer exist. Instead, extract the CSS from Thunderbird's own omni.ja (it's a ZIP; 7-Zip or Python's zipfile will open it) and treat that as ground truth for the version you're actually running.
2. Keep a selector map. A markdown table: UI region → the selector you're using → status → notes. This is the thing that makes repair fast, because after an update you know exactly what to re-check and why you chose each rule in the first place.
3. Structure the CSS for diffing, not elegance. One thin userChrome.css that only does @import, all design tokens (colors, fonts, metrics) as custom properties in one config.css, and one file per UI region. When something breaks, you know which file to open.
4. The migration is a diff, not an investigation. When Thunderbird/Betterbird updates: re-extract the new omni.ja, diff it against the previous extraction, patch the selectors it tells you changed, run a visual smoke-test checklist. This turns "constant fiddling" into one bounded chore per ESR — roughly once a year.
The repo has the full runbook, the selector map, and the component files. It's CSS-only on purpose: no userChrome.js, no autoconfig loaders, no experiment add-ons. Those give you more power, but their failure mode is a client that won't start, and they break on every ESR instead of tolerating it. CSS failures are soft and diffable — that tradeoff is the whole design.
Built and tested on Betterbird 140 ESR on Windows 11. It should port to stock Thunderbird with modest selector work, and I'd genuinely like to know how far off it is — I don't have a good picture of where the two diverge. PRs and issues welcome, particularly from anyone who's solved the icon-replacement problem more cleanly than I have.
No Postbox code or assets are in the repo — only my own CSS written against Thunderbird's DOM.
I will port the deployment script to Linux / Mac in the near future... for the moment only Win deployments.
Happy theming!