HTML & CSS Guide

TODO eventually extend this guide to RDSanize it...but for now...

RDS developers and implementers should follow the standards for developing consistent, flexible, and sustainable HTML and CSS at https://codeguide.co.

Below are a few rules taken from the guide. If you are working with RDS, you are encouraged to read and follow the complete guide when adding HTML and CSS to RDS projects.

HTML

Syntax

Don't capitalize tags, including the doctype.
Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment.
Nested elements should be indented once (two spaces).
Always use double quotes, never single quotes, on attributes.
Don't include a trailing slash in self-closing elements—the HTML5 spec says they're optional.
Don’t omit optional closing tags (e.g. </li> or </body>).

<!doctype html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

Attribute order

HTML attributes should come in this particular order for easier reading of code.

class
id, name
data-*
src, for, type, href, value
title, alt
role, aria-*

Classes make for great reusable components, so they come first. Ids are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come second.

Reducing markup

Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example:

<!-- Not cool -->
<span class="avatar">
  <img src="...">
</span>

<!-- 🏍 Cool like Fonzie -->
<img class="avatar" src="...">

CSS

Syntax

Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment.
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. The last declaration's is optional, but your code is more error prone without it.
Comma-separated property values should include a space after each comma (e.g., box-shadow).
Don't include spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values. This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).
Don't prefix property values or color parameters with a leading zero (e.g., .5 instead of 0.5 and -.5px instead of -0.5px).
Lowercase all hex values, e.g., #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, e.g., #fff instead of #ffffff.
Quote attribute values in selectors, e.g., input[type="text"]. They’re only optional in some cases, and it’s a good practice for consistency.
Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.

/* Not cool 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 #FFFFFF
}

/*  🏍 Cool CSS, like Fonzie */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Declaration order

Related property declarations should be grouped together following the order:

Positioning
Box model
Typographic
Visual
Misc

Positioning comes first because it can remove an element from the normal flow of the document and override box model related styles. The box model comes next as it dictates a component's dimensions and placement.

Everything else takes place inside the component or without impacting the previous two sections, and thus they come last.

TODO set up RDS Stylelint

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

Nesting in Sass

Avoid unnecessary nesting. Just because you can nest, doesn't mean you always should. Consider nesting only if you must scope styles to a parent and if there are multiple elements to be nested.

// Without nesting
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// With nesting
.table > thead > tr {
  > th { … }
  > td { … }
}

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.