On this page…
Much of this document is taken from the Google HTML/CSS Style Guide, which is available under a Creative Commons Attribution 3.0 Unported (CC BY 3.0) license. Many alterations, however, have been made.
Background
This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. It applies to raw, working files that use HTML and CSS, including GSS files. Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained.
General Formatting Rules
Indentation
Indent by 2 spaces at a time.
Don’t use tabs or mix tabs and spaces for indentation.
<ul>
<li>Fantastic
<li>Great
</ul>
.example {
color: blue;
}
Capitalization
Use only lowercase.
All code has to be lowercase: this applies to element names, attributes, attribute values (unless text/CDATA), selectors, properties, & property values (with the exception of strings).
<!-- Not recommended -->
<A HREF="/">Home</A>
<!-- Recommended -->
<img src="google.png" alt="Google">
Trailing whitespace
Remove trailing white spaces.
Trailing white spaces are unnecessary and can complicate diffs.
<!-- Not recommended -->
<p>What?[space]</p>
<!-- Recommended -->
<p>What?</p>
General Meta Rules
Encoding
Use UTF-8 (no BOM).
Make sure your editor uses UTF-8 as character encoding, without a byte order mark.
Specify the encoding in HTML templates and documents via <meta charset="utf-8">.
Do not specify the encoding of style sheets as these assume UTF-8.
(More on encodings and when and how to specify them can be found in Everything You Need to Know About Character Encoding.)
Comments
Explain code as needed, where possible.
Use comments to explain code: what does it cover, what purpose does it serve, why is respective solution used or preferred?
(This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)
HTML Style Rules
Document type
Use HTML5.
HTML5 (HTML syntax) is preferred for all HTML documents: <!DOCTYPE html>.
ADVANCED: (It is recommended to use HTML, as
text/html. Do not use XHTML. XHTML, asapplication/xhtml+xml, lacks both browser and infrastructure support and offers less room for optimization than HTML.)
HTML validity
Use valid HTML where possible.
Use tools such as the W3C HTML validator to test.
Using valid HTML is a measurable baseline quality attribute that contributes to learning about technical requirements and constraints, and that ensures proper HTML usage.
<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.
<!-- Recommended -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
Semantics
Use HTML according to its purpose.
Use elements (sometimes incorrectly called “tags”) for what they have been created for. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc.
Using HTML according to its purpose is important for accessibility, reuse, and code efficiency reasons.
<!-- Not recommended -->
<p><strong>All recommendations</strong></p>
<!-- Recommended -->
<h3>All recommendations</h3>
<!-- Not recommended -->
Some text
<br>
<br>
Some more text
<!-- Recommended -->
<p>Some text</p>
Multimedia fallback
Provide alternative contents for multimedia.
For multimedia, such as images, videos, animated objects via canvas, make sure to offer alternative access. For images that means use of meaningful alternative text (alt) and for video and audio transcripts and captions, if available.
Providing alternative contents is important for accessibility reasons: a blind user has few cues to tell what an image is about without alt, and other users may have no way of understanding what video or audio contents are about either.
(For images whose alt attributes would introduce redundancy, and for images whose purpose is purely decorative which you cannot immediately use CSS for, use no alternative text, as in alt="".)
<!-- Not recommended -->
<img src="spreadsheet.png">
<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot">
Character entities
Do not use character entities, with 3 exceptions.
There is no need to use entity references like —, ”, or ☺, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like non-breaking spaces). Those should be displayed with character entities.
<!-- Not recommended -->
The currency symbol for the Euro is `“&eur;”`.
<!-- Recommended -->
The currency symbol for the Euro is “€”.
type attributes
Omit type attributes for style sheets and scripts.
Do not use type attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
Specifying type attributes in these contexts is not necessary as HTML5 implies text/css and text/javascript as defaults. This can be safely done even for older browsers.
<!-- Not recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css" type="text/css">
<!-- Recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">
<!-- Not recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
HTML Formatting Rules
General formatting
Use a new line for every block, list, or table element, and indent every such child element.
Independent of the styling of an element (as CSS allows elements to assume a different role per display property), put every block, list, or table element on a new line.
Also, indent them if they are child elements of a block, list, or table element.
(If you run into issues around whitespace between list items it is acceptable to put all li elements in one line.)
<blockquote>
<p>
<em>Space</em>, the final frontier.
</p>
</blockquote>
<ul>
<li>Moe</li>
<li>Larry</li>
<li>Curly</li>
</ul>
<table>
<thead>
<tr>
<th scope="col">Income</th>
<th scope="col">Taxes</th>
</tr>
</thead>
<tbody>
<tr>
<td>$ 5.00</td>
<td>$ 4.50</td>
</tr>
</tbody>
</table>
CSS Style Rules
CSS validity
Use valid CSS where possible.
Unless dealing with CSS validator bugs or requiring proprietary syntax, use valid CSS code.
Use tools such as the W3C CSS validator to test.
Using valid CSS is a measurable baseline quality attribute that makes it easier to spot CSS code that may not have any effect and can be removed, and that ensures proper CSS usage.
ID and class naming
Use meaningful or generic ID and class names.
Instead of presentational or cryptic names, always use ID and class names that reflect the purpose of the element in question, or that are otherwise generic.
Names that are specific and reflect the purpose of the element should be preferred as these are most understandable and the least likely to change.
Generic names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are typically needed as “helpers.”
Using functional or generic names reduces the probability of unnecessary document or template changes.
/* Not recommended: meaningless */
#yee-1901 {}
/* Not recommended: presentational */
.button-green {}
.clear {}
/* Recommended: specific */
#gallery {}
#login {}
.video {}
/* Recommended: generic */
.aux {}
.alt {}
ID and class name style
Use ID and class names that are as short as possible but as long as necessary.
Try to convey what an ID or class is about while being as brief as possible.
Using ID and class names this way contributes to acceptable levels of understandability and code efficiency.
/* Not recommended */
#navigation {}
.atr {}
/* Recommended */
#nav {}
.author {}
Type selectors
Avoid qualifying ID and class names with type selectors.
Unless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes.
Avoiding unnecessary ancestor selectors is useful for performance reasons.
/* Not recommended */
ul#example {}
div.error {}
/* Recommended */
#example {}
.error {}
Shorthand properties
Use shorthand properties where possible.
CSS offers a variety of shorthand properties (like font) that should be used whenever possible, even in cases where only one value is explicitly set.
Using shorthand properties is useful for code efficiency and understandability.
/* Not recommended */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
0 and units
Omit unit specification after “0” values.
Do not use units after 0 values unless they are required.
margin: 0;
padding: 0;
Leading 0s
Omit leading “0”s in values.
Do not use put 0s in front of values or lengths between -1 and 1.
font-size: .8em;
Quotation marks in URI values
Omit quotation marks in URI values.
Do not use quotation marks ("", '') with url().
@import url(//www.google.com/css/go.css);
Hexadecimal notation
Use 3 character hexadecimal notation where possible.
For color values that permit it, 3 character hexadecimal notation is shorter and more succinct.
/* Not recommended */
color: #eebbcc;
/* Recommended */
color: #ebc;
ID and class name delimiters
Separate words in ID and class names by a hyphen.
Do not concatenate words and abbreviations in selectors by any characters (including none at all) other than hyphens, in order to improve understanding and scannability.
/* Not recommended: does not separate the words “demo” and “image” */
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
/* Recommended */
#video-id {}
.ads-sample {}
Hacks
Avoid user agent detection as well as CSS “hacks”—try a different approach first.
It is tempting to address styling differences over user agent detection or special CSS filters, workarounds, and hacks. Both approaches should be considered last resort in order to achieve and maintain an efficient and manageable code base. Put another way, giving detection and hacks a free pass will hurt projects in the long run as projects tend to take the way of least resistance. That is, allowing and making it easy to use detection and hacks means using detection and hacks more frequently—and more frequently is too frequently.
CSS Formatting Rules
Declaration order
Alphabetize declarations.
Put declarations in alphabetical order in order to achieve consistent code in a way that is easy to remember and maintain.
Ignore vendor-specific prefixes for sorting purposes. However, multiple vendor-specific prefixes for a certain CSS property should be kept sorted (e.g. -moz prefix comes before -webkit).
background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;
Block content indentation
Indent all block content.
Indent all block content, that is rules within rules as well as declarations, so to reflect hierarchy and improve understanding.
@media screen, projection {
html {
background: #fff;
color: #444;
}
}
Declaration stops
Use a semicolon after every declaration.
End every declaration with a semicolon for consistency and extensibility reasons.
/* Not recommended */
.test {
display: block;
height: 100px
}
/* Recommended */
.test {
display: block;
height: 100px;
}
Property name stops
Use a space after a property name’s colon.
Always use a single space between property and value (but no space between property and colon) for consistency reasons.
/* Not recommended */
h3 {
font-weight:bold;
}
/* Recommended */
h3 {
font-weight: bold;
}
Selector and declaration separation
Separate selectors and declarations by new lines.
Always start a new line for each selector and declaration.
/* Not recommended */
a:focus, a:active {
position: relative; top: 1px;
}
/* Recommended */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
Rule separation
Separate rules by new lines.
Always put a line between rules.
html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
CSS Meta Rules
Section comments
Group sections by a section comment (optional).
If possible, group style sheets sections together by using comments. Separate sections with new lines.
/* Header */
#adw-header {}
/* Footer */
#adw-footer {}
/* Gallery */
.adw-gallery {}
Parting Words
Be consistent.
If you’re editing code, take a few minutes to look at the code already generated around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.
The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.