DEV Community

Cover image for A Style Guide For HTML & CSS
Joe Mainwaring
Joe Mainwaring

Posted on

A Style Guide For HTML & CSS

#css #html #tutorial #beginners

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

  1. Preface
  2. Project
    1. Naming Convention
    2. Organization
  3. HTML
    1. Syntax
    2. HTML5 Doctype
    3. Character Encoding
    4. Including Stylesheets
    5. Attributes
    6. Naming
    7. Order
    8. Reducing Markup
  4. CSS
    1. Syntax
    2. Selectors
    3. Declarations
    4. Single Declarations
    5. Multiple Declarations
    6. Order
    7. Organization
  5. References

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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

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

<!-- Correct -->
<div class="double-quote"></div>
Enter fullscreen mode Exit fullscreen mode

Include a trailing slash in self-closing elements

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

<!-- Correct -->
<img src="foo.jpg" class="bar" />
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Attributes

Naming

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

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

<!-- Correct -->
<section id="fooBar">...</section>
Enter fullscreen mode Exit fullscreen mode

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" />
Enter fullscreen mode Exit fullscreen mode

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" />
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

CSS

Syntax

Include one space before the opening brace of declaration blocks for readability.

// Incorrect
.foo{display: block;}

// Correct
.foo {display: block;}
Enter fullscreen mode Exit fullscreen mode

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;}
Enter fullscreen mode Exit fullscreen mode

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;}
Enter fullscreen mode Exit fullscreen mode

Avoid specifying units for zero values

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

// Better
.foo {margin: 0;}
Enter fullscreen mode Exit fullscreen mode

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;}
Enter fullscreen mode Exit fullscreen mode

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;}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

Credits and License

Heavily inspired by @mdo's Code Guide. Made with <3 in Chicago.

Open Source under MIT. Copyright 2015 Joe Mainwaring.

References

Top comments (0)

Read next

martygo profile image

🛑 Stop Create Hooks in React 🪝🎣

Martins Gouveia -

mahmud-r-farhan profile image

Typing App (docx)

Mahmud R. Farhan -

ianbrumby profile image

Finally got some time to play with the new JSONata and Variables support for Step Functions, and I have to say, it is massive improvement. Check out my latest blog post, where I walk through a simple example of how easy it is to handle pagination now

Ian -

kittipat1413 profile image

Configuration Management in Go with Viper

Kittipat.po -