Manual:Coding conventions/CSS

shortcut: CC/CSS

See Manual:CSS for additional caveats and tips that aren't mentioned here.

WhitespaceEdit

One selector per line
Opening braces for the CSS declaration block on the same line as the (last) selector
Indent each declaration with a tab
No space before the colon
One space between the colon and the value
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.

.selector,
#some-element {
	float: right;
	text-align: left;
}
 
#look-at-the-left {
	/* @noflip */
	float: left;
	/* @embed */
	background-image: url(images/foobar.png);
}

QuotesEdit

In the background-image declaration, the url() 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.

CSS3Edit

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

And in the case of gradients, make sure to provide a good solid fallback color. And make sure that whatever content is displayed on top of the background does not depend on it being a gradient (depend, as in, should not become less readable or usable).

/* Wrong */
.bar {
	border-radius: 30px 10px;
	-webkit-border-radius: 30px 10px;
}
 
/* Right */
.bar {
	-webkit-border-radius: 30px 10px;
	/* It is important that the -webkit version is before the standardized version.
	 * Otherwise it will override it (as expected in CSS), including triggering the
	 * bugs the old -webkit- version has that WebKit has since fixed (in CSS3), but keeps
	 * in the old implementation (for backwards compatibility).
	 * see also: css-tricks.com/ordering-css3-properties
	 */
	border-radius: 30px 10px;
}
 
/* Wrong */
.foo {
	background-image: linear-gradient(top, #444444, #999999);
	background-image: -o-linear-gradient(top, #444444, #999999);
	background-image: -moz-linear-gradient(top, #444444, #999999);
	background-image: -webkit-linear-gradient(top, #444444, #999999);
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444444), to(#999999));
}
 
/* Right */
.foo {
	background-color: #444444;
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444444), to(#999999));
	background-image: -webkit-linear-gradient(top, #444444, #999999);
	background-image: -moz-linear-gradient(top, #444444, #999999);
	background-image: -o-linear-gradient(top, #444444, #999999);
	background-image: linear-gradient(to bottom, #444444, #999999);
}
 
/* Right (commented) */
.foo {
	/* Fallback color in case background-image is broken or not supported */
	background-color: #444444;
	/* Safari 4+, Chrome 2, iOS 2 */
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444444), to(#999999));
	/* Safari 5.1+, Chrome 10+, iOS 5 */
	background-image: -webkit-linear-gradient(top, #444444, #999999);
	/* Firefox 3.6 - 15 */
	background-image: -moz-linear-gradient(top, #444444, #999999);
	/* Opera 11.10 - 12.5 */
	background-image: -o-linear-gradient(top, #444444, #999999);
	/* Standard (Firefox 16+, Opera 12.5+, IE10) */
	background-image: linear-gradient(to bottom, #444444, #999999);
}

NamingEdit

See Manual:Interface/IDs and classes for the documentation of of common IDs and classes.

Name classes and IDs the same way: all lowercase and broken up by dashes. Use the mw- prefix to avoid conflicts with IDs generated by the wikitext parser to mark section headings.

Some examples:

/* Site-wide elements */
.mw-body
#mw-panel
#mw-jsmessage
.mw-headline
.mw-label
.mw-input
 
/* Special pages */
.mw-sp-content
/* - Special:AllPages */
.mw-spallpages-table-form
.mw-spallpages-nav
/* - Special:BlockIp */
#mw-spbi-target

client-js and client-nojsEdit

MediaWiki outputs class client-nojs on the <html> element on every page. At runtime, JavaScript code replaces this with class client-js. 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 mw.loader (see Developing with ResourceLoader)

z-indexEdit

Avoid using z-indexes when possible. Instead, try to use the natural stacking order in the DOM.

LESSEdit

shortcut: CC/LESS

Starting with MediaWiki 1.22, there is native support for LESS. 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 url(image.png) in CSS).
No quotes around parameter values (same as for url(image.png) in CSS).

Example:

/*
	You do not need to copy .background-image into your code.
	It is provided by mediawiki core (in mediawiki.less).  It is
	here as an example of guard syntax.
*/
.background-image(@url) when (embeddable(@url)) {
	background-image: embed(@url);
	background-image: url(@url)!ie;
}
 
.background-image(@url) when not (embeddable(@url)) {
	background-image: url(@url);
}
 
.mw-example {
	padding: 0.2em 0.5em;
	border: 1px solid #aaa;
	.background-image(images/example.png);
	font-size: 1em;
 
	.mw-example-thing {
		display: inline-block;
		/* @noflip */
		float: left;
		border: 1px solid #ddd;
		padding: 1px 4px;
		border-radius: 2px;
	}
}

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

StructureEdit

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.

ImportEdit

The filename of an import statement should omit the .less file extension.
Use @import to load mix-ins 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 @import to bundle stylesheets that are related to one another only conceptually; instead, reference the set of files in the styles array of a ResourceLoader module.

TroubleshootingEdit

If your LESS import doesn't work, here some things to check:

Does your code contain @font-face? See this question on StackOverFlow about how to use @font-face with LESS.

MediaWiki LESS libraryEdit

resources/src/mediawiki.less/mediawiki.mixins.less is a common LESS library for MediaWiki. The directory is in $wgResourceLoaderLESSImportPaths, so you don't need to provide the full path to it. For example:

@import "mediawiki.mixins";
 
.my-create-link {
    .background-image-svg('images/create_normal.svg', 'images/create_normal.png');
}

MixinsEdit

Mixin names should use hyphen-case, just like CSS properties. They should be prefixed with `mixin-` 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 the semi colon ; in Less to separate the arguments instead. This will free up the comma to be used in the literal value.

.mixin-example(@function, @properties) {
	transition-timing-function: @function;
	transition-property: @property;
}
 
/* Good */
.mw-example {
	.mixin-example(easy-in-out; opacity, color);
 
	/* Expands to: */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;
}
 
/* Bad */
.mw-example {
	.mixin-example('easy-in-out', 'opacity, color');
 
	/* Expands to: */
	transition-timing-function: 'easy-in-out';
	transition-property: 'opacity, color';
 
	/* Values include the quotes, this is invalid CSS
	 * and results in the browser ignoring these properties
	 */
}
 
/* Bad */
.mw-example {
	.mixin-example(~'easy-in-out', ~'opacity, color');
 
	/* Expands to: */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;
 
	/* The ~ operator instructs Less to unquote the values.
	 * This produces good CSS but we avoid this pattern
	 * in favour of using ';' consistently.
	 */
}

Conventions
General	All languages · Security for developers · Pre-commit checklist · Performance guidelines (draft) · Style guide · Accessibility guide for developers (draft)
PHP	Code conventions · PHPUnit test conventions · Security checklist for developers
JavaScript	Code conventions · Learning JavaScript
CSS	Code conventions
Database	Code conventions
Python	Code conventions
Ruby	Code conventions
Selenium/Cucumber	Code conventions