Approach

Learn about the guiding principles, strategies, and techniques used to build and maintain Grayshift so you can more easily customize and extend it yourself.

Golden rule

Every line of code should appear to be written by a single person, no matter the number of contributors.

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 HTML 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="..." alt="...">
  </body>
</html>

HTML5 Doctype

Enforce standards mode and more consistent rendering in every browser possible with this simple doctype at the beginning of every HTML page.

<!doctype html>

Language attribute

From the HTML spec:

Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.

Read more about the lang attribute in the spec. Head to Sitepoint for a list of language codes.

<html lang="en"></html>

Character encoding

Quickly and easily ensure proper rendering of your content by declaring an explicit character encoding. When doing so, you may avoid using character entities in your HTML, provided their encoding matches that of the document (generally utf-8).

<meta charset="utf-8">

CSS and JavaScript includes

Per HTML5 spec, typically there is no need to specify a type when including CSS and JavaScript files as text/css and text/javascript are their respective defaults.

<!-- External CSS -->
<link rel="stylesheet" href="#">

<!-- JavaScript -->
<script src="..."></script>

Practicality over purity

Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.

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.

<a class="..." id="..." data-toggle="..." href="#">Example link</a>
<input class="..." type="text">
<img src="..." alt="...">

Boolean attributes

A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement.

For further reading, consult the WhatWG section on boolean attributes:

The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.

If you must include the attribute's value, and you don't need to, follow this WhatWG guideline:

If the attribute is present, its value must either be the empty string or [...] the attribute's canonical name, with no leading or trailing whitespace.

In short, don't add a value.

<input type="text" disabled>
<input type="checkbox" value="1" checked>
<select>
  <option value="1" selected>One</option>
</select>

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 so great -->
<span class="...">
  <img src="..." alt="...">
</span>

<!-- Better -->
<img class="..." src="..." alt="...">

JavaScript generated markup

Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible.

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 prefix property values or color parameters with a leading zero (e.g., .8 instead of 0.8 and -.8px instead of -0.8px).
  • 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

Questions on the terms used here? See the syntax section of the Cascading Style Sheets article on Wikipedia.

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:1rem;
  margin:0rem 0rem 1rem
  box-shadow:0rem 1rem 2rem #CCC,inset 0 1rem 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 1rem;
  margin-bottom: 1rem;
  box-shadow: 0 1rem 2rem #ccc, inset 0 1rem 0 #fff;
}

Declaration order

Related property declarations should be grouped together following the order:

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual
  5. 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.

For a complete list of properties and their order, please see the Bootstrap property order for Stylelint.

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

  /* Box-model */
  float: right;
  width: 100%;
  height: 100%;

  /* Typography */
  font: 500 1rem/1.5 "Inter", sans-serif;
  color: var(--body-color);
  text-align: center;

  /* Visual */
  background-color: var(--card-bg);
  border: 2px solid var(--fill-bg);
  border-radius: .5rem;

  /* Misc */
  opacity: 1;
}

Don't use @import

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead Use multiple <link> elements.

For more information, read this article by Steve Souders.

<!-- Use link elements -->
<link rel="stylesheet" href="#">

<!-- Avoid @imports -->
<style>
  @import url("...");
</style>

Media query placement

Place media queries as close to their relevant rule sets whenever possible. Don't 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: 576px) {
  .element {}
  .element-avatar {}
  .element-selected {}
}

Shorthand notation

Limit shorthand declaration usage to instances where you must explicitly set all available values. Frequently overused shorthand properties include:

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

Usually we don't 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. A `0` value implies an override of either a browser default or previously specified value.

Excessive use of shorthand properties leads to sloppier code with unnecessary overrides and unintended side effects.

The Mozilla Developer Network has a great article on shorthand properties for those unfamiliar with notation and behavior.

/* Bad example */
.element {
  margin: 0 0 1rem;;
  background: red;
  background: url("...");
  border-radius: .5rem .5rem 0 0;
}

/* Good example */
.element {
  margin-bottom: 1rem;
  background-color: red;
  background-image: url("...");
  border-top-left-radius: .5rem;
  border-top-right-radius: .5rem;
}

Class names

  • Keep classes lowercase and use dashes (not underscores or camelCase). Dashes serve as natural breaks in related class (e.g., .btn and .btn-primary).
  • Avoid excessive and arbitrary shorthand notation. .btn is useful for button, but .b doesn't mean anything.
  • Keep classes as short and succinct as possible.
  • Use meaningful names; use structural or purposeful names over presentational.
  • Prefix classes based on the closest parent or base class.
  • Use .js-* classes to denote behavior (as opposed to style), but keep these classes out of your CSS.
/* Bad example */
.b {}
.primary {}

/* Good example */
.btn {}
.btn-primary {}

Selectors

  • Use classes over generic element tag for optimum rendering performance.
  • Avoid using several attribute selectors (e.g., [class^="..."]) on commonly occuring components. Browser performance is known to be impacted by these
  • Keep selectors short and strive to limit the number of elements in each selector to three.
  • Scope classes to the closest parent only when necessary (e.g., when not using prefixed classes).
/* Bad example */
button {}
.element .element .element .element .element .element {}

/* Good example */
.btn {}
.element .element {}

Organization

  • Organize sections of code by component.
  • 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.