Ted Osborne | 505ba68 | 2018-01-30 12:36:50 -0500 | [diff] [blame] | 1 | <!DOCTYPE html> |
| 2 | <html lang="en"> |
| 3 | <head> |
| 4 | <meta charset="utf-8"> |
| 5 | <title>Google HTML/CSS Style Guide</title> |
| 6 | <link rel="stylesheet" href="javaguide.css"> |
| 7 | <script src="include/styleguide.js"></script> |
| 8 | <link rel="shortcut icon" href="https://www.google.com/favicon.ico"> |
| 9 | <script src="include/jsguide.js"></script> |
| 10 | </head> |
| 11 | <body onload="initStyleGuide();"> |
| 12 | <div id="content"> |
| 13 | <h1>Google HTML/CSS Style Guide</h1> |
| 14 | <h2 id="Background">1 Background</h2> |
| 15 | |
| 16 | <p>This document defines formatting and style rules for HTML and CSS. It aims at |
| 17 | improving collaboration, code quality, and enabling supporting infrastructure. |
| 18 | It applies to raw, working files that use HTML and CSS, including GSS files. |
| 19 | Tools are free to obfuscate, minify, and compile as long as the general code |
| 20 | quality is maintained.</p> |
| 21 | |
| 22 | <h2 id="General">2 General</h2> |
| 23 | |
| 24 | <h3 id="General_Style_Rules">2.1 General Style Rules</h3> |
| 25 | |
| 26 | <h4 id="Protocol">2.1.1 Protocol</h4> |
| 27 | |
Eric Clinger | 967ca82 | 2019-02-21 18:32:43 -0700 | [diff] [blame] | 28 | <p>Use HTTPS for embedded resources where possible.</p> |
Ted Osborne | 505ba68 | 2018-01-30 12:36:50 -0500 | [diff] [blame] | 29 | |
Eric Clinger | 967ca82 | 2019-02-21 18:32:43 -0700 | [diff] [blame] | 30 | <p>Always use HTTPS (<code>https:</code>) for images and other media |
Ted Osborne | 505ba68 | 2018-01-30 12:36:50 -0500 | [diff] [blame] | 31 | files, style sheets, and scripts, unless the respective files are not available |
| 32 | over HTTPS.</p> |
| 33 | |
| 34 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended: omits the protocol --> |
| 35 | <script src="//ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script> |
| 36 | |
Eric Clinger | 967ca82 | 2019-02-21 18:32:43 -0700 | [diff] [blame] | 37 | <!-- Not recommended: uses HTTP --> |
Ted Osborne | 505ba68 | 2018-01-30 12:36:50 -0500 | [diff] [blame] | 38 | <script src="http://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script> |
| 39 | </code></pre> |
| 40 | |
| 41 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 42 | <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script> |
| 43 | </code></pre> |
| 44 | |
| 45 | <pre><code class="language-css prettyprint badcode">/* Not recommended: omits the protocol */ |
| 46 | @import '//fonts.googleapis.com/css?family=Open+Sans'; |
| 47 | |
Eric Clinger | 967ca82 | 2019-02-21 18:32:43 -0700 | [diff] [blame] | 48 | /* Not recommended: uses HTTP */ |
Ted Osborne | 505ba68 | 2018-01-30 12:36:50 -0500 | [diff] [blame] | 49 | @import 'http://fonts.googleapis.com/css?family=Open+Sans'; |
| 50 | </code></pre> |
| 51 | |
| 52 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 53 | @import 'https://fonts.googleapis.com/css?family=Open+Sans'; |
| 54 | </code></pre> |
| 55 | |
| 56 | <h3 id="General_Formatting_Rules">2.2 General Formatting Rules</h3> |
| 57 | |
| 58 | <h4 id="Indentation">2.2.1 Indentation</h4> |
| 59 | |
| 60 | <p>Indent by 2 spaces at a time.</p> |
| 61 | |
| 62 | <p>Don’t use tabs or mix tabs and spaces for indentation.</p> |
| 63 | |
| 64 | <pre><code class="language-html prettyprint"><ul> |
| 65 | <li>Fantastic |
| 66 | <li>Great |
| 67 | </ul> |
| 68 | </code></pre> |
| 69 | |
| 70 | <pre><code class="language-css prettyprint">.example { |
| 71 | color: blue; |
| 72 | } |
| 73 | </code></pre> |
| 74 | |
| 75 | <h4 id="Capitalization">2.2.2 Capitalization</h4> |
| 76 | |
| 77 | <p>Use only lowercase.</p> |
| 78 | |
| 79 | <p>All code has to be lowercase: This applies to HTML element names, attributes, |
| 80 | attribute values (unless <code>text/CDATA</code>), CSS selectors, properties, and property |
| 81 | values (with the exception of strings).</p> |
| 82 | |
| 83 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 84 | <A HREF="/">Home</A> |
| 85 | </code></pre> |
| 86 | |
| 87 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 88 | <img src="google.png" alt="Google"> |
| 89 | </code></pre> |
| 90 | |
| 91 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 92 | color: #E5E5E5; |
| 93 | </code></pre> |
| 94 | |
| 95 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 96 | color: #e5e5e5; |
| 97 | </code></pre> |
| 98 | |
| 99 | <h4 id="Trailing_Whitespace">2.2.3 Trailing Whitespace</h4> |
| 100 | |
| 101 | <p>Remove trailing white spaces.</p> |
| 102 | |
| 103 | <p>Trailing white spaces are unnecessary and can complicate diffs.</p> |
| 104 | |
| 105 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 106 | <p>What?_ |
| 107 | </code></pre> |
| 108 | |
| 109 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 110 | <p>Yes please. |
| 111 | </code></pre> |
| 112 | |
| 113 | <h3 id="General_Meta_Rules">2.3 General Meta Rules</h3> |
| 114 | |
| 115 | <h4 id="Encoding">2.3.1 Encoding</h4> |
| 116 | |
| 117 | <p>Use UTF-8 (no BOM).</p> |
| 118 | |
| 119 | <p>Make sure your editor uses UTF-8 as character encoding, without a byte order |
| 120 | mark.</p> |
| 121 | |
| 122 | <p>Specify the encoding in HTML templates and documents via <code><meta |
| 123 | charset="utf-8"></code>. Do not specify the encoding of style sheets as these assume |
| 124 | UTF-8.</p> |
| 125 | |
| 126 | <p>(More on encodings and when and how to specify them can be found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling |
| 127 | character encodings in HTML and CSS</a>.)</p> |
| 128 | |
| 129 | <h4 id="Comments">2.3.2 Comments</h4> |
| 130 | |
| 131 | <p>Explain code as needed, where possible.</p> |
| 132 | |
| 133 | <p>Use comments to explain code: What does it cover, what purpose does it serve, |
| 134 | why is respective solution used or preferred?</p> |
| 135 | |
| 136 | <p>(This item is optional as it is not deemed a realistic expectation to always |
| 137 | demand fully documented code. Mileage may vary heavily for HTML and CSS code and |
| 138 | depends on the project’s complexity.)</p> |
| 139 | |
| 140 | <h4 id="Action_Items">2.3.3 Action Items</h4> |
| 141 | |
| 142 | <p>Mark todos and action items with <code>TODO</code>.</p> |
| 143 | |
| 144 | <p>Highlight todos by using the keyword <code>TODO</code> only, not other common formats like |
| 145 | <code>@@</code>.</p> |
| 146 | |
| 147 | <p>Append a contact (username or mailing list) in parentheses as with the format |
| 148 | <code>TODO(contact)</code>.</p> |
| 149 | |
| 150 | <p>Append action items after a colon as in <code>TODO: action item</code>.</p> |
| 151 | |
| 152 | <pre><code class="language-django prettyprint external">{# TODO(john.doe): revisit centering #} |
| 153 | <center>Test</center> |
| 154 | </code></pre> |
| 155 | |
| 156 | <pre><code class="language-html prettyprint"><!-- TODO: remove optional tags --> |
| 157 | <ul> |
| 158 | <li>Apples</li> |
| 159 | <li>Oranges</li> |
| 160 | </ul> |
| 161 | </code></pre> |
| 162 | |
| 163 | <h2 id="HTML">3 HTML</h2> |
| 164 | |
| 165 | <h3 id="HTML_Style_Rules">3.1 HTML Style Rules</h3> |
| 166 | |
| 167 | <h4 id="Document_Type">3.1.1 Document Type</h4> |
| 168 | |
| 169 | <p>Use HTML5.</p> |
| 170 | |
| 171 | <p>HTML5 (HTML syntax) is preferred for all HTML documents: <code><!DOCTYPE html></code>.</p> |
| 172 | |
| 173 | <p>(It’s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as |
| 174 | <a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, lacks both browser |
| 175 | and infrastructure support and offers less room for optimization than HTML.)</p> |
| 176 | |
| 177 | <p>Although fine with HTML, do not close void elements, i.e. write <code><br></code>, not |
| 178 | <code><br /></code>.</p> |
| 179 | |
| 180 | <h4 id="HTML_Validity">3.1.2 HTML Validity</h4> |
| 181 | |
| 182 | <p>Use valid HTML where possible.</p> |
| 183 | |
| 184 | <p>Use valid HTML code unless that is not possible due to otherwise unattainable |
| 185 | performance goals regarding file size.</p> |
| 186 | |
| 187 | <p> |
| 188 | |
| 189 | Use tools such as the <a href="https://validator.w3.org/nu/">W3C HTML validator</a> |
| 190 | to test. |
| 191 | </p> |
| 192 | |
| 193 | <p>Using valid HTML is a measurable baseline quality attribute that contributes to |
| 194 | learning about technical requirements and constraints, and that ensures proper |
| 195 | HTML usage.</p> |
| 196 | |
| 197 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 198 | <title>Test</title> |
| 199 | <article>This is only a test. |
| 200 | </code></pre> |
| 201 | |
| 202 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 203 | <!DOCTYPE html> |
| 204 | <meta charset="utf-8"> |
| 205 | <title>Test</title> |
| 206 | <article>This is only a test.</article> |
| 207 | </code></pre> |
| 208 | |
| 209 | <h4 id="Semantics">3.1.3 Semantics</h4> |
| 210 | |
| 211 | <p>Use HTML according to its purpose.</p> |
| 212 | |
| 213 | <p>Use elements (sometimes incorrectly called “tags”) for what they have been |
| 214 | created for. For example, use heading elements for headings, <code>p</code> elements for |
| 215 | paragraphs, <code>a</code> elements for anchors, etc.</p> |
| 216 | |
| 217 | <p>Using HTML according to its purpose is important for accessibility, reuse, and |
| 218 | code efficiency reasons.</p> |
| 219 | |
| 220 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 221 | <div onclick="goToRecommendations();">All recommendations</div> |
| 222 | </code></pre> |
| 223 | |
| 224 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 225 | <a href="recommendations/">All recommendations</a> |
| 226 | </code></pre> |
| 227 | |
| 228 | <h4 id="Multimedia_Fallback">3.1.4 Multimedia Fallback</h4> |
| 229 | |
| 230 | <p>Provide alternative contents for multimedia.</p> |
| 231 | |
| 232 | <p>For multimedia, such as images, videos, animated objects via <code>canvas</code>, make sure |
| 233 | to offer alternative access. For images that means use of meaningful alternative |
| 234 | text (<code>alt</code>) and for video and audio transcripts and captions, if available.</p> |
| 235 | |
| 236 | <p>Providing alternative contents is important for accessibility reasons: A blind |
| 237 | user has few cues to tell what an image is about without <code>@alt</code>, and other users |
| 238 | may have no way of understanding what video or audio contents are about either.</p> |
| 239 | |
| 240 | <p>(For images whose <code>alt</code> attributes would introduce redundancy, and for images |
| 241 | whose purpose is purely decorative which you cannot immediately use CSS for, use |
| 242 | no alternative text, as in <code>alt=""</code>.)</p> |
| 243 | |
| 244 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 245 | <img src="spreadsheet.png"> |
| 246 | </code></pre> |
| 247 | |
| 248 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 249 | <img src="spreadsheet.png" alt="Spreadsheet screenshot."> |
| 250 | </code></pre> |
| 251 | |
| 252 | <h4 id="Separation_of_Concerns">3.1.5 Separation of Concerns</h4> |
| 253 | |
| 254 | <p>Separate structure from presentation from behavior.</p> |
| 255 | |
| 256 | <p>Strictly keep structure (markup), presentation (styling), and behavior |
| 257 | (scripting) apart, and try to keep the interaction between the three to an |
| 258 | absolute minimum.</p> |
| 259 | |
| 260 | <p>That is, make sure documents and templates contain only HTML and HTML that is |
| 261 | solely serving structural purposes. Move everything presentational into style |
| 262 | sheets, and everything behavioral into scripts.</p> |
| 263 | |
| 264 | <p>In addition, keep the contact area as small as possible by linking as few style |
| 265 | sheets and scripts as possible from documents and templates.</p> |
| 266 | |
| 267 | <p>Separating structure from presentation from behavior is important for |
| 268 | maintenance reasons. It is always more expensive to change HTML documents and |
| 269 | templates than it is to update style sheets and scripts.</p> |
| 270 | |
| 271 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 272 | <!DOCTYPE html> |
| 273 | <title>HTML sucks</title> |
| 274 | <link rel="stylesheet" href="base.css" media="screen"> |
| 275 | <link rel="stylesheet" href="grid.css" media="screen"> |
| 276 | <link rel="stylesheet" href="print.css" media="print"> |
| 277 | <h1 style="font-size: 1em;">HTML sucks</h1> |
| 278 | <p>I’ve read about this on a few sites but now I’m sure: |
| 279 | <u>HTML is stupid!!1</u> |
| 280 | <center>I can’t believe there’s no way to control the styling of |
| 281 | my website without doing everything all over again!</center> |
| 282 | </code></pre> |
| 283 | |
| 284 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 285 | <!DOCTYPE html> |
| 286 | <title>My first CSS-only redesign</title> |
| 287 | <link rel="stylesheet" href="default.css"> |
| 288 | <h1>My first CSS-only redesign</h1> |
| 289 | <p>I’ve read about this on a few sites but today I’m actually |
| 290 | doing it: separating concerns and avoiding anything in the HTML of |
| 291 | my website that is presentational. |
| 292 | <p>It’s awesome! |
| 293 | </code></pre> |
| 294 | |
| 295 | <h4 id="Entity_References">3.1.6 Entity References</h4> |
| 296 | |
| 297 | <p>Do not use entity references.</p> |
| 298 | |
| 299 | <p>There is no need to use entity references like <code>&mdash;</code>, <code>&rdquo;</code>, or |
| 300 | <code>&#x263a;</code>, assuming the same encoding (UTF-8) is used for files and editors |
| 301 | as well as among teams.</p> |
| 302 | |
| 303 | <p>The only exceptions apply to characters with special meaning in HTML (like <code><</code> |
| 304 | and <code>&</code>) as well as control or “invisible” characters (like no-break spaces).</p> |
| 305 | |
| 306 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 307 | The currency symbol for the Euro is &ldquo;&eur;&rdquo;. |
| 308 | </code></pre> |
| 309 | |
| 310 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 311 | The currency symbol for the Euro is “€”. |
| 312 | </code></pre> |
| 313 | |
| 314 | <h4 id="Optional_Tags">3.1.7 Optional Tags</h4> |
| 315 | |
| 316 | <p>Omit optional tags (optional).</p> |
| 317 | |
| 318 | <p>For file size optimization and scannability purposes, consider omitting optional |
| 319 | tags. The <a href="https://html.spec.whatwg.org/multipage/syntax.html#syntax-tag-omission">HTML5 specification</a> |
| 320 | defines what tags can be omitted.</p> |
| 321 | |
| 322 | <p>(This approach may require a grace period to be established as a wider guideline |
| 323 | as it’s significantly different from what web developers are typically taught. |
| 324 | For consistency and simplicity reasons it’s best served omitting all optional |
| 325 | tags, not just a selection.)</p> |
| 326 | |
| 327 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 328 | <!DOCTYPE html> |
| 329 | <html> |
| 330 | <head> |
| 331 | <title>Spending money, spending bytes</title> |
| 332 | </head> |
| 333 | <body> |
| 334 | <p>Sic.</p> |
| 335 | </body> |
| 336 | </html> |
| 337 | </code></pre> |
| 338 | |
| 339 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 340 | <!DOCTYPE html> |
| 341 | <title>Saving money, saving bytes</title> |
| 342 | <p>Qed. |
| 343 | </code></pre> |
| 344 | |
| 345 | <h4 id="type_Attributes">3.1.8 <code>type</code> Attributes</h4> |
| 346 | |
| 347 | <p>Omit <code>type</code> attributes for style sheets and scripts.</p> |
| 348 | |
| 349 | <p>Do not use <code>type</code> attributes for style sheets (unless not using CSS) and scripts |
| 350 | (unless not using JavaScript).</p> |
| 351 | |
| 352 | <p>Specifying <code>type</code> attributes in these contexts is not necessary as HTML5 implies |
| 353 | <a href="https://html.spec.whatwg.org/multipage/obsolete.html#attr-style-type"><code>text/css</code></a> |
| 354 | and <a href="https://html.spec.whatwg.org/multipage/scripting.html#attr-script-type"><code>text/javascript</code></a> |
| 355 | as defaults. This can be safely done even for older browsers.</p> |
| 356 | |
| 357 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 358 | <link rel="stylesheet" href="https://www.google.com/css/maia.css" |
| 359 | type="text/css"> |
| 360 | </code></pre> |
| 361 | |
| 362 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 363 | <link rel="stylesheet" href="https://www.google.com/css/maia.css"> |
| 364 | </code></pre> |
| 365 | |
| 366 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 367 | <script src="https://www.google.com/js/gweb/analytics/autotrack.js" |
| 368 | type="text/javascript"></script> |
| 369 | </code></pre> |
| 370 | |
| 371 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 372 | <script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script> |
| 373 | </code></pre> |
| 374 | |
| 375 | <h3 id="HTML_Formatting_Rules">3.2 HTML Formatting Rules</h3> |
| 376 | |
| 377 | <h4 id="General_Formatting">3.2.1 General Formatting</h4> |
| 378 | |
| 379 | <p>Use a new line for every block, list, or table element, and indent every such |
| 380 | child element.</p> |
| 381 | |
| 382 | <p>Independent of the styling of an element (as CSS allows elements to assume a |
| 383 | different role per <code>display</code> property), put every block, list, or table element |
| 384 | on a new line.</p> |
| 385 | |
| 386 | <p>Also, indent them if they are child elements of a block, list, or table element.</p> |
| 387 | |
| 388 | <p>(If you run into issues around whitespace between list items it’s acceptable to |
| 389 | put all <code>li</code> elements in one line. A linter is encouraged to throw a warning |
| 390 | instead of an error.)</p> |
| 391 | |
| 392 | <pre><code class="language-html prettyprint"><blockquote> |
| 393 | <p><em>Space</em>, the final frontier.</p> |
| 394 | </blockquote> |
| 395 | </code></pre> |
| 396 | |
| 397 | <pre><code class="language-html prettyprint"><ul> |
| 398 | <li>Moe |
| 399 | <li>Larry |
| 400 | <li>Curly |
| 401 | </ul> |
| 402 | </code></pre> |
| 403 | |
| 404 | <pre><code class="language-html prettyprint"><table> |
| 405 | <thead> |
| 406 | <tr> |
| 407 | <th scope="col">Income |
| 408 | <th scope="col">Taxes |
| 409 | <tbody> |
| 410 | <tr> |
| 411 | <td>$ 5.00 |
| 412 | <td>$ 4.50 |
| 413 | </table> |
| 414 | </code></pre> |
| 415 | |
| 416 | <h4 id="HTML_Line-Wrapping">3.2.2 HTML Line-Wrapping</h4> |
| 417 | |
| 418 | <p>Break long lines (optional).</p> |
| 419 | |
| 420 | <p>While there is no column limit recommendation for HTML, you may consider |
| 421 | wrapping long lines if it significantly improves readability.</p> |
| 422 | |
| 423 | <p>When line-wrapping, each continuation line should be indented at least 4 |
| 424 | additional spaces from the original line.</p> |
| 425 | |
| 426 | <pre><code class="language-html prettyprint"><md-progress-circular md-mode="indeterminate" class="md-accent" |
| 427 | ng-show="ctrl.loading" md-diameter="35"> |
| 428 | </md-progress-circular> |
| 429 | </code></pre> |
| 430 | |
| 431 | <pre><code class="language-html prettyprint"><md-progress-circular |
| 432 | md-mode="indeterminate" |
| 433 | class="md-accent" |
| 434 | ng-show="ctrl.loading" |
| 435 | md-diameter="35"> |
| 436 | </md-progress-circular> |
| 437 | </code></pre> |
| 438 | |
| 439 | <pre><code class="language-html prettyprint"><md-progress-circular md-mode="indeterminate" |
| 440 | class="md-accent" |
| 441 | ng-show="ctrl.loading" |
| 442 | md-diameter="35"> |
| 443 | </md-progress-circular> |
| 444 | </code></pre> |
| 445 | |
| 446 | <h4 id="HTML_Quotation_Marks">3.2.3 HTML Quotation Marks</h4> |
| 447 | |
| 448 | <p>When quoting attributes values, use double quotation marks.</p> |
| 449 | |
| 450 | <p>Use double (<code>""</code>) rather than single quotation marks (<code>''</code>) around attribute |
| 451 | values.</p> |
| 452 | |
| 453 | <pre><code class="language-html prettyprint badcode"><!-- Not recommended --> |
| 454 | <a class='maia-button maia-button-secondary'>Sign in</a> |
| 455 | </code></pre> |
| 456 | |
| 457 | <pre><code class="language-html prettyprint"><!-- Recommended --> |
| 458 | <a class="maia-button maia-button-secondary">Sign in</a> |
| 459 | </code></pre> |
| 460 | |
| 461 | <h2 id="CSS">4 CSS</h2> |
| 462 | |
| 463 | <h3 id="CSS_Style_Rules">4.1 CSS Style Rules</h3> |
| 464 | |
| 465 | <h4 id="CSS_Validity">4.1.1 CSS Validity</h4> |
| 466 | |
| 467 | <p>Use valid CSS where possible.</p> |
| 468 | |
| 469 | <p>Unless dealing with CSS validator bugs or requiring proprietary syntax, use |
| 470 | valid CSS code.</p> |
| 471 | |
| 472 | <p> |
| 473 | |
| 474 | Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C CSS validator</a> |
| 475 | to test. |
| 476 | </p> |
| 477 | |
| 478 | <p>Using valid CSS is a measurable baseline quality attribute that allows to spot |
| 479 | CSS code that may not have any effect and can be removed, and that ensures |
| 480 | proper CSS usage.</p> |
| 481 | |
| 482 | <h4 id="ID_and_Class_Naming">4.1.2 ID and Class Naming</h4> |
| 483 | |
| 484 | <p>Use meaningful or generic ID and class names.</p> |
| 485 | |
| 486 | <p>Instead of presentational or cryptic names, always use ID and class names that |
| 487 | reflect the purpose of the element in question, or that are otherwise generic.</p> |
| 488 | |
| 489 | <p>Names that are specific and reflect the purpose of the element should be |
| 490 | preferred as these are most understandable and the least likely to change.</p> |
| 491 | |
| 492 | <p>Generic names are simply a fallback for elements that have no particular or no |
| 493 | meaning different from their siblings. They are typically needed as “helpers.”</p> |
| 494 | |
| 495 | <p>Using functional or generic names reduces the probability of unnecessary |
| 496 | document or template changes.</p> |
| 497 | |
| 498 | <pre><code class="language-css prettyprint badcode">/* Not recommended: meaningless */ |
| 499 | #yee-1901 {} |
| 500 | |
| 501 | /* Not recommended: presentational */ |
| 502 | .button-green {} |
| 503 | .clear {} |
| 504 | </code></pre> |
| 505 | |
| 506 | <pre><code class="language-css prettyprint">/* Recommended: specific */ |
| 507 | #gallery {} |
| 508 | #login {} |
| 509 | .video {} |
| 510 | |
| 511 | /* Recommended: generic */ |
| 512 | .aux {} |
| 513 | .alt {} |
| 514 | </code></pre> |
| 515 | |
| 516 | <h4 id="ID_and_Class_Name_Style">4.1.3 ID and Class Name Style</h4> |
| 517 | |
| 518 | <p>Use ID and class names that are as short as possible but as long as necessary.</p> |
| 519 | |
| 520 | <p>Try to convey what an ID or class is about while being as brief as possible.</p> |
| 521 | |
| 522 | <p>Using ID and class names this way contributes to acceptable levels of |
| 523 | understandability and code efficiency.</p> |
| 524 | |
| 525 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 526 | #navigation {} |
| 527 | .atr {} |
| 528 | </code></pre> |
| 529 | |
| 530 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 531 | #nav {} |
| 532 | .author {} |
| 533 | </code></pre> |
| 534 | |
| 535 | <h4 id="Type_Selectors">4.1.4 Type Selectors</h4> |
| 536 | |
| 537 | <p>Avoid qualifying ID and class names with type selectors.</p> |
| 538 | |
| 539 | <p>Unless necessary (for example with helper classes), do not use element names in |
| 540 | conjunction with IDs or classes.</p> |
| 541 | |
| 542 | <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> |
| 543 | |
| 544 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 545 | ul#example {} |
| 546 | div.error {} |
| 547 | </code></pre> |
| 548 | |
| 549 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 550 | #example {} |
| 551 | .error {} |
| 552 | </code></pre> |
| 553 | |
| 554 | <h4 id="Shorthand_Properties">4.1.5 Shorthand Properties</h4> |
| 555 | |
| 556 | <p>Use shorthand properties where possible.</p> |
| 557 | |
| 558 | <p>CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a> |
| 559 | properties (like <code>font</code>) that should be used whenever possible, even in cases |
| 560 | where only one value is explicitly set.</p> |
| 561 | |
| 562 | <p>Using shorthand properties is useful for code efficiency and understandability.</p> |
| 563 | |
| 564 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 565 | border-top-style: none; |
| 566 | font-family: palatino, georgia, serif; |
| 567 | font-size: 100%; |
| 568 | line-height: 1.6; |
| 569 | padding-bottom: 2em; |
| 570 | padding-left: 1em; |
| 571 | padding-right: 1em; |
| 572 | padding-top: 0; |
| 573 | </code></pre> |
| 574 | |
| 575 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 576 | border-top: 0; |
| 577 | font: 100%/1.6 palatino, georgia, serif; |
| 578 | padding: 0 1em 2em; |
| 579 | </code></pre> |
| 580 | |
| 581 | <h4 id="0_and_Units">4.1.6 0 and Units</h4> |
| 582 | |
| 583 | <p>Omit unit specification after “0” values, unless required.</p> |
| 584 | |
| 585 | <p>Do not use units after <code>0</code> values unless they are required.</p> |
| 586 | |
| 587 | <pre><code class="language-css prettyprint">flex: 0px; /* This flex-basis component requires a unit. */ |
| 588 | flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */ |
| 589 | margin: 0; |
| 590 | padding: 0; |
| 591 | </code></pre> |
| 592 | |
| 593 | <h4 id="Leading_0s">4.1.7 Leading 0s</h4> |
| 594 | |
| 595 | <p>Omit leading “0”s in values.</p> |
| 596 | |
| 597 | <p>Do not put <code>0</code>s in front of values or lengths between -1 and 1.</p> |
| 598 | |
| 599 | <pre><code class="language-css prettyprint">font-size: .8em; |
| 600 | </code></pre> |
| 601 | |
| 602 | <h4 id="Hexadecimal_Notation">4.1.8 Hexadecimal Notation</h4> |
| 603 | |
| 604 | <p>Use 3 character hexadecimal notation where possible.</p> |
| 605 | |
| 606 | <p>For color values that permit it, 3 character hexadecimal notation is shorter and |
| 607 | more succinct.</p> |
| 608 | |
| 609 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 610 | color: #eebbcc; |
| 611 | </code></pre> |
| 612 | |
| 613 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 614 | color: #ebc; |
| 615 | </code></pre> |
| 616 | |
| 617 | <h4 id="Prefixes">4.1.9 Prefixes</h4> |
| 618 | |
| 619 | <p>Prefix selectors with an application-specific prefix (optional).</p> |
| 620 | |
| 621 | <p>In large projects as well as for code that gets embedded in other projects or on |
| 622 | external sites use prefixes (as namespaces) for ID and class names. Use short, |
| 623 | unique identifiers followed by a dash.</p> |
| 624 | |
| 625 | <p>Using namespaces helps preventing naming conflicts and can make maintenance |
| 626 | easier, for example in search and replace operations.</p> |
| 627 | |
| 628 | <pre><code class="language-css prettyprint">.adw-help {} /* AdWords */ |
| 629 | #maia-note {} /* Maia */ |
| 630 | </code></pre> |
| 631 | |
| 632 | <h4 id="ID_and_Class_Name_Delimiters">4.1.10 ID and Class Name Delimiters</h4> |
| 633 | |
| 634 | <p>Separate words in ID and class names by a hyphen.</p> |
| 635 | |
| 636 | <p>Do not concatenate words and abbreviations in selectors by any characters |
| 637 | (including none at all) other than hyphens, in order to improve understanding |
| 638 | and scannability.</p> |
| 639 | |
| 640 | <pre><code class="language-css prettyprint badcode">/* Not recommended: does not separate the words “demo” and “image” */ |
| 641 | .demoimage {} |
| 642 | |
| 643 | /* Not recommended: uses underscore instead of hyphen */ |
| 644 | .error_status {} |
| 645 | </code></pre> |
| 646 | |
| 647 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 648 | #video-id {} |
| 649 | .ads-sample {} |
| 650 | </code></pre> |
| 651 | |
| 652 | <h4 id="Hacks">4.1.11 Hacks</h4> |
| 653 | |
| 654 | <p>Avoid user agent detection as well as CSS “hacks”—try a different approach |
| 655 | first.</p> |
| 656 | |
| 657 | <p>It’s tempting to address styling differences over user agent detection or |
| 658 | special CSS filters, workarounds, and hacks. Both approaches should be |
| 659 | considered last resort in order to achieve and maintain an efficient and |
| 660 | manageable code base. Put another way, giving detection and hacks a free pass |
| 661 | will hurt projects in the long run as projects tend to take the way of least |
| 662 | resistance. That is, allowing and making it easy to use detection and hacks |
| 663 | means using detection and hacks more frequently—and more frequently is too |
| 664 | frequently.</p> |
| 665 | |
| 666 | <h3 id="CSS_Formatting_Rules">4.2 CSS Formatting Rules</h3> |
| 667 | |
| 668 | <h4 id="Declaration_Order">4.2.1 Declaration Order</h4> |
| 669 | |
| 670 | <p>Alphabetize declarations.</p> |
| 671 | |
| 672 | <p>Put declarations in alphabetical order in order to achieve consistent code in a |
| 673 | way that is easy to remember and maintain.</p> |
| 674 | |
| 675 | <p>Ignore vendor-specific prefixes for sorting purposes. However, multiple |
| 676 | vendor-specific prefixes for a certain CSS property should be kept sorted (e.g. |
| 677 | -moz prefix comes before -webkit).</p> |
| 678 | |
| 679 | <pre><code class="language-css prettyprint">background: fuchsia; |
| 680 | border: 1px solid; |
| 681 | -moz-border-radius: 4px; |
| 682 | -webkit-border-radius: 4px; |
| 683 | border-radius: 4px; |
| 684 | color: black; |
| 685 | text-align: center; |
| 686 | text-indent: 2em; |
| 687 | </code></pre> |
| 688 | |
| 689 | <h4 id="Block_Content_Indentation">4.2.2 Block Content Indentation</h4> |
| 690 | |
| 691 | <p>Indent all block content.</p> |
| 692 | |
| 693 | <p>Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block content</a>, |
| 694 | that is rules within rules as well as declarations, so to reflect hierarchy and |
| 695 | improve understanding.</p> |
| 696 | |
| 697 | <pre><code class="language-css prettyprint">@media screen, projection { |
| 698 | |
| 699 | html { |
| 700 | background: #fff; |
| 701 | color: #444; |
| 702 | } |
| 703 | |
| 704 | } |
| 705 | </code></pre> |
| 706 | |
| 707 | <h4 id="Declaration_Stops">4.2.3 Declaration Stops</h4> |
| 708 | |
| 709 | <p>Use a semicolon after every declaration.</p> |
| 710 | |
| 711 | <p>End every declaration with a semicolon for consistency and extensibility |
| 712 | reasons.</p> |
| 713 | |
| 714 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 715 | .test { |
| 716 | display: block; |
| 717 | height: 100px |
| 718 | } |
| 719 | </code></pre> |
| 720 | |
| 721 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 722 | .test { |
| 723 | display: block; |
| 724 | height: 100px; |
| 725 | } |
| 726 | </code></pre> |
| 727 | |
| 728 | <h4 id="Property_Name_Stops">4.2.4 Property Name Stops</h4> |
| 729 | |
| 730 | <p>Use a space after a property name’s colon.</p> |
| 731 | |
| 732 | <p>Always use a single space between property and value (but no space between |
| 733 | property and colon) for consistency reasons.</p> |
| 734 | |
| 735 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 736 | h3 { |
| 737 | font-weight:bold; |
| 738 | } |
| 739 | </code></pre> |
| 740 | |
| 741 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 742 | h3 { |
| 743 | font-weight: bold; |
| 744 | } |
| 745 | </code></pre> |
| 746 | |
| 747 | <h4 id="Declaration_Block_Separation">4.2.5 Declaration Block Separation</h4> |
| 748 | |
| 749 | <p>Use a space between the last selector and the declaration block.</p> |
| 750 | |
| 751 | <p>Always use a single space between the last selector and the opening brace that |
| 752 | begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration block</a>.</p> |
| 753 | |
| 754 | <p>The opening brace should be on the same line as the last selector in a given |
| 755 | rule.</p> |
| 756 | |
| 757 | <pre><code class="language-css prettyprint badcode">/* Not recommended: missing space */ |
| 758 | #video{ |
| 759 | margin-top: 1em; |
| 760 | } |
| 761 | |
| 762 | /* Not recommended: unnecessary line break */ |
| 763 | #video |
| 764 | { |
| 765 | margin-top: 1em; |
| 766 | } |
| 767 | </code></pre> |
| 768 | |
| 769 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 770 | #video { |
| 771 | margin-top: 1em; |
| 772 | } |
| 773 | </code></pre> |
| 774 | |
| 775 | <h4 id="Selector_and_Declaration_Separation">4.2.6 Selector and Declaration Separation</h4> |
| 776 | |
| 777 | <p>Separate selectors and declarations by new lines.</p> |
| 778 | |
| 779 | <p>Always start a new line for each selector and declaration.</p> |
| 780 | |
| 781 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 782 | a:focus, a:active { |
| 783 | position: relative; top: 1px; |
| 784 | } |
| 785 | </code></pre> |
| 786 | |
| 787 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 788 | h1, |
| 789 | h2, |
| 790 | h3 { |
| 791 | font-weight: normal; |
| 792 | line-height: 1.2; |
| 793 | } |
| 794 | </code></pre> |
| 795 | |
| 796 | <h4 id="Rule_Separation">4.2.7 Rule Separation</h4> |
| 797 | |
| 798 | <p>Separate rules by new lines.</p> |
| 799 | |
| 800 | <p>Always put a blank line (two line breaks) between rules.</p> |
| 801 | |
| 802 | <pre><code class="language-css prettyprint">html { |
| 803 | background: #fff; |
| 804 | } |
| 805 | |
| 806 | body { |
| 807 | margin: auto; |
| 808 | width: 50%; |
| 809 | } |
| 810 | </code></pre> |
| 811 | |
| 812 | <h4 id="CSS_Quotation_Marks">4.2.8 CSS Quotation Marks</h4> |
| 813 | |
| 814 | <p>Use single (<code>''</code>) rather than double (<code>""</code>) quotation marks for attribute |
| 815 | selectors and property values.</p> |
| 816 | |
| 817 | <p>Do not use quotation marks in URI values (<code>url()</code>).</p> |
| 818 | |
| 819 | <p>Exception: If you do need to use the <code>@charset</code> rule, use double quotation |
| 820 | marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p> |
| 821 | |
| 822 | <pre><code class="language-css prettyprint badcode">/* Not recommended */ |
| 823 | @import url("https://www.google.com/css/maia.css"); |
| 824 | |
| 825 | html { |
| 826 | font-family: "open sans", arial, sans-serif; |
| 827 | } |
| 828 | </code></pre> |
| 829 | |
| 830 | <pre><code class="language-css prettyprint">/* Recommended */ |
| 831 | @import url(https://www.google.com/css/maia.css); |
| 832 | |
| 833 | html { |
| 834 | font-family: 'open sans', arial, sans-serif; |
| 835 | } |
| 836 | </code></pre> |
| 837 | |
| 838 | <h3 id="CSS_Meta_Rules">4.3 CSS Meta Rules</h3> |
| 839 | |
| 840 | <h4 id="Section_Comments">4.3.1 Section Comments</h4> |
| 841 | |
| 842 | <p>Group sections by a section comment (optional).</p> |
| 843 | |
| 844 | <p>If possible, group style sheet sections together by using comments. Separate |
| 845 | sections with new lines.</p> |
| 846 | |
| 847 | <pre><code class="language-css prettyprint">/* Header */ |
| 848 | |
| 849 | #adw-header {} |
| 850 | |
| 851 | /* Footer */ |
| 852 | |
| 853 | #adw-footer {} |
| 854 | |
| 855 | /* Gallery */ |
| 856 | |
| 857 | .adw-gallery {} |
| 858 | </code></pre> |
| 859 | |
| 860 | <h2 id="Parting_Words">Parting Words</h2> |
| 861 | |
| 862 | <p><em>Be consistent.</em></p> |
| 863 | |
| 864 | <p>If you’re editing code, take a few minutes to look at the code around you and |
| 865 | determine its style. If they use spaces around all their arithmetic operators, |
| 866 | you should too. If their comments have little boxes of hash marks around them, |
| 867 | make your comments have little boxes of hash marks around them too.</p> |
| 868 | |
| 869 | <p>The point of having style guidelines is to have a common vocabulary of coding so |
| 870 | people can concentrate on what you’re saying rather than on how you’re saying |
| 871 | it. We present global style rules here so people know the vocabulary, but local |
| 872 | style is also important. If code you add to a file looks drastically different |
| 873 | from the existing code around it, it throws readers out of their rhythm when |
| 874 | they go to read it. Avoid this.</p> |
| 875 | </div> |
| 876 | </body> |
| 877 | </html> |