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:
Table of Contents
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 classdata-*-
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.
// 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
// 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.
// 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.
// 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
Heavily inspired by @mdo's Code Guide. Made with <3 in Chicago.
Open Source under MIT. Copyright 2015 Joe Mainwaring.
Top comments (0)