| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <title>Google HTML/CSS Style Guide</title> |
| <link rel="stylesheet" href="javaguide.css"> |
| <script src="include/styleguide.js"></script> |
| <link rel="shortcut icon" href="/styleguide/favicon.ico"> |
| <script src="include/jsguide.js"></script> |
| </head> |
| <body onload="initStyleGuide();"> |
| <div id="content"> |
| <h1>Google HTML/CSS Style Guide</h1> |
| <h2 id="Background" class="numbered">Background</h2> |
| |
| <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 Sass and GSS |
| files. Tools are free to obfuscate, minify, and compile as long as the general |
| code quality is maintained.</p> |
| |
| <h2 id="General" class="numbered">General</h2> |
| |
| <h3 id="General_Style_Rules" class="numbered">General Style Rules</h3> |
| |
| <h4 id="Protocol" class="numbered">Protocol</h4> |
| |
| <p>Use HTTPS for embedded resources where possible.</p> |
| |
| <p>Always use HTTPS (<code>https:</code>) for images and other media files, style sheets, and |
| scripts, unless the respective files are not available over HTTPS.</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended: omits the protocol --> |
| <script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script> |
| |
| <!-- Not recommended: uses HTTP --> |
| <script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script> |
| </code></pre> |
| |
| <pre><code class="language-css bad">/* Not recommended: omits the protocol */ |
| @import '//fonts.googleapis.com/css?family=Open+Sans'; |
| |
| /* Not recommended: uses HTTP */ |
| @import 'http://fonts.googleapis.com/css?family=Open+Sans'; |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| @import 'https://fonts.googleapis.com/css?family=Open+Sans'; |
| </code></pre> |
| |
| <h3 id="General_Formatting_Rules" class="numbered">General Formatting Rules</h3> |
| |
| <h4 id="Indentation" class="numbered">Indentation</h4> |
| |
| <p>Indent by 2 spaces at a time.</p> |
| |
| <p>Don’t use tabs or mix tabs and spaces for indentation.</p> |
| |
| <pre><code class="language-html good"><ul> |
| <li>Fantastic |
| <li>Great |
| </ul> |
| </code></pre> |
| |
| <pre><code class="language-css good">.example { |
| color: blue; |
| } |
| </code></pre> |
| |
| <h4 id="Capitalization" class="numbered">Capitalization</h4> |
| |
| <p>Use only lowercase.</p> |
| |
| <p>All code has to be lowercase: This applies to HTML element names, attributes, |
| attribute values (unless <code>text/CDATA</code>), CSS selectors, properties, and property |
| values (with the exception of strings).</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <A HREF="/">Home</A> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <img src="google.png" alt="Google"> |
| </code></pre> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| color: #E5E5E5; |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| color: #e5e5e5; |
| </code></pre> |
| |
| <h4 id="Trailing_Whitespace" class="numbered">Trailing Whitespace</h4> |
| |
| <p>Remove trailing white spaces.</p> |
| |
| <p>Trailing white spaces are unnecessary and can complicate diffs.</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <p>What?_ |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <p>Yes please. |
| </code></pre> |
| |
| <h3 id="General_Meta_Rules" class="numbered">General Meta Rules</h3> |
| |
| <h4 id="Encoding" class="numbered">Encoding</h4> |
| |
| <p>Use UTF-8 (no BOM).</p> |
| |
| <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="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling character encodings in HTML and CSS</a>.)</p> |
| |
| <h4 id="Comments" class="numbered">Comments</h4> |
| |
| <p>Explain code as needed, where possible.</p> |
| |
| <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> |
| |
| <h4 id="Action_Items" class="numbered">Action Items</h4> |
| |
| <p>Mark todos and action items with <code>TODO</code>.</p> |
| |
| <p>Highlight todos by using the keyword <code>TODO</code> only, not other common formats like |
| <code>@@</code>.</p> |
| |
| <p>Append action items after a colon as in <code>TODO: action |
| item</code>.</p> |
| |
| <pre><code class="language-django external good">{# TODO: Revisit centering. #} |
| <center>Test</center> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- TODO: Remove optional tags. --> |
| <ul> |
| <li>Apples</li> |
| <li>Oranges</li> |
| </ul> |
| </code></pre> |
| |
| <h2 id="HTML" class="numbered">HTML</h2> |
| |
| <h3 id="HTML_Style_Rules" class="numbered">HTML Style Rules</h3> |
| |
| <h4 id="Document_Type" class="numbered">Document Type</h4> |
| |
| <p>Use <code><!doctype html></code>.</p> |
| |
| <p>Always put your HTML in |
| <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode">no-quirks mode</a> |
| by including <code><!doctype html></code> at the beginning of the document.</p> |
| |
| <p>A document without a doctype is rendered in “quirks mode”, and one with a |
| different doctype may be rendered in “limited-quirks mode”. These modes don’t |
| follow the widely-understood, widely-documented behavior for various core HTML |
| and CSS constructs, and are likely to cause subtle failures and |
| incompatibilities especially when re-using code that expects no-quirks mode.</p> |
| |
| <h4 id="HTML_Validity" class="numbered">HTML Validity</h4> |
| |
| <p>Use valid HTML where possible.</p> |
| |
| <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="https://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> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <title>Test</title> |
| <article>This is only a test. |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <!doctype html> |
| <meta charset="utf-8"> |
| <title>Test</title> |
| <article>This is only a test.</article> |
| </code></pre> |
| |
| <h4 id="Semantics" class="numbered">Semantics</h4> |
| |
| <p>Use HTML according to its purpose.</p> |
| |
| <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> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <div onclick="goToRecommendations();">All recommendations</div> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <a href="recommendations/">All recommendations</a> |
| </code></pre> |
| |
| <h4 id="Multimedia_Fallback" class="numbered">Multimedia Fallback</h4> |
| |
| <p>Provide alternative contents for multimedia.</p> |
| |
| <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> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <img src="spreadsheet.png"> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <img src="spreadsheet.png" alt="Spreadsheet screenshot."> |
| </code></pre> |
| |
| <h4 id="Separation_of_Concerns" class="numbered">Separation of Concerns</h4> |
| |
| <p>Separate structure from presentation from behavior.</p> |
| |
| <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> |
| |
| <pre><code class="language-html bad"><!-- 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> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- 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></pre> |
| |
| <h4 id="Entity_References" class="numbered">Entity References</h4> |
| |
| <p>Do not use entity references.</p> |
| |
| <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> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| The currency symbol for the Euro is &ldquo;&eur;&rdquo;. |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| The currency symbol for the Euro is “€”. |
| </code></pre> |
| |
| <h4 id="Optional_Tags" class="numbered">Optional Tags</h4> |
| |
| <p>Omit optional tags (optional).</p> |
| |
| <p>For file size optimization and scannability purposes, consider omitting optional |
| tags. The |
| <a href="https://html.spec.whatwg.org/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’s significantly different from what web developers are typically taught. |
| For consistency and simplicity reasons it’s best served omitting all optional |
| tags, not just a selection.)</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <!doctype html> |
| <html> |
| <head> |
| <title>Spending money, spending bytes</title> |
| </head> |
| <body> |
| <p>Sic.</p> |
| </body> |
| </html> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <!doctype html> |
| <title>Saving money, saving bytes</title> |
| <p>Qed. |
| </code></pre> |
| |
| <h4 id="type_Attributes" class="numbered"><code>type</code> Attributes</h4> |
| |
| <p>Omit <code>type</code> attributes for style sheets and scripts.</p> |
| |
| <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="https://html.spec.whatwg.org/multipage/obsolete.html#attr-style-type"><code>text/css</code></a> |
| and |
| <a href="https://html.spec.whatwg.org/multipage/scripting.html#attr-script-type"><code>text/javascript</code></a> |
| as defaults. This can be safely done even for older browsers.</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <link rel="stylesheet" href="https://www.google.com/css/maia.css" |
| type="text/css"> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <link rel="stylesheet" href="https://www.google.com/css/maia.css"> |
| </code></pre> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <script src="https://www.google.com/js/gweb/analytics/autotrack.js" |
| type="text/javascript"></script> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script> |
| </code></pre> |
| |
| <h4 id="id_Attributes" class="numbered"><code>id</code> Attributes</h4> |
| |
| <p>Avoid unnecessary <code>id</code> attributes.</p> |
| |
| <p>Prefer <code>class</code> attributes for styling and <code>data</code> attributes for scripting.</p> |
| |
| <p>Where <code>id</code> attributes are strictly required, always include a hyphen in the |
| value to ensure it does not match the JavaScript identifier syntax, e.g. use |
| <code>user-profile</code> rather than just <code>profile</code> or <code>userProfile</code>.</p> |
| |
| <p>When an element has an <code>id</code> attribute, browsers will make that available as a |
| <a href="https://html.spec.whatwg.org/multipage/window-object.html#named-access-on-the-window-object">named property on the global <code>window</code> prototype</a>, |
| which may cause unexpected behavior. While <code>id</code> attribute values containing a |
| hyphen are still available as property names, these cannot be referenced as |
| global JavaScript variables.</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended: `window.userProfile` will resolve to reference the <div> node --> |
| <div id="userProfile"></div> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended: `id` attribute is required and its value includes a hyphen --> |
| <div aria-describedby="user-profile"> |
| … |
| <div id="user-profile"></div> |
| … |
| </div> |
| </code></pre> |
| |
| <h3 id="HTML_Formatting_Rules" class="numbered">HTML Formatting Rules</h3> |
| |
| <h4 id="General_Formatting" class="numbered">General Formatting</h4> |
| |
| <p>Use a new line for every block, list, or table element, and indent every such |
| child element.</p> |
| |
| <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’s acceptable to |
| put all <code>li</code> elements in one line. A linter is encouraged to throw a warning |
| instead of an error.)</p> |
| |
| <pre><code class="language-html good"><blockquote> |
| <p><em>Space</em>, the final frontier.</p> |
| </blockquote> |
| </code></pre> |
| |
| <pre><code class="language-html good"><ul> |
| <li>Moe |
| <li>Larry |
| <li>Curly |
| </ul> |
| </code></pre> |
| |
| <pre><code class="language-html good"><table> |
| <thead> |
| <tr> |
| <th scope="col">Income |
| <th scope="col">Taxes |
| <tbody> |
| <tr> |
| <td>$ 5.00 |
| <td>$ 4.50 |
| </table> |
| </code></pre> |
| |
| <h4 id="HTML_Line-Wrapping" class="numbered">HTML Line-Wrapping</h4> |
| |
| <p>Break long lines (optional).</p> |
| |
| <p>While there is no column limit recommendation for HTML, you may consider |
| wrapping long lines if it significantly improves readability.</p> |
| |
| <p>When line-wrapping, each continuation line should be indented to distinguish |
| wrapped attributes from child elements. Lines should be wrapped consistently |
| within a project, ideally enforced by automated code formatting tools.</p> |
| |
| <pre><code class="language-html good"><button |
| mat-icon-button |
| color="primary" |
| class="menu-button" |
| (click)="openMenu()" |
| > |
| <mat-icon>menu</mat-icon> |
| </button> |
| </code></pre> |
| |
| <pre><code class="language-html good"><button mat-icon-button color="primary" class="menu-button" |
| (click)="openMenu()"> |
| <mat-icon>menu</mat-icon> |
| </button> |
| </code></pre> |
| |
| <pre><code class="language-html good"><button |
| mat-icon-button |
| color="primary" |
| class="menu-button" |
| (click)="openMenu()"> |
| <mat-icon>menu</mat-icon> |
| </button> |
| </code></pre> |
| |
| <pre><code class="language-html good"><button mat-icon-button |
| color="primary" |
| class="menu-button" |
| (click)="openMenu()"> |
| <mat-icon>menu</mat-icon> |
| </button> |
| </code></pre> |
| |
| <h4 id="HTML_Quotation_Marks" class="numbered">HTML Quotation Marks</h4> |
| |
| <p>When quoting attributes values, use double quotation marks.</p> |
| |
| <p>Use double (<code>""</code>) rather than single quotation marks (<code>''</code>) around attribute |
| values.</p> |
| |
| <pre><code class="language-html bad"><!-- Not recommended --> |
| <a class='maia-button maia-button-secondary'>Sign in</a> |
| </code></pre> |
| |
| <pre><code class="language-html good"><!-- Recommended --> |
| <a class="maia-button maia-button-secondary">Sign in</a> |
| </code></pre> |
| |
| <h2 id="CSS" class="numbered">CSS</h2> |
| |
| <h3 id="CSS_Style_Rules" class="numbered">CSS Style Rules</h3> |
| |
| <h4 id="CSS_Validity" class="numbered">CSS Validity</h4> |
| |
| <p>Use valid CSS where possible.</p> |
| |
| <p>Unless dealing with CSS validator bugs or requiring proprietary syntax, use |
| valid CSS code.</p> |
| |
| <p> Use tools such as the |
| <a href="https://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> |
| |
| <h4 id="ID_and_Class_Naming" class="numbered">Class Naming</h4> |
| |
| <p>Use meaningful or generic class names.</p> |
| |
| <p>Instead of presentational or cryptic names, always use 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> |
| |
| <pre><code class="language-css bad">/* Not recommended: meaningless */ |
| .yee-1901 {} |
| |
| /* Not recommended: presentational */ |
| .button-green {} |
| .clear {} |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended: specific */ |
| .gallery {} |
| .login {} |
| .video {} |
| |
| /* Recommended: generic */ |
| .aux {} |
| .alt {} |
| </code></pre> |
| |
| <h4 id="ID_and_Class_Name_Style" class="numbered">Class Name Style</h4> |
| |
| <p>Use class names that are as short as possible but as long as necessary.</p> |
| |
| <p>Try to convey what a class is about while being as brief as possible.</p> |
| |
| <p>Using class names this way contributes to acceptable levels of understandability |
| and code efficiency.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| .navigation {} |
| .atr {} |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .nav {} |
| .author {} |
| </code></pre> |
| |
| <h4 id="ID_and_Class_Name_Delimiters" class="numbered">Class Name Delimiters</h4> |
| |
| <p>Separate words in class names by a hyphen.</p> |
| |
| <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> |
| |
| <pre><code class="language-css bad">/* Not recommended: does not separate the words “demo” and “image” */ |
| .demoimage {} |
| |
| /* Not recommended: uses underscore instead of hyphen */ |
| .error_status {} |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .video-id {} |
| .ads-sample {} |
| </code></pre> |
| |
| <h4 id="Prefixes" class="numbered">Prefixes</h4> |
| |
| <p>Prefix selectors with an application-specific prefix (optional).</p> |
| |
| <p>In large projects as well as for code that gets embedded in other projects or on |
| external sites use prefixes (as namespaces) for 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> |
| |
| <pre><code class="language-css good">.adw-help {} /* AdWords */ |
| .maia-note {} /* Maia */ |
| </code></pre> |
| |
| <h4 id="Type_Selectors" class="numbered">Type Selectors</h4> |
| |
| <p>Avoid qualifying class names with type selectors.</p> |
| |
| <p>Unless necessary (for example with helper classes), do not use element names in |
| conjunction with 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> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| ul.example {} |
| div.error {} |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .example {} |
| .error {} |
| </code></pre> |
| |
| <h4 id="ID_Selectors" class="numbered">ID Selectors</h4> |
| |
| <p>Avoid ID selectors.</p> |
| |
| <p>ID attributes are expected to be unique across an entire page, which is |
| difficult to guarantee when a page contains many components worked on by many |
| different engineers. Class selectors should be preferred in all situations.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| #example {} |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .example {} |
| </code></pre> |
| |
| <h4 id="Shorthand_Properties" class="numbered">Shorthand Properties</h4> |
| |
| <p>Use shorthand properties where possible.</p> |
| |
| <p>CSS offers a variety of |
| <a href="https://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> |
| |
| <pre><code class="language-css bad">/* 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; |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| border-top: 0; |
| font: 100%/1.6 palatino, georgia, serif; |
| padding: 0 1em 2em; |
| </code></pre> |
| |
| <h4 id="0_and_Units" class="numbered">0 and Units</h4> |
| |
| <p>Omit unit specification after “0” values, unless required.</p> |
| |
| <p>Do not use units after <code>0</code> values unless they are required.</p> |
| |
| <pre><code class="language-css good">flex: 0px; /* This flex-basis component requires a unit. */ |
| flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */ |
| margin: 0; |
| padding: 0; |
| </code></pre> |
| |
| <h4 id="Leading_0s" class="numbered">Leading 0s</h4> |
| |
| <p>Always include leading “0”s in values.</p> |
| |
| <p>Put <code>0</code>s in front of values or lengths between -1 and 1.</p> |
| |
| <pre><code class="language-css good">font-size: 0.8em; |
| </code></pre> |
| |
| <h4 id="Hexadecimal_Notation" class="numbered">Hexadecimal Notation</h4> |
| |
| <p>Use 3 character hexadecimal notation where possible.</p> |
| |
| <p>For color values that permit it, 3 character hexadecimal notation is shorter and |
| more succinct.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| color: #eebbcc; |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| color: #ebc; |
| </code></pre> |
| |
| <h4 id="Important_Declarations" class="numbered">Important Declarations</h4> |
| |
| <p>Avoid using <code>!important</code> declarations.</p> |
| |
| <p>These declarations break the natural cascade of CSS and make it difficult to |
| reason about and compose styles. Use |
| <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity">selector specificity</a> |
| to override properties instead.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| .example { |
| font-weight: bold !important; |
| } |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .example { |
| font-weight: bold; |
| } |
| </code></pre> |
| |
| <h4 id="Hacks" class="numbered">Hacks</h4> |
| |
| <p>Avoid user agent detection as well as CSS “hacks”—try a different approach |
| first.</p> |
| |
| <p>It’s 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> |
| |
| <h3 id="CSS_Formatting_Rules" class="numbered">CSS Formatting Rules</h3> |
| |
| <h4 id="Declaration_Order" class="numbered">Declaration Order</h4> |
| |
| <p>Alphabetize declarations (optional).</p> |
| |
| <p>Sort declarations consistently within a project. In the absence of tooling to |
| automate and enforce a consistent sort order, consider putting declarations in |
| alphabetical order in order to achieve consistent code in a way that is easy to |
| learn, remember, and manually 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> |
| |
| <pre><code class="language-css good">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></pre> |
| |
| <h4 id="Block_Content_Indentation" class="numbered">Block Content Indentation</h4> |
| |
| <p>Indent all block content.</p> |
| |
| <p>Indent all |
| <a href="https://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> |
| |
| <pre><code class="language-css good">@media screen, projection { |
| |
| html { |
| background: #fff; |
| color: #444; |
| } |
| |
| } |
| </code></pre> |
| |
| <h4 id="Declaration_Stops" class="numbered">Declaration Stops</h4> |
| |
| <p>Use a semicolon after every declaration.</p> |
| |
| <p>End every declaration with a semicolon for consistency and extensibility |
| reasons.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| .test { |
| display: block; |
| height: 100px |
| } |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .test { |
| display: block; |
| height: 100px; |
| } |
| </code></pre> |
| |
| <h4 id="Property_Name_Stops" class="numbered">Property Name Stops</h4> |
| |
| <p>Use a space after a property name’s colon.</p> |
| |
| <p>Always use a single space between property and value (but no space between |
| property and colon) for consistency reasons.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| h3 { |
| font-weight:bold; |
| } |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| h3 { |
| font-weight: bold; |
| } |
| </code></pre> |
| |
| <h4 id="Declaration_Block_Separation" class="numbered">Declaration Block Separation</h4> |
| |
| <p>Use a space between the last selector and the declaration block.</p> |
| |
| <p>Always use a single space between the last selector and the opening brace that |
| begins the |
| <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration block</a>.</p> |
| |
| <p>The opening brace should be on the same line as the last selector in a given |
| rule.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended: missing space */ |
| .video{ |
| margin-top: 1em; |
| } |
| |
| /* Not recommended: unnecessary line break */ |
| .video |
| { |
| margin-top: 1em; |
| } |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| .video { |
| margin-top: 1em; |
| } |
| </code></pre> |
| |
| <h4 id="Selector_and_Declaration_Separation" class="numbered">Selector and Declaration Separation</h4> |
| |
| <p>Separate selectors and declarations by new lines.</p> |
| |
| <p>Always start a new line for each selector and declaration.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| a:focus, a:active { |
| position: relative; top: 1px; |
| } |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| h1, |
| h2, |
| h3 { |
| font-weight: normal; |
| line-height: 1.2; |
| } |
| </code></pre> |
| |
| <h4 id="Rule_Separation" class="numbered">Rule Separation</h4> |
| |
| <p>Separate rules by new lines.</p> |
| |
| <p>Always put a blank line (two line breaks) between rules.</p> |
| |
| <pre><code class="language-css good">html { |
| background: #fff; |
| } |
| |
| body { |
| margin: auto; |
| width: 50%; |
| } |
| </code></pre> |
| |
| <h4 id="CSS_Quotation_Marks" class="numbered">CSS Quotation Marks</h4> |
| |
| <p>Use single (<code>''</code>) rather than double (<code>""</code>) quotation marks for attribute |
| selectors and property values.</p> |
| |
| <p>Do not use quotation marks in URI values (<code>url()</code>).</p> |
| |
| <p>Exception: If you do need to use the <code>@charset</code> rule, use double quotation |
| marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p> |
| |
| <pre><code class="language-css bad">/* Not recommended */ |
| @import url("https://www.google.com/css/maia.css"); |
| |
| html { |
| font-family: "open sans", arial, sans-serif; |
| } |
| </code></pre> |
| |
| <pre><code class="language-css good">/* Recommended */ |
| @import url(https://www.google.com/css/maia.css); |
| |
| html { |
| font-family: 'open sans', arial, sans-serif; |
| } |
| </code></pre> |
| |
| <h3 id="CSS_Meta_Rules" class="numbered">CSS Meta Rules</h3> |
| |
| <h4 id="Section_Comments" class="numbered">Section Comments</h4> |
| |
| <p>Group sections by a section comment (optional).</p> |
| |
| <p>If possible, group style sheet sections together by using comments. Separate |
| sections with new lines.</p> |
| |
| <pre><code class="language-css good">/* Header */ |
| |
| .adw-header {} |
| |
| /* Footer */ |
| |
| .adw-footer {} |
| |
| /* Gallery */ |
| |
| .adw-gallery {} |
| </code></pre> |
| |
| <h2 id="Parting_Words">Parting Words</h2> |
| |
| <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> |
| </div> |
| </body> |
| </html> |
