Revision 2.23

This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see “Hooray” appear below.

Hooray! Now you know you can expand points to get more details. Alternatively, there’s a “toggle all” at the top of this document.


Omit the protocol from embedded resources.

Omit the protocol portion (http:, https:) from URLs pointing to images and other media files, style sheets, and scripts unless the respective files are not available over both protocols.

Omitting the protocol—which makes the URL relative—prevents mixed content issues and results in minor file size savings.

<!-- Not recommended --> <script src=""></script> <!-- Recommended --> <script src="//"></script> /* Not recommended */ .example { background: url(; } /* Recommended */ .example { background: url(//; }
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; }
Use only lowercase.


<!-- Not recommended --> <A HREF="/">Home</A> <!-- Recommended --> <img src="google.png" alt="Google"> /* Not recommended */ color: #E5E5E5; /* Recommended */ color: #e5e5e5;
Remove trailing white spaces.

Trailing white spaces are unnecessary and can complicate diffs.

<!-- Not recommended --> <p>What?_ <!-- Recommended --> <p>Yes please.
Use UTF-8 (no BOM).


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 Handling character encodings in HTML and CSS.)

Explain code as needed, where possible.



Mark todos and action items with TODO.

Highlight todos by using the keyword TODO only, not other common formats like @@.



{# TODO(john.doe): revisit centering #} <center>Test</center> <!-- TODO: remove optional tags --> <ul> <li>Apples</li> <li>Oranges</li> </ul>
Use HTML5.



Although fine with HTML, do not close void elements, i.e. write <br>, not <br />.

Use valid HTML where possible.

Use valid HTML code unless that is not possible due to otherwise unattainable performance goals regarding file size.

Use tools such as the W3C HTML validator to test.


<!-- 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>
Use HTML according to its purpose.



<!-- Not recommended --> <div onclick="goToRecommendations();">All recommendations</div> <!-- Recommended --> <a href="recommendations/">All recommendations</a>
Provide alternative contents for multimedia.


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.


<!-- Not recommended --> <img src="spreadsheet.png"> <!-- Recommended --> <img src="spreadsheet.png" alt="Spreadsheet screenshot.">
Separate structure from presentation from behavior.

Strictly keep structure (markup), presentation (styling), and behavior (scripting) apart, and try to keep the interaction between the three to an absolute minimum.

That is, make sure documents and templates contain only HTML and HTML that is solely serving structural purposes. Move everything presentational into style sheets, and everything behavioral into scripts.

In addition, keep the contact area as small as possible by linking as few style sheets and scripts as possible from documents and templates.

Separating structure from presentation from behavior is important for maintenance reasons. It is always more expensive to change HTML documents and templates than it is to update style sheets and scripts.

<!-- Not recommended --> <!DOCTYPE html> <title>HTML sucks</title> <link rel="stylesheet" href="base.css" media="screen"> <link rel="stylesheet" href="grid.css" media="screen"> <link rel="stylesheet" href="print.css" media="print"> <h1 style="font-size: 1em;">HTML sucks</h1> <p>I’ve read about this on a few sites but now I’m sure: <u>HTML is stupid!!1</u> <center>I can’t believe there’s no way to control the styling of my website without doing everything all over again!</center> <!-- Recommended --> <!DOCTYPE html> <title>My first CSS-only redesign</title> <link rel="stylesheet" href="default.css"> <h1>My first CSS-only redesign</h1> <p>I’ve read about this on a few sites but today I’m actually doing it: separating concerns and avoiding anything in the HTML of my website that is presentational. <p>It’s awesome!
Do not use entity references.

There is no need to use entity references like &mdash;, &rdquo;, or &#x263a;, 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 no-break spaces).

<!-- Not recommended --> The currency symbol for the Euro is &ldquo;&eur;&rdquo;. <!-- Recommended --> The currency symbol for the Euro is “€”.
Omit optional tags (optional).


(This approach may require a grace period to be established as a wider guideline as it’s significantly different from what web developers are typically taught. For consistency and simplicity reasons it’s best served omitting all optional tags, not just a selection.)

<!-- Not recommended --> <!DOCTYPE html> <html> <head> <title>Spending money, spending bytes</title> </head> <body> <p>Sic.</p> </body> </html> <!-- Recommended --> <!DOCTYPE html> <title>Saving money, saving bytes</title> <p>Qed.
Omit type attributes for style sheets and scripts.



<!-- Not recommended --> <link rel="stylesheet" href="//" type="text/css"> <!-- Recommended --> <link rel="stylesheet" href="//"> <!-- Not recommended --> <script src="//" type="text/javascript"></script> <!-- Recommended --> <script src="//"></script>



(If you run into issues around whitespace between list items it’s acceptable to put all li elements in one line. A linter is encouraged to throw a warning instead of an error.)

<blockquote> <p><em>Space</em>, the final frontier.</p> </blockquote> <ul> <li>Moe <li>Larry <li>Curly </ul> <table> <thead> <tr> <th scope="col">Income <th scope="col">Taxes <tbody> <tr> <td>$ 5.00 <td>$ 4.50 </table>
When quoting attributes values, use double quotation marks.


<!-- Not recommended --> <a class='maia-button maia-button-secondary'>Sign in</a> <!-- Recommended --> <a class="maia-button maia-button-secondary">Sign in</a>
Use valid CSS where possible.


Use tools such as the W3C CSS validator to test.

Using valid CSS is a measurable baseline quality attribute that allows to spot CSS code that may not have any effect and can be removed, and that ensures proper CSS usage.

Use meaningful or generic ID and class names.





/* Not recommended: meaningless */ #yee-1901 {} /* Not recommended: presentational */ .button-green {} .clear {} /* Recommended: specific */ #gallery {} #login {} .video {} /* Recommended: generic */ .aux {} .alt {}



/* Not recommended */ #navigation {} .atr {} /* Recommended */ #nav {} .author {}
Avoid qualifying ID and class names with type selectors.


Avoiding unnecessary ancestor selectors is useful for performance reasons.

/* Not recommended */ ul#example {} div.error {} /* Recommended */ #example {} .error {}
Use shorthand properties where possible.


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;
Omit unit specification after “0” values.

Do not use units after 0 values unless they are required.

margin: 0; padding: 0;
Omit leading “0”s in values.


font-size: .8em;
Use 3 character hexadecimal notation where possible.


/* Not recommended */ color: #eebbcc; /* Recommended */ color: #ebc;
Prefix selectors with an application-specific prefix (optional).

In large projects as well as for code that gets embedded in other projects or on external sites use prefixes (as namespaces) for ID and class names. Use short, unique identifiers followed by a dash.

Using namespaces helps preventing naming conflicts and can make maintenance easier, for example in search and replace operations.

.adw-help {} /* AdWords */ #maia-note {} /* Maia */
Separate words in ID and class names by a hyphen.


/* 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 {}


Alphabetize declarations.



background: fuchsia; border: 1px solid; -moz-border-radius: 4px; -webkit-border-radius: 4px; border-radius: 4px; color: black; text-align: center; text-indent: 2em;
Indent all block content.


@media screen, projection { html { background: #fff; color: #444; } }
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; }
Use a space after a property name’s colon.


/* Not recommended */ h3 { font-weight:bold; } /* Recommended */ h3 { font-weight: bold; }
Use a space between the last selector and the declaration block.

Always use a single space between the last selector and the opening brace that begins the declaration block.

The opening brace should be on the same line as the last selector in a given rule.

/* Not recommended: missing space */ #video{ margin-top: 1em; } /* Not recommended: unnecessary line break */ #video { margin-top: 1em; } /* Recommended */ #video { margin-top: 1em; }
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; }
Separate rules by new lines.


html { background: #fff; } body { margin: auto; width: 50%; }
Use single quotation marks for attribute selectors and property values.

Use single ('') rather than double ("") quotation marks for attribute selectors or property values. Do not use quotation marks in URI values (url()).

Exception: If you do need to use the @charset rule, use double quotation marks—single quotation marks are not permitted.

/* Not recommended */ @import url("//"); html { font-family: "open sans", arial, sans-serif; } /* Recommended */ @import url(//; html { font-family: 'open sans', arial, sans-serif; }
Group sections by a section comment (optional).

If possible, group style sheet sections together by using comments. Separate sections with new lines.

/* Header */ #adw-header {} /* Footer */ #adw-footer {} /* Gallery */ .adw-gallery {}

Be consistent.



Revision 2.23