Examples
<ul>
<li>Fantastic
<li>Great
</ul>
.example {
color: blue;
}
Bad
<A HREF="/">Home</A>
Good
<img src="google.png" alt="Google">
Bad
color: #E5E5E5;
Good
color: #e5e5e5;
{# TODO(john.doe): revisit centering #}
<center>Test</center>
<!-- TODO: remove optional tags -->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>
Do not use white space in file names. They complicate shell scripts
Bad
<title>Test</title>
<article>This is only a test.
Good
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
Bad
<div onclick="goToRecommendations();">All recommendations</div>
Good
<a href="recommendations/">All recommendations</a>
alt)alt attributes introduces redundancy, and images whose purpose is decorative, use no alternative text, as in alt=""Bad
<img src="spreadsheet.png">
Good
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
Separate structure from presentation from behavior.
That is, make sure documents and templates contain only HTML and HTML that is solely serving structural purposes. Move everything presentational into style sheets, and everything behavioral into scripts.
Separating structure from presentation from behavior is important for maintenance reasons. It is always more expensive to change HTML documents and templates than it is to update style sheets and scripts.
Bad
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
<u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
my website without doing everything all over again!</center>
Good
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
<p>It’s awesome!
—, ”, or ☺< and &) and “invisible” characters (like no-break spaces).Bad
The currency symbol for the Euro is “&eur;”.
Good
The currency symbol for the Euro is “€”.
type attributestype attributes for style sheets and scripts.Bad
<link rel="stylesheet" href="https://www.google.com/css/maia.css" type="text/css">
<script src="https://www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>
Good
<link rel="stylesheet" href="https://www.google.com/css/maia.css">
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
Use a new line for every block, list, or table element, and indent every such child element.
Independent of the styling of an element (as CSS allows elements to assume a different role per display property), put every block, list, or table element on a new line.
Also, indent them if they are child elements of a block, list, or table element.
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
<ul>
<li>Moe</li>
<li>Larry</li>
<li>Curly</li>
</ul>
Break long lines (optional).
While there is no column limit recommendation for HTML, you may consider wrapping long lines if it significantly improves readability.
When line-wrapping, each continuation line should be indented 2 spaces from the original line.
Too long line, too many attributes in single line
<img src="images/Search.svg" class="img-big" alt="search">
Each element should be on a new line
<img src="images/Search.svg"
class="img-big"
alt="search">
attributes should be indented with 2 spaces
<img
src="images/Search.svg"
class="img-big"
alt="search">
closing braket(>) should be on the new line
<img
src="images/Search.svg"
class="img-big"
alt="search">
closing braket(>) should be alined as open tag
<img
src="images/Search.svg"
class="img-big"
alt="search"
>
<img
src="images/Search.svg"
class="img-big"
alt="search"
>
Bad
<a class='maia-button maia-button-secondary'>Sign in</a>
Good
<a class="maia-button maia-button-secondary">Sign in</a>
{ in rule declarations: character.} of rule declarations on a new lineBad
.avatar{
border-radius:50%;
border:2px solid white; }
.no, .nope, .not_good {
// ...
}
#lol-no {
// ...
}
Good
.avatar {
border-radius: 50%;
border: 2px solid white;
}
.one,
.selector,
.per-line {
// ...
}
// in Sass-land) to block comments.Bad
<a style="color:red;">red link</a>
Good
<a class="highlighted-link">red link</a>
Do no hardcode width of elements containing text that might be i18n-ed. e.g. buttons and links almost never have fixed width.
<IMG> (with alt text) when the image has an important semantic meaning. This ensures that the meaning of the image can be communicated in all user-agents, including screen readers.background-image if the image is not part of the content (e.g. icons).We encourage some combination of OOCSS and BEM for these reasons:
OOCSS, or “Object Oriented CSS”, is an approach for writing CSS that encourages you to think about your stylesheets as a collection of “objects”: reusable, repeatable snippets that can be used independently throughout a website.
BEM, or “Block-Element-Modifier”, is a naming convention for classes in HTML and CSS. It was originally developed by Yandex with large codebases and scalability in mind, and can serve as a solid set of guidelines for implementing OOCSS.
We recommend a variant of BEM with PascalCased “blocks”, which works particularly well when combined with components (e.g. React). Underscores and dashes are still used for modifiers and children.
Example
// ListingCard.jsx
function ListingCard() {
return (
<article class="ListingCard ListingCard--featured">
<h1 class="ListingCard__title">Adorable 2BR in the sunny Mission</h1>
<div class="ListingCard__content">
<p>Vestibulum id ligula porta felis euismod semper.</p>
</div>
</article>
);
}
/* ListingCard.css */
.ListingCard { }
.ListingCard--featured { }
.ListingCard__title { }
.ListingCard__content { }
.ListingCard is the “block” and represents the higher-level component.ListingCard__title is an “element” and represents a descendant of .ListingCard that helps compose the block as a whole..ListingCard--featured is a “modifier” and represents a different state or variation on the .ListingCard block.While it is possible to select elements by ID in CSS, it should generally be considered an anti-pattern. ID selectors introduce an unnecessarily high level of specificity to your rule declarations, and they are not reusable.
For more on this subject, read CSS Wizardry’s article on dealing with specificity.
Avoid binding to the same class in both your CSS and JavaScript. Conflating the two often leads to, at a minimum, time wasted during refactoring when a developer must cross-reference each class they are changing, and at its worst, developers being afraid to make changes for fear of breaking functionality.
We recommend creating JavaScript-specific classes to bind to, prefixed with .js-:
<button class="btn btn-primary js-request-to-book">Request to Book</button>
Use 0 instead of none to specify that a style has no border.
Bad
.foo {
border: none;
}
Good
.foo {
border: 0;
}
.scss syntax, never the original .sass syntax@include declarations logically (see below)Property declarations
List all standard property declarations, anything that isn’t an @include or a nested selector.
.btn-green {
background: green;
font-weight: bold;
// ...
}
@include declarations
Grouping @includes at the end makes it easier to read the entire selector.
.btn-green {
background: green;
font-weight: bold;
@include transition(background 0.5s ease);
// ...
}
Nested selectors
Nested selectors, if necessary, go last, and nothing goes after them. Add whitespace between your rule declarations and nested selectors, as well as between adjacent nested selectors. Apply the same guidelines as above to your nested selectors.
.btn {
background: green;
font-weight: bold;
@include transition(background 0.5s ease);
.icon {
margin-right: 10px;
}
}
Prefer dash-cased variable names (e.g. $my-variable) over camelCased or snake_cased variable names. It is acceptable to prefix variable names that are intended to be used only within the same file with an underscore (e.g. $_my-variable).
Mixins should be used to DRY up your code, add clarity, or abstract complexity–in much the same way as well-named functions. Mixins that accept no arguments can be useful for this, but note that if you are not compressing your payload (e.g. gzip), this may contribute to unnecessary code duplication in the resulting styles.
@extend should be avoided because it has unintuitive and potentially dangerous behavior, especially when used with nested selectors. Even extending top-level placeholder selectors can cause problems if the order of selectors ends up changing later (e.g. if they are in other files and the order the files are loaded shifts). Gzipping should handle most of the savings you would have gained by using @extend, and you can DRY up your stylesheets nicely with mixins.
Do not nest selectors more than three levels deep!
.page-container {
.content {
.profile {
// STOP!
}
}
}
When selectors become this long, you’re likely writing CSS that is:
Again: never nest ID selectors!
If you must use an ID selector in the first place (and you should really try not to), they should never be nested. If you find yourself doing this, you need to revisit your markup, or figure out why such strong specificity is needed. If you are writing well formed HTML and CSS, you should never need to do this.
.menu {
li {
list-style: none;
margin: 0;
padding: 0;
a {
color: $my-blue;
text-decoration: none;
}
}
}
<ul class="menu">
<li><a href="#">My Link</a></li>
<li><a href="#">My Second Link</a></li>
</ul>
.menu {
&__item {
list-style: none;
margin: 0;
padding: 0;
}
&__link {
color: $my-blue;
text-decoration: none;
}
}
<ul class="menu">
<li class="menu__item"><a href="#" class="menu__link">My Link</a></li>
<li class="menu__item"><a href="#" class="menu__link">My Second Link</a></li>
</ul>
.menu {
&__item {
list-style: none;
margin: 0;
padding: 0;
&:first-child .menu__link {
border-left: 1px solid $my-blue;
}
}
&__link {
color: $my-blue;
text-decoration: none;
}
&__active {
color: $my-green;
}
}
<ul class="menu">
<li class="menu__item">
<a href="#" class="menu__link">My Link</a>
</li>
<li class="menu__item">
<a href="#" class="menu__link menu__active">My Second Link</a>
</li>
</ul>
.menu {
&__item {
list-style: none;
margin: 0;
padding: 0;
}
&__link {
color: $my-blue;
text-decoration: none;
&--first {
border-left: 1px solid $my-blue;
}
&--active {
color: $my-green;
}
}
}
<ul class="menu">
<li class="menu__item">
<a href="#" class="menu__link menu__link--first">My Link</a>
</li>
<li class="menu__item">
<a href="#" class="menu__link menu__link--active">My Second Link</a>
</li>
</ul>
// header.scss
.header {
&__menu {
// ...
}
.button {
margin: 0;
}
}
// button.scss
.button {
background: $my-blue;
color: $white;
margin: 5px 0;
padding: 10px;
&--primary {
background: $my-green;
}
}
<div class="header">
<ul class="header__menu">...</ul>
<a href="#" class="button button--primary">
My awesome Button
</a>
</div>
// header.scss
.header {
&__menu {
// ...
}
}
// button.scss
.button {
background: $my-blue;
color: $white;
margin: 5px 0;
padding: 10px;
&--primary {
background: $my-green;
}
&--no-margin {
margin: 0;
}
}
<div class="header">
<ul class="header__menu">...</ul>
<a href="#" class="button button--primary button--no-margin">
My awesome Button
</a>
</div>