HTML5+CSS3 coding standards

The Golden Rule

No matter how many people are working on a project, it's important to make sure every line of code looks like it was written by the same person.

grammar

1. Use two spaces instead of tabs – this is the only way to ensure consistent display in all environments.
2. Nested elements should be indented once (i.e. two spaces).
3. For attribute definitions, make sure to use double quotes throughout and never use single quotes.
4. Don’t add a trailing slash to self-closing elements – the HTML5 specification explicitly states that this is optional.
5. Don’t omit the optional closing tag

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Adding a standards mode declaration to the first line of every HTML page ensures consistent display in every browser.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Language attributes

According to the HTML5 specification:
It is strongly recommended to specify the lang attribute on the root html element to set the correct language for the document. This will help speech synthesis tools determine the pronunciation they should use, help translation tools determine the rules they should follow when translating, and so on.

<html lang="en-us">
  <!-- ... -->
</html>

IE compatibility mode

IE supports using specific tags to determine the IE version that should be used to draw the current page. Unless there is a strong special need, it is best to set it to edge mode to inform IE to use the latest mode it supports.

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Character encoding

By explicitly declaring the character encoding, you ensure that the browser can quickly and easily determine how to render the page content. The advantage of doing this is that you can avoid using character entity tags in HTML, so that everything is consistent with the document encoding (usually UTF-8 encoding).

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

Import CSS and JavaScript files

According to the HTML5 specification, you generally do not need to specify the type attribute when importing CSS and JavaScript files, because text/css and text/javascript are their default values, respectively.

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Practicality is king

Try to follow HTML standards and semantics, but not at the expense of practicality. Always try to use the fewest number of tags and keep complexity to a minimum.

Attribute Order

HTML attributes should be arranged in the order given below to ensure the readability of the code.

class
id, name
data-*
src, for, type, href, value
title, alt
role, aria-*

Class is used to identify highly reusable components, so it should come first. id is used to identify a specific component and should be used with caution (for example, a bookmark within a page), so it comes second.

Boolean properties

Boolean properties can be declared without a value. The XHTML specification requires it to be assigned a value, but the HTML5 specification does not.
For more information see the WhatWG section on boolean attributes:
A Boolean attribute of an element is true if it has a value, and false if it does not.
If you must assign a value to it, please refer to the WhatWG specification:
If the attribute is present, its value must be either the empty string or [...] the canonical name of the attribute, with no leading or trailing whitespace.
Simply put, there is no need to assign a value.

Reduce the number of tags

When writing HTML code, try to avoid redundant parent elements. Often times this requires iteration and refactoring to achieve. Please see the following example:

Not so great
<span class="avatar">
  <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

JavaScript generated tags

Tags generated via JavaScript make content harder to find, edit, and slow down performance. Avoid when you can.

CSS Syntax

1. Use two spaces instead of tabs – this is the only way to ensure consistent display in all environments.
2. When grouping selectors, place each selector on its own line.
3. For code readability, add a space before the opening curly brace of each declaration block.
4. The closing curly brace of a declaration block should be on a separate line.
5. A space should be inserted after each declaration statement:
6. For more accurate error reporting, each statement should appear on its own line.
7. All declaration statements should end with a semicolon. The semicolon after the last declaration is optional, but your code may be more error-prone if you omit it.
8. For property values separated by commas, a space should be inserted after each comma (for example, box-shadow).
9. Do not insert spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values. This helps distinguish multiple color values (with commas, no spaces) from multiple attribute values (with both commas and spaces).
10. For attribute values or color parameters, omit the leading zero for decimals less than 1 (for example, .5 instead of 0.5; -.5px instead of -0.5px).
11/Hexadecimal values should be all lowercase, for example, #fff. When scanning documents, lowercase characters are easier to distinguish because their forms are more easily distinguished.
12. Try to use abbreviated hexadecimal values, for example, #fff instead of #ffffff.
13. Add double quotes to attributes in selectors, for example, input[type="text"]. It is optional only in certain cases, however, for consistency in your code it is recommended to always use double quotes.
14. Avoid specifying units for zero values, for example, use margin: 0; instead of margin: 0px;.

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Declaration Order

Related property declarations should be grouped together and arranged in the following order:

Positioning
Box model
Typographic
Visual

Positioning comes first because it removes elements from the normal document flow and can also override box model related styles. The box model comes second, as it determines the size and position of components.
The other properties only affect the inside of the component or do not affect the first two groups of properties, so they are placed at the end.

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

Don't use @import

Compared to tags, the @import directive is much slower, not only increasing the number of additional requests, but also causing unpredictable problems. There are several alternatives:

Using multiple elements

Compile multiple CSS files into one file using a CSS preprocessor like Sass or Less. Use Rails, Jekyll, or other systems that provide CSS file merging capabilities.

<!-- Use link elements -->
<link rel="stylesheet" href="core.css">

<!-- Avoid @imports -->
<style>
  @import url("more.css");
</style>

Media query location

Place media queries as close to related rules as possible. Do not bundle them into a single style sheet or put them at the bottom of the document. If you separate them, they will be forgotten in the future. A typical example is given below.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Single-line rule declaration

For styles that contain only one declaration, it is recommended to place the statement on a single line for readability and quick editing. For styles with multiple declarations, the declarations should still be split across multiple lines.

The key reason for this is error detection – for example, the CSS validator points out a syntax error on line 183. If it is a single statement on a single line, you will not ignore the error; if it is multiple statements on a single line, you have to analyze it carefully to avoid missing the error.

/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon { background-position: 0 0; }
.icon-home { background-position: 0 -20px; }
.icon-account { background-position: 0 -40px; }

Shorthand property declaration

In situations where you need to explicitly set all values, you should limit the use of shorthand property declarations to a minimum. Common abuses of shorthand property declarations include:

padding
margin
font
background
border
border-radius

In most cases, we do not need to specify all values for the shorthand property declaration. For example, the HTML heading element only needs to set the top and bottom margin values, so when necessary, just override these two values. Overuse of shorthand property declarations can lead to cluttered code and cause unexpected side effects by overwriting property values unnecessarily.

/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Nesting in Less and Sass

Avoid unnecessary nesting. This is because just because you can nest, doesn't mean you should. Only use nesting when you must restrict styles to the parent element (aka a descendant selector) and when there are multiple elements that need to be nested.

// Without nesting
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// With nesting
.table > thead > tr {
  > th { … }
  > td { … }
}

Operators in Less and Sass

To improve readability, add a space between values, variables, and operators in mathematical expressions enclosed in parentheses.

// Bad example
.element {
  margin: 10px 0 @variable*2 10px;
}

// Good example
.element {
  margin: 10px 0 (@variable * 2) 10px;
}

Notes

Code is written and maintained by people. Make sure your code is self-describing, well-commented, and easy for others to understand. Good code comments convey the context and purpose of the code. Do not simply reiterate component or class names.

For longer comments, be sure to write complete sentences; for general notes, concise phrases are fine.

/* Bad example */
/* Modal header */
.modal-header {
  ...
}

/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Class naming

1. Only lowercase characters and dashes can appear in class names (not underscores or camelCase). Dashes should be used to name related classes (similar to namespaces) (for example, .btn and .btn-danger).
2. Avoid overly arbitrary abbreviations. .btn stands for button, but .s doesn't mean anything.
3. Class names should be as short as possible and have clear meanings.
4. Use meaningful names. Use organizational or purposeful names rather than presentational names.
5. Use the nearest parent class or base class as a prefix for the new class.
6. Use .js-* classes to identify behavior (as opposed to style) and do not include these classes in your CSS files.

/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selector

Use class for common elements, which helps optimize rendering performance.
Avoid using attribute selectors (e.g., [class^="..."]) for frequently occurring components. The performance of your browser will be affected by these factors.
The selector should be as short as possible, and the number of elements that make up the selector should be limited to no more than 3.
Only restrict a class to the nearest parent (ie a descendant selector) when necessary (ie when not using a class with a prefix – a prefix is like a namespace).

/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Editor Configuration

Set up your editor to the following configuration to avoid common code inconsistencies and differences:

Use two spaces instead of tab characters (soft-tab means using spaces instead of tab characters).
When saving the file, remove trailing whitespace.
Set the file encoding to UTF-8.
Add a blank line to the end of the file.

Follow the documentation and add these configuration information to your project's .editorconfig file. For example: Bootstrap's .editorconfig example. For more information, see about EditorConfig.

For better and more comfortable reading, please check this article https://www.jb51.net/shouce/codeguide/.

<<: Example of how to implement a 2-column layout in HTML (fixed width on the left, adaptive width on the right)

>>: Several ways to center a box in Web development