| <?xml version="1.0"?> |
| <?xml-stylesheet type="text/xsl" href="styleguide.xsl"?> |
| <GUIDE title="Google HTML/CSS Style Guide"> |
| <p class="revision"> |
| |
| Revision 2.1 |
| </p> |
| |
| <OVERVIEW> |
| <CATEGORY title="Important Note"> |
| <STYLEPOINT title="Displaying Hidden Details in this Guide"> |
| <SUMMARY> |
| 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. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Hooray! Now you know you can expand points to get more |
| details. Alternatively, there’s a “toggle all” at the |
| top of this document. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| <CATEGORY title="Background"> |
| |
| <p> |
| 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. |
| </p> |
| |
| |
| </CATEGORY> |
| </OVERVIEW> |
| |
| <CATEGORY title="General Style Rules"> |
| <STYLEPOINT title="Protocol"> |
| <SUMMARY> |
| Omit the protocol from embedded resources. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Omit the protocol portion (<code>http:</code>, |
| <code>https:</code>) from URLs pointing to images and other |
| media files, style sheets, and scripts unless the respective |
| files are not available over both protocols. |
| </p> |
| <p> |
| Omitting the protocol—which makes the URL |
| relative—prevents mixed content issues and results in |
| minor file size savings. |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script> |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| .example { |
| background: url(http://www.google.com/images/example); |
| } |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| .example { |
| background: url(//www.google.com/images/example); |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| </CATEGORY> |
| |
| <CATEGORY title="General Formatting Rules"> |
| <STYLEPOINT title="Indentation"> |
| <SUMMARY> |
| Indent by 2 spaces at a time. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Don’t use tabs or mix tabs and spaces for indentation. |
| </p> |
| <CODE_SNIPPET> |
| <ul> |
| <li>Fantastic |
| <li>Great |
| </ul> |
| </CODE_SNIPPET> |
| <CODE_SNIPPET> |
| .example { |
| color: blue; |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Capitalization"> |
| <SUMMARY> |
| Use only lowercase. |
| </SUMMARY> |
| <BODY> |
| <p> |
| All code has to be lowercase: this applies to element names, |
| attributes, attribute values (unless |
| text/<code>CDATA</code>), selectors, properties, and |
| property values (with the exception of strings). |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <A HREF="/">Home</A> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <img src="google.png" alt="Google"> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Trailing whitespace"> |
| <SUMMARY> |
| Remove trailing white spaces. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Trailing white spaces are unnecessary and can complicate |
| diffs. |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <p>What?_ |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <p>Yes please. |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="General Meta Rules"> |
| <STYLEPOINT title="Encoding"> |
| <SUMMARY> |
| Use UTF-8 (no BOM). |
| </SUMMARY> |
| <BODY> |
| <p> |
| Make sure your editor uses UTF-8 as character encoding, |
| without a byte order mark. |
| </p> |
| <p> |
| Specify the encoding in HTML templates and documents via |
| <code><meta charset="utf-8"></code>. Do not specify |
| the encoding of style sheets as these assume UTF-8. |
| </p> |
| <p> |
| (More on encodings and when and how to specify them can be |
| found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/en/all.html">Character |
| Sets & Encodings in XHTML, HTML and CSS</a>.) |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Comments"> |
| <SUMMARY> |
| Explain code as needed, where possible. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Use comments to explain code: what does it cover, what |
| purpose does it serve, why is respective solution used or |
| preferred? |
| </p> |
| <p> |
| (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.) |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Action items"> |
| <SUMMARY> |
| Mark todos and action items with <code>TODO</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Highlight todos by using the keyword <code>TODO</code> only, |
| not other common formats like <code>@@</code>. |
| </p> |
| <p> |
| Append a contact (username or mailing list) in parentheses |
| as with the format <code>TODO(contact)</code>. |
| </p> |
| <p> |
| Append action items after a colon as in <code>TODO: action |
| item</code>. |
| </p> |
| |
| <CODE_SNIPPET> |
| {# TODO(john.doe): revisit centering #} |
| <center>Test</center> |
| </CODE_SNIPPET> |
| |
| <CODE_SNIPPET> |
| <!-- TODO: remove optional tags --> |
| <ul> |
| <li>Apples</li> |
| <li>Oranges</li> |
| </ul> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="HTML Style Rules"> |
| <STYLEPOINT title="Document type"> |
| <SUMMARY> |
| Use HTML5. |
| </SUMMARY> |
| <BODY> |
| <p> |
| HTML5 (HTML syntax) is preferred for all HTML documents: |
| <code><!DOCTYPE html></code>. |
| </p> |
| <p> |
| (It is recommended to use HTML, as <code>text/html</code>. Do not use |
| XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, |
| lacks both browser and infrastructure support and offers |
| less room for optimization than HTML.) |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="HTML validity"> |
| <SUMMARY> |
| Use valid HTML where possible. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Use valid HTML code unless that is not possible due to |
| otherwise unattainable performance goals regarding file size. |
| </p> |
| |
| <p> |
| Use tools such as the <a href="http://validator.w3.org/nu/">W3C |
| HTML validator</a> to test. |
| </p> |
| <p> |
| Using valid HTML is a measurable baseline quality attribute |
| that contributes to learning about technical requirements |
| and constraints, and that ensures proper HTML usage. |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <title>Test</title> |
| <article>This is only a test. |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <!DOCTYPE html> |
| <meta charset="utf-8"> |
| <title>Test</title> |
| <article>This is only a test.</article> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Semantics"> |
| <SUMMARY> |
| Use HTML according to its purpose. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Use elements (sometimes incorrectly called “tags”) for what |
| they have been created for. For example, use heading |
| elements for headings, <code>p</code> elements for |
| paragraphs, <code>a</code> elements for anchors, etc. |
| </p> |
| <p> |
| Using HTML according to its purpose is important for |
| accessibility, reuse, and code efficiency reasons. |
| </p> |
| |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <div onclick="goToRecommendations();">All recommendations</div> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <a href="recommendations/">All recommendations</a> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Multimedia fallback"> |
| <SUMMARY> |
| Provide alternative contents for multimedia. |
| </SUMMARY> |
| <BODY> |
| <p> |
| For multimedia, such as images, videos, animated objects via |
| <code>canvas</code>, make sure to offer alternative |
| access. For images that means use of meaningful alternative |
| text (<code>alt</code>) and for video and audio transcripts |
| and captions, if available. |
| </p> |
| <p> |
| Providing alternative contents is important for |
| accessibility reasons: a blind user has few cues to tell |
| what an image is about without <code>@alt</code>, and other |
| users may have no way of understanding what video or audio |
| contents are about either. |
| </p> |
| <p> |
| (For images whose <code>alt</code> 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 <code>alt=""</code>.) |
| </p> |
| |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <img src="spreadsheet.png"> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <img src="spreadsheet.png" alt="Spreadsheet screenshot."> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Separation of concerns"> |
| <SUMMARY> |
| Separate structure from presentation from behavior. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Strictly keep structure (markup), presentation (styling), |
| and behavior (scripting) apart, and try to keep the |
| interaction between the three to an absolute minimum. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| In addition, keep the contact area as small as possible by |
| linking as few style sheets and scripts as possible from |
| documents and templates. |
| </p> |
| <p> |
| 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. |
| </p> |
| |
| <BAD_CODE_SNIPPET> |
| <!-- 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> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- 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! |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Entity references"> |
| <SUMMARY> |
| Do not use entity references. |
| </SUMMARY> |
| <BODY> |
| <p> |
| There is no need to use entity references like |
| <code>&mdash;</code>, <code>&rdquo;</code>, or |
| <code>&#x263a;</code>, assuming the same encoding |
| (UTF-8) is used for files and editors as well as among |
| teams. |
| </p> |
| <p> |
| The only exceptions apply to characters with special meaning |
| in HTML (like <code><</code> and <code>&</code>) as |
| well as control or “invisible” characters (like no-break |
| spaces). |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| The currency symbol for the Euro is &ldquo;&eur;&rdquo;. |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| The currency symbol for the Euro is “€”. |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Optional tags"> |
| <SUMMARY> |
| Omit optional tags (optional). |
| </SUMMARY> |
| <BODY> |
| <p> |
| For file size optimization and scannability purposes, |
| consider omitting optional tags. |
| The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5 |
| specification</a> defines what tags can be omitted. |
| </p> |
| <p> |
| (This approach may require a grace period to be established |
| as a wider guideline as it is significantly different |
| from what web developers are typically taught. For |
| consistency and simplicity reasons it is best served |
| omitting all optional tags, not just a selection.) |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <!DOCTYPE html> |
| <html> |
| <head> |
| <title>Spending money, spending bytes</title> |
| </head> |
| <body> |
| <p>Sic.</p> |
| </body> |
| </html> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <!DOCTYPE html> |
| <title>Saving money, saving bytes</title> |
| <p>Qed. |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="type attributes"> |
| <SUMMARY> |
| Omit <code>type</code> attributes for style sheets and scripts. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Do not use <code>type</code> attributes for style sheets |
| (unless not using CSS) and scripts (unless not using |
| JavaScript). |
| </p> |
| <p> |
| Specifying <code>type</code> attributes in these contexts is |
| not necessary as HTML5 implies |
| <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a> |
| and |
| <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a> |
| as defaults. This can be safely done even for older browsers. |
| </p> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <link rel="stylesheet" href="//www.google.com/css/maia.css" |
| type="text/css"> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <link rel="stylesheet" href="//www.google.com/css/maia.css"> |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| <!-- Not recommended --> |
| <script src="//www.google.com/js/gweb/analytics/autotrack.js" |
| type="text/javascript"></script> |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <!-- Recommended --> |
| <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="HTML Formatting Rules"> |
| <STYLEPOINT title="General formatting"> |
| <SUMMARY> |
| Use a new line for every block, list, or table element, and |
| indent every such child element. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Independent of the styling of an element (as CSS allows |
| elements to assume a different role per <code>display</code> |
| property), put every block, list, or table element on a new |
| line. |
| </p> |
| <p> |
| Also, indent them if they are child elements of a block, |
| list, or table element. |
| </p> |
| <p> |
| (If you run into issues around whitespace between list items |
| it is acceptable to put all <code>li</code> elements in one |
| line. A linter is encouraged to throw a warning instead of |
| an error.) |
| </p> |
| <CODE_SNIPPET> |
| <blockquote> |
| <p><em>Space</em>, the final frontier.</p> |
| </blockquote> |
| </CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <ul> |
| <li>Moe |
| <li>Larry |
| <li>Curly |
| </ul> |
| </CODE_SNIPPET> |
| <CODE_SNIPPET> |
| <table> |
| <thead> |
| <tr> |
| <th scope="col">Income |
| <th scope="col">Taxes |
| <tbody> |
| <tr> |
| <td>$ 5.00 |
| <td>$ 4.50 |
| </table> |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="CSS Style Rules"> |
| <STYLEPOINT title="CSS validity"> |
| <SUMMARY> |
| Use valid CSS where possible. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Unless dealing with CSS validator bugs or requiring |
| proprietary syntax, use valid CSS code. |
| </p> |
| |
| <p> |
| Use tools such as the |
| <a href="http://jigsaw.w3.org/css-validator/">W3C CSS validator</a> to |
| test. |
| </p> |
| <p> |
| 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. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="ID and class naming"> |
| <SUMMARY> |
| Use meaningful or generic ID and class names. |
| </SUMMARY> |
| <BODY> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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.” |
| </p> |
| <p> |
| Using functional or generic names reduces the probability of |
| unnecessary document or template changes. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended: meaningless */ |
| #yee-1901 {} |
| |
| /* Not recommended: presentational */ |
| .button-green {} |
| .clear {} |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended: specific */ |
| #gallery {} |
| #login {} |
| .video {} |
| |
| /* Recommended: generic */ |
| .aux {} |
| .alt {} |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="ID and class name style"> |
| <SUMMARY> |
| Use ID and class names that are as short as possible but as long as |
| necessary. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Try to convey what an ID or class is about while being as |
| brief as possible. |
| </p> |
| <p> |
| Using ID and class names this way contributes to acceptable |
| levels of understandability and code efficiency. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| #navigation {} |
| .atr {} |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| #nav {} |
| .author {} |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Type selectors"> |
| <SUMMARY> |
| Avoid qualifying ID and class names with type selectors. |
| </SUMMARY> |
| <BODY> |
| <p>Unless necessary (for example with helper classes), do not |
| use element names in conjunction with IDs or classes. |
| </p> |
| <p> |
| Avoiding unnecessary ancestor selectors is useful for |
| <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance |
| reasons</a>. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| ul#example {} |
| div.error {} |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| #example {} |
| .error {} |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Shorthand properties"> |
| <SUMMARY> |
| Use shorthand properties where possible. |
| </SUMMARY> |
| <BODY> |
| <p> |
| CSS offers a variety of |
| <a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a> |
| properties (like <code>font</code>) |
| that should be used whenever possible, even in cases where |
| only one value is explicitly set. |
| </p> |
| <p> |
| Using shorthand properties is useful for code efficiency and |
| understandability. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* 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; |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| border-top: 0; |
| font: 100%/1.6 palatino, georgia, serif; |
| padding: 0 1em 2em; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="0 and units"> |
| <SUMMARY> |
| Omit unit specification after “0” values. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Do not use units after <code>0</code> values unless they are |
| required. |
| </p> |
| <CODE_SNIPPET> |
| margin: 0; |
| padding: 0; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Leading 0s"> |
| <SUMMARY> |
| Omit leading “0”s in values. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Do not use put <code>0</code>s in front of values or lengths |
| between -1 and 1. |
| </p> |
| <CODE_SNIPPET> |
| font-size: .8em; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Quotation marks in URI values"> |
| <SUMMARY> |
| Omit quotation marks in URI values. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Do not use quotation marks (<code>""</code>, |
| <code>''</code>) with <code>url()</code>. |
| </p> |
| <CODE_SNIPPET> |
| @import url(//www.google.com/css/go.css); |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Hexadecimal notation"> |
| <SUMMARY> |
| Use 3 character hexadecimal notation where possible. |
| </SUMMARY> |
| <BODY> |
| <p> |
| For color values that permit it, 3 character hexadecimal |
| notation is shorter and more succinct. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| color: #eebbcc; |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| color: #ebc; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Prefixes"> |
| <SUMMARY> |
| Prefix selectors with an application-specific prefix (optional). |
| </SUMMARY> |
| <BODY> |
| <p> |
| 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. |
| </p> |
| |
| |
| <p> |
| Using namespaces helps preventing naming conflicts and can |
| make maintenance easier, for example in search and replace |
| operations. |
| </p> |
| <CODE_SNIPPET> |
| .adw-help {} /* AdWords */ |
| #maia-note {} /* Maia */ |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="ID and class name delimiters"> |
| <SUMMARY> |
| Separate words in ID and class names by a hyphen. |
| </SUMMARY> |
| <BODY> |
| <p> |
| 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. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended: does not separate the words “demo” and “image” */ |
| .demoimage {} |
| |
| /* Not recommended: uses underscore instead of hyphen */ |
| .error_status {} |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| #video-id {} |
| .ads-sample {} |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Hacks"> |
| <SUMMARY> |
| Avoid user agent detection as well as CSS “hacks”—try a different |
| approach first. |
| </SUMMARY> |
| <BODY> |
| <p> |
| 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. |
| </p> |
| |
| |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="CSS Formatting Rules"> |
| <STYLEPOINT title="Declaration order"> |
| <SUMMARY> |
| Alphabetize declarations. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Put declarations in alphabetical order in order to achieve |
| consistent code in a way that is easy to remember and |
| maintain. |
| </p> |
| <p> |
| 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). |
| </p> |
| <CODE_SNIPPET> |
| background: fuchsia; |
| border: 1px solid; |
| -moz-border-radius: 4px; |
| -webkit-border-radius: 4px; |
| border-radius: 4px; |
| color: black; |
| text-align: center; |
| text-indent: 2em; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Block content indentation"> |
| <SUMMARY> |
| Indent all block content. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Indent all <a href="http://www.w3.org/TR/CSS21/syndata.html#block">block |
| content</a>, that is rules within rules as well as declarations, so to |
| reflect hierarchy and improve understanding. |
| </p> |
| <CODE_SNIPPET> |
| @media screen, projection { |
| |
| html { |
| background: #fff; |
| color: #444; |
| } |
| |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Declaration stops"> |
| <SUMMARY> |
| Use a semicolon after every declaration. |
| </SUMMARY> |
| <BODY> |
| <p> |
| End every declaration with a semicolon for consistency and |
| extensibility reasons. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| .test { |
| display: block; |
| height: 100px |
| } |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| .test { |
| display: block; |
| height: 100px; |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Property name stops"> |
| <SUMMARY> |
| Use a space after a property name’s colon. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Always use a single space between property and value (but no |
| space between property and colon) for consistency reasons. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| h3 { |
| font-weight:bold; |
| } |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| h3 { |
| font-weight: bold; |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Selector and declaration separation"> |
| <SUMMARY> |
| Separate selectors and declarations by new lines. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Always start a new line for each selector and declaration. |
| </p> |
| <BAD_CODE_SNIPPET> |
| /* Not recommended */ |
| a:focus, a:active { |
| position: relative; top: 1px; |
| } |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| /* Recommended */ |
| h1, |
| h2, |
| h3 { |
| font-weight: normal; |
| line-height: 1.2; |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| <STYLEPOINT title="Rule separation"> |
| <SUMMARY> |
| Separate rules by new lines. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Always put a line between rules. |
| </p> |
| <CODE_SNIPPET> |
| html { |
| background: #fff; |
| } |
| |
| body { |
| margin: auto; |
| width: 50%; |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="CSS Meta Rules"> |
| |
| <STYLEPOINT title="Section comments"> |
| <SUMMARY> |
| Group sections by a section comment (optional). |
| </SUMMARY> |
| <BODY> |
| <p> |
| If possible, group style sheets sections together by using |
| comments. Separate sections with new lines. |
| </p> |
| <CODE_SNIPPET> |
| /* Header */ |
| |
| #adw-header {} |
| |
| /* Footer */ |
| |
| #adw-footer {} |
| |
| /* Gallery */ |
| |
| .adw-gallery {} |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <PARTING_WORDS> |
| <p> |
| <em>Be consistent.</em> |
| </p> |
| <p> |
| If you’re editing code, take a few minutes to look at the code |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| </PARTING_WORDS> |
| |
| <p align="right"> |
| Revision 2.1 |
| </p> |
| |
| </GUIDE> |