Manual:Coding conventions/CSS
Naming
editName 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-headline,
.mw-label,
.mw-input {
}
/* Special pages */
.mw-body-content,
/* - Special:AllPages */
.mw-allpages-table-form,
.mw-allpages-nav {
}
Whitespace
edit- One selector/one property 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 between the colon and before the value.
- One space after commas (
,
) in multi-value properties. - A semi-colon (
;
) after each declaration (including the last one). - Closing braces unindented back to the left.
- Annotation comments 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.
.mw-selector,
#mw-some-element {
background-color: #fff;
color: #252525;
float: right;
font-family: Arial, Helvetica, sans-serif;
text-align: left;
}
/* CSSMin/CSSJanus example annotations */
.mw-look-at-the-left {
/* @embed */
background-image: url( images/foobar.png );
/* @noflip */
float: left;
}
Quotes
editIn 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.
Colour property values
editWith CSS3 developers have a plethora of accepted colour values for CSS properties like background-color
, color
, border-color
and all others.
For maintainability and file size[1] use in lowercase:
- Hex colour values like
#fff
(shorthand notation if possible) or#fefefe
rgba()
values if an alpha transparency > 0 is necessarytransparent
colour keyword (Attention at some <= IE9 caveats)
Avoid other colour keyword values, rgb()
, hsl()
and hsla()
notations.
Also make sure, that your colour contrast ratio of foreground and background (same for background gradients) should reach at least Level AA, but better AAA of WCAG 2.0.[2]
Vendor prefixes
editAlways 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/.
/* 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).
*/
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: #444;
background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999));
background-image: -webkit-linear-gradient( top, #444, #999);
background-image: -moz-linear-gradient( top, #444, #999);
background-image: -o-linear-gradient( top, #444, #999);
background-image: linear-gradient(to bottom, #444, #999);
}
/* Right (commented) */
.foo {
/* Fallback colour in case background-image is broken or not supported */
background-color: #444;
/* Safari 4+, Chrome 2, iOS 2 */
background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999));
/* Safari 5.1+, Chrome 10+, iOS 5 */
background-image: -webkit-linear-gradient( top, #444, #999);
/* Firefox 3.6 - 15 */
background-image: -moz-linear-gradient( top, #444, #999);
/* Opera 11.10 - 12.5 */
background-image: -o-linear-gradient( top, #444, #999);
/* Standard (Firefox 16+, Opera 12.5+, IE10) */
background-image: linear-gradient(to bottom, #444, #999);
}
.client-js and .client-nojs
editMediaWiki 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 customise 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 )
Anti-patterns
editz-index
editAvoid using z-index
when possible.
Instead, try to use the natural stacking order in the DOM.
Known exceptions include:
- Compact Personal Bar at
100
- Page Previews starting at
110
- Navigation Popups starting at a
1000
.
!important
editAvoid using !important
(with the exception of working around upstream code running on the same page that also uses !important
, because only !important
can override !important
).
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).[3]
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:
- Repeat the same selector to increase weight, like
.foo.foo.foo.foo
.[4] - Add or repeat attribute selectors, like
[class]
. - Use default elements as ancestor selector (e.g.
body .foo
,html body .foo
).
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.)
LESS
editStarting with MediaWiki 1.22 , there is native support in ResourceLoader for transparently using LESS (with file extension .less
) 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
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.
Structure
edit- 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
edit- The filename of an import statement should omit the
.less
file extension. - Use
@import
to load mixins and variables so that they may be used by the current LESS stylesheet; these are processed synchronously byphpless
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 thestyles
array of a ResourceLoader module.
Troubleshooting
editIf 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 library
editresources/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');
}
Mixins
editMixin 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.
*/
}
References
edit- ↑ Lowercase markup has smaller gzip output, HTML5 Boilerplate 2015
- ↑ WCAG 2.0 Understanding Contrast
- ↑ Specifics on CSS Specificity
- ↑ 3.14 things I didn’t know about CSS, CSS Day Conference 2014