Manual:Coding conventions/CSS

Naming
Name classes and IDs the same way: all lowercase and broken up by dashes. In MediaWiki core, use the  prefix to avoid conflicts with IDs generated by the wikitext parser to mark section headings. In extensions, use a  prefix.

Some examples:

Whitespace
We ♡ whitespace:
 * One selector per line.
 * One declaration per line.
 * Opening braces for the CSS declaration block on the same line as the (last) selector.
 * Indent each property declaration with a tab.
 * No space before the colon.
 * One space after the colon and before the value.
 * One space after commas in multi-value properties.
 * One space after a starting and before an ending parentheses ( and  ) in selectors (ex.  ) and properties (ex.  ).
 * A semi-colon after each declaration (including the last one).
 * Closing braces unindented back to the left.
 * Annotation for CSSJanus and CSSMin should be on their own line, above the CSS declaration they're for.
 * An empty line between one CSS rule set and the next.

Quotes
In the  declaration, the   syntax is preferred to be used without quotes. They are not needed. The only case where it could cause problems is when an unescaped closing parenthesis occurs in the given path, but those should be URL-escaped.

Color property values
CSS3 supports many different kinds of color values for CSS properties like,  ,  , et al. For consistency and compatibility, only use these three:
 * Hex color values like  and  . (Use lowercase! Use shorthand notation when possible.)
 * values if an alpha transparency is required. (Attention: IE8 doesn't support  notation, so always provide a matching declaration before this one with a hex color value as fallback.)
 * color keyword. (Attention: IE 7-8 supports it only for  and  . It draws   as black. )

Prefer all values in lowercase for consistency and optimized file compression. . See also Talk page section. Avoid other color values (including color names/keywords – think i18n while picturing,  ,  , and   notations). Also make sure that your color contrast ratio of foreground and background (incl. background gradients, and fallback colors) reaches at least Level AA, ideally Level AAA, of WCAG 2.0.

Read further at MDN.

Vendor prefixes
Always put newer versions after older versions in case of CSS vendor prefixes, putting the standardized declaration at the end. See also https://css-tricks.com/ordering-css3-properties/.

.client-js and .client-nojs
MediaWiki outputs class  on the   element on every page. At runtime, JavaScript code replaces this with class. Hence you can use this class in your selector to conditionally show, hide, or customize certain elements depending on whether the browser has JavaScript enabled and is supported by ResourceLoader. Note that for this to be useful, the stylesheet in question must not be loaded with  (see Developing with ResourceLoader)

z-index
Avoid using  when possible. Instead, try to use the natural stacking order in the DOM. Known exceptions include:
 * Personal portlet (part of Skin) at.
 * Hovercards starting at.
 * Navigation Popups starting at a.

!important
Avoid using  (with the exception of working around upstream code running on the same page that also uses , because only   can override  ).

In most cases you don't need it at all (e.g. paranoia). In other cases it may be the result of a bug elsewhere in the program. In general, to override a rule you use the same selector as the original style rule. Since CSS cascades, this works naturally (styles applied later override styles applied earlier, selectors don't need to be of higher specificity ).

If the overriding styles apply before the original styles, the styles got loaded in the wrong order. That should be addressed, but you may resort to workarounds to artificially increase the specificity: Add however many points you need. It will still allow multiple stylesheets to use the same technique and each express their specificity. Better than adding in ancestors classes not related to your code. (And more maintainable as they won't change.)
 * Repeat the same selector to increase weight, like.
 * Add or repeat attribute selectors, like.
 * Use default elements as ancestor selector (e.g.,  ).

Less
Starting with MediaWiki 1.22, there is native support in ResourceLoader for transparently using Less (with file extension ) in place of CSS. Most of the Less syntax can be formatted using the CSS conventions:
 * Indent nested blocks with 1 tab (same as for indenting declarations inside CSS rules).
 * Don't space-align declarations values inside mixins (same as for CSS rules).
 * No spaces on the outside of the parameter lists in function invocations, mixin uses and mixin definitions (same as for  in CSS).
 * No quotes around parameter values (same as for  in CSS).

Example:

There's a few new concepts that don't map to CSS conventions, outlined below.

Structure

 * Separate nested CSS rules from the parent declarations by 1 empty line.
 * @noflip tags must be on the immediate line above the declaration, as shown in the example above.

Import

 * The filename of an import statement should omit the  file extension.
 * Use  to load mixins and variables so that they may be used by the current Less stylesheet; these are processed synchronously by phpless and are not present in the generated CSS output.
 * Don't use  to bundle stylesheets that are related to one another only conceptually; instead, reference the set of files in the   array of a ResourceLoader module.

Troubleshooting
If your Less import doesn't work, here some things to check:
 * Does your code contain ? See this question on Stack Overflow about how to use @font-face with Less.

MediaWiki Less library
is a common Less mixins library for MediaWiki. The directory is in, so you don't need to provide the full path to it. For example:

Mixins
Mixin names should use hyphen-case, just like CSS properties. They should be prefixed with  to avoid confusing developers who are familiar with CSS, but not Less and distinguish them from classes, the syntax for which is similar.

As mentioned above, no spaces on the outside of the parameter list and avoid quoting values.

If you need to call a mixin with one or more arguments that contain a comma use a semicolon  in Less to separate the arguments. This allows you to use commas in the literal value.

Automated linting
The node module  checks for some of these rules; some extensions run it as part of Continuous integration. However, it doesn't parse Less output (T106780).