# WhiteSur-firefox-theme and making Firefox look like Safari on Linux

> WhiteSur-firefox-theme is a set of CSS and an install script that reskins Firefox on Linux to resemble macOS Safari, with a Monterey variant, an alt variant and an adaptive colour version, plus a manual installation path for anyone who does not want to run a shell script. The interesting constraint is that it works by writing into the Firefox profile, which means a browser update can undo it.

**vinceliuice/WhiteSur-firefox-theme** — Mac OS Safari theme for Firefox on Linux

- Repository: https://github.com/vinceliuice/WhiteSur-firefox-theme
- Stars: 567 · Forks: 37
- Language: CSS
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/vinceliuice-whitesur-firefox-theme

## What the project actually is

The README describes the project in a single sentence: this is a bunch of CSS code to make Firefox look closer to MacOSX Safari theme. The header calls it a MacOSX Safari theme for Firefox 80+, and the repository description says Mac OS Safari theme for Firefox on Linux.

So the shape of it is clear. There is no extension, no add-on, no patched binary. What exists is a set of stylesheets that override Firefox's own chrome, plus a shell script that copies those stylesheets into the right place in your Firefox profile and registers the theme with the profile. The repository root holds only .gitattributes, LICENSE, README.md, install.sh and a src/ directory, so the code is small and the script is the entry point.

The lineage is documented too: the project is based on rafaelmardojai's firefox-gnome-theme, which is itself a Firefox theme in the GNOME family. WhiteSur is a broader design language, and this repository is one of its ports to a specific application, namely Firefox on Linux, with the same name also covering a GTK theme, a window manager style and other ports in the same family.

The audience is narrow and worth naming precisely: a Linux user running Firefox who wants the visual language of macOS Safari and is prepared to manage the result by hand. That last clause is not a minor caveat. Because the theme is implemented by writing CSS into the browser profile directory, the browser owns that directory, and the relationship between a profile and a theme is not something the browser promises to keep stable.

## Running install.sh and the options it exposes

Installation on Linux is one command:

```sh
./install.sh
```

And there is an explicit warning attached to it: do not run it with sudo, or it will install in root user folder. That warning is worth taking seriously rather than skimming, because installing a Firefox profile into the root account means the theme applies to a profile that is not the one you are using, and the failure mode is a theme that appears not to work.

The script's own help output lists the options. The -m, --monterey flag takes a value describing topbar buttons, not window control buttons, as a+b where a is the number of urlbar left side buttons and b the number of urlbar right side buttons, with the accepted combinations running from 3+3 up to 5+5. The -a, --alt flag installs the Monterey theme alt version. The -A, --adaptive flag installs the Firefox adaptive colour version. The -e, --edit flag takes an optional argument of monterey, alt or adaptive, edits the theme settings and also connects the theme to the current Firefox profiles. The -r, --remove, --revert flag removes themes and does the opposite of install and connect. And -h, --help shows the help.

The README then gives the short forms of the same thing in prose: run ./install.sh -e if you want to edit the style, ./install.sh -m for the Monterey style, and ./install.sh -a for the Monterey alt style.

The -e flag is the most interesting of these because it does two things at once. Editing the theme and connecting it to the current profiles are bundled into one operation, which tells you the script's model: it manages a set of profiles and a set of theme files, and it knows how to link them.

The -r flag matters just as much for anyone who wants to try this and change their mind. A theme that writes into your profile directory without an uninstall path is a bad neighbour, and this one has one.

## Manual installation, and the about:config step that makes it work

The README also documents a fully manual path, which is the more honest way to understand what the script does for you.

The steps are: go to about:support in Firefox, then Application Basics, then Profile Directory, then Open Directory. Copy the chrome folder into the Firefox config folder. If you are using Firefox 69 or later, go to about:config, search for toolkit.legacyUserProfileCustomizations.stylesheets and set it to true. Restart Firefox. Then open the Firefox customization panel and use the Title bar option to toggle CSD if it is not set by default, move the new tab button to headerbar, and select light or dark variants on the theme switcher.

Two details do the real work. The first is toolkit.legacyUserProfileCustomizations.stylesheets, and the reason it is needed is in the name: userChrome.css, the file that carries the custom chrome, is a legacy mechanism. Firefox still honours it, but only when that preference is flipped. Without it, copying the chrome folder does nothing at all, and the most common support question about any Firefox chrome theme is exactly this.

The second is the Title bar toggle, which is about client-side decorations. CSD is what lets the browser draw its own title bar instead of using the window manager's, and that is the difference between a themed Firefox that looks like Safari and a themed Firefox that looks like Safari with a native title bar on top of it.

The light and dark variant switch in the customization panel is worth noting as a design decision. Rather than shipping two separate themes, the theme exposes a switch in the place the user already goes to change colours.

## Optional features and the cost of enabling them

There is a section on enabling optional features, and its warning is the most useful paragraph in the README.

The instruction is to open userChrome.css with a text editor and follow the instructions there to enable extra features. The caveat is that this file might change in future versions and your configuration will be lost. The workaround given is to copy the @imports you want to enable to a new file named customChrome directly in your chrome directory, if you want it to survive updates. And the ordering constraint: all @imports must be at the top of the file, before other statements.

That is a real cost and it is worth naming it plainly. The optional features are not switched on by a setting; they are switched on by editing a file that the project itself regenerates. So the work of enabling them is a one-time edit that the upgrade path can wipe out, and the mitigation is to move the import list out of the file the project owns and into one it does not.

The CSS @import mechanism is what makes this possible at all. An @import at the top of a stylesheet pulls in another stylesheet, so the theme is decomposed into a main file and a set of optional partials, and the optional ones are commented out until you want them. That structure is why the ordering rule exists, since CSS requires imports to precede other rules.

The customChrome file in your profile directory is the durable place to put them, and it is worth doing that from the start rather than discovering the problem after a Firefox update.

## Known bugs: the CSD corners problem

The known bugs section describes one issue in detail, and it is the kind of detail that tells you about the quality of the rest of the project.

The symptom is CSD have sharp corners, and the README links an upstream bug on Bugzilla rather than claiming the problem is fixed. The reason it happens is in the upstream bug, not in this theme.

Two workarounds are given, one per display server. For Wayland, go to the about:config page, search for the layers.acceleration.force-enabled preference and set it to true, then restart Firefox. For X11, go to about:config, type mozilla.widget.use-argb-visuals, set it as a boolean and click on the add button, then restart Firefox.

The reason this is a known bug at all is instructive about the nature of the project. Client-side decorations are drawn by the browser, and the rounding of the window corners is a property of the compositor and the graphics backend rather than of the stylesheet. The theme can make the browser request rounded corners, but whether it gets them depends on the graphics stack, which is why there are two different fixes for two different display servers.

The workaround for X11 is a workaround for a missing capability: a boolean preference that has to be added rather than changed implies the default is not what you want. The honest framing is that on X11, getting the macOS-style rounded window requires turning on a feature that is off by default, and any user who cares about the appearance has to do that step themselves.

## Development, other platforms, and the licence

The README closes with a development section, which is the part most theme repositories omit.

To use the Inspector to debug the UI, open the developer tools with F12 on any page, go to options, and check two things: Enable browser chrome and add-on debugging toolboxes, and Enable remote debugging. Then close those tools and press Ctrl+Alt+Shift+I to inspect the browser UI.

That is a meaningful addition, because the browser chrome is not the page, so the ordinary developer tools will not show you the elements your CSS is targeting. The two debug checkboxes make the chrome inspectable, and Ctrl+Alt+Shift+I is the shortcut that opens the inspector for it. Anyone who has tried to modify a userChrome theme without this will recognise the problem it solves.

The platform boundary is stated early. This project applies custom CSS to Firefox on Linux, and for other operating systems the README points to the MacOS and Windows version, which is a separate repository by AdamXweb, WhiteSurFirefoxThemeMacOS. So there is a Linux implementation here and a different one elsewhere, and they are not the same code.

The licence is MIT, with the LICENSE file at the repository root, so the CSS and the script can be used and modified freely, including in commercial work, with the notice retained.

The release history is dated rather than versioned, with tags named by date, most recently 2026-07-07 and before that 2025-07-28 and 2025-02-12. The repository is not archived and the last push was on 2026-08-11. A date-based tag is a reasonable convention for a visual theme, since there is no API to break, but it does mean you cannot tell from the tag alone whether a change affects the profile layout.

## Conclusion

WhiteSur-firefox-theme is a good fit for a Linux Firefox user who wants the macOS Safari look and can live with re-applying it after a browser upgrade, because the theme is pure CSS with a script that installs, edits and reverts it across profiles. It is a poor fit if you are on macOS or Windows, since the project explicitly says it applies to Firefox on Linux and points elsewhere for other systems, and a poor fit if you want a theme that survives upgrades without work, because the optional feature configuration lives in userChrome.css and is documented as lost on updates. Before installing, read the sudo warning, because running the script as root installs into the root user folder, and check whether you want the Monterey, alt or adaptive variant, since the install is a separate decision per option.

## FAQ

### How do I install WhiteSur-firefox-theme on Linux?

Run `./install.sh` in the terminal from the cloned repository. The README warns not to run it with sudo, because it would install into the root user folder instead of your own Firefox profile.

### Which install.sh options are available?

The help output lists -m, --monterey for the number of topbar buttons as an a+b value, -a, --alt for the alt version of the Monterey theme, -A, --adaptive for the adaptive colour version, -e, --edit to edit settings and connect to current profiles, -r, --remove and --revert to undo the install, and -h, --help.

### Does WhiteSur-firefox-theme work on macOS and Windows?

No. The README states the project applies custom CSS to Firefox on Linux, and points to a separate MacOS and Windows version, WhiteSurFirefoxThemeMacOS by AdamXweb, for other operating systems.

### Why is my manual theme installation not showing any effect?

The manual instructions require setting toolkit.legacyUserProfileCustomizations.stylesheets to true in about:config, because userChrome.css is a legacy mechanism that Firefox only honours when that preference is enabled. You also need to restart Firefox afterwards.

### How do I fix the sharp corners on the themed Firefox window?

There is a Wayland fix and an X11 fix. On Wayland, set layers.acceleration.force-enabled to true in about:config. On X11, add mozilla.widget.use-argb-visuals as a boolean in about:config. Restart Firefox after either change.

### What licence is WhiteSur-firefox-theme released under?

MIT, with the LICENSE file at the repository root. The project is based on rafaelmardojai's firefox-gnome-theme, and the most recent release tag is dated 2026-07-07.

## Sources

- [Issues](https://github.com/vinceliuice/WhiteSur-firefox-theme/issues)
- [License: MIT](https://github.com/vinceliuice/WhiteSur-firefox-theme/blob/main/LICENSE)
- [README](https://github.com/vinceliuice/WhiteSur-firefox-theme/blob/main/README.md)
- [Releases](https://github.com/vinceliuice/WhiteSur-firefox-theme/releases)
- [vinceliuice/WhiteSur-firefox-theme on GitHub](https://github.com/vinceliuice/WhiteSur-firefox-theme)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vinceliuice-whitesur-firefox-theme