CSS

Generation

  • Use CSS post processing such as PostCSS to help generate CSS with high browser compatibility. Do not use CSS pre-processors.
  • Do not use other Frameworks (such as Bootstrap or Foundation).

Syntax

  • Use tabs rather than spaces to format the code as this enables the developer to set the indenting to their own preference.
  • When grouping selectors, keep individual selectors to a single line.
  • Include one space before the opening brace of declaration blocks for legibility.
  • Place closing braces of declaration blocks on a new line.
  • Include one space after : for each declaration.
  • Each declaration should appear on its own line for more accurate error reporting.
  • End all declarations with a semi-colon.
  • Comma-separated property values should include a space after each comma (eg. box-shadow).
  • Lowercase all hex values, eg. #fff. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.
  • Use shorthand hex values where available, eg. #fff instead of #ffffff.
  • Quote attribute values in selectors, eg. input[type="text"].
  • Use classes to apply all styling — but apply common sense
  • Always include styles to notify a users of when an interactive element gains focus, hovers and for links has been visited.
  • Always use relative units such as em or rem for setting font sizes, padding etc, do not use pixels units
  • Do not prefix property values or color parameters with a leading zero (eg. .5 instead of 0.5 and -.5em instead of -0.5em).
  • Never specify units for zero values, eg. margin: 0; instead of margin: 0px;.
  • Never use !important as it blocks users from their own override styles.
  • Never fix the height of an element containing text. Elements must be allowed to reflow if the content is no longer going to fit.
/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
	padding:15px;
	margin:0px 0px 15px;
	background-color:rgba(0,0,0,0.5);
	box-shadow:0px 1px 2px #ccc,inset 0 1px 0 #fff
}
.selector{color:#fff;}/* Good CSS */
.selector,
.selector-secondary,
.selector[type = 'text'] {
	background-color: rgba(0, 0, 0, .5);
	box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
	margin-bottom: 15px;
	padding: 15px;
}
.selector {
	color: #fff;
}

Naming

  • Choose names according to semantic meaning rather than presentation.
  • Keep classes as short and succinct as possible, but avoid excessive and arbitrary shorthand notation — .a-button is useful for button, but .s doesn't mean anything.
  • Use meaningful names — use structural or purposeful names over presentational.
  • Do not use IDs for styling.
  • Use BEM notation.

Declaration order

Related property declarations should be ordered alphabetically.

.declaration-order {
	background-color: #f5f5f5;
	border: 1px solid #e5e5e5;
	border-radius: 3px;
	color: #333;
	display: block;
	font: normal 1.2em "Helvetica Neue", sans-serif;
	left: 0;
	opacity: .5;
	position: absolute;
	top: 0;
	z-index: 100;
}

Do not use @import

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:

  • Use multiple <link> elements.
  • Concatenate your CSS files with features provided in Rails, Jekyll, and other environments.
<!-- Use link elements -->
<link rel="stylesheet" href="core.css"><!-- Avoid @imports -->
<style>
	@import url("more.css");
</style>

Media query placement

Place media queries as close to their relevant rule sets whenever possible. Do not bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future. Here's a typical setup.

.element {
	...
}
.element-avatar {
	...
}
.element-selected {
	...
}@media (min-width: 480px) {
	.element {
		...
	}
	.element-avatar {
		...
	}
	.element-selected {
		...
	}
}

Prefixed properties

When using vendor prefixed properties, indent each property such that the declaration's value lines up vertically for easy multi-line editing.

/* Prefixed properties */
.selector {
	-webkit-box-shadow: 0 1px 2px rgba(0, 0, 0, .15);
			box-shadow: 0 1px 2px rgba(0, 0, 0, .15);
}

Shorthand notation

Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. Common overused shorthand properties include:

  • padding
  • margin
  • font
  • background
  • border
  • border-radius

Often we do not need to set all the values a shorthand property represents. For example, HTML headings only set top and bottom margin, so when necessary, only override those two values. Excessive use of shorthand properties often leads to sloppier code with unnecessary overrides and unintended side effects.

/* Bad example */
.element {
	background: red;
	background: url("image.jpg");
	border-radius: 3px 3px 0 0;
	margin: 0 0 10px;
}/* Good example */
.element {
	background-color: red;
	background-image: url('image.jpg');
	border-top-left-radius: 3px;
	border-top-right-radius: 3px;
	margin-bottom: 10px;
}

Comments

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name.

Be sure to write in complete sentences for larger comments and succinct phrases for general notes.

/* Bad example */
/* Modal header */
.o-modal-header {
	...
}/* Good example */
/* Wrapping element for .o-modal-title and .o-modal-close */
.o-modal-header {
	...
}

Organization

  • Organize sections of code by component.
  • Develop a consistent commenting hierarchy.
  • Use consistent white space to your advantage when separating sections of code for scanning larger documents.
  • When using multiple CSS files, break them down by component instead of page. Pages can be rearranged and components moved.
  • Keep module styles together, include all breakpoints
/*
* Component section heading
*/.element {
	...
}
/*
* Component section heading
*
* Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
*/.element {
	...
}/* Contextual sub-component or modifier */
.element-heading {
	...
}

Backgrounds

A page background colour must always be defined in the CSS, even if it is white. Also whenever specifying a text colour or a background image a suitable background colour must also be specified.

The CSS background: property should be used to add colour and decorative images to the HTML. The general rule of thumb is images that are used for decoration should be inserted using the CSS background:/background–image: property. Images that are integral to the content should be declared inline in the HTML document.

When adding gradient backgrounds these should be provided using the CSS3 property in browsers that support it. As a fallback an SVG background can be provided for browsers lacking CSS3 support. Do not use MS filters for gradients or opacity effects however as this can lead to accessibility problems.

Background images

Background images should be used to add decorative images to a web page. The content of a web page must be visible with or without images.

Background Image sprites

Sprites should be used to create images that change in response to user actions. Sprites reduce the number of server calls and remove the image flicker effect that occurs when an image is downloaded. This can be used for buttons and iconography, etc.

Print

Always provide and appropriate print stylesheet, ensuring the following:

  • Remove unneeded items from the page by setting them to display: none;, only include the content the user will need, other items such as navigational functionality do not need to be included.
  • Format the page layout for printing by linearising the content, removing positioning such as floats amd ensuring the content spans the full width of the paper.
  • Ensure all colours used have sufficient contrast when printed in greyscale on white paper. Remove background colours and images as these will not print in most circumstances.
  • Consider carefully whether images need to be printed out or if they are just decorative and so can be removed.
  • Format fonts for printing – use font–sizes in pt and ensure all fonts are easy to read.
  • Ensure any links printed are clearly indicated when printed in greyscale and consider including the link location as described in Improving Link Display for Print by Aaron Gustafson

Editor preferences

Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:

  • Use tabs rather than soft tabs.
  • Trim trailing white space on save.
  • Set encoding to UTF-8.
  • Add new line at end of files.

Linting

There is a standardised set of CSS linting rules available to ensure that all code produced is consistently formatted.

For more information see the code linting documentation.