This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. It applies to raw, working files that use HTML and CSS. Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained.
- Indentation
- Block Content Indentation
- Capitalization
- Trailing White Space
- Declaration Stops
- Property Name Stops
- Declaration Block Separation
- Selector and Declaration Separation
- Rule Separation
- CSS Quotation Marks
- CSS Validity
- ID and Classes
- ID and Class Naming
- ID and Class Name Delimiters
- ID and Class Name Style
- Type Selectors
- Shorthand Properties
- 0 and Units
- Leading 0s
- Hexadecimal Notation
- Hacks
Omit the protocol portion (http:, https:) from URLs pointing to external stylesheets and other media files unless the respective files are not available over both protocols.
<!-- Not recommended -->
<link href="https://www.example.com/style.css" rel="stylesheet" media="screen" />
<!-- Recommended -->
<link href="//www.example.com/style.css" rel="stylesheet" media="screen" />Indent by 2 spaces.
Do not use tabs or mixed tabs and spaces for indentation.
.example {
color: blue;
}Indent all block content.
@media screen, projection {
html {
color: blue;
}
}Use only lowercase.
All code has to be lowercase: This applies to HTML element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings).
/* Not recommended */
HTML {
color: #E5E5E5;
}
/* Recommended */
html {
color: #e5e5e5;
}Remove trailing white spaces.
Trailing white spaces are unnecessary and can complicate diffs.
/* Not Recommended */
.example {
color: blue;_
}
/* Recommended */
.example {
color: blue;
}Use a semicolon after every declaration.
/* Not Recommend */
.example {
display: block;
color: blue
}
/* Recommended */
.example {
display: block;
color: blue;
}Use a space after a property name's colon.
/* Not Recommend */
.example {
margin:20px;
}
/* Recommended */
.example {
margin: 20px;
}Use a space between the first and last selector and the declaration block.
Always use a single space between the last selector and the opening brace of the block. Blocks should never be on a single line. The opening brace should be on the same line as the last selector.
/* Not Recommend */
.example{
display: block;
}
/* Not Recommend */
.example { display: block; }
/* Not Recommend */
.example
{
display: block;
}
/* Recommended */
.example {
display: block;
}Separate new selectors and declarations by new lines.
/* Not Recommend */
h1, h2 {
font-weight: normal; top: 1px;
}
/* Not Recommend */
.example { display: block; }
/* Recommended */
h1,
h2 {
font-weight: normal;
top: 1px;
}Separate new rules by new lines.
Always put a blank line (two line breaks) between rules.
html {
font-size: 12px;
}
body {
margin: auto;
}Use a single quote for attribute selectors and property values.
Do not use quotation marks for URL values.
Exception: If you do need to use the @charset rule, use double quotation marks.
/* Not Recommend */
html {
font-family: "open sans", arial, sans-serif;
background: url('example.jpg');
}
/* Recommended */
html {
font-family: 'open sans', arial, sans-serif;
background: url(example.jpg);
}Use valid CSS where possible.
Use only valid CSS code using such tools as the W3C CSS Validator. Validations tools can not spot all errors and may even give false positives for newer valid CSS. Take care to note that valid CSS can still contain visual bugs as support and implementation of properties can vary from browser to browser.
Use classes for modularity.
For general page styling uses classes. ID's should be reserved for special cases or hooks into other languages such as Javascript.
Use meaningful or generic ID or class names.
Use ID and class names that reflect the purpose of the element in question, or that is otherwise generic that can be used anywhere needed. Names that reflect presentational or cryptic in nature should be avoided.
/* Not Recommended */
.ml20 {}
.blue {}
/* Recommended */
.video {}
.login {}Separate ID and class names by hyphens.
Do not use underscores, camel case, double hyphens, or any other delimiters.
/* Not Recommended */
.demoImage {}
.error_status {}
/* Recommended */
.demo-image {}
.error-status {}Use ID and class names that are as short as possible but as long as necessary.
Use ID and Class names that is easy to understand but is not verbose. This will help with readability and code efficiency.
/* Not Recommended */
.a {}
.main-header-navigation-right {}
/* Recommended */
.author {}
.navigation {}Avoid qualifying ID and class names with type selectors.
/* Not Recommended */
div.example {}
/* Recommended */
.example {}Use shorthand properties where possible.
Using shorthand properties is useful for code efficiency and understandability.
/* Not Recommended */
margin-right: 20px;
margin-bottom: 10px;
margin-left: 10px;
/* Recommended */
margin: 0 20px 10px 10px;Omit units after "0" values.
margin: 0;
padding: 0;Omit leading 0s in values.
font-size: .8rem;Use 3 character hexadecimal notation where possible.
/* Not Recommended */
color: #eebbcc;
/* Recommended */
color: #ebc;Avoid CSS hacks. Try a different approach first.
The days of IE6 are far behind us. Avoid hacks to target specific browsers unless absolutely necessary. Try a different coding approach first before resorting to a "hack".
Use UTF-8.
Specify the encoding in HTML via <meta charset="utf-8">. Do not specify the encoding of stylesheets as these assume UTF-8.
Explain code as needed when possible.
Use comments to explain code. What does it cover? What purpose does it serve? Be thoughtful in the amount of comments as a large project can quickly become unmaintainable with too many comments. Leave comments for only technically difficult or confusing parts of code.
Group sections by a section comment.
If possible, group stylesheet sections by using comments.
/*
-----------------------------------------
Large Section Comment
-----------------------------------------
*/
/* Small Section Comment*/Separate your files into logical groups.
Split your files into logical files and folders to keep things organized and clear to understand. There are many ways to do this. The following is an example of what could be done, but not what has to be done.
css/
|
|-- helpers/ # Bootstrapping
| |-- _normalize.scss
| |-- _variables.scss
| |-- _mixins.scss
|
|-- base-styles/ # Base Styles
| |-- _general.scss
| |-- _layout.scss
| |-- _fonts.scss
| |-- _typogrpahy.scss
| |-- _buttons.scss
| |-- _forms.scss
| ...
|
|-- modules/ # Modules
| |-- _masthead.sass
| |-- _footer.scss
| |-- _home.scss
| ...
|
|-- utility/ # CSS or Sass from other projects
| |-- _colorpicker.scss
| |-- _jquery.ui.core.scss
| ...
|
|-- media-queries/ # Media Queries (if using separate files)
| |-- _responsive-768.scss
| |-- _responsive-480.scss
| ...
|
|-- style.scss # Primary Sass file
Separate blocks of rules by new lines.
The only exception to this is if the parent do not have any styles.
/* Not Recommended */
.container {
p {
color: blue;
span {
display: block;
}
}
ul {
margin: 20px;
}
}
/* Recommended */
.container {
p {
color: blue;
span {
display: block;
}
}
ul {
margin: 20px;
}
}Line up all properties and values when declaring multiple variables.
/* SCSS Variables */
$primary: #b20215;
$secondary: #149ff6;
$grey: #848484;
$brown: #a89f94;There are many ways to clear a float, but the following does it in the most efficient way possible. Support is IE8 and above.
/* Use as a class */
.clear-fix:after {
content: "";
display: table;
clear: both;
}/* Use as a mixin */
@mixin clear-fix() {
.clear-fix {
&:after {
content: "";
display: table;
clear: both;
}
}
}
/* Usage */
.example {
@include clear-fix();
}/* Use as a mixin */
.clear-fix {
&:after {
content: "";
display: table;
clear: both;
}
}
/* Usage */
.example {
.clear-fix();
}Using rem units gives us flexibility in our designs, and the ability to scale elements up and down, instead of being stuck with fixed sizes. We can use this flexibility to make our designs easier to adjust during development, more responsive, and to allow browser users to control the overall scale of sites for maximum readability.
With this rem conversion you can automatically convert a px unit into a rem with px unit fall back.
/* Requires $font-size variable to be set */
$font-size: 14px;
/* Requires function to strip units */
@function strip-unit($num) {
@return $num / ($num * 0 + 1);
}
/* Mixin for Rem Conversion */
@mixin rem-size($value, $property: font-size) {
$pxValue: strip-unit($value);
$baseValue: strip-unit($font-size);
$remValue: ($pxValue / $baseValue);
#{$property}: $value;
#{$property}: $remValue + rem;
}
/* Usage */
p {
@include rem-size(20px);
}/* Requires @font-size variable to be set */
@font-size: 14px;
/* Mixin for Rem Conversion */
.rem-size(@value, @property: font-size) {
@pxValue: unit(@value);
@baseValue: unit(@font-size);
@remValue: (@pxValue / @baseValue);
@{property}: @value;
@{property}: unit(@remValue,rem);
}
/* Usage */
p {
.rem-size(20px);
}By default this mixin will output to font-size. If you need to use another property instead of font-size you can pass a 2nd argument with the desired property to the mixin.
| Argument | Required | Default |
|---|---|---|
| Value | Required | None |
| Property | Optional | 'font-size' |
Mixin for defining box sizing.
/* Mixin for Box Sizing */
@mixin box-sizing($sizing: border-box) {
-moz-box-sizing: $sizing;
-webkit-box-sizing: $sizing;
box-sizing: $sizing;
}
/* Usage */
@include box-sizing();