Best practices and guidelines for writing HTML and CSS with approachable formatting, syntax, and more.
<p>
tag. Never use multiple <br>
tags.<ul>
, <ol>
, or <dl>
. Never use a set of <div>
or <p>
.<label>
tag. Especially radio or checkbox elements.<!-- /.element -->
. This just adds to page load time. Plus, most editors have indentation guides and open-close tag highlighting.<br>
, <hr>
, <img>
, and <input>
.tabindex
manually—rely on the browser to set the order.<p class="line-note" data-attribute="106">
This is my paragraph of special text.
</p>
Many attributes don’t require a value to be set, like disabled
or checked
, so don’t set them.
<input type="text" disabled>
<input type="checkbox" value="1" checked>
<select>
<option value="1" selected>1</option>
</select>
For more information, read the WhatWG section.
Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. For example:
<!-- Not so great -->
<span class="avatar">
<img src="...">
</span>
<!-- Better -->
<img class="avatar" src="...">
<label>
s. No need for for
attributes here—the wrapping automatically associates the two.type
. Use primary buttons for the type="submit"
button and regular buttons for type="button"
.float: right;
on each button.Make use of <thead>
, <tfoot>
, <tbody>
, and <th>
tags (and scope
attribute) when appropriate. (Note: <tfoot>
goes above <tbody>
for speed reasons. You want the browser to load the footer before a table full of data.)
<table summary="This is a chart of invoices for 2011.">
<thead>
<tr>
<th scope="col">Table header 1</th>
<th scope="col">Table header 2</th>
</tr>
</thead>
<tfoot>
<tr>
<td>Table footer 1</td>
<td>Table footer 2</td>
</tr>
</tfoot>
<tbody>
<tr>
<td>Table data 1</td>
<td>Table data 2</td>
</tr>
</tbody>
</table>
:
in property declarations.{
in rule declarations.#000
unless using rgba()
in raw CSS (SCSS’ rgba()
function is overloaded to accept hex colors as a param, e.g., rgba(#000, .5)
).//
for comment blocks (instead of /* */
).margin: 0;
instead of margin: 0px;
.As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for three levels. If you cannot help it, step back and rethink your overall strategy (either the specificity needed, or the layout of the nesting).
Here are some good examples that apply the above guidelines:
// Example of good basic formatting practices
.styleguide-format {
color: #000;
background-color: rgba(0, 0, 0, .5);
border: 1px solid #0f0;
}
// Example of individual selectors getting their own lines (for error reporting)
.multiple,
.classes,
.get-new-lines {
display: block;
}
// Avoid unnecessary shorthand declarations
.not-so-good {
margin: 0 0 20px;
}
.good {
margin-bottom: 20px;
}
In general, the CSS file organization should follow something like this:
styles
├── components
│ ├── comments.scss
│ └── listings.scss
├── globals
│ ├── browser_helpers.scss
│ ├── responsive_helpers.scss
│ └── variables.scss
├── plugins
│ ├── jquery.fancybox-1.3.4.css
│ └── reset.scss
├── sections
│ ├── issues.scss
│ └── profile.scss
└── shared
├── forms.scss
└── markdown.scss
Variations on this structure include the multi-bundle Rails approach, as seen in the github/github
repo:
stylesheets
├── github
│ ├── base.scss
│ ├── layout.scss
│ └── buttons.scss
├── github2
│ ├── about.scss
│ └── blog.scss
└── mobile
├── _variables.scss
└── base.scss
Here, we have two desktop bundles to support IE9’s maximum selector limit per CSS file, as well as a dedicated mobile bundle to go with our separate mobile views.
Use Sprockets to require files. However, you should explicitly import any scss that does not generate styles (globals/
) in the particular SCSS file you’ll be needing its helpers in. Here’s a good example:
//= require_tree ./plugins
//= require my_awesome_styles
@import "../globals/basic";
.rule { ... }
This is also how Dojo’s styles are to be included, should you need them.
Use px
for font-size
, because it offers absolute control over text. Additionally, unit-less line-height
is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the font-size
.
Never reference js-
prefixed class names from CSS files. js-
are used exclusively from JS files.
Use the is-
prefix for state rules that are shared between CSS and JS.
Elements that occur exactly once inside a page should use IDs, otherwise, use classes. When in doubt, use a class name.
When styling a component, start with an element + class namespace (prefer class names over ids), prefer direct descendant selectors by default, and use as little specificity as possible. Here is a good example:
<ul class="category-list">
<li class="item">Category 1</li>
<li class="item">Category 2</li>
<li class="item">Category 3</li>
</ul>
.category-list { // element + class namespace
// Direct descendant selector > for list items
> li {
list-style-type: disc;
}
// Minimal specificity for all links
a {
color: #f00;
}
}
#selector
) make sure that you have no more than one in your rule declaration. A rule like #header .search #quicksearch { ... }
is considered harmful..listings-layout.bigger
use rules like .listings-layout.listings-bigger
. Think about ack/grep
ing your code in the future.disabled
, mousedown
, danger
, hover
, selected
, and active
should always be namespaced by a class (button.selected
is a good example).