Firefox-UI-Fix (Lepton): a userChrome layer that keeps Proton but tightens it

What Firefox-UI-Fix changes, and who it is for

Proton is Firefox's design starting from Firefox 89. Photon is the older design used until version 88. The README is explicit that the author likes Proton's overall feel but lists specific complaints: tabs that look like buttons, missing menu icons, ActivityStream icons that are too small, and padding gaps. Firefox-UI-Fix exists to fix those items rather than revert the whole interface. Lepton is the name of the light theme layer built on top.

The feature list is long and concrete. Under padding it names tabs, panels, menus and density. Under tab design it covers box shadow on the selected tab, bottom rounding, a divide line on unselected tabs, dimming for unloaded tabs, clearer text for clipped tabs, a close button that appears on hover, and container tab highlight lines. Color work includes contrast enhancement for the default light and dark themes, colorful context menus, and Windows, Mac and Linux system theme support. There are also tab bar layouts: tabs on bottom, one liner, and vertical tab support.

This is aimed at people who already customize Firefox through CSS and are willing to read a wiki. It is not a one-click theme from addons.mozilla.org. The disclaimer in the README is that it works on Firefox 89 and above, and there is a separate note that on Firefox v102 or lower you have to set userChrome.compatibility.accent_color to true as well.

Why user.js is the switchboard, not the stylesheet

The README leads with a warning: if the theme does not work after installation, you should copy the user.js file before the theme works. The option system depends on user configuration, and nothing applies without settings. That is the single most important architectural fact about this project. The CSS files are generated output; the behavior you see is decided by preferences that user.js sets.

The repository layout supports that reading. The top level holds src/, css/, user.js, userChrome.css and userContent.css. The package.json build script runs sass over four entry points in src/: leptonChromeNightly.scss to css/leptonChrome.css, leptonContentNightly.scss to css/leptonContent.css, and the same pair for ESR. So the SCSS in src/ is the source, and the css/ directory is the compiled artifact that ships.

A second constraint follows from how Firefox loads these files. The README states that real-time changes are difficult because of technical limitations and require a restart. It also warns that some settings can conflict and should be explicitly set to false. If you are used to editing a stylesheet and hitting reload, this workflow will feel slower. The trade-off is that a preference-driven theme can expose named options instead of asking users to patch CSS by hand.

Installing Firefox-UI-Fix and getting a first result

The README offers an installation script and calls it experimental. On Linux and Mac the command is a single line that pipes a remote script into bash:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/black7375/Firefox-UI-Fix/master/install.sh)"

Windows users run a PowerShell one-liner instead. The README notes that it does not work on Windows 7 and links to a compatibility page:

Powershell -c "Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iwr https://raw.githubusercontent.com/black7375/Firefox-UI-Fix/master/install.ps1 -useb | iex"

Manual installation is documented with screenshots on the wiki. Download the ZIP from the green Code button, open about:support in a new tab, and find the Profile Directory entry on Linux or Profile Folder on Windows. Open that directory. Extract the ZIP, copy user.js into the profile directory, create a directory named chrome inside it, and copy the remaining extracted files into chrome. Then restart Firefox by clicking Clear startup cache at the top of about:support.

The file that decides what you actually get is user.js. If you skip it, the CSS lands in chrome/ and nothing changes, which is exactly the failure the README warns about first. The README also points to two branches for people who want a different base: photon-style for the older Photon look and proton-style for the Proton look.

Restarts, conflicting options and the v102 accent color case

The most common failure mode is not a broken stylesheet. It is a missing or incomplete user.js. The README puts this at the top of the page in bold, and the reason is structural: the option system depends on user configuration, so a correct chrome/ directory with no preferences produces no visible change. If you install the files and see the stock interface, check user.js before you debug CSS.

The second failure mode is option conflicts. The README states that some settings can be conflicted and should be explicitly set to false. That means a value left at its default is not always the same as a value set to false, and a theme that looks half-applied may be the result of two options fighting rather than one option being wrong.

The third is version drift. On Firefox v102 or lower you have to set userChrome.compatibility.accent_color to true additionally, according to the README, which links to a compatibility page for the accent color case. There is also a documented Windows 7 caveat: the PowerShell script does not work there, and the feature list separately mentions Windows 7 compatibility for the theme itself. Those are different things, and confusing them will send you looking in the wrong place.

Finally, there is no live preview. Because real-time changes are difficult and require a restart, iterating on a setting means editing user.js, restarting Firefox, and looking again. For a theme with this many options, that loop is the real cost of ownership.

Lepton against a plain userChrome.css setup

The obvious alternative is writing your own userChrome.css. Firefox has loaded a chrome/ directory from the profile for years, and the related searches around Firefox userChrome CSS show that this is the path many people take. The difference in approach is not aesthetic, it is about who maintains the rules. A hand-written userChrome.css is a few dozen selectors you wrote and can debug because you know why each one exists. Firefox-UI-Fix is a generated artifact: SCSS in src/ compiles to css/leptonChrome.css and css/leptonContent.css, and the repository carries a validate script that runs csstree-validator over the compiled Chrome and Content CSS, plus a Jest test setup.

That build pipeline is the actual distinction. You get a maintained set of rules covering tabs, panels, menus, icons, ActivityStream, error pages, the video player and fullscreen overlap, and you get a named option system so you change behavior through preferences rather than patching selectors. In exchange you inherit the project's assumptions about padding, contrast and tab shape, and you take on its restart cycle.

The second alternative is upstream Proton itself. If your complaints are the ones the README lists, staying on stock Firefox costs nothing and breaks on nothing. Lepton is worth the setup when the padding and tab-shape issues bother you enough to maintain a profile directory.

Licence, build cost and what the repository does not answer

Firefox-UI-Fix is licensed MPL-2.0, and the package.json license field reads MPL 2.0. MPL-2.0 is a file-level copyleft licence, so if you fork the SCSS and redistribute modified files, the obligations attach to those files. This is a description of the licence identifier, not legal advice; read the LICENSE file in the repository if you plan to redistribute.

Upgrade cost is low if you install by hand. The theme is a set of files in your profile, and the release history shows v8.7.6 on 2026-09-06, v8.7.5 on 2026-01-01 and v8.7.4 on 2025-11-30, so releases are not on a fixed schedule. The last push to the repository was on 2026-09-06. There is no package manager involved for end users, no auto-update, and no version pinning mechanism described in the README, which means upgrading means downloading again and repeating the copy step.

If you want to build from source, the toolchain is Node with yarn. The package.json pins packageManager to [email protected] and defines build as yarn build:scss followed by yarn format:build, with sass, prettier, csstree-validator, jest and sass-true as devDependencies. That is a real build chain, not a single file you edit.

What the README does not cover: there is no documented rollback procedure, and no uninstall section. Removing the theme means deleting user.js and the chrome directory from your profile, which the README never states. It also does not document behavior on Firefox for Android, despite that being a common search phrase around this project.

Editorial conclusion

Adopt it if you run Firefox 89 or newer, you are comfortable editing user.js, and you want Proton with tighter padding rather than a return to Photon. Skip it if you want changes without restarting Firefox, or if you are looking for something that works on Firefox for Android. Before you start, confirm your profile directory in about:support, check whether your Firefox is v102 or lower so you know whether userChrome.compatibility.accent_color must be set to true, and keep in mind that conflicting settings must be explicitly set to false.

Frequently asked questions

Official sources

1. black7375/Firefox-UI-Fix on GitHub
2. Issues
3. License: MPL-2.0
4. README
5. Releases