The purpose of this document is to provide guidelines for writing CSS. Code conventions are important for the long-term maintainability of code. Most of the time, developers are maintaining code, either their own or someone else’s. The goal is to have everyone’s code look the same, which allows any developer to easily work on another developer’s code.
We've borrowed some ideas from Idiomatic CSS and credited it throughout the document.
Class names should be camel case, with no dashes or underscores.
/* Good - Use camel case */
.thisIsGood {}
/* Bad - don't use underscores */
.this_is_bad {}
/* Bad - don't use dashes */
.this-is-bad {}Each indentation level is made up of four spaces. Do not use tabs. (Please set your editor to use four spaces)
/* Good */
.stubbornella {
color: #fff;
background-color: #000;
}
/* Bad - all on one line */
.stubbornella {color: #fff; background-color: #000;}Rules inside of @media must be indented an additional level.
/* Good */
@media screen and (max-width:480px) {
.stubbornella {
color: green;
}
}The opening brace should be on the same line as the last selector in the rule and should be preceded by a space. The closing brace should be on its own line after the last property and be indented to the same level as the line on which the opening brace is.
/* Good */
.stubbornella {
color: #fff;
}
/* Bad - closing brace is in the wrong place */
.stubbornella {
color: #fff;
}
/* Bad - opening brace missing space */
.stubbornella{
color: #fff;
}Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon.
/* Good */
.stubbornella {
background-color: blue;
color: red;
}
/* Bad - missing spaces after colons */
.stubbornella {
background-color:blue;
color:red;
}
/* Bad - missing last semicolon */
.stubbornella {
background-color: blue;
color:red
}Keep nesting to 3 levels deep.
/* Good */
.stubbornella {
.inner {
...
.title {
....
.subtxt {
...
}
}
}
}
/* Bad - more than 3 levels of nesting */
.stubbornella {
.inner {
...
.title {
....
.subtxt {
...
.element {
...
}
}
}
}
}Declare @extend followed by @include statements first in a declaration block. (Borrowed from [Idiomatic CSS] (https://github.com/necolas/idiomatic-css#4-format))
/* Good */
.stubbornella {
@extend .company;
@include font-size(14);
color: #555;
font-size: 11px;
}
/* Bad */
.stubbornella {
color: #555;
@extend .company;
font-size: 11px;
@include font-size(14);
}When using vendor-prefixed properties, always use the standard property as well. The standard property must always come after all of the vendor-prefixed versions of the same property.
.stubbornella {
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
}If a vendor prefixed property is used, -moz, -webkit, -o, -ms vendor prefixes should also be used. Vendor-prefixed classes should align to the left with all other properties.
/* Good */
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
/* Bad - colons aligned */
-webkit-border-radius:4px;
-moz-border-radius:4px;
border-radius:4px;Suffix property value pairs that apply only to a particular browser or class of browsers with a comment listing browsers affected.
background: #fcfcfc; /* Old browsers */
background: -moz-linear-gradient(...); /* FF3.6+ */
background: -webkit-gradient(...); /* Chrome,Safari4+ */
background: -webkit-linear-gradient(...); /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(...); /* Opera 11.10+ */
background: -ms-linear-gradient(...); /* IE10+ */
background: linear-gradient(...); /* W3C */Suffix fallback with “Old browsers” and standard property with “W3C”. Add a plus or minus to indicate that a property applies to all previous browsers by the same vendor or all future browsers by the same vendor. Using !important
Do not use !important on CSS properties. The only time this is allowed is in a global style (provided by Core team).
/* Good */
.stubbornella {
color: red;
}
/* Bad - don't use !important */
.stubbornella {
color: red !important;
}All font sizes must be specified using rem only with a pixel fall back. Do not use percentages, ems or pixels alone.
/* Good */
.stubbornella {
font-size: 14px; /* pixel fall back rule should come first */
font-size: 1.4rem;
}
/* Bad - uses ems */
.stubbornella {
font-size: 1.2em;
}
/* Bad - uses percentage */
.stubbornella {
font-size: 86%;
}
/* Bad - uses pixel only */
.stubbornella {
font-size: 14px;
}When declaring HEX values, use lowercase and shorthand (where possible) (Borrowed from [Idiomatic CSS] (https://github.com/necolas/idiomatic-css#4-format))
/* Good */
.stubbornella {
color: #ccc;
}
/* Bad */
.stubbornella {
color: #CCCCCC;
}Strings should always use double quotes (never single quotes).
/* Good */
.stubbornella:after {
content: "Stubbornella";
}
/* Bad - single quotes */
.stubbornella:after {
content: 'Stubbornella';
}When using a url() value, always use quotes around the actual URL.
/* Good */
.stubbornella {
background: url("img/logo.png");
}
/* Bad - missing quotes */
.stubbornella {
background: url(img/logo.png);
}Use double quotes around attribute selectors.
/* Good */
input[type="submit"] {
...
}
/* Bad - missing quotes */
input[type=submit] {
...
}
/* Bad - using single quote */
input[type='submit'] {
...
}Zero values do not require named units, omit the “px” or other unit.
/* Good */
.stubbornella {
margin: 0;
}
/* Bad - uses units */
.stubbornella {
margin: 0px;
}Only property hacks are allowed. To target Internet Explorer, use Internet Explorer-specific hacks like * and _ in the normal CSS files. Browser specific styles should not be in separate per-browser stylesheets. We prefer to keep all the CSS for a particular object in one place as it is more maintainable. In addition selector hacks should not be used. Classes like .ie6 increase specificity. Hacks should be kept within the CSS rule they affect and only property hacks should be used.
/* Good */
.stubbornella {
margin: 0;
_margin: -1px;
}
/* Bad - uses selector hacks */
.stubbornella {
margin: 0px;
}
.ie6 .stubbornella {
margin: -1px;
}Each selector should appear on its own line. The line should break immediately after the comma. Each selector should be aligned to the same left column.
/* Good */
button,
input.button {
color: red;
}
/* Bad - selectors on one line */
button, input.button {
color: red;
}Do not over-qualify class name selectors with an element type unless you are specifying exceptions to the default styling of a particular class.
/* Good */
.buttonAsLink {}
/* Bad - element name should be omitted */
span.buttonAsLink {}
/* Good - element is providing exceptions */
.buttonAsLink {}
span.buttonAsLink {}All selectors for a particular component start with the wrapper class name.
/* Good */
.calloutButton {
color: blue;
}
.calloutButton span {
color: green;
}
/* Bad - second rule missing scope */
.calloutButton {
color: blue;
}
span {
color: green;
}All rules should be coded to expect JavaScript to be enabled. Rules that apply when JavaScript is disabled should be preceded by the noJS class.
/* Good */
.noJS .calloutContent {
display: block;
}
/* Bad - don't use .js */
.js .calloutContent{
display: none;
}If :hover pseudo class is styled, :focus should also be styled for accessibility. Focus styles should never be removed.
/* Good */
a:hover,
a:focus {
color: green;
}
/* Bad - missing :focus */
a:hover {
color: green;
}Selectors should never use HTML element IDs. Always use classes for applying styles to specific areas of a page.
/* Good */
.header {
height: 100px;
}
/* Bad - using an ID */
#header {
height: 100px;
}The author field should contain the username of the person who first created the file. Subsequent authors or primary maintainers may also choose to add their name. The browsers in which this file was tested should be listed next to @tested.
No heights on anything that contains text. Components should be flexible and their widths should be controlled by grids.
/* Good - no width specified */
.calloutContent {
border: 1px solid #ccc;
background: #fff;
}
/* Bad - dimension specified */
.calloutContent {
width: 200px;
height: 150px;
border: 1px solid #ccc;
background: #fff;
}When labelling elements within a component with a class, try to avoid generic classes like .inner, .hd, .bd. Instead, prefix the class name with the name of the component. This is to avoid CSS getting overwritten when classes are too generic.
/* Good */
.boxHd {
background: #ccc;
}
.boxBd {
background: #ccc;
}
/* Bad */
.box .hd {
background: #ccc;
}
.box .bd {
background: #ccc;
}However when extending a component and styling the inner elements, try to use the base component's inner elements' class name for styling, instead of extending the class names of the inner elements as well.
/* Good */
.boxSimple .boxHd {
background: #ccc;
}
.boxSimple .boxBd {
background: #ccc;
}
/* Avoid this if possible */
.boxSimple .boxSimpleHd {
background: #ccc;
}We follow the commenting guideline from [Idiomatic CSS] (https://github.com/necolas/idiomatic-css#comments) with the following exception:
- Place comment on the same line as the CSS declaration it's related to.
Also, add file-level comments at the top of every CSS file, describing the file in the following format:
/**
* @desc Description of the file.
* @name Simple name for the file (i.e., Search_Widget)
* @author username
* @tested browsers
* @requires helpers.css (tied to the @name of another file)
*/