This is a work in progress…
For HTML, CSS (Sass) and JavaScript.
The purpose of this guide is to help you write readable, maintainable and scalable code. It is a living document which should reviewed on an ongoing basis.
Please open an issue on GitHub if you’d like to contribute.
- 1. General
- 2. Browsers
- 3. HTML
- 3.1 General
- 3.2 Terminology
- 3.3 Syntax
- 3.4 Document Type Definition (DTD)
- 3.5 Language
- 3.6 Character Encoding
- 3.7 Internet Explorer Compatibility Mode
- 3.8 Attribute Order
- 3.9 Boolean Attributes
- 3.10 Semantics
- 3.11 Using WAI-ARIA in HTML
- 3.12 Validation
- 4. CSS
- 4.1 General
- 4.2 Terminology
- 4.3 Syntax
- 4.4 Commenting
- 4.5 Naming Conventions
- 4.6 Declaration Order
- 4.7 Selectors
- 5. Sass
- 6. JavaScript
- 7. Linting
- 8. References
- 9. Inspiration & Credits
- There must always be a clear separation of concerns: structure, presentation and behavior
- Indentation must be 4 spaces (and not tabs)
- Make meaningful use of whitespace
- Consider a sensible maximum for line-length e.g. 80 character wide columns
- Remove any trailing whitespace from the end of each line
- EditorConfig can help maintain the basic whitespace conventions
- When in doubt use existing, common patterns or refer to other guidelines
Through the practice of progressive enhancement and graceful degradation a website should render in any web browser. But the experience for each visitor will differ based on the features supported in the version of the browser in use.
- Chrome
- Firefox
- Internet Explorer 9+
- Microsoft Edge
- Opera
- Safari
Do websites need to look exactly the same in every browser?
No. Although your HTML should render without CSS or JavaScript – the content must be accessible and form submissions must work.
The basic structure of an HTML document:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>Hello, World!</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="apple-touch-icon" href="apple-touch-icon.png">
<link rel="stylesheet" href="main.css">
</head>
<body>
<header role="banner">
</header>
<main role="main">
</main>
<footer role="contentinfo">
</footer>
<script src="main.js"></script>
</body>
</html>Elements typically consist of a start and end tag, attributes and contents. The contents of an element are determined by it’s content model. Attributes and their values are not considered to be part of the contents of an element.
Example of an element: <p>This is the content of a paragraph element.</p>
A void element is an element whose content model never allows it to have contents under any circumstances. Void elements can have attributes. – W3C
Examples of void elements in HTML: <hr>, <img>, <input>, <link>, <meta>
Tags are used to mark the start and end of HTML elements. Optionally, tags can have attributes.
Example of a start tag: <p>
Example of an end tag: </p>
Attributes have a name and value and are specified in the element’s start tag.
Example of an element’s attributes: <img src="" alt="">
- HTML tag names and attribute values must be in lowercase
- Use double quotes (
"") around attribute values - Omit the
typeattribute when including style sheets and scripts - Use a new line for every block-level element
Include the HTML5 doctype:
<!doctype html>Including the doctype in a document ensures that the browser makes a best-effort attempt at following the relevant specifications. – W3C
Specify the language code for your HTML document:
<html lang="en">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. – W3C
Define the HTML document’s character set as utf-8:
<meta charset="utf-8">Unicode is a universal character set, ie. a standard that defines, in one place, all the characters needed for writing the majority of living languages in use on computers. It aims to be, and to a large extent already is, a superset of all other character sets that have been encoded. – W3C
Ensure that IE uses the latest engine:
<meta http-equiv="x-ua-compatible" content="ie=edge">The idea behind compatibility mode is to allow web sites and applications that are not designed to modern standards to continue to work while upgrades can be made, allowing end users to upgrade to the latest browser version. Designating 'IE=edge' is the best practice because it ensures Internet Explorer uses the latest engine. The most current Internet Explorer version includes the latest security updates as well as feature support. The current version is also the fastest version. – modern.IE
In order to improve the general readability of code, it is recommended to place tag attributes in the following order:
classtypeid,nameplaceholder,value,maxlength, 'checked,selected,disabled,required`for,href,src,srcsetaction,method,href,targetwidth,heighttitle,altdata-*aria-*,role
This is an example of the recommended attribute order for an image:
<img src="…" width="…" height="…" title="…" alt="…">This is an example of the recommended attribute order for a form control:
<input class="…" type="…" name="…" required>This is an example of the recommended attribute order for an anchor:
<a class="…" href="…" target="…" title="…" data-attribute="…">This is an example of the recommended attribute order for a div:
<div class="…" id="…" aria-controls="…" role="…">The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value. – WHATWG
In HTML5, the following variations for setting a boolean attribute to true are valid:
autofocus
autofocus=""
autofocus="autofocus"
However, the preference is to not add a value. For example:
<input type="text" autofocus>
Use the appropriate element when marking up your content to give it meaning on a web page. Semantic code describes the value of the content on a page, independent of it’s style.
<!-- ✗ -->
<div class="button">Submit</div>
<!-- ✓ -->
<button>Submit</button>
Have a look at the HTML5 Sectioning Element Flowchart if you get stuck.
Avoid adding superflous parent elements when writing HTML – reduce markup wherever possible.
<!-- ✗ -->
<span class="logo">
<img src="…">
</span>
<!-- ✓ -->
<img class="logo" src="…">
The main goal of the ARIA specification is to improve the overall accessibility of websites.
WAI-ARIA, the Accessible Rich Internet Applications Suite, defines a way to make Web content and Web applications more accessible to people with disabilities. It especially helps with dynamic content and advanced user interface controls developed with Ajax, HTML, JavaScript, and related technologies. – WAI-ARIA Overview
As per the W3C draft, using WAI-ARIA in HTML, rather use native HTML elements wherever possible as it will have the semantics and required behaviour built-in.
Use tools like the W3C Markup Validation Service or the Nu Markup Checker to validate your markup.
Reasons for validating:
- Useful as a debugging tool (modern browsers do a good job of fixing “tag soup”)
- Helps to future-proof your code by adhering to Web Standards
- Improves maintainability over time by agreeing to a global code style
- Teaches best practices to newcomers and raises awareness of accessbility
Continue reading about why you should validate.
Every time you write inline styles in your markup, a front-end developer somewhere dies – whether it’s in a style tag or directly in the markup. Don’t do it. – TMWtech
This guide assumes that Sass will be used as the preprocessor to compile your CSS. The majority of the rules in this guide also apply to vanilla CSS, unless otherwise stated.
The features in Sass that we use are:
- Variables
- Nesting
- Partials
- Mixins
A rule set (also called “rule”) consists of a selector followed by a declaration block:
[selector] {
[property]: [value];
}
A selector is a chain of one or more sequences of simple selectors separated by combinators. One pseudo-element may be appended to the last sequence of simple selectors in a selector. – W3C
For example:
.foo {
background-color: red;
color: white;
}
A simple selector is either a type selector, universal selector, attribute selector, class selector, ID selector, or pseudo-class. – W3C
h1 {
}
* {
}
a[rel="external"] {
}
.hero {
}
#top {
}
button:focus {
}
Combinators are: whitespace, "greater-than sign" (U+003E, >), "plus sign" (U+002B, +) and "tilde" (U+007E, ~). – W3C
For example:
nav a {
}
ul > li {
}
p + h2 {
}
div ~ hr {
}