Draft

This page is not complete.

This document contains guidelines defining how CSS inside the Firefox codebase should be written, it is notably relevant for Firefox front-end engineers.

Basics

Here are some basic tips that can optimize reviews if you are changing CSS:

Boilerplate

Make sure each file starts with the standard copyright header (see License Boilerplate).

Before adding more CSS

It is good practice to check if the CSS that is being written is needed, it can be the case that a common component has been already written could be reused with or without changes. Most of the time, the common component already follows the a11y/theme standards defined in this guide. So, when possible, always prefer editing common components to writing your own.

Also, it is good practice to introduce a common class when the new element you are styling reuses some styles from another element, this allows the maintenance cost and the amount of code duplication to be reduced.

Formatting

Spacing & Indentation

linear-gradient(to bottom, black 1px, rgba(255,255,255,0.2) 1px)

Omit units on 0 values

Do this:

  margin: 0;

Not this:

  margin: 0px;

Use expanded syntax

It is often harder to understand what the shorthand is doing and the shorthand can also hide some unwanted default values. It is good to privilege expanded syntax to make your intentions explicit.

Do this:

  border-color: red;

Not this:

  border: red;

Put multiple selectors on different lines

Do this:

h1,
h2,
h3 {
  font-family: sans-serif;
  text-align: center;
}

Not this:

h1, h2, h3 {
  font-family: sans-serif;
  text-align: center;
}

Naming standards for class names

Other tips

Overriding CSS

Before overriding any CSS rules, check whether overriding is really needed. Sometimes, when copy-pasting older code, it happens that the code in question contains unnecessary overrides. This could be because the CSS that it was overriding got removed in the meantime. In this case, dropping the override should work.

It is also good practice to look at whether the rule you are overriding is still needed: maybe the UX spec for the component has changed and that rule can actually be updated or removed. When this is the case, don't be afraid to remove or update that rule.

Once the two things above have been checked, check if the other rule you are overriding contains !important, if that is case, try putting it in question, because it might have become obsolete.

Afterwards, check the specificity of the other selector; if it is causing your rule to be overridden, you can try reducing its specificity, either by simplifying the selector or by changing where the rule is placed in the stylesheet. If this isn't possible, you can also try introducing a :not() to prevent the other rule from applying, this is especially relevant for different element states (:hover, :active, [checked] or [disabled]). However, never try to increase the selector of the rule you are adding as it can easily become hard to understand.

Finally, once you have checked all the things above, you can permit yourself to use !important along with a comment why it is needed.

Using CSS variables

Adding new variables

Before adding new CSS variables, please consider the following questions:

  1. Is the variable value changed at runtime?
    (Either from JavaScript or overridden by another CSS file)

    If the answer is no, consider using a preprocessor variable or inlining the value.
     
  2. Is the variable value used multiple times?

    If the answer is no and the value isn't changed at runtime, then you likely don't need a CSS variable.
     
  3. Is there an alternative to using the variable like inheriting or using the currentcolor keyword?
    Using inheriting or using currentcolor will prevent repetition of the value and it is usually good practice to do so.

In general, it's good to first think of how some CSS could be written cleanly without the CSS variable(s) and then think of how the CSS variable could improve that CSS.

Using variables

Use the variable according to its naming

Do this:

xul|tab:hover {
  background-color: var(--in-content-box-background-hover);
}

Not this:

#certificateErrorDebugInformation {
  background-color: var(--in-content-box-background-hover);
}

Localization

Text Direction

Note: See CSS Logical Properties and Values for more information.

Testing

To test for RTL layouts, you can go to about:config and set intl.uidirection to -1.

Writing cross-platform CSS

Firefox supports many different platforms and each of those platforms can contain many different configurations:

File structure

Under each of those two directories, there is a themes directory containing 4 sub-directories:

The shared directories contain styles shared across all 3 platforms, while the other 3 directories contain styles respective to their platform.

For new CSS, when possible try to privilege using the shared directory, instead of writing the same CSS for the 3 platform specific directories, especially for large blocks of CSS.

Content CSS vs. Theme CSS

The following directories also contain CSS:

These directories contain content CSS, that applies on all platforms, which is styling deemed to be essential for the browser to behave correctly. To determine whether some CSS is theme-side or content-side, it is useful to know that certain CSS properties are going to lean one way or the other: color - 99% of the time it will be theme CSS, overflow - 99% content.

99% theme 70% theme 70% content 99% content
font-*, color, *-color, border-*, -moz-appearance [1] line-height, padding, margin cursor, width, max-width, top, bottom [2], etc overflow, direction, display, *-align, align-*, *-box-*, flex-*, order

If some CSS is layout or functionality related, then it is likely content CSS. If it is esthetics related, then it is likely theme CSS.

When importing your stylesheets, it's best to import the content CSS before the theme CSS, that way the theme values get to override the content values (which is probably what you want), and you're going to want them both after the global values, so your imports will look like this:

<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>
<?xml-stylesheet href="chrome://browser/content/path/module.css" type="text/css"?>
<?xml-stylesheet href="chrome://browser/skin/path/module.css" type="text/css"?>

[1] -moz-appearance is tricky. Generally, when specifying -moz-appearance: foo; you're giving hints as to how something should act, however -moz-appearance: none; is probably saying 'ignore browser preconceptions - I want a blank sheet', so that's more visual. However -moz-appearance values aren't implemented and don't behave consistently across platforms, so idealism aside -moz-appearance should always be in theme CSS.

[2] However there is probably a better way than using absolute positioning.

Colors

For common areas of the Firefox interface (panels, toolbar buttons, etc.), mozilla-central often comes with some useful CSS variables that are adjusted with the correct values for different platform configurations, so using those CSS variables can definitively save some testing time, as you can assume they already work correctly.

Using the currentcolor keyword or inheriting is also good practice, because sometimes the needed value is already in the color or on the parent element. This is especially useful in conjunction with icons using -moz-context-properties: fill; where the icon can adjust to the right platform color automatically from the text color. It is also possible to use currentcolor with other properties like opacity or fill-opacity to have different opacities of the platform color.

High contrast mode

Content area

On Windows high contrast mode, in the content area, Gecko does some automatic color adjustments regarding page colors. Part of those adjustments include making all box-shadow invisible, so this is something to be aware of if you create a focus ring or a border using the box-shadow property: consider using a border or an outline if you want the border/focus ring to stay visible in high-contrast mode. An example of such bug is bug 1516767.

Another adjustment to be aware of is that Gecko removes all the background-image when high contrast mode is enabled. Consider using an actual <img> tag (for HTML documents) or list-style-image (for XUL documents) if rendering the image is important.

If you are not using Windows, one way to test against those adjustments on other platforms is:

Chrome area

The automatic adjustments previously mentioned only apply to pages rendered in the content area. The chrome area of Firefox uses colors as authored, which is why using pre-defined variables, currentcolor or inheritance is useful to integrate with the system theme with little hassle.

If not, as a last resort, using system colors also works for non-default Windows themes or Linux. In general, the following colors are used:

Using the background/text pairs is especially important to ensure the contrast is respected in all situations. Never mix custom text colors with a system background color and vice-versa.

Note that using system colors is only useful for the chrome area, since content area colors are overridden by Gecko anyway.

Writing media queries

Boolean media queries

Do this:

@media (-moz-mac-yosemite-theme: 0) {

Not this:

@media not all and (-moz-mac-yosemite-theme) {

Privilege CSS for most common configuration

It is better to put the most common configuration (latest version of an OS, or default theme for example) outside of the media query. In the following example, -moz-mac-yosemite-theme targets macOS 10.10 and higher, so it should be privileged over the styling for macOS 10.9.

Do this:

@media (-moz-mac-yosemite-theme: 0) {
  #placesList {
    box-shadow: inset -2px 0 0 hsla(0,0%,100%,.2);
  }
}

Not this:

#placesList {
  box-shadow: inset -2px 0 0 hsla(0,0%,100%,.2);
}

@media (-moz-mac-yosemite-theme) {
  #placesList {
    box-shadow: none;
  }
}

Theme support

Firefox comes built-in with 3 themes: default, light and dark. The built-in light/dark themes are a bit special as they load the compacttheme.css stylesheet. In addition to this, Firefox supports a variety of WebExtension themes that can be installed from AMO. For testing purposes, here is an example of a WebExtension theme.

Writing theme-friendly CSS

Variables

For clarity, CSS variables that are only used when a theme is enabled have the --lwt- prefix.

Layout & performance

Layout

Mixing XUL flexbox and HTML flexbox can lead to undefined behavior.

CSS selectors

When targeting the root element of a page, using :root is the most performant way of doing so.

Reflows and style flushes

See Performance best practices for Firefox front-end engineers for more information about this.

Misc

Text aliasing

When convenient, avoid setting the opacity property on text as it will cause text to be aliased differently.

HDPI support

It's recommended to use SVG since it keeps the CSS clean when supporting multiple resolutions. See the SVG Guidelines for more information on SVG usage.

However, if only 1x and 2x PNG assets are available, you can use this @media query to target higher density displays (HDPI):

@media (min-resolution: 1.1dppx)