A Style Guide For HTML & CSS

Back in the mid 2010s I was an Instructor for the Startup Institute, a bootcamp program that offered several different tracts to help individuals get entry-level jobs at startups. I wrote this style guide to help my students learn HTML and CSS:

Preface

This style guide is intended for students enrolled in Startup Institute's RampUp Web Design class, but is useful for anyone learning HTML & CSS. This document outlines guidelines, best practices, and common approaches to writing clean maintainable HTML & CSS files.

Project

Naming Convention

Names for your project, files, and folders should be short, lowercase, and use dashes instead of spaces. This improves readability both in and outside of your code.

\\ Incorrect
My Really Awesome Project
Facebook Profile Picture.jpg

\\ Not Ideal
my-really-awesome-project
facebook-profile-picture.jpg

\\ Ideal
my-project
avatar.jpg

Organization

Keep your files organized by their type. Files should be kept in the following folders:

Path

Types of Files

File Types

my-project/

HTML Documents

.html

my-project/css

Stylesheets

.css

my-project/fonts

Web Fonts

.wotff

my-project/img

Images

.jpg .gif .png .svg

my-project/js

Scripts

.js

HTML

Syntax

Nested (child) elements should start on a new line and be indented within the parent element.

<!-- Incorrect -->
<div><p>Foo</p></div>

<!-- Incorrect -->
<div>
<p>Foo</p>
</div>

<!-- Correct -->
<div>
    <p>Foo</p>
</div>

Always use double quotes, never single quotes, on attributes.

<!-- Incorrect -->
<div class='single-quote'></div>

<!-- Correct -->
<div class="double-quote"></div>

Include a trailing slash in self-closing elements

<!-- Incorrect -->
<img src="foo.jpg" class="bar" >

<!-- Correct -->
<img src="foo.jpg" class="bar" />

Don’t omit optional closing tags

<!-- Incorrect -->
<ul>
    <li>Foo
    <li>Bar
    <li>Baz
</ul>

<!-- Correct -->
<ul>
    <li>Foo</li>
    <li>Bar</li>
    <li>Baz</li>
</ul>

HTML5 doctype

Every html document should start with the DOCTYPE tag.

<!-- Incorrect -->
<html>
    <head>...</head>
    <body>...</body>
<html>

<!-- Correct -->
<!DOCTYPE html>
<html>
    <head>...</head>
    <body>...</body>
<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 (UTF-8).

<head>
  <meta charset="UTF-8">
</head>

Including Stylesheets

Stylesheets are nested in the <head> section of your HTML document.

<!-- Incorrect -->
<!DOCTYPE html>
<html>
    <head>...</head>
    <body>
        <link rel="stylesheet" href="css/style.css">
    </body>
<html>

<!-- Correct -->
<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" href="css/style.css">
    </head>
    <body>...</body>
<html>

Attributes

Naming

For unique attributes like id & name should follow the camelCasing convention.

<!-- Incorrect -->
<section id="foo-bar">...</section>

<!-- Correct -->
<section id="fooBar">...</section>

Class names should be formatted using kabab-case.

<!-- Incorrect -->
<img class="fooBar" src="img/baz.jpg" />

<!-- Incorrect -->
<img class="foo_bar" src="img/baz.jpg" />

<!-- Correct -->
<img class="foo-bar" src="img/baz.jpg" />

Order

HTML attributes should come in this particular order for easier reading of code: - `id`, `name` - `class` - `data-*` - `src`, `for`, `type`, `href`, `value` - `title`, `alt` - `role`, `aria-*`

Attributes which uniquely identify an element (id, name) should come first for ease of readability, followed by classes, which are typically the most common attribute found across all elements in an HTML document.

<!-- Incorrect -->
<img src="img/foo.jpg" id="foo" class="bar baz" />

<!-- Correct -->
<img id="foo" class="bar baz" src="img/foo.jpg" />

Reducing Markup

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

<!-- Not so great -->
<section>
    <div class="row">
        <div class="col-left category">...</div>
        <div class="col-right category">...</div>
    </div>
    <div class="row">
        <div class="col-left category">...</div>
        <div class="col-right category">...</div>
    </div>
</section>

<!-- Better -->
<section>
    <div class="row">
        <div class="col-left category">...</div>
        <div class="col-right category">...</div>
        <div class="col-left category">...</div>
        <div class="col-right category">...</div>
    </div>
</section>

CSS

Syntax

Include one space before the opening brace of declaration blocks for readability. ```css // Incorrect .foo{display: block;}

// Correct .foo {display: block;}


For each declaration within a declaration block:
- Include one space after `:` for each declaration
- Do not include one space before `:` for each declaration
- End all declarations with a semi-colon
```css
// Incorrect
.foo {display:block;}

// Incorrect
.foo {display : block;}

// Incorrect
.foo {display: block}

// Correct
.foo {display: block;}

Declarations with multiple property values should include a space after each comma

// Incorrect
.foo {box-shadow: 0 1px 2px #ccc,inset 0 1px 0 #fff;}

// Correct
.foo {box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;}

Avoid specifying units for zero values

// Overkill
.foo {margin: 0px;}

// Better
.foo {margin: 0;}

Selectors

Keep selectors short and strive to limit the number of elements in each selector to three.

// Incorrect
section ul.nav li a {text-decoration: none;}

// Correct
ul.nav a {text-decoration: none;}

Declarations

Single Declarations

Selectors with a single declaration can be kept on a single line.

// Less ideal
.foo {
    margin: 0px;
}

// More ideal
.foo {margin: 0;}

Multiple Declarations

For selectors with multiple declarations:

Each declaration should appear on its own line
Declarations are nested within the selector block
Place closing braces of declaration blocks on a new line

// Incorrect
.foo {display: block; position: relative;}

// Incorrect
.foo {
display: block;
position: relative;
}

// Incorrect
.foo {
    display: block;
    position: relative;}

// Correct
.foo {
    display: block;
    position: relative;
}

Order

Declarations should be arranged alphabetically within selectors since in-browser developer tools will list declarations this way. ```css // Incorrect .foo { position: relative; top: 0; left: 12px; display: block; }

// Correct .foo { display: block; left: 0; position: relative; top: 0; }


### Organization
Organize sections of code by component.
```css
// Incorrect
header {
    background-color: #034f80;
    display: block;
}

footer {
    background-color: #000000;
}

header nav ul {list-style: none;}

// Correct
header {
    background-color: #034f80;
    display: block;
}

header nav ul {list-style: none;}

footer {
    background-color: #000000;
}

Credits and License

References

Code Guide by @mdo

Last updated 2 years ago

Table of Contents

Preface

Project

Naming Convention

Organization

HTML

Syntax

HTML5 doctype

Character Encoding

Including Stylesheets

Attributes

Naming

Order

Reducing Markup

CSS

Syntax

Selectors

Declarations

Single Declarations

Multiple Declarations

Order

Credits and License

References