Style Guide

Style Guide

This Style Guide serves as a very opinionated and intentional guide to how I develop websites, covering my approach to writing HTML, Sass, CSS and the likes.

Table of Contents

  1. HTML5
    1. Doctype
    2. Writing HTML Syntax
    3. Spacing
    4. URLs
  2. Sass
    1. Variables
    2. Functions
    3. Mixins
    4. Nesting
    5. Class Names
  3. CSS
    1. Writing CSS Syntax
    2. Properties and Values
    3. Browser Prefixes
    4. Selectors
    5. Pseudo-elements and Pseudo-classes
  4. Inspiration

HTML5

The use of HTML5 should strictly follow the HTML5 W3 Specifications. For browser support, use CanIUse.

Doctype

Enforce standards mode and more consistent rendering in every browser by declaring the HTML5 Doctype at the beginning of every HTML page.

1
<!DOCTYPE html>

Writing HTML Syntax

Spacing

Large sections of HTML should be separated by a one line break for readability.

1
2
3
4
5
6
7
8
9
10
11
<main>
<section>
...
</section>
<section>
...
</section>
</main>

URLs

Use relative URLs whenever possible; this will prevent problems if the base URL ever changes during a project’s lifespan.

1
<a href='/about'>About</a>

Sass

Sass is my preferred choice for CSS preprocessing, it allows the author to add variables, nesting, functions, and mixins to their stylesheets. This document uses Sass syntax.

Variables

Write global variables just as you would a CSS declaration, but optionally include one line break and comments between related variables for grouping and readability.

1
2
3
4
5
6
7
8
9
10
11
12
13
/* Colors */
$c--primary: #5B3C70;
$c--secondary: #E57B5D;
$c--primary-text: #0d0d0d;
/* Typography */
$font-stack: 'proxima-nova', Helvetica, sans-serif;
/* Base Styles */
$base-margin: 2rem;
$base-padding: 1rem;
$base-border: 0.25rem solid;
$base-border-radius: 0.125rem;

When writing local variables, include them as you would a CSS declaration, but always declare them before usage.

1
2
3
4
5
6
.example {
$base: 2em;
height: $base;
width: $base;
margin: $base/2;
}

It is a best practice to include your variables in a separate stylesheet (partial) titled _variables.scss and import that stylesheet into your main style.scss stylesheet where your Sass sources are being compiled.

When importing, do not include the .scss file extension or prepending underscore.

1
@import 'utilities/variables';

Functions

1
Documentation in progress.

Mixins

1
Documentation in progress.

Nesting

Avoid nesting too deeply Sass for the sake of it. Things can get pretty ugly, pretty quickly.

1
2
3
4
5
6
7
8
9
10
.content__list {
ul {
li {
a {
&:hover {
}
}
}
}
}

The result will not be good.

1
2
3
4
5
.content__list { ... }
.content__list ul { ... }
.content__list ul li { ... }
.content__list ul li a { ... }
.content__list ul li a:hover { ... }

Class Names

CSS

The use of CSS should strictly follow the CSS W3 Specifications for CSS properties and values. For browser support, use CanIUse.

Writing CSS Syntax

Properties and Values

Browser Prefixes

Figuring out which properties require browser prefixes is a hefty task, but CanIUse provides information about browser support and which properties require prefixes. I recommend using Autoprefixer if you are comfortable using a task runner.

Selectors

Pseudo-elements and Pseudo-classes

When grouping pseudo-elements and classes with other selectors, include after the element they affect.

1
2
3
a { ... }
a:hover { ... }
a:visited { ... }

Always declare the pseudo-elements :before first and :after following, but they should always come after element they affect. It is also best practice to include content property first.

1
2
3
4
5
h1 { ... }
h1:before { ... }
h1:after {
content: ' - See below';
}

When combining pseudo-classes, use two colons for the second class, i.e., h1:after::hover.

Inspiration

This document is inspired by my personal writing style, Code Guide by @mdo, Google’s Styleguide, and CSS Guidelines.