mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
2173b8d68c
This removes the guidance around not closing void elements since this is incompatible with the Prettier formatter.
957 lines
31 KiB
HTML
957 lines
31 KiB
HTML
<!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="https://www.google.com/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 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 a contact (username or mailing list) in parentheses as with the format
|
||
<code>TODO(contact)</code>.</p>
|
||
|
||
<p>Append action items after a colon as in <code>TODO: action item</code>.</p>
|
||
|
||
<pre><code class="language-django external good">{# TODO(john.doe): 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 HTML5.</p>
|
||
|
||
<p>HTML5 (HTML syntax) is preferred for all HTML documents: <code><!DOCTYPE html></code>.</p>
|
||
|
||
<p>(It’s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
|
||
<a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, lacks both browser
|
||
and infrastructure support and offers less room for optimization than HTML.)</p>
|
||
|
||
<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>
|