# gwfox: restyling Firefox with two CSS files and a set of preferences

> gwfox is a Firefox theme delivered as userChrome.css and userContent.css rather than as an add-on, so it restyles the browser chrome through the profile instead of through the extension API. Installation is a file copy and a handful of about:config preferences, and the look is controlled by gwfox.* toggles that the stylesheets read directly.

**akkva/gwfox** — Bringing a crisp new look to Firefox

- Repository: https://github.com/akkva/gwfox
- Stars: 900 · Forks: 38
- Language: CSS
- License: MPL-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/akkva-gwfox

## The problem: the browser chrome you cannot change

Firefox is famously extensible and famously stubborn about its own interface. The window frame, the tab strip, the address bar and the new tab page are all drawn by the browser itself, and the stylesheets that control them are locked down by default. Extensions cannot touch them through the normal extension API, which is a security decision rather than an oversight.

gwfox is a theme that goes around that restriction. Its description is one line, bringing a crisp new look to Firefox, and the repository is the smallest possible expression of that idea: two stylesheets, a licence, a readme, and no code.

What that buys the user is control. The theme is not a static design, it is a set of layers that you switch on and off, and the switches are exposed as Firefox preferences rather than as a settings panel, so the theme and the browser share one configuration surface.

The audience is people who have already spent time in about:config, which is a specific and self-selecting group. It is also the natural home for a theme that wants to imitate a different operating system's window decorations, since those are not something Firefox exposes to add-ons either.

The project is licensed MPL-2.0, the repository is not archived, and the last push was on 2026-10-19, so it tracks current Firefox releases rather than a fixed version.

## The payload: userChrome.css and userContent.css, and nothing else

The entire repository is a licence, a readme and two stylesheets. There is no build step, no package to install, no manifest and no JavaScript. That is the design, and it has consequences.

userChrome.css is the file that styles the browser interface, the parts of the window that are not web content: the tab strip, the toolbar, the address bar, the menus, the find bar. userContent.css styles the content area, which in practice means the new tab page and the built-in pages.

Because the stylesheets are plain CSS read by the browser at startup, there is nothing to compile and nothing to minify. The price is that there is no versioned artefact and no automatic update. When the author publishes a change, you replace the file.

The other price is the one that catches most people out. The browser ships with a protection that prevents user stylesheets from loading, and this theme requires you to turn that protection off. The preference toolkit.legacyUserProfileCustomizations.stylesheets, which the documentation marks as required, is what does it. The name says legacy, which is an accurate description of where the theme sits in the browser's design.

So the real cost of this theme is not a compatibility risk, it is that you are editing files inside your browser profile, in a directory the browser owns, and any profile reset takes your theme with it.

## Installing: copy the files, set four preferences, restart

The installation is three steps, and none of them is a package manager.

First, move the theme files into your profile's chrome folder. That is the folder in your Firefox profile directory where the browser looks for userChrome.css and userContent.css. You are overwriting whatever is there, so if you have customised your own userChrome.css, that is the moment to back it up.

Second, configure about:config with the required preferences. Four of them are marked as required, and the documentation lists them with their values:

- toolkit.legacyUserProfileCustomizations.stylesheets set to true, which is what allows the stylesheets to load at all.
- svg.context-properties.content.enabled set to true.
- browser.newtabpage.activity-stream.nova.enabled set to true.
- browser.nova.enabled set to true.

Then there are platform specific ones. On Windows, widget.windows.mica set to true and widget.windows.mica.toplevel-backdrop set to 2, which together give the translucent window backing. On Linux, widget.gtk.rounded-bottom-corners.enabled set to true. On macOS, widget.macos.native-context-menus set to false, which is what lets the theme draw its own context menus.

Third, restart Firefox to apply the changes. The stylesheets are read at startup, so there is no live reload for most of it.

One extra instruction catches East Asian users out, and it is not a preference but a Settings toggle: enable Address Bar: show results during IME composition, in Settings then Firefox Labs. Without it, IME composition in the address bar fights with the theme's restyled input handling.

## The gwfox.* preferences: the theme as a set of switches

The customisation model is a namespace of preferences, and reading the list is the fastest way to understand what the theme can do.

There are boolean toggles such as gwfox.urlbar, which moves the address bar into the sidebar, gwfox.toolbar, which auto-hides the bookmarks toolbar, and gwfox.urlbar.ac, which auto-collapses the address bar for horizontal tabs. There are appearance switches too: gwfox.blur adds an acrylic effect to the floating panel, gwfox.ac enables the accent colour, which you customise by editing the --bg0 CSS variable, and gwfox.noborder removes window borders.

Then there are the ones that make the theme imitate another platform. gwfox.mwc enables macOS-style window controls on Windows and Linux, gwfox.msc enables a macOS-style tab close button, and gwfox.twc enables theme-styled window controls, with gwfox.twc.ac auto-collapsing them. gwfox.bms enables main window transparency on Linux, gwfox.icons adds menu icons, gwfox.fxa replaces the app menu icon with your avatar, and gwfox.fsi switches to the FluentUI System Icons set.

Two of the toggles depend on other things. gwfox.newtab enables new tab transparency and requires allow_transparent_browser. gwfox.atbc exists for compatibility with the Adaptive Tab Bar Colour add-on, and gwfox.urlbar does not work with the hover-expand mode.

The single numerical setting is gwfox.sidebar, which sets the sidebar width to 1 for narrow, 3 for wide, or the default otherwise.

The mechanism that ties this together is worth spelling out, because it is unusual. The CSS reads the preferences with an at-rule that tests a preference directly, which is how a stylesheet can respond to a boolean you toggled in about:config without any JavaScript.

## Editing userChrome.css: the sidebar collapse threshold

Because the preferences drive the CSS, the theme can be adjusted by editing the stylesheet, and the documentation gives a worked example.

The gwfox.urlbar.ac toggle auto-collapses the address bar. By default it triggers whenever the setting is on, but the documentation shows how to make it trigger only when the window is narrow. You find this line in your userChrome.css:

```css
@media -moz-pref("gwfox.urlbar.ac") and (not -moz-pref("sidebar.verticalTabs")) {
```

and change it to add a width condition:

```css
@media -moz-pref("gwfox.urlbar.ac") and (not -moz-pref("sidebar.verticalTabs")) and (width < 1500px) {
```

The documentation notes that you can adjust the 1500px value to whatever suits you.

The at-rule is the whole trick. It combines a test on your custom preference with a test on a built-in Firefox preference, and a media query on the window width, all in one condition. The theme is therefore a set of CSS branches selected by configuration state, and it is the reason a boolean toggle in about:config can change the layout of a window without any script reloading anything.

This is also the practical answer to the question of how you make the theme yours. The documented extension points are the --bg0 CSS variable for the accent colour, the media query for the collapse threshold, and the fact that the address bar in the sidebar expands in an Arc-like hover mode from the left when gwfox.urlbar is enabled.

## Platform differences, versioning and the limits of a CSS theme

The theme is not one thing across operating systems, and the documentation is honest about it. On Windows the mica preferences are what produce the translucent window backing, and the macOS-style window controls are opt-in for Windows and Linux. On Linux, rounded bottom corners come from a GTK preference and main window transparency is a separate toggle. On macOS, native context menus are turned off so the theme can draw its own. Each of these is a different set of Firefox internals being leaned on, which is why the required preference list is not short.

The versioning follows Firefox rather than the project. The only release is v158.0.9, published on 2026-10-19, the same day as the last push, and the number follows the browser release the theme targets, so a new Firefox release means a new tag. For a user this is the one thing to keep an eye on, because a stylesheet that depends on internal selectors can break when the browser changes them, and the tag number is the signal that a change has been made.

The limit to be honest about is that this is a restyle of the browser, not a change to it. It cannot add a feature, it cannot change how tabs behave beyond appearance, and it cannot survive a profile reset. The alternative approach, a Firefox add-on that ships a theme through the add-on API, is closer to the supported path: it installs and updates itself, and it is reviewed by the store, but it can only do what the extension API allows, which for chrome restyling is very little. gwfox exists precisely because that route is closed.

So the decision is between a supported but limited mechanism and an unsupported but complete one. For a browser you use daily, that trade is worth understanding before you overwrite your profile files.

## Conclusion

Adopt gwfox if you want a different Firefox chrome, you are willing to edit files in your browser profile, and you are comfortable turning off the legacy stylesheet protections that Firefox ships for safety. Do not adopt it if you want a theme that survives a profile reset, since gwfox lives in the profile and is not an add-on you can reinstall from the store. Before you apply it, copy your existing userChrome.css and userContent.css, because the installation replaces them, and check the four required preferences, since the theme does not render correctly without toolkit.legacyUserProfileCustomizations.stylesheets and the two nova preferences enabled.

## FAQ

### How do I install the gwfox Firefox theme?

Move userChrome.css and userContent.css into the chrome folder of your Firefox profile, set the required preferences in about:config, including toolkit.legacyUserProfileCustomizations.stylesheets set to true and the two nova preferences, then restart Firefox.

### What preferences does gwfox add to Firefox?

A set of gwfox.* preferences, mostly booleans, such as gwfox.urlbar to move the address bar into the sidebar, gwfox.toolbar to auto-hide the bookmarks toolbar, gwfox.ac for the accent colour, gwfox.mwc for macOS-style window controls and gwfox.bms for main window transparency on Linux. The one numeric setting is gwfox.sidebar, with values 1 for narrow, 3 for wide, or the default.

### Why does gwfox need Firefox Labs enabled for Chinese input?

The documentation asks East Asian users to enable Address Bar: show results during IME composition in Settings then Firefox Labs, because the theme restyles the address bar input and IME composition otherwise conflicts with it.

### Can I change gwfox settings without editing CSS?

Yes. The theme reads its own gwfox.* preferences from about:config, and the stylesheets select behaviour with an at-rule that tests a preference directly. For finer changes, the documentation shows how to edit the media query in userChrome.css that controls when the address bar auto-collapses, and to adjust the --bg0 variable for the accent colour.

### What licence is gwfox released under?

MPL-2.0, with the LICENSE file at the root of the repository. The repository contains only that licence, the README and the two stylesheets, with the latest release being v158.0.9 on 2026-10-19.

## Sources

- [akkva/gwfox on GitHub](https://github.com/akkva/gwfox)
- [Issues](https://github.com/akkva/gwfox/issues)
- [License: MPL-2.0](https://github.com/akkva/gwfox/blob/main/LICENSE)
- [README](https://github.com/akkva/gwfox/blob/main/README.md)
- [Releases](https://github.com/akkva/gwfox/releases)

---

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