jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1 | <?xml version="1.0"?> |
jensmeiert@google.com | 864b0dc | 2012-07-17 20:17:21 +0000 | [diff] [blame] | 2 | <?xml-stylesheet type="text/xsl" href="styleguide.xsl"?> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 3 | <GUIDE title="Google HTML/CSS Style Guide"> |
| 4 | <p class="revision"> |
| 5 | |
mark@chromium.org | 5684bbc | 2013-07-12 18:53:13 +0000 | [diff] [blame] | 6 | Revision 2.23 |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 7 | </p> |
| 8 | |
| 9 | <OVERVIEW> |
| 10 | <CATEGORY title="Important Note"> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 11 | <STYLEPOINT title="Displaying Hidden Details in This Guide"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 12 | <SUMMARY> |
| 13 | This style guide contains many details that are initially |
| 14 | hidden from view. They are marked by the triangle icon, which you |
| 15 | see here on your left. Click it now. |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 16 | You should see “Hooray” appear below. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 17 | </SUMMARY> |
| 18 | <BODY> |
| 19 | <p> |
| 20 | Hooray! Now you know you can expand points to get more |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 21 | details. Alternatively, there’s a “toggle all” at the |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 22 | top of this document. |
| 23 | </p> |
| 24 | </BODY> |
| 25 | </STYLEPOINT> |
| 26 | </CATEGORY> |
| 27 | <CATEGORY title="Background"> |
| 28 | |
| 29 | <p> |
| 30 | This document defines formatting and style rules for HTML and |
| 31 | CSS. It aims at improving collaboration, code quality, and |
| 32 | enabling supporting infrastructure. It applies to raw, |
| 33 | working files that use HTML and CSS, including GSS |
| 34 | files. Tools are free to obfuscate, minify, and compile as |
| 35 | long as the general code quality is maintained. |
| 36 | </p> |
| 37 | |
| 38 | |
| 39 | </CATEGORY> |
| 40 | </OVERVIEW> |
| 41 | |
| 42 | <CATEGORY title="General Style Rules"> |
| 43 | <STYLEPOINT title="Protocol"> |
| 44 | <SUMMARY> |
| 45 | Omit the protocol from embedded resources. |
| 46 | </SUMMARY> |
| 47 | <BODY> |
| 48 | <p> |
| 49 | Omit the protocol portion (<code>http:</code>, |
| 50 | <code>https:</code>) from URLs pointing to images and other |
| 51 | media files, style sheets, and scripts unless the respective |
| 52 | files are not available over both protocols. |
| 53 | </p> |
| 54 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 55 | Omitting the protocol—which makes the URL |
| 56 | relative—prevents mixed content issues and results in |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 57 | minor file size savings. |
| 58 | </p> |
| 59 | <BAD_CODE_SNIPPET> |
| 60 | <!-- Not recommended --> |
| 61 | <script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script> |
| 62 | </BAD_CODE_SNIPPET> |
| 63 | <CODE_SNIPPET> |
| 64 | <!-- Recommended --> |
| 65 | <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script> |
| 66 | </CODE_SNIPPET> |
| 67 | <BAD_CODE_SNIPPET> |
| 68 | /* Not recommended */ |
| 69 | .example { |
| 70 | background: url(http://www.google.com/images/example); |
| 71 | } |
| 72 | </BAD_CODE_SNIPPET> |
| 73 | <CODE_SNIPPET> |
| 74 | /* Recommended */ |
| 75 | .example { |
| 76 | background: url(//www.google.com/images/example); |
| 77 | } |
| 78 | </CODE_SNIPPET> |
| 79 | </BODY> |
| 80 | </STYLEPOINT> |
| 81 | |
| 82 | </CATEGORY> |
| 83 | |
| 84 | <CATEGORY title="General Formatting Rules"> |
| 85 | <STYLEPOINT title="Indentation"> |
| 86 | <SUMMARY> |
| 87 | Indent by 2 spaces at a time. |
| 88 | </SUMMARY> |
| 89 | <BODY> |
| 90 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 91 | Don’t use tabs or mix tabs and spaces for indentation. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 92 | </p> |
| 93 | <CODE_SNIPPET> |
| 94 | <ul> |
| 95 | <li>Fantastic |
| 96 | <li>Great |
| 97 | </ul> |
| 98 | </CODE_SNIPPET> |
| 99 | <CODE_SNIPPET> |
| 100 | .example { |
| 101 | color: blue; |
| 102 | } |
| 103 | </CODE_SNIPPET> |
| 104 | </BODY> |
| 105 | </STYLEPOINT> |
| 106 | <STYLEPOINT title="Capitalization"> |
| 107 | <SUMMARY> |
| 108 | Use only lowercase. |
| 109 | </SUMMARY> |
| 110 | <BODY> |
| 111 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 112 | All code has to be lowercase: This applies to HTML element names, |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 113 | attributes, attribute values (unless |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 114 | <code>text/CDATA</code>), CSS selectors, properties, and |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 115 | property values (with the exception of strings). |
| 116 | </p> |
| 117 | <BAD_CODE_SNIPPET> |
| 118 | <!-- Not recommended --> |
| 119 | <A HREF="/">Home</A> |
| 120 | </BAD_CODE_SNIPPET> |
| 121 | <CODE_SNIPPET> |
| 122 | <!-- Recommended --> |
| 123 | <img src="google.png" alt="Google"> |
| 124 | </CODE_SNIPPET> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 125 | <BAD_CODE_SNIPPET> |
| 126 | /* Not recommended */ |
| 127 | color: #E5E5E5; |
| 128 | </BAD_CODE_SNIPPET> |
| 129 | <CODE_SNIPPET> |
| 130 | /* Recommended */ |
| 131 | color: #e5e5e5; |
| 132 | </CODE_SNIPPET> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 133 | </BODY> |
| 134 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 135 | <STYLEPOINT title="Trailing Whitespace"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 136 | <SUMMARY> |
| 137 | Remove trailing white spaces. |
| 138 | </SUMMARY> |
| 139 | <BODY> |
| 140 | <p> |
| 141 | Trailing white spaces are unnecessary and can complicate |
| 142 | diffs. |
| 143 | </p> |
| 144 | <BAD_CODE_SNIPPET> |
| 145 | <!-- Not recommended --> |
| 146 | <p>What?_ |
| 147 | </BAD_CODE_SNIPPET> |
| 148 | <CODE_SNIPPET> |
| 149 | <!-- Recommended --> |
| 150 | <p>Yes please. |
| 151 | </CODE_SNIPPET> |
| 152 | </BODY> |
| 153 | </STYLEPOINT> |
| 154 | </CATEGORY> |
| 155 | |
| 156 | <CATEGORY title="General Meta Rules"> |
| 157 | <STYLEPOINT title="Encoding"> |
| 158 | <SUMMARY> |
| 159 | Use UTF-8 (no BOM). |
| 160 | </SUMMARY> |
| 161 | <BODY> |
| 162 | <p> |
| 163 | Make sure your editor uses UTF-8 as character encoding, |
| 164 | without a byte order mark. |
| 165 | </p> |
| 166 | <p> |
| 167 | Specify the encoding in HTML templates and documents via |
| 168 | <code><meta charset="utf-8"></code>. Do not specify |
| 169 | the encoding of style sheets as these assume UTF-8. |
| 170 | </p> |
| 171 | <p> |
| 172 | (More on encodings and when and how to specify them can be |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 173 | found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/">Handling |
| 174 | character encodings in HTML and CSS</a>.) |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 175 | </p> |
| 176 | </BODY> |
| 177 | </STYLEPOINT> |
| 178 | <STYLEPOINT title="Comments"> |
| 179 | <SUMMARY> |
| 180 | Explain code as needed, where possible. |
| 181 | </SUMMARY> |
| 182 | <BODY> |
| 183 | <p> |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 184 | Use comments to explain code: What does it cover, what |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 185 | purpose does it serve, why is respective solution used or |
| 186 | preferred? |
| 187 | </p> |
| 188 | <p> |
| 189 | (This item is optional as it is not deemed a realistic |
| 190 | expectation to always demand fully documented code. Mileage |
| 191 | may vary heavily for HTML and CSS code and depends on the |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 192 | project’s complexity.) |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 193 | </p> |
| 194 | </BODY> |
| 195 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 196 | <STYLEPOINT title="Action Items"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 197 | <SUMMARY> |
| 198 | Mark todos and action items with <code>TODO</code>. |
| 199 | </SUMMARY> |
| 200 | <BODY> |
| 201 | <p> |
| 202 | Highlight todos by using the keyword <code>TODO</code> only, |
| 203 | not other common formats like <code>@@</code>. |
| 204 | </p> |
| 205 | <p> |
| 206 | Append a contact (username or mailing list) in parentheses |
| 207 | as with the format <code>TODO(contact)</code>. |
| 208 | </p> |
| 209 | <p> |
| 210 | Append action items after a colon as in <code>TODO: action |
| 211 | item</code>. |
| 212 | </p> |
| 213 | |
| 214 | <CODE_SNIPPET> |
| 215 | {# TODO(john.doe): revisit centering #} |
| 216 | <center>Test</center> |
| 217 | </CODE_SNIPPET> |
| 218 | |
| 219 | <CODE_SNIPPET> |
| 220 | <!-- TODO: remove optional tags --> |
| 221 | <ul> |
| 222 | <li>Apples</li> |
| 223 | <li>Oranges</li> |
| 224 | </ul> |
| 225 | </CODE_SNIPPET> |
| 226 | </BODY> |
| 227 | </STYLEPOINT> |
| 228 | </CATEGORY> |
| 229 | |
| 230 | <CATEGORY title="HTML Style Rules"> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 231 | <STYLEPOINT title="Document Type"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 232 | <SUMMARY> |
| 233 | Use HTML5. |
| 234 | </SUMMARY> |
| 235 | <BODY> |
| 236 | <p> |
| 237 | HTML5 (HTML syntax) is preferred for all HTML documents: |
| 238 | <code><!DOCTYPE html></code>. |
| 239 | </p> |
| 240 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 241 | (It’s recommended to use HTML, as <code>text/html</code>. Do not use |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 242 | XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, |
| 243 | lacks both browser and infrastructure support and offers |
| 244 | less room for optimization than HTML.) |
| 245 | </p> |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 246 | <p> |
| 247 | Although fine with HTML, do not close void elements, i.e. write |
| 248 | <code><br></code>, not <code><br /></code>. |
| 249 | </p> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 250 | </BODY> |
| 251 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 252 | <STYLEPOINT title="HTML Validity"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 253 | <SUMMARY> |
| 254 | Use valid HTML where possible. |
| 255 | </SUMMARY> |
| 256 | <BODY> |
| 257 | <p> |
| 258 | Use valid HTML code unless that is not possible due to |
| 259 | otherwise unattainable performance goals regarding file size. |
| 260 | </p> |
| 261 | |
| 262 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 263 | Use tools such as the <a href="http://validator.w3.org/nu/">W3C |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 264 | HTML validator</a> to test. |
| 265 | </p> |
| 266 | <p> |
| 267 | Using valid HTML is a measurable baseline quality attribute |
| 268 | that contributes to learning about technical requirements |
| 269 | and constraints, and that ensures proper HTML usage. |
| 270 | </p> |
| 271 | <BAD_CODE_SNIPPET> |
| 272 | <!-- Not recommended --> |
| 273 | <title>Test</title> |
| 274 | <article>This is only a test. |
| 275 | </BAD_CODE_SNIPPET> |
| 276 | <CODE_SNIPPET> |
| 277 | <!-- Recommended --> |
| 278 | <!DOCTYPE html> |
| 279 | <meta charset="utf-8"> |
| 280 | <title>Test</title> |
| 281 | <article>This is only a test.</article> |
| 282 | </CODE_SNIPPET> |
| 283 | </BODY> |
| 284 | </STYLEPOINT> |
| 285 | <STYLEPOINT title="Semantics"> |
| 286 | <SUMMARY> |
| 287 | Use HTML according to its purpose. |
| 288 | </SUMMARY> |
| 289 | <BODY> |
| 290 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 291 | Use elements (sometimes incorrectly called “tags”) for what |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 292 | they have been created for. For example, use heading |
| 293 | elements for headings, <code>p</code> elements for |
| 294 | paragraphs, <code>a</code> elements for anchors, etc. |
| 295 | </p> |
| 296 | <p> |
| 297 | Using HTML according to its purpose is important for |
| 298 | accessibility, reuse, and code efficiency reasons. |
| 299 | </p> |
| 300 | |
| 301 | <BAD_CODE_SNIPPET> |
| 302 | <!-- Not recommended --> |
| 303 | <div onclick="goToRecommendations();">All recommendations</div> |
| 304 | </BAD_CODE_SNIPPET> |
| 305 | <CODE_SNIPPET> |
| 306 | <!-- Recommended --> |
| 307 | <a href="recommendations/">All recommendations</a> |
| 308 | </CODE_SNIPPET> |
| 309 | </BODY> |
| 310 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 311 | <STYLEPOINT title="Multimedia Fallback"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 312 | <SUMMARY> |
| 313 | Provide alternative contents for multimedia. |
| 314 | </SUMMARY> |
| 315 | <BODY> |
| 316 | <p> |
| 317 | For multimedia, such as images, videos, animated objects via |
| 318 | <code>canvas</code>, make sure to offer alternative |
| 319 | access. For images that means use of meaningful alternative |
| 320 | text (<code>alt</code>) and for video and audio transcripts |
| 321 | and captions, if available. |
| 322 | </p> |
| 323 | <p> |
| 324 | Providing alternative contents is important for |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 325 | accessibility reasons: A blind user has few cues to tell |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 326 | what an image is about without <code>@alt</code>, and other |
| 327 | users may have no way of understanding what video or audio |
| 328 | contents are about either. |
| 329 | </p> |
| 330 | <p> |
| 331 | (For images whose <code>alt</code> attributes would |
| 332 | introduce redundancy, and for images whose purpose is purely |
| 333 | decorative which you cannot immediately use CSS for, use no |
| 334 | alternative text, as in <code>alt=""</code>.) |
| 335 | </p> |
| 336 | |
| 337 | <BAD_CODE_SNIPPET> |
| 338 | <!-- Not recommended --> |
| 339 | <img src="spreadsheet.png"> |
| 340 | </BAD_CODE_SNIPPET> |
| 341 | <CODE_SNIPPET> |
| 342 | <!-- Recommended --> |
| 343 | <img src="spreadsheet.png" alt="Spreadsheet screenshot."> |
| 344 | </CODE_SNIPPET> |
| 345 | </BODY> |
| 346 | </STYLEPOINT> |
| 347 | |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 348 | <STYLEPOINT title="Separation of Concerns"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 349 | <SUMMARY> |
| 350 | Separate structure from presentation from behavior. |
| 351 | </SUMMARY> |
| 352 | <BODY> |
| 353 | <p> |
| 354 | Strictly keep structure (markup), presentation (styling), |
| 355 | and behavior (scripting) apart, and try to keep the |
| 356 | interaction between the three to an absolute minimum. |
| 357 | </p> |
| 358 | <p> |
| 359 | That is, make sure documents and templates contain only HTML |
| 360 | and HTML that is solely serving structural purposes. Move |
| 361 | everything presentational into style sheets, and everything |
| 362 | behavioral into scripts. |
| 363 | </p> |
| 364 | <p> |
| 365 | In addition, keep the contact area as small as possible by |
| 366 | linking as few style sheets and scripts as possible from |
| 367 | documents and templates. |
| 368 | </p> |
| 369 | <p> |
| 370 | Separating structure from presentation from behavior is |
| 371 | important for maintenance reasons. It is always more |
| 372 | expensive to change HTML documents and templates than it is |
| 373 | to update style sheets and scripts. |
| 374 | </p> |
| 375 | |
| 376 | <BAD_CODE_SNIPPET> |
| 377 | <!-- Not recommended --> |
| 378 | <!DOCTYPE html> |
| 379 | <title>HTML sucks</title> |
| 380 | <link rel="stylesheet" href="base.css" media="screen"> |
| 381 | <link rel="stylesheet" href="grid.css" media="screen"> |
| 382 | <link rel="stylesheet" href="print.css" media="print"> |
| 383 | <h1 style="font-size: 1em;">HTML sucks</h1> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 384 | <p>I’ve read about this on a few sites but now I’m sure: |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 385 | <u>HTML is stupid!!1</u> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 386 | <center>I can’t believe there’s no way to control the styling of |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 387 | my website without doing everything all over again!</center> |
| 388 | </BAD_CODE_SNIPPET> |
| 389 | <CODE_SNIPPET> |
| 390 | <!-- Recommended --> |
| 391 | <!DOCTYPE html> |
| 392 | <title>My first CSS-only redesign</title> |
| 393 | <link rel="stylesheet" href="default.css"> |
| 394 | <h1>My first CSS-only redesign</h1> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 395 | <p>I’ve read about this on a few sites but today I’m actually |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 396 | doing it: separating concerns and avoiding anything in the HTML of |
| 397 | my website that is presentational. |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 398 | <p>It’s awesome! |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 399 | </CODE_SNIPPET> |
| 400 | </BODY> |
| 401 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 402 | <STYLEPOINT title="Entity References"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 403 | <SUMMARY> |
| 404 | Do not use entity references. |
| 405 | </SUMMARY> |
| 406 | <BODY> |
| 407 | <p> |
| 408 | There is no need to use entity references like |
| 409 | <code>&mdash;</code>, <code>&rdquo;</code>, or |
| 410 | <code>&#x263a;</code>, assuming the same encoding |
| 411 | (UTF-8) is used for files and editors as well as among |
| 412 | teams. |
| 413 | </p> |
| 414 | <p> |
| 415 | The only exceptions apply to characters with special meaning |
| 416 | in HTML (like <code><</code> and <code>&</code>) as |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 417 | well as control or “invisible” characters (like no-break |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 418 | spaces). |
| 419 | </p> |
| 420 | <BAD_CODE_SNIPPET> |
| 421 | <!-- Not recommended --> |
| 422 | The currency symbol for the Euro is &ldquo;&eur;&rdquo;. |
| 423 | </BAD_CODE_SNIPPET> |
| 424 | <CODE_SNIPPET> |
| 425 | <!-- Recommended --> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 426 | The currency symbol for the Euro is “€”. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 427 | </CODE_SNIPPET> |
| 428 | </BODY> |
| 429 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 430 | <STYLEPOINT title="Optional Tags"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 431 | <SUMMARY> |
| 432 | Omit optional tags (optional). |
| 433 | </SUMMARY> |
| 434 | <BODY> |
| 435 | <p> |
| 436 | For file size optimization and scannability purposes, |
| 437 | consider omitting optional tags. |
| 438 | The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5 |
| 439 | specification</a> defines what tags can be omitted. |
| 440 | </p> |
| 441 | <p> |
| 442 | (This approach may require a grace period to be established |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 443 | as a wider guideline as it’s significantly different |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 444 | from what web developers are typically taught. For |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 445 | consistency and simplicity reasons it’s best served |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 446 | omitting all optional tags, not just a selection.) |
| 447 | </p> |
| 448 | <BAD_CODE_SNIPPET> |
| 449 | <!-- Not recommended --> |
| 450 | <!DOCTYPE html> |
| 451 | <html> |
| 452 | <head> |
| 453 | <title>Spending money, spending bytes</title> |
| 454 | </head> |
| 455 | <body> |
| 456 | <p>Sic.</p> |
| 457 | </body> |
| 458 | </html> |
| 459 | </BAD_CODE_SNIPPET> |
| 460 | <CODE_SNIPPET> |
| 461 | <!-- Recommended --> |
| 462 | <!DOCTYPE html> |
| 463 | <title>Saving money, saving bytes</title> |
| 464 | <p>Qed. |
| 465 | </CODE_SNIPPET> |
| 466 | </BODY> |
| 467 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 468 | <STYLEPOINT title="type Attributes"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 469 | <SUMMARY> |
| 470 | Omit <code>type</code> attributes for style sheets and scripts. |
| 471 | </SUMMARY> |
| 472 | <BODY> |
| 473 | <p> |
| 474 | Do not use <code>type</code> attributes for style sheets |
| 475 | (unless not using CSS) and scripts (unless not using |
| 476 | JavaScript). |
| 477 | </p> |
| 478 | <p> |
| 479 | Specifying <code>type</code> attributes in these contexts is |
| 480 | not necessary as HTML5 implies |
| 481 | <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a> |
| 482 | and |
| 483 | <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a> |
| 484 | as defaults. This can be safely done even for older browsers. |
| 485 | </p> |
| 486 | <BAD_CODE_SNIPPET> |
| 487 | <!-- Not recommended --> |
| 488 | <link rel="stylesheet" href="//www.google.com/css/maia.css" |
| 489 | type="text/css"> |
| 490 | </BAD_CODE_SNIPPET> |
| 491 | <CODE_SNIPPET> |
| 492 | <!-- Recommended --> |
| 493 | <link rel="stylesheet" href="//www.google.com/css/maia.css"> |
| 494 | </CODE_SNIPPET> |
| 495 | <BAD_CODE_SNIPPET> |
| 496 | <!-- Not recommended --> |
| 497 | <script src="//www.google.com/js/gweb/analytics/autotrack.js" |
| 498 | type="text/javascript"></script> |
| 499 | </BAD_CODE_SNIPPET> |
| 500 | <CODE_SNIPPET> |
| 501 | <!-- Recommended --> |
| 502 | <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script> |
| 503 | </CODE_SNIPPET> |
| 504 | </BODY> |
| 505 | </STYLEPOINT> |
| 506 | </CATEGORY> |
| 507 | |
| 508 | <CATEGORY title="HTML Formatting Rules"> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 509 | <STYLEPOINT title="General Formatting"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 510 | <SUMMARY> |
| 511 | Use a new line for every block, list, or table element, and |
| 512 | indent every such child element. |
| 513 | </SUMMARY> |
| 514 | <BODY> |
| 515 | <p> |
| 516 | Independent of the styling of an element (as CSS allows |
| 517 | elements to assume a different role per <code>display</code> |
| 518 | property), put every block, list, or table element on a new |
| 519 | line. |
| 520 | </p> |
| 521 | <p> |
| 522 | Also, indent them if they are child elements of a block, |
| 523 | list, or table element. |
| 524 | </p> |
| 525 | <p> |
| 526 | (If you run into issues around whitespace between list items |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 527 | it’s acceptable to put all <code>li</code> elements in one |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 528 | line. A linter is encouraged to throw a warning instead of |
| 529 | an error.) |
| 530 | </p> |
| 531 | <CODE_SNIPPET> |
| 532 | <blockquote> |
| 533 | <p><em>Space</em>, the final frontier.</p> |
| 534 | </blockquote> |
| 535 | </CODE_SNIPPET> |
| 536 | <CODE_SNIPPET> |
| 537 | <ul> |
| 538 | <li>Moe |
| 539 | <li>Larry |
| 540 | <li>Curly |
| 541 | </ul> |
| 542 | </CODE_SNIPPET> |
| 543 | <CODE_SNIPPET> |
| 544 | <table> |
| 545 | <thead> |
| 546 | <tr> |
| 547 | <th scope="col">Income |
| 548 | <th scope="col">Taxes |
| 549 | <tbody> |
| 550 | <tr> |
| 551 | <td>$ 5.00 |
| 552 | <td>$ 4.50 |
| 553 | </table> |
| 554 | </CODE_SNIPPET> |
| 555 | </BODY> |
| 556 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 557 | <STYLEPOINT title="HTML Quotation Marks"> |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 558 | <SUMMARY> |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 559 | When quoting attributes values, use double quotation marks. |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 560 | </SUMMARY> |
| 561 | <BODY> |
| 562 | <p> |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 563 | Use double (<code>""</code>) rather than single quotation marks |
| 564 | (<code>''</code>) around attribute values. |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 565 | </p> |
| 566 | <BAD_CODE_SNIPPET> |
| 567 | <!-- Not recommended --> |
| 568 | <a class='maia-button maia-button-secondary'>Sign in</a> |
| 569 | </BAD_CODE_SNIPPET> |
| 570 | <CODE_SNIPPET> |
| 571 | <!-- Recommended --> |
| 572 | <a class="maia-button maia-button-secondary">Sign in</a> |
| 573 | </CODE_SNIPPET> |
| 574 | </BODY> |
| 575 | </STYLEPOINT> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 576 | </CATEGORY> |
| 577 | |
| 578 | <CATEGORY title="CSS Style Rules"> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 579 | <STYLEPOINT title="CSS Validity"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 580 | <SUMMARY> |
| 581 | Use valid CSS where possible. |
| 582 | </SUMMARY> |
| 583 | <BODY> |
| 584 | <p> |
| 585 | Unless dealing with CSS validator bugs or requiring |
| 586 | proprietary syntax, use valid CSS code. |
| 587 | </p> |
| 588 | |
| 589 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 590 | Use tools such as the <a href="http://jigsaw.w3.org/css-validator/">W3C |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 591 | CSS validator</a> to test. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 592 | </p> |
| 593 | <p> |
| 594 | Using valid CSS is a measurable baseline quality attribute |
| 595 | that allows to spot CSS code that may not have any effect |
| 596 | and can be removed, and that ensures proper CSS usage. |
| 597 | </p> |
| 598 | </BODY> |
| 599 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 600 | <STYLEPOINT title="ID and Class Naming"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 601 | <SUMMARY> |
| 602 | Use meaningful or generic ID and class names. |
| 603 | </SUMMARY> |
| 604 | <BODY> |
| 605 | <p> |
| 606 | Instead of presentational or cryptic names, always use ID |
| 607 | and class names that reflect the purpose of the element in |
| 608 | question, or that are otherwise generic. |
| 609 | </p> |
| 610 | <p> |
| 611 | Names that are specific and reflect the purpose of the |
| 612 | element should be preferred as these are most understandable |
| 613 | and the least likely to change. |
| 614 | </p> |
| 615 | <p> |
| 616 | Generic names are simply a fallback for elements that have no |
| 617 | particular or no meaning different from their siblings. They are |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 618 | typically needed as “helpers.” |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 619 | </p> |
| 620 | <p> |
| 621 | Using functional or generic names reduces the probability of |
| 622 | unnecessary document or template changes. |
| 623 | </p> |
| 624 | <BAD_CODE_SNIPPET> |
| 625 | /* Not recommended: meaningless */ |
| 626 | #yee-1901 {} |
| 627 | |
| 628 | /* Not recommended: presentational */ |
| 629 | .button-green {} |
| 630 | .clear {} |
| 631 | </BAD_CODE_SNIPPET> |
| 632 | <CODE_SNIPPET> |
| 633 | /* Recommended: specific */ |
| 634 | #gallery {} |
| 635 | #login {} |
| 636 | .video {} |
| 637 | |
| 638 | /* Recommended: generic */ |
| 639 | .aux {} |
| 640 | .alt {} |
| 641 | </CODE_SNIPPET> |
| 642 | </BODY> |
| 643 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 644 | <STYLEPOINT title="ID and Class Name Style"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 645 | <SUMMARY> |
| 646 | Use ID and class names that are as short as possible but as long as |
| 647 | necessary. |
| 648 | </SUMMARY> |
| 649 | <BODY> |
| 650 | <p> |
| 651 | Try to convey what an ID or class is about while being as |
| 652 | brief as possible. |
| 653 | </p> |
| 654 | <p> |
| 655 | Using ID and class names this way contributes to acceptable |
| 656 | levels of understandability and code efficiency. |
| 657 | </p> |
| 658 | <BAD_CODE_SNIPPET> |
| 659 | /* Not recommended */ |
| 660 | #navigation {} |
| 661 | .atr {} |
| 662 | </BAD_CODE_SNIPPET> |
| 663 | <CODE_SNIPPET> |
| 664 | /* Recommended */ |
| 665 | #nav {} |
| 666 | .author {} |
| 667 | </CODE_SNIPPET> |
| 668 | </BODY> |
| 669 | </STYLEPOINT> |
| 670 | |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 671 | <STYLEPOINT title="Type Selectors"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 672 | <SUMMARY> |
| 673 | Avoid qualifying ID and class names with type selectors. |
| 674 | </SUMMARY> |
| 675 | <BODY> |
| 676 | <p>Unless necessary (for example with helper classes), do not |
| 677 | use element names in conjunction with IDs or classes. |
| 678 | </p> |
| 679 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 680 | Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 681 | reasons</a>. |
| 682 | </p> |
| 683 | <BAD_CODE_SNIPPET> |
| 684 | /* Not recommended */ |
| 685 | ul#example {} |
| 686 | div.error {} |
| 687 | </BAD_CODE_SNIPPET> |
| 688 | <CODE_SNIPPET> |
| 689 | /* Recommended */ |
| 690 | #example {} |
| 691 | .error {} |
| 692 | </CODE_SNIPPET> |
| 693 | </BODY> |
| 694 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 695 | <STYLEPOINT title="Shorthand Properties"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 696 | <SUMMARY> |
| 697 | Use shorthand properties where possible. |
| 698 | </SUMMARY> |
| 699 | <BODY> |
| 700 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 701 | CSS offers a variety of <a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 702 | properties (like <code>font</code>) |
| 703 | that should be used whenever possible, even in cases where |
| 704 | only one value is explicitly set. |
| 705 | </p> |
| 706 | <p> |
| 707 | Using shorthand properties is useful for code efficiency and |
| 708 | understandability. |
| 709 | </p> |
| 710 | <BAD_CODE_SNIPPET> |
| 711 | /* Not recommended */ |
| 712 | border-top-style: none; |
| 713 | font-family: palatino, georgia, serif; |
| 714 | font-size: 100%; |
| 715 | line-height: 1.6; |
| 716 | padding-bottom: 2em; |
| 717 | padding-left: 1em; |
| 718 | padding-right: 1em; |
| 719 | padding-top: 0; |
| 720 | </BAD_CODE_SNIPPET> |
| 721 | <CODE_SNIPPET> |
| 722 | /* Recommended */ |
| 723 | border-top: 0; |
| 724 | font: 100%/1.6 palatino, georgia, serif; |
| 725 | padding: 0 1em 2em; |
| 726 | </CODE_SNIPPET> |
| 727 | </BODY> |
| 728 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 729 | <STYLEPOINT title="0 and Units"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 730 | <SUMMARY> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 731 | Omit unit specification after “0” values. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 732 | </SUMMARY> |
| 733 | <BODY> |
| 734 | <p> |
| 735 | Do not use units after <code>0</code> values unless they are |
| 736 | required. |
| 737 | </p> |
| 738 | <CODE_SNIPPET> |
| 739 | margin: 0; |
| 740 | padding: 0; |
| 741 | </CODE_SNIPPET> |
| 742 | </BODY> |
| 743 | </STYLEPOINT> |
| 744 | <STYLEPOINT title="Leading 0s"> |
| 745 | <SUMMARY> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 746 | Omit leading “0”s in values. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 747 | </SUMMARY> |
| 748 | <BODY> |
| 749 | <p> |
| 750 | Do not use put <code>0</code>s in front of values or lengths |
| 751 | between -1 and 1. |
| 752 | </p> |
| 753 | <CODE_SNIPPET> |
| 754 | font-size: .8em; |
| 755 | </CODE_SNIPPET> |
| 756 | </BODY> |
| 757 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 758 | <STYLEPOINT title="Hexadecimal Notation"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 759 | <SUMMARY> |
| 760 | Use 3 character hexadecimal notation where possible. |
| 761 | </SUMMARY> |
| 762 | <BODY> |
| 763 | <p> |
| 764 | For color values that permit it, 3 character hexadecimal |
| 765 | notation is shorter and more succinct. |
| 766 | </p> |
| 767 | <BAD_CODE_SNIPPET> |
| 768 | /* Not recommended */ |
| 769 | color: #eebbcc; |
| 770 | </BAD_CODE_SNIPPET> |
| 771 | <CODE_SNIPPET> |
| 772 | /* Recommended */ |
| 773 | color: #ebc; |
| 774 | </CODE_SNIPPET> |
| 775 | </BODY> |
| 776 | </STYLEPOINT> |
| 777 | <STYLEPOINT title="Prefixes"> |
| 778 | <SUMMARY> |
| 779 | Prefix selectors with an application-specific prefix (optional). |
| 780 | </SUMMARY> |
| 781 | <BODY> |
| 782 | <p> |
| 783 | In large projects as well as for code that gets embedded in |
| 784 | other projects or on external sites use prefixes (as |
| 785 | namespaces) for ID and class names. Use short, unique |
| 786 | identifiers followed by a dash. |
| 787 | </p> |
| 788 | |
| 789 | |
| 790 | <p> |
| 791 | Using namespaces helps preventing naming conflicts and can |
| 792 | make maintenance easier, for example in search and replace |
| 793 | operations. |
| 794 | </p> |
| 795 | <CODE_SNIPPET> |
| 796 | .adw-help {} /* AdWords */ |
| 797 | #maia-note {} /* Maia */ |
| 798 | </CODE_SNIPPET> |
| 799 | </BODY> |
| 800 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 801 | <STYLEPOINT title="ID and Class Name Delimiters"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 802 | <SUMMARY> |
| 803 | Separate words in ID and class names by a hyphen. |
| 804 | </SUMMARY> |
| 805 | <BODY> |
| 806 | <p> |
| 807 | Do not concatenate words and abbreviations in selectors by |
| 808 | any characters (including none at all) other than hyphens, |
| 809 | in order to improve understanding and scannability. |
| 810 | </p> |
| 811 | <BAD_CODE_SNIPPET> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 812 | /* Not recommended: does not separate the words “demo” and “image” */ |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 813 | .demoimage {} |
| 814 | |
| 815 | /* Not recommended: uses underscore instead of hyphen */ |
| 816 | .error_status {} |
| 817 | </BAD_CODE_SNIPPET> |
| 818 | <CODE_SNIPPET> |
| 819 | /* Recommended */ |
| 820 | #video-id {} |
| 821 | .ads-sample {} |
| 822 | </CODE_SNIPPET> |
| 823 | </BODY> |
| 824 | </STYLEPOINT> |
| 825 | <STYLEPOINT title="Hacks"> |
| 826 | <SUMMARY> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 827 | Avoid user agent detection as well as CSS “hacks”—try a different |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 828 | approach first. |
| 829 | </SUMMARY> |
| 830 | <BODY> |
| 831 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 832 | It’s tempting to address styling differences over user |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 833 | agent detection or special CSS filters, workarounds, and |
| 834 | hacks. Both approaches should be considered last resort in |
| 835 | order to achieve and maintain an efficient and manageable |
| 836 | code base. Put another way, giving detection and hacks a |
| 837 | free pass will hurt projects in the long run as projects |
| 838 | tend to take the way of least resistance. That is, allowing |
| 839 | and making it easy to use detection and hacks means using |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 840 | detection and hacks more frequently—and more frequently |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 841 | is too frequently. |
| 842 | </p> |
| 843 | |
| 844 | |
| 845 | </BODY> |
| 846 | </STYLEPOINT> |
| 847 | </CATEGORY> |
| 848 | |
| 849 | <CATEGORY title="CSS Formatting Rules"> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 850 | <STYLEPOINT title="Declaration Order"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 851 | <SUMMARY> |
| 852 | Alphabetize declarations. |
| 853 | </SUMMARY> |
| 854 | <BODY> |
| 855 | <p> |
| 856 | Put declarations in alphabetical order in order to achieve |
| 857 | consistent code in a way that is easy to remember and |
| 858 | maintain. |
| 859 | </p> |
| 860 | <p> |
| 861 | Ignore vendor-specific prefixes for sorting purposes. However, |
| 862 | multiple vendor-specific prefixes for a certain CSS property should |
| 863 | be kept sorted (e.g. -moz prefix comes before -webkit). |
| 864 | </p> |
| 865 | <CODE_SNIPPET> |
| 866 | background: fuchsia; |
| 867 | border: 1px solid; |
| 868 | -moz-border-radius: 4px; |
| 869 | -webkit-border-radius: 4px; |
| 870 | border-radius: 4px; |
| 871 | color: black; |
| 872 | text-align: center; |
| 873 | text-indent: 2em; |
| 874 | </CODE_SNIPPET> |
| 875 | </BODY> |
| 876 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 877 | <STYLEPOINT title="Block Content Indentation"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 878 | <SUMMARY> |
| 879 | Indent all block content. |
| 880 | </SUMMARY> |
| 881 | <BODY> |
| 882 | <p> |
| 883 | Indent all <a href="http://www.w3.org/TR/CSS21/syndata.html#block">block |
| 884 | content</a>, that is rules within rules as well as declarations, so to |
| 885 | reflect hierarchy and improve understanding. |
| 886 | </p> |
| 887 | <CODE_SNIPPET> |
| 888 | @media screen, projection { |
| 889 | |
| 890 | html { |
| 891 | background: #fff; |
| 892 | color: #444; |
| 893 | } |
| 894 | |
| 895 | } |
| 896 | </CODE_SNIPPET> |
| 897 | </BODY> |
| 898 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 899 | <STYLEPOINT title="Declaration Stops"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 900 | <SUMMARY> |
| 901 | Use a semicolon after every declaration. |
| 902 | </SUMMARY> |
| 903 | <BODY> |
| 904 | <p> |
| 905 | End every declaration with a semicolon for consistency and |
| 906 | extensibility reasons. |
| 907 | </p> |
| 908 | <BAD_CODE_SNIPPET> |
| 909 | /* Not recommended */ |
| 910 | .test { |
| 911 | display: block; |
| 912 | height: 100px |
| 913 | } |
| 914 | </BAD_CODE_SNIPPET> |
| 915 | <CODE_SNIPPET> |
| 916 | /* Recommended */ |
| 917 | .test { |
| 918 | display: block; |
| 919 | height: 100px; |
| 920 | } |
| 921 | </CODE_SNIPPET> |
| 922 | </BODY> |
| 923 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 924 | <STYLEPOINT title="Property Name Stops"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 925 | <SUMMARY> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 926 | Use a space after a property name’s colon. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 927 | </SUMMARY> |
| 928 | <BODY> |
| 929 | <p> |
| 930 | Always use a single space between property and value (but no |
| 931 | space between property and colon) for consistency reasons. |
| 932 | </p> |
| 933 | <BAD_CODE_SNIPPET> |
| 934 | /* Not recommended */ |
| 935 | h3 { |
| 936 | font-weight:bold; |
| 937 | } |
| 938 | </BAD_CODE_SNIPPET> |
| 939 | <CODE_SNIPPET> |
| 940 | /* Recommended */ |
| 941 | h3 { |
| 942 | font-weight: bold; |
| 943 | } |
| 944 | </CODE_SNIPPET> |
| 945 | </BODY> |
| 946 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 947 | <STYLEPOINT title="Declaration Block Separation"> |
| 948 | <SUMMARY> |
| 949 | Use a space between the last selector and the declaration block. |
| 950 | </SUMMARY> |
| 951 | <BODY> |
| 952 | <p> |
| 953 | Always use a single space between the last selector and the opening |
| 954 | brace that begins the <a href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration |
| 955 | block</a>. |
| 956 | </p> |
| 957 | <p> |
| 958 | The opening brace should be on the same line as the last selector in a |
| 959 | given rule. |
| 960 | </p> |
| 961 | <BAD_CODE_SNIPPET> |
| 962 | /* Not recommended: missing space */ |
| 963 | #video{ |
| 964 | margin-top: 1em; |
| 965 | } |
| 966 | |
| 967 | /* Not recommended: unnecessary line break */ |
| 968 | #video |
| 969 | { |
| 970 | margin-top: 1em; |
| 971 | } |
| 972 | </BAD_CODE_SNIPPET> |
| 973 | <CODE_SNIPPET> |
| 974 | /* Recommended */ |
| 975 | #video { |
| 976 | margin-top: 1em; |
| 977 | } |
| 978 | </CODE_SNIPPET> |
| 979 | </BODY> |
| 980 | </STYLEPOINT> |
| 981 | <STYLEPOINT title="Selector and Declaration Separation"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 982 | <SUMMARY> |
| 983 | Separate selectors and declarations by new lines. |
| 984 | </SUMMARY> |
| 985 | <BODY> |
| 986 | <p> |
| 987 | Always start a new line for each selector and declaration. |
| 988 | </p> |
| 989 | <BAD_CODE_SNIPPET> |
| 990 | /* Not recommended */ |
| 991 | a:focus, a:active { |
| 992 | position: relative; top: 1px; |
| 993 | } |
| 994 | </BAD_CODE_SNIPPET> |
| 995 | <CODE_SNIPPET> |
| 996 | /* Recommended */ |
| 997 | h1, |
| 998 | h2, |
| 999 | h3 { |
| 1000 | font-weight: normal; |
| 1001 | line-height: 1.2; |
| 1002 | } |
| 1003 | </CODE_SNIPPET> |
| 1004 | </BODY> |
| 1005 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1006 | <STYLEPOINT title="Rule Separation"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1007 | <SUMMARY> |
| 1008 | Separate rules by new lines. |
| 1009 | </SUMMARY> |
| 1010 | <BODY> |
| 1011 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1012 | Always put a blank line (two line breaks) between rules. |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1013 | </p> |
| 1014 | <CODE_SNIPPET> |
| 1015 | html { |
| 1016 | background: #fff; |
| 1017 | } |
| 1018 | |
| 1019 | body { |
| 1020 | margin: auto; |
| 1021 | width: 50%; |
| 1022 | } |
| 1023 | </CODE_SNIPPET> |
| 1024 | </BODY> |
| 1025 | </STYLEPOINT> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1026 | <STYLEPOINT title="CSS Quotation Marks"> |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 1027 | <SUMMARY> |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 1028 | Use single quotation marks for attribute selectors and property values. |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 1029 | </SUMMARY> |
| 1030 | <BODY> |
| 1031 | <p> |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 1032 | Use single (<code>''</code>) rather than double (<code>""</code>) |
| 1033 | quotation marks for attribute selectors or property values. Do not |
| 1034 | use quotation marks in URI values (<code>url()</code>). |
| 1035 | </p> |
| 1036 | <p> |
| 1037 | Exception: If you do need to use the <code>@charset</code> rule, |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1038 | use double quotation marks—<a href="http://www.w3.org/TR/CSS21/syndata.html#charset">single |
mark@chromium.org | c8c76a2 | 2012-11-28 20:26:27 +0000 | [diff] [blame] | 1039 | quotation marks are not permitted</a>. |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 1040 | </p> |
| 1041 | <BAD_CODE_SNIPPET> |
| 1042 | /* Not recommended */ |
| 1043 | @import url("//www.google.com/css/maia.css"); |
| 1044 | |
| 1045 | html { |
| 1046 | font-family: "open sans", arial, sans-serif; |
| 1047 | } |
| 1048 | </BAD_CODE_SNIPPET> |
| 1049 | <CODE_SNIPPET> |
| 1050 | /* Recommended */ |
| 1051 | @import url(//www.google.com/css/maia.css); |
| 1052 | |
| 1053 | html { |
| 1054 | font-family: 'open sans', arial, sans-serif; |
| 1055 | } |
| 1056 | </CODE_SNIPPET> |
| 1057 | </BODY> |
| 1058 | </STYLEPOINT> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1059 | </CATEGORY> |
| 1060 | |
| 1061 | <CATEGORY title="CSS Meta Rules"> |
| 1062 | |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1063 | <STYLEPOINT title="Section Comments"> |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1064 | <SUMMARY> |
| 1065 | Group sections by a section comment (optional). |
| 1066 | </SUMMARY> |
| 1067 | <BODY> |
| 1068 | <p> |
jensmeiert@google.com | 1e1b50b | 2012-07-17 20:12:10 +0000 | [diff] [blame] | 1069 | If possible, group style sheet sections together by using |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1070 | comments. Separate sections with new lines. |
| 1071 | </p> |
| 1072 | <CODE_SNIPPET> |
| 1073 | /* Header */ |
| 1074 | |
| 1075 | #adw-header {} |
| 1076 | |
| 1077 | /* Footer */ |
| 1078 | |
| 1079 | #adw-footer {} |
| 1080 | |
| 1081 | /* Gallery */ |
| 1082 | |
| 1083 | .adw-gallery {} |
| 1084 | </CODE_SNIPPET> |
| 1085 | </BODY> |
| 1086 | </STYLEPOINT> |
| 1087 | </CATEGORY> |
| 1088 | |
mark@chromium.org | 5684bbc | 2013-07-12 18:53:13 +0000 | [diff] [blame] | 1089 | |
| 1090 | |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1091 | <PARTING_WORDS> |
| 1092 | <p> |
| 1093 | <em>Be consistent.</em> |
| 1094 | </p> |
| 1095 | <p> |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1096 | If you’re editing code, take a few minutes to look at the code |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1097 | around you and determine its style. If they use spaces around |
| 1098 | all their arithmetic operators, you should too. If their |
| 1099 | comments have little boxes of hash marks around them, make your |
| 1100 | comments have little boxes of hash marks around them too. |
| 1101 | </p> |
| 1102 | <p> |
| 1103 | The point of having style guidelines is to have a common vocabulary |
mark@chromium.org | 8190c13 | 2013-03-21 16:03:26 +0000 | [diff] [blame] | 1104 | of coding so people can concentrate on what you’re saying rather |
| 1105 | than on how you’re saying it. We present global style rules here so |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1106 | people know the vocabulary, but local style is also important. If |
| 1107 | code you add to a file looks drastically different from the existing |
| 1108 | code around it, it throws readers out of their rhythm when they go to |
| 1109 | read it. Avoid this. |
| 1110 | </p> |
| 1111 | </PARTING_WORDS> |
| 1112 | |
| 1113 | <p align="right"> |
mark@chromium.org | 5684bbc | 2013-07-12 18:53:13 +0000 | [diff] [blame] | 1114 | Revision 2.23 |
jensmeiert@google.com | dc19d7e | 2012-04-24 22:21:00 +0000 | [diff] [blame] | 1115 | </p> |
| 1116 | |
| 1117 | </GUIDE> |