mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
1035 lines
33 KiB
XML
1035 lines
33 KiB
XML
|
<?xml version="1.0"?>
|
||
|
|
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
|
||
|
|
<GUIDE title="Google HTML/CSS Style Guide">
|
||
|
|
<p class="revision">
|
||
|
|
|
||
|
|
Revision 2.1
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<OVERVIEW>
|
||
|
|
<CATEGORY title="Important Note">
|
||
|
|
<STYLEPOINT title="Displaying Hidden Details in this Guide">
|
||
|
|
<SUMMARY>
|
||
|
|
This style guide contains many details that are initially
|
||
|
|
hidden from view. They are marked by the triangle icon, which you
|
||
|
|
see here on your left. Click it now.
|
||
|
|
You should see “Hooray” appear below.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Hooray! Now you know you can expand points to get more
|
||
|
|
details. Alternatively, there’s a “toggle all” at the
|
||
|
|
top of this document.
|
||
|
|
</p>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
<CATEGORY title="Background">
|
||
|
|
|
||
|
|
<p>
|
||
|
|
This document defines formatting and style rules for HTML and
|
||
|
|
CSS. It aims at improving collaboration, code quality, and
|
||
|
|
enabling supporting infrastructure. It applies to raw,
|
||
|
|
working files that use HTML and CSS, including GSS
|
||
|
|
files. Tools are free to obfuscate, minify, and compile as
|
||
|
|
long as the general code quality is maintained.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
</CATEGORY>
|
||
|
|
</OVERVIEW>
|
||
|
|
|
||
|
|
<CATEGORY title="General Style Rules">
|
||
|
|
<STYLEPOINT title="Protocol">
|
||
|
|
<SUMMARY>
|
||
|
|
Omit the protocol from embedded resources.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Omit the protocol portion (<code>http:</code>,
|
||
|
|
<code>https:</code>) from URLs pointing to images and other
|
||
|
|
media files, style sheets, and scripts unless the respective
|
||
|
|
files are not available over both protocols.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Omitting the protocol—which makes the URL
|
||
|
|
relative—prevents mixed content issues and results in
|
||
|
|
minor file size savings.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
.example {
|
||
|
|
background: url(http://www.google.com/images/example);
|
||
|
|
}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
.example {
|
||
|
|
background: url(//www.google.com/images/example);
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="General Formatting Rules">
|
||
|
|
<STYLEPOINT title="Indentation">
|
||
|
|
<SUMMARY>
|
||
|
|
Indent by 2 spaces at a time.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Don’t use tabs or mix tabs and spaces for indentation.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<ul>
|
||
|
|
<li>Fantastic
|
||
|
|
<li>Great
|
||
|
|
</ul>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
.example {
|
||
|
|
color: blue;
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Capitalization">
|
||
|
|
<SUMMARY>
|
||
|
|
Use only lowercase.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
All code has to be lowercase: this applies to element names,
|
||
|
|
attributes, attribute values (unless
|
||
|
|
text/<code>CDATA</code>), selectors, properties, and
|
||
|
|
property values (with the exception of strings).
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<A HREF="/">Home</A>
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<img src="google.png" alt="Google">
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Trailing whitespace">
|
||
|
|
<SUMMARY>
|
||
|
|
Remove trailing white spaces.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Trailing white spaces are unnecessary and can complicate
|
||
|
|
diffs.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<p>What?_
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<p>Yes please.
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="General Meta Rules">
|
||
|
|
<STYLEPOINT title="Encoding">
|
||
|
|
<SUMMARY>
|
||
|
|
Use UTF-8 (no BOM).
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Make sure your editor uses UTF-8 as character encoding,
|
||
|
|
without a byte order mark.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Specify the encoding in HTML templates and documents via
|
||
|
|
<code><meta charset="utf-8"></code>. Do not specify
|
||
|
|
the encoding of style sheets as these assume UTF-8.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(More on encodings and when and how to specify them can be
|
||
|
|
found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/en/all.html">Character
|
||
|
|
Sets & Encodings in XHTML, HTML and CSS</a>.)
|
||
|
|
</p>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Comments">
|
||
|
|
<SUMMARY>
|
||
|
|
Explain code as needed, where possible.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Use comments to explain code: what does it cover, what
|
||
|
|
purpose does it serve, why is respective solution used or
|
||
|
|
preferred?
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(This item is optional as it is not deemed a realistic
|
||
|
|
expectation to always demand fully documented code. Mileage
|
||
|
|
may vary heavily for HTML and CSS code and depends on the
|
||
|
|
project’s complexity.)
|
||
|
|
</p>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Action items">
|
||
|
|
<SUMMARY>
|
||
|
|
Mark todos and action items with <code>TODO</code>.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Highlight todos by using the keyword <code>TODO</code> only,
|
||
|
|
not other common formats like <code>@@</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Append a contact (username or mailing list) in parentheses
|
||
|
|
as with the format <code>TODO(contact)</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Append action items after a colon as in <code>TODO: action
|
||
|
|
item</code>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
{# TODO(john.doe): revisit centering #}
|
||
|
|
<center>Test</center>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- TODO: remove optional tags -->
|
||
|
|
<ul>
|
||
|
|
<li>Apples</li>
|
||
|
|
<li>Oranges</li>
|
||
|
|
</ul>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="HTML Style Rules">
|
||
|
|
<STYLEPOINT title="Document type">
|
||
|
|
<SUMMARY>
|
||
|
|
Use HTML5.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
HTML5 (HTML syntax) is preferred for all HTML documents:
|
||
|
|
<code><!DOCTYPE html></code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(It is recommended to use HTML, as <code>text/html</code>. Do not use
|
||
|
|
XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
|
||
|
|
lacks both browser and infrastructure support and offers
|
||
|
|
less room for optimization than HTML.)
|
||
|
|
</p>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="HTML validity">
|
||
|
|
<SUMMARY>
|
||
|
|
Use valid HTML where possible.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Use valid HTML code unless that is not possible due to
|
||
|
|
otherwise unattainable performance goals regarding file size.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Use tools such as the <a href="http://validator.w3.org/">W3C
|
||
|
|
HTML validator</a> to test.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Using valid HTML is a measurable baseline quality attribute
|
||
|
|
that contributes to learning about technical requirements
|
||
|
|
and constraints, and that ensures proper HTML usage.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<title>Test</title>
|
||
|
|
<article>This is only a test.
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<!DOCTYPE html>
|
||
|
|
<meta charset="utf-8">
|
||
|
|
<title>Test</title>
|
||
|
|
<article>This is only a test.</article>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Semantics">
|
||
|
|
<SUMMARY>
|
||
|
|
Use HTML according to its purpose.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Use elements (sometimes incorrectly called “tags”) for what
|
||
|
|
they have been created for. For example, use heading
|
||
|
|
elements for headings, <code>p</code> elements for
|
||
|
|
paragraphs, <code>a</code> elements for anchors, etc.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Using HTML according to its purpose is important for
|
||
|
|
accessibility, reuse, and code efficiency reasons.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<div onclick="goToRecommendations();">All recommendations</div>
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<a href="recommendations/">All recommendations</a>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Multimedia fallback">
|
||
|
|
<SUMMARY>
|
||
|
|
Provide alternative contents for multimedia.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
For multimedia, such as images, videos, animated objects via
|
||
|
|
<code>canvas</code>, make sure to offer alternative
|
||
|
|
access. For images that means use of meaningful alternative
|
||
|
|
text (<code>alt</code>) and for video and audio transcripts
|
||
|
|
and captions, if available.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Providing alternative contents is important for
|
||
|
|
accessibility reasons: a blind user has few cues to tell
|
||
|
|
what an image is about without <code>@alt</code>, and other
|
||
|
|
users may have no way of understanding what video or audio
|
||
|
|
contents are about either.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(For images whose <code>alt</code> attributes would
|
||
|
|
introduce redundancy, and for images whose purpose is purely
|
||
|
|
decorative which you cannot immediately use CSS for, use no
|
||
|
|
alternative text, as in <code>alt=""</code>.)
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<img src="spreadsheet.png">
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
|
||
|
|
<STYLEPOINT title="Separation of concerns">
|
||
|
|
<SUMMARY>
|
||
|
|
Separate structure from presentation from behavior.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Strictly keep structure (markup), presentation (styling),
|
||
|
|
and behavior (scripting) apart, and try to keep the
|
||
|
|
interaction between the three to an absolute minimum.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
That is, make sure documents and templates contain only HTML
|
||
|
|
and HTML that is solely serving structural purposes. Move
|
||
|
|
everything presentational into style sheets, and everything
|
||
|
|
behavioral into scripts.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
In addition, keep the contact area as small as possible by
|
||
|
|
linking as few style sheets and scripts as possible from
|
||
|
|
documents and templates.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Separating structure from presentation from behavior is
|
||
|
|
important for maintenance reasons. It is always more
|
||
|
|
expensive to change HTML documents and templates than it is
|
||
|
|
to update style sheets and scripts.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<!DOCTYPE html>
|
||
|
|
<title>HTML sucks</title>
|
||
|
|
<link rel="stylesheet" href="base.css" media="screen">
|
||
|
|
<link rel="stylesheet" href="grid.css" media="screen">
|
||
|
|
<link rel="stylesheet" href="print.css" media="print">
|
||
|
|
<h1 style="font-size: 1em;">HTML sucks</h1>
|
||
|
|
<p>I’ve read about this on a few sites but now I’m sure:
|
||
|
|
<u>HTML is stupid!!1</u>
|
||
|
|
<center>I can’t believe there’s no way to control the styling of
|
||
|
|
my website without doing everything all over again!</center>
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<!DOCTYPE html>
|
||
|
|
<title>My first CSS-only redesign</title>
|
||
|
|
<link rel="stylesheet" href="default.css">
|
||
|
|
<h1>My first CSS-only redesign</h1>
|
||
|
|
<p>I’ve read about this on a few sites but today I’m actually
|
||
|
|
doing it: separating concerns and avoiding anything in the HTML of
|
||
|
|
my website that is presentational.
|
||
|
|
<p>It’s awesome!
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Entity references">
|
||
|
|
<SUMMARY>
|
||
|
|
Do not use entity references.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
There is no need to use entity references like
|
||
|
|
<code>&mdash;</code>, <code>&rdquo;</code>, or
|
||
|
|
<code>&#x263a;</code>, assuming the same encoding
|
||
|
|
(UTF-8) is used for files and editors as well as among
|
||
|
|
teams.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The only exceptions apply to characters with special meaning
|
||
|
|
in HTML (like <code><</code> and <code>&</code>) as
|
||
|
|
well as control or “invisible” characters (like no-break
|
||
|
|
spaces).
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
The currency symbol for the Euro is “€”.
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Optional tags">
|
||
|
|
<SUMMARY>
|
||
|
|
Omit optional tags (optional).
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
For file size optimization and scannability purposes,
|
||
|
|
consider omitting optional tags.
|
||
|
|
The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5
|
||
|
|
specification</a> defines what tags can be omitted.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(This approach may require a grace period to be established
|
||
|
|
as a wider guideline as it is significantly different
|
||
|
|
from what web developers are typically taught. For
|
||
|
|
consistency and simplicity reasons it is best served
|
||
|
|
omitting all optional tags, not just a selection.)
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<title>Spending money, spending bytes</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<p>Sic.</p>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<!DOCTYPE html>
|
||
|
|
<title>Saving money, saving bytes</title>
|
||
|
|
<p>Qed.
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="type attributes">
|
||
|
|
<SUMMARY>
|
||
|
|
Omit <code>type</code> attributes for style sheets and scripts.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Do not use <code>type</code> attributes for style sheets
|
||
|
|
(unless not using CSS) and scripts (unless not using
|
||
|
|
JavaScript).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Specifying <code>type</code> attributes in these contexts is
|
||
|
|
not necessary as HTML5 implies
|
||
|
|
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
|
||
|
|
and
|
||
|
|
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a>
|
||
|
|
as defaults. This can be safely done even for older browsers.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<link rel="stylesheet" href="//www.google.com/css/maia.css"
|
||
|
|
type="text/css">
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<link rel="stylesheet" href="//www.google.com/css/maia.css">
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
<!-- Not recommended -->
|
||
|
|
<script src="//www.google.com/js/gweb/analytics/autotrack.js"
|
||
|
|
type="text/javascript"></script>
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<!-- Recommended -->
|
||
|
|
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="HTML Formatting Rules">
|
||
|
|
<STYLEPOINT title="General formatting">
|
||
|
|
<SUMMARY>
|
||
|
|
Use a new line for every block, list, or table element, and
|
||
|
|
indent every such child element.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Independent of the styling of an element (as CSS allows
|
||
|
|
elements to assume a different role per <code>display</code>
|
||
|
|
property), put every block, list, or table element on a new
|
||
|
|
line.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Also, indent them if they are child elements of a block,
|
||
|
|
list, or table element.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
(If you run into issues around whitespace between list items
|
||
|
|
it is acceptable to put all <code>li</code> elements in one
|
||
|
|
line. A linter is encouraged to throw a warning instead of
|
||
|
|
an error.)
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<blockquote>
|
||
|
|
<p><em>Space</em>, the final frontier.</p>
|
||
|
|
</blockquote>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<ul>
|
||
|
|
<li>Moe
|
||
|
|
<li>Larry
|
||
|
|
<li>Curly
|
||
|
|
</ul>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
<table>
|
||
|
|
<thead>
|
||
|
|
<tr>
|
||
|
|
<th scope="col">Income
|
||
|
|
<th scope="col">Taxes
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<td>$ 5.00
|
||
|
|
<td>$ 4.50
|
||
|
|
</table>
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="CSS Style Rules">
|
||
|
|
<STYLEPOINT title="CSS validity">
|
||
|
|
<SUMMARY>
|
||
|
|
Use valid CSS where possible.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Unless dealing with CSS validator bugs or requiring
|
||
|
|
proprietary syntax, use valid CSS code.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Use tools such as the
|
||
|
|
<a href="http://jigsaw.w3.org/css-validator/">W3C CSS validator</a> to
|
||
|
|
test.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Using valid CSS is a measurable baseline quality attribute
|
||
|
|
that allows to spot CSS code that may not have any effect
|
||
|
|
and can be removed, and that ensures proper CSS usage.
|
||
|
|
</p>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="ID and class naming">
|
||
|
|
<SUMMARY>
|
||
|
|
Use meaningful or generic ID and class names.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Instead of presentational or cryptic names, always use ID
|
||
|
|
and class names that reflect the purpose of the element in
|
||
|
|
question, or that are otherwise generic.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Names that are specific and reflect the purpose of the
|
||
|
|
element should be preferred as these are most understandable
|
||
|
|
and the least likely to change.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Generic names are simply a fallback for elements that have no
|
||
|
|
particular or no meaning different from their siblings. They are
|
||
|
|
typically needed as “helpers.”
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Using functional or generic names reduces the probability of
|
||
|
|
unnecessary document or template changes.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended: meaningless */
|
||
|
|
#yee-1901 {}
|
||
|
|
|
||
|
|
/* Not recommended: presentational */
|
||
|
|
.button-green {}
|
||
|
|
.clear {}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended: specific */
|
||
|
|
#gallery {}
|
||
|
|
#login {}
|
||
|
|
.video {}
|
||
|
|
|
||
|
|
/* Recommended: generic */
|
||
|
|
.aux {}
|
||
|
|
.alt {}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="ID and class name style">
|
||
|
|
<SUMMARY>
|
||
|
|
Use ID and class names that are as short as possible but as long as
|
||
|
|
necessary.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Try to convey what an ID or class is about while being as
|
||
|
|
brief as possible.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Using ID and class names this way contributes to acceptable
|
||
|
|
levels of understandability and code efficiency.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
#navigation {}
|
||
|
|
.atr {}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
#nav {}
|
||
|
|
.author {}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
|
||
|
|
<STYLEPOINT title="Type selectors">
|
||
|
|
<SUMMARY>
|
||
|
|
Avoid qualifying ID and class names with type selectors.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>Unless necessary (for example with helper classes), do not
|
||
|
|
use element names in conjunction with IDs or classes.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Avoiding unnecessary ancestor selectors is useful for
|
||
|
|
<a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
|
||
|
|
reasons</a>.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
ul#example {}
|
||
|
|
div.error {}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
#example {}
|
||
|
|
.error {}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Shorthand properties">
|
||
|
|
<SUMMARY>
|
||
|
|
Use shorthand properties where possible.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
CSS offers a variety of
|
||
|
|
<a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
|
||
|
|
properties (like <code>font</code>)
|
||
|
|
that should be used whenever possible, even in cases where
|
||
|
|
only one value is explicitly set.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Using shorthand properties is useful for code efficiency and
|
||
|
|
understandability.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
border-top-style: none;
|
||
|
|
font-family: palatino, georgia, serif;
|
||
|
|
font-size: 100%;
|
||
|
|
line-height: 1.6;
|
||
|
|
padding-bottom: 2em;
|
||
|
|
padding-left: 1em;
|
||
|
|
padding-right: 1em;
|
||
|
|
padding-top: 0;
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
border-top: 0;
|
||
|
|
font: 100%/1.6 palatino, georgia, serif;
|
||
|
|
padding: 0 1em 2em;
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="0 and units">
|
||
|
|
<SUMMARY>
|
||
|
|
Omit unit specification after “0” values.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Do not use units after <code>0</code> values unless they are
|
||
|
|
required.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
margin: 0;
|
||
|
|
padding: 0;
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Leading 0s">
|
||
|
|
<SUMMARY>
|
||
|
|
Omit leading “0”s in values.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Do not use put <code>0</code>s in front of values or lengths
|
||
|
|
between -1 and 1.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
font-size: .8em;
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Quotation marks in URI values">
|
||
|
|
<SUMMARY>
|
||
|
|
Omit quotation marks in URI values.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Do not use quotation marks (<code>""</code>,
|
||
|
|
<code>''</code>) with <code>url()</code>.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
@import url(//www.google.com/css/go.css);
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Hexadecimal notation">
|
||
|
|
<SUMMARY>
|
||
|
|
Use 3 character hexadecimal notation where possible.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
For color values that permit it, 3 character hexadecimal
|
||
|
|
notation is shorter and more succinct.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
color: #eebbcc;
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
color: #ebc;
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Prefixes">
|
||
|
|
<SUMMARY>
|
||
|
|
Prefix selectors with an application-specific prefix (optional).
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
In large projects as well as for code that gets embedded in
|
||
|
|
other projects or on external sites use prefixes (as
|
||
|
|
namespaces) for ID and class names. Use short, unique
|
||
|
|
identifiers followed by a dash.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Using namespaces helps preventing naming conflicts and can
|
||
|
|
make maintenance easier, for example in search and replace
|
||
|
|
operations.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
.adw-help {} /* AdWords */
|
||
|
|
#maia-note {} /* Maia */
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="ID and class name delimiters">
|
||
|
|
<SUMMARY>
|
||
|
|
Separate words in ID and class names by a hyphen.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Do not concatenate words and abbreviations in selectors by
|
||
|
|
any characters (including none at all) other than hyphens,
|
||
|
|
in order to improve understanding and scannability.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended: does not separate the words “demo” and “image” */
|
||
|
|
.demoimage {}
|
||
|
|
|
||
|
|
/* Not recommended: uses underscore instead of hyphen */
|
||
|
|
.error_status {}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
#video-id {}
|
||
|
|
.ads-sample {}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Hacks">
|
||
|
|
<SUMMARY>
|
||
|
|
Avoid user agent detection as well as CSS “hacks”—try a different
|
||
|
|
approach first.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
It is tempting to address styling differences over user
|
||
|
|
agent detection or special CSS filters, workarounds, and
|
||
|
|
hacks. Both approaches should be considered last resort in
|
||
|
|
order to achieve and maintain an efficient and manageable
|
||
|
|
code base. Put another way, giving detection and hacks a
|
||
|
|
free pass will hurt projects in the long run as projects
|
||
|
|
tend to take the way of least resistance. That is, allowing
|
||
|
|
and making it easy to use detection and hacks means using
|
||
|
|
detection and hacks more frequently—and more frequently
|
||
|
|
is too frequently.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="CSS Formatting Rules">
|
||
|
|
<STYLEPOINT title="Declaration order">
|
||
|
|
<SUMMARY>
|
||
|
|
Alphabetize declarations.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Put declarations in alphabetical order in order to achieve
|
||
|
|
consistent code in a way that is easy to remember and
|
||
|
|
maintain.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Ignore vendor-specific prefixes for sorting purposes. However,
|
||
|
|
multiple vendor-specific prefixes for a certain CSS property should
|
||
|
|
be kept sorted (e.g. -moz prefix comes before -webkit).
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
background: fuchsia;
|
||
|
|
border: 1px solid;
|
||
|
|
-moz-border-radius: 4px;
|
||
|
|
-webkit-border-radius: 4px;
|
||
|
|
border-radius: 4px;
|
||
|
|
color: black;
|
||
|
|
text-align: center;
|
||
|
|
text-indent: 2em;
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Block content indentation">
|
||
|
|
<SUMMARY>
|
||
|
|
Indent all block content.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Indent all <a href="http://www.w3.org/TR/CSS21/syndata.html#block">block
|
||
|
|
content</a>, that is rules within rules as well as declarations, so to
|
||
|
|
reflect hierarchy and improve understanding.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
@media screen, projection {
|
||
|
|
|
||
|
|
html {
|
||
|
|
background: #fff;
|
||
|
|
color: #444;
|
||
|
|
}
|
||
|
|
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Declaration stops">
|
||
|
|
<SUMMARY>
|
||
|
|
Use a semicolon after every declaration.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
End every declaration with a semicolon for consistency and
|
||
|
|
extensibility reasons.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
.test {
|
||
|
|
display: block;
|
||
|
|
height: 100px
|
||
|
|
}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
.test {
|
||
|
|
display: block;
|
||
|
|
height: 100px;
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Property name stops">
|
||
|
|
<SUMMARY>
|
||
|
|
Use a space after a property name’s colon.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Always use a single space between property and value (but no
|
||
|
|
space between property and colon) for consistency reasons.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
h3 {
|
||
|
|
font-weight:bold;
|
||
|
|
}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
h3 {
|
||
|
|
font-weight: bold;
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Selector and declaration separation">
|
||
|
|
<SUMMARY>
|
||
|
|
Separate selectors and declarations by new lines.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Always start a new line for each selector and declaration.
|
||
|
|
</p>
|
||
|
|
<BAD_CODE_SNIPPET>
|
||
|
|
/* Not recommended */
|
||
|
|
a:focus, a:active {
|
||
|
|
position: relative; top: 1px;
|
||
|
|
}
|
||
|
|
</BAD_CODE_SNIPPET>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Recommended */
|
||
|
|
h1,
|
||
|
|
h2,
|
||
|
|
h3 {
|
||
|
|
font-weight: normal;
|
||
|
|
line-height: 1.2;
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
<STYLEPOINT title="Rule separation">
|
||
|
|
<SUMMARY>
|
||
|
|
Separate rules by new lines.
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
Always put a line between rules.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
html {
|
||
|
|
background: #fff;
|
||
|
|
}
|
||
|
|
|
||
|
|
body {
|
||
|
|
margin: auto;
|
||
|
|
width: 50%;
|
||
|
|
}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<CATEGORY title="CSS Meta Rules">
|
||
|
|
|
||
|
|
<STYLEPOINT title="Section comments">
|
||
|
|
<SUMMARY>
|
||
|
|
Group sections by a section comment (optional).
|
||
|
|
</SUMMARY>
|
||
|
|
<BODY>
|
||
|
|
<p>
|
||
|
|
If possible, group style sheets sections together by using
|
||
|
|
comments. Separate sections with new lines.
|
||
|
|
</p>
|
||
|
|
<CODE_SNIPPET>
|
||
|
|
/* Header */
|
||
|
|
|
||
|
|
#adw-header {}
|
||
|
|
|
||
|
|
/* Footer */
|
||
|
|
|
||
|
|
#adw-footer {}
|
||
|
|
|
||
|
|
/* Gallery */
|
||
|
|
|
||
|
|
.adw-gallery {}
|
||
|
|
</CODE_SNIPPET>
|
||
|
|
</BODY>
|
||
|
|
</STYLEPOINT>
|
||
|
|
</CATEGORY>
|
||
|
|
|
||
|
|
<PARTING_WORDS>
|
||
|
|
<p>
|
||
|
|
<em>Be consistent.</em>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If you’re editing code, take a few minutes to look at the code
|
||
|
|
around you and determine its style. If they use spaces around
|
||
|
|
all their arithmetic operators, you should too. If their
|
||
|
|
comments have little boxes of hash marks around them, make your
|
||
|
|
comments have little boxes of hash marks around them too.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The point of having style guidelines is to have a common vocabulary
|
||
|
|
of coding so people can concentrate on what you’re saying rather
|
||
|
|
than on how you’re saying it. We present global style rules here so
|
||
|
|
people know the vocabulary, but local style is also important. If
|
||
|
|
code you add to a file looks drastically different from the existing
|
||
|
|
code around it, it throws readers out of their rhythm when they go to
|
||
|
|
read it. Avoid this.
|
||
|
|
</p>
|
||
|
|
</PARTING_WORDS>
|
||
|
|
|
||
|
|
<p align="right">
|
||
|
|
Revision 2.1
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</GUIDE>
|