diff --git a/htmlcssguide.html b/htmlcssguide.html index f23825df2..c89b863c2 100644 --- a/htmlcssguide.html +++ b/htmlcssguide.html @@ -8,149 +8,150 @@ - +

Google HTML/CSS Style Guide

+

Background

-

This document defines formatting and style rules for HTML and CSS. It aims at +

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.

- +

General

-

General Style Rules

+

General Style Rules

-

Protocol

+

Protocol

-

Use HTTPS for embedded resources where possible.

+

Use HTTPS for embedded resources where possible.

-

Always use HTTPS (https:) for images and other media files, style sheets, and +

Always use HTTPS (https:) for images and other media files, style sheets, and scripts, unless the respective files are not available over HTTPS.

-
<!-- Not recommended: omits the protocol -->
+
<!-- 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>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
 

 
-
/* Not recommended: omits the protocol */
+
/* 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';
 

 
-
/* Recommended */
+
/* Recommended */
 @import 'https://fonts.googleapis.com/css?family=Open+Sans';
 

 
-
General Formatting Rules

+
General Formatting Rules

 
-
Indentation

+
Indentation

 
-
Indent by 2 spaces at a time.

+
Indent by 2 spaces at a time.

 
-
Don’t use tabs or mix tabs and spaces for indentation.

+
Don’t use tabs or mix tabs and spaces for indentation.

 
-
<ul>
+
<ul>
   <li>Fantastic
   <li>Great
 </ul>
 

 
-
.example {
+
.example {
   color: blue;
 }
 

 
-
Capitalization

+
Capitalization

 
-
Use only lowercase.

+
Use only lowercase.

 
-
All code has to be lowercase: This applies to HTML element names, attributes,
+
All code has to be lowercase: This applies to HTML element names, attributes,
 attribute values (unless text/CDATA), CSS selectors, properties, and property
 values (with the exception of strings).

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <A HREF="/">Home</A>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <img src="google.png" alt="Google">
 

 
-
/* Not recommended */
+
/* Not recommended */
 color: #E5E5E5;
 

 
-
/* Recommended */
+
/* Recommended */
 color: #e5e5e5;
 

 
-
Trailing Whitespace

+
Trailing Whitespace

 
-
Remove trailing white spaces.

+
Remove trailing white spaces.

 
-
Trailing white spaces are unnecessary and can complicate diffs.

+
Trailing white spaces are unnecessary and can complicate diffs.

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <p>What?_
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <p>Yes please.
 

 
-
General Meta Rules

+
General Meta Rules

 
-
Encoding

+
Encoding

 
-
Use UTF-8 (no BOM).

+
Use UTF-8 (no BOM).

 
-
Make sure your editor uses UTF-8 as character encoding, without a byte order
+
Make sure your editor uses UTF-8 as character encoding, without a byte order
 mark.

 
-
Specify the encoding in HTML templates and documents via <meta
+
Specify the encoding in HTML templates and documents via <meta
 charset="utf-8">. Do not specify the encoding of style sheets as these assume
 UTF-8.

 
 
(More on encodings and when and how to specify them can be found in
 Handling character encodings in HTML and CSS.)

 
-
Comments

+
Comments

 
-
Explain code as needed, where possible.

+
Explain code as needed, where possible.

 
-
Use comments to explain code: What does it cover, what purpose does it serve,
+
Use comments to explain code: What does it cover, what purpose does it serve,
 why is respective solution used or preferred?

 
 
(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.)

 
-
Action Items

+
Action Items

 
-
Mark todos and action items with TODO.

+
Mark todos and action items with TODO.

 
-
Highlight todos by using the keyword TODO only, not other common formats like
+
Highlight todos by using the keyword TODO only, not other common formats like
 @@.

 
-
Append action items after a colon as in TODO: action
+
Append action items after a colon as in TODO: action
 item.

 
-
{# TODO: Revisit centering. #}
+
{# TODO: Revisit centering. #}
 <center>Test</center>
 

 
-
<!-- TODO: Remove optional tags. -->
+
<!-- TODO: Remove optional tags. -->
 <ul>
   <li>Apples</li>
   <li>Oranges</li>
@@ -161,7 +162,7 @@ 
HTML

 
 
HTML Style Rules

 
-
Document Type

+
Document Type

 
 
Use <!doctype html>.

 
@@ -175,7 +176,7 @@ 
Document Type

 and CSS constructs, and are likely to cause subtle failures and
 incompatibilities especially when re-using code that expects no-quirks mode.

 
-
HTML Validity

+
HTML Validity

 
 
Use valid HTML where possible.

 
@@ -190,19 +191,19 @@ 
HTML Validity

 learning about technical requirements and constraints, and that ensures proper
 HTML usage.

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <title>Test</title>
 <article>This is only a test.
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <!doctype html>
 <meta charset="utf-8">
 <title>Test</title>
 <article>This is only a test.</article>
 

 
-
Semantics

+
Semantics

 
 
Use HTML according to its purpose.

 
@@ -213,15 +214,15 @@ 
Semantics

 
Using HTML according to its purpose is important for accessibility, reuse, and
 code efficiency reasons.

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <div onclick="goToRecommendations();">All recommendations</div>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <a href="recommendations/">All recommendations</a>
 

 
-
Multimedia Fallback

+
Multimedia Fallback

 
 
Provide alternative contents for multimedia.

 
@@ -237,15 +238,15 @@ 
Multimedia Fallback

 whose purpose is purely decorative which you cannot immediately use CSS for, use
 no alternative text, as in alt="".)

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <img src="spreadsheet.png">
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <img src="spreadsheet.png" alt="Spreadsheet screenshot.">
 

 
-
Separation of Concerns

+
Separation of Concerns

 
 
Separate structure from presentation from behavior.

 
@@ -264,7 +265,7 @@ 
Separation of Concerns

 maintenance reasons. It is always more expensive to change HTML documents and
 templates than it is to update style sheets and scripts.

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <!doctype html>
 <title>HTML sucks</title>
 <link rel="stylesheet" href="base.css" media="screen">
@@ -277,7 +278,7 @@ 
Separation of Concerns

   my website without doing everything all over again!</center>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <!doctype html>
 <title>My first CSS-only redesign</title>
 <link rel="stylesheet" href="default.css">
@@ -288,7 +289,7 @@ 
Separation of Concerns

 <p>It’s awesome!
 

 
-
Entity References

+
Entity References

 
 
Do not use entity references.

 
@@ -299,15 +300,15 @@ 
Entity References

 
The only exceptions apply to characters with special meaning in HTML (like <
 and &) as well as control or “invisible” characters (like no-break spaces).

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 The currency symbol for the Euro is “€”.
 

 
-
Optional Tags

+
Optional Tags

 
 
Omit optional tags (optional).

 
@@ -321,7 +322,7 @@ 
Optional Tags

 For consistency and simplicity reasons it’s best served omitting all optional
 tags, not just a selection.)

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <!doctype html>
 <html>
   <head>
@@ -333,13 +334,13 @@ 
Optional Tags

 </html>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <!doctype html>
 <title>Saving money, saving bytes</title>
 <p>Qed.
 

 
-
type Attributes

+
type Attributes

 
 
Omit type attributes for style sheets and scripts.

 
@@ -352,25 +353,25 @@ 
type Attributes

 text/javascript
 as defaults. This can be safely done even for older browsers.

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <link rel="stylesheet" href="https://www.google.com/css/maia.css"
     type="text/css">
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <link rel="stylesheet" href="https://www.google.com/css/maia.css">
 

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <script src="https://www.google.com/js/gweb/analytics/autotrack.js"
     type="text/javascript"></script>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
 

 
-
id Attributes

+
id Attributes

 
 
Avoid unnecessary id attributes.

 
@@ -386,11 +387,11 @@ 
id Attributes

 hyphen are still available as property names, these cannot be referenced as
 global JavaScript variables.

 
-
<!-- Not recommended: `window.userProfile` will resolve to reference the <div> node -->
+
<!-- Not recommended: `window.userProfile` will resolve to reference the <div> node -->
 <div id="userProfile"></div>
 

 
-
<!-- Recommended: `id` attribute is required and its value includes a hyphen -->
+
<!-- Recommended: `id` attribute is required and its value includes a hyphen -->
 <div aria-describedby="user-profile">
   …
   <div id="user-profile"></div>
@@ -400,7 +401,7 @@ 
id Attributes

 
 
HTML Formatting Rules

 
-
General Formatting

+
General Formatting

 
 
Use a new line for every block, list, or table element, and indent every such
 child element.

@@ -415,19 +416,19 @@ 
General Formatting

 put all li elements in one line. A linter is encouraged to throw a warning
 instead of an error.)

 
-
<blockquote>
+
<blockquote>
   <p><em>Space</em>, the final frontier.</p>
 </blockquote>
 

 
-
<ul>
+
<ul>
   <li>Moe
   <li>Larry
   <li>Curly
 </ul>
 

 
-
<table>
+
<table>
   <thead>
     <tr>
       <th scope="col">Income
@@ -439,7 +440,7 @@ 
General Formatting

 </table>
 

 
-
HTML Line-Wrapping

+
HTML Line-Wrapping

 
 
Break long lines (optional).

 
@@ -450,7 +451,7 @@ 
HTML Line-Wrapping

 wrapped attributes from child elements. Lines should be wrapped consistently
 within a project, ideally enforced by automated code formatting tools.

 
-
<button
+
<button
   mat-icon-button
   color="primary"
   class="menu-button"
@@ -460,13 +461,13 @@ 
HTML Line-Wrapping

 </button>
 

 
-
<button mat-icon-button color="primary" class="menu-button"
+
<button mat-icon-button color="primary" class="menu-button"
     (click)="openMenu()">
   <mat-icon>menu</mat-icon>
 </button>
 

 
-
<button
+
<button
     mat-icon-button
     color="primary"
     class="menu-button"
@@ -475,7 +476,7 @@ 
HTML Line-Wrapping

 </button>
 

 
-
<button mat-icon-button
+
<button mat-icon-button
         color="primary"
         class="menu-button"
         (click)="openMenu()">
@@ -483,18 +484,18 @@ 
HTML Line-Wrapping

 </button>
 

 
-
HTML Quotation Marks

+
HTML Quotation Marks

 
 
When quoting attributes values, use double quotation marks.

 
 
Use double ("") rather than single quotation marks ('') around attribute
 values.

 
-
<!-- Not recommended -->
+
<!-- Not recommended -->
 <a class='maia-button maia-button-secondary'>Sign in</a>
 

 
-
<!-- Recommended -->
+
<!-- Recommended -->
 <a class="maia-button maia-button-secondary">Sign in</a>
 

 
@@ -502,7 +503,7 @@ 
CSS

 
 
CSS Style Rules

 
-
CSS Validity

+
CSS Validity

 
 
Use valid CSS where possible.

 
@@ -517,7 +518,7 @@ 
CSS Validity

 CSS code that may not have any effect and can be removed, and that ensures
 proper CSS usage.

 
-
Class Naming

+
Class Naming

 
 
Use meaningful or generic class names.

 
@@ -533,7 +534,7 @@ 
Class Naming

 
Using functional or generic names reduces the probability of unnecessary
 document or template changes.

 
-
/* Not recommended: meaningless */
+
/* Not recommended: meaningless */
 .yee-1901 {}
 
 /* Not recommended: presentational */
@@ -541,7 +542,7 @@ 
Class Naming

 .clear {}
 

 
-
/* Recommended: specific */
+
/* Recommended: specific */
 .gallery {}
 .login {}
 .video {}
@@ -551,7 +552,7 @@ 
Class Naming

 .alt {}
 

 
-
Class Name Style

+
Class Name Style

 
 
Use class names that are as short as possible but as long as necessary.

 
@@ -560,17 +561,17 @@ 
Class Name Style

 
Using class names this way contributes to acceptable levels of understandability
 and code efficiency.

 
-
/* Not recommended */
+
/* Not recommended */
 .navigation {}
 .atr {}
 

 
-
/* Recommended */
+
/* Recommended */
 .nav {}
 .author {}
 

 
-
Class Name Delimiters

+
Class Name Delimiters

 
 
Separate words in class names by a hyphen.

 
@@ -578,14 +579,14 @@ 
Class Name Delimiters

 
-
/* Not recommended: does not separate the words “demo” and “image” */
+
/* Not recommended: does not separate the words “demo” and “image” */
 .demoimage {}
 
 /* Not recommended: uses underscore instead of hyphen */
 .error_status {}
 

 
-
/* Recommended */
+
/* Recommended */
 .video-id {}
 .ads-sample {}
 

@@ -601,11 +602,11 @@ 
Prefixes

 
Using namespaces helps preventing naming conflicts and can make maintenance
 easier, for example in search and replace operations.

 
-
.adw-help {} /* AdWords */
+
.adw-help {} /* AdWords */
 .maia-note {} /* Maia */
 

 
-
Type Selectors

+
Type Selectors

 
 
Avoid qualifying class names with type selectors.

 
@@ -615,17 +616,17 @@ 
Type Selectors

 
Avoiding unnecessary ancestor selectors is useful for
 performance reasons.

 
-
/* Not recommended */
+
/* Not recommended */
 ul.example {}
 div.error {}
 

 
-
/* Recommended */
+
/* Recommended */
 .example {}
 .error {}
 

 
-
ID Selectors

+
ID Selectors

 
 
Avoid ID selectors.

 
@@ -633,15 +634,15 @@ 
ID Selectors

 difficult to guarantee when a page contains many components worked on by many
 different engineers. Class selectors should be preferred in all situations.

 
-
/* Not recommended */
+
/* Not recommended */
 #example {}
 

 
-
/* Recommended */
+
/* Recommended */
 .example {}
 

 
-
Shorthand Properties

+
Shorthand Properties

 
 
Use shorthand properties where possible.

 
@@ -652,7 +653,7 @@ 
Shorthand Properties

 
 
Using shorthand properties is useful for code efficiency and understandability.

 
-
/* Not recommended */
+
/* Not recommended */
 border-top-style: none;
 font-family: palatino, georgia, serif;
 font-size: 100%;
@@ -663,49 +664,49 @@ 
Shorthand Properties

 padding-top: 0;
 

 
-
/* Recommended */
+
/* Recommended */
 border-top: 0;
 font: 100%/1.6 palatino, georgia, serif;
 padding: 0 1em 2em;
 

 
-
0 and Units

+
0 and Units

 
 
Omit unit specification after “0” values, unless required.

 
 
Do not use units after 0 values unless they are required.

 
-
flex: 0px; /* This flex-basis component requires a unit. */
+
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;
 

 
-
Leading 0s

+
Leading 0s

 
 
Always include leading “0”s in values.

 
 
Put 0s in front of values or lengths between -1 and 1.

 
-
font-size: 0.8em;
+
font-size: 0.8em;
 

 
-
Hexadecimal Notation

+
Hexadecimal Notation

 
 
Use 3 character hexadecimal notation where possible.

 
 
For color values that permit it, 3 character hexadecimal notation is shorter and
 more succinct.

 
-
/* Not recommended */
+
/* Not recommended */
 color: #eebbcc;
 

 
-
/* Recommended */
+
/* Recommended */
 color: #ebc;
 

 
-
Important Declarations

+
Important Declarations

 
 
Avoid using !important declarations.

 
@@ -714,19 +715,19 @@ 
Important Declarations

 selector specificity
 to override properties instead.

 
-
/* Not recommended */
+
/* Not recommended */
 .example {
   font-weight: bold !important;
 }
 

 
-
/* Recommended */
+
/* Recommended */
 .example {
   font-weight: bold;
 }
 

 
-
Hacks

+
Hacks

 
 
Avoid user agent detection as well as CSS “hacks”—try a different approach
 first.

@@ -742,7 +743,7 @@ 
Hacks

 
 
CSS Formatting Rules

 
-
Declaration Order

+
Declaration Order

 
 
Alphabetize declarations (optional).

 
@@ -755,17 +756,17 @@ 
Declaration Order

 vendor-specific prefixes for a certain CSS property should be kept sorted (e.g.
 -moz prefix comes before -webkit).

 
-
background: fuchsia;
+
background: fuchsia;
 border: 1px solid;
 -moz-border-radius: 4px;
 -webkit-border-radius: 4px;
 border-radius: 4px;
-color: black;
+color: rgb(255, 200, 200);
 text-align: center;
 text-indent: 2em;
 

 
-
Block Content Indentation

+
Block Content Indentation

 
 
Indent all block content.

 
@@ -774,7 +775,7 @@ 
Block Content Indentation
 
-
@media screen, projection {
+
@media screen, projection {
 
   html {
     background: #fff;
@@ -784,47 +785,47 @@ 
Block Content Indentation

 
-
Declaration Stops

+
Declaration Stops

 
 
Use a semicolon after every declaration.

 
 
End every declaration with a semicolon for consistency and extensibility
 reasons.

 
-
/* Not recommended */
+
/* Not recommended */
 .test {
   display: block;
   height: 100px
 }
 

 
-
/* Recommended */
+
/* Recommended */
 .test {
   display: block;
   height: 100px;
 }
 

 
-
Property Name Stops

+
Property Name Stops

 
 
Use a space after a property name’s colon.

 
 
Always use a single space between property and value (but no space between
 property and colon) for consistency reasons.

 
-
/* Not recommended */
+
/* Not recommended */
 h3 {
   font-weight:bold;
 }
 

 
-
/* Recommended */
+
/* Recommended */
 h3 {
   font-weight: bold;
 }
 

 
-
Declaration Block Separation

+
Declaration Block Separation

 
 
Use a space between the last selector and the declaration block.

 
@@ -835,7 +836,7 @@ 
Declaration Block Separat
 
The opening brace should be on the same line as the last selector in a given
 rule.

 
-
/* Not recommended: missing space */
+
/* Not recommended: missing space */
 .video{
   margin-top: 1em;
 }
@@ -847,25 +848,25 @@ 
Declaration Block Separat
 }
 

 
-
/* Recommended */
+
/* Recommended */
 .video {
   margin-top: 1em;
 }
 

 
-
Selector and Declaration Separation

+
Selector and Declaration Separation

 
 
Separate selectors and declarations by new lines.

 
 
Always start a new line for each selector and declaration.

 
-
/* Not recommended */
+
/* Not recommended */
 a:focus, a:active {
   position: relative; top: 1px;
 }
 

 
-
/* Recommended */
+
/* Recommended */
 h1,
 h2,
 h3 {
@@ -874,13 +875,13 @@ 
Selector and Decla
 }
 

 
-
Rule Separation

+
Rule Separation

 
 
Separate rules by new lines.

 
 
Always put a blank line (two line breaks) between rules.

 
-
html {
+
html {
   background: #fff;
 }
 
@@ -890,7 +891,7 @@ 
Rule Separation

 }
 

 
-
CSS Quotation Marks

+
CSS Quotation Marks

 
 
Use single ('') rather than double ("") quotation marks for attribute
 selectors and property values.

@@ -900,7 +901,7 @@ 
CSS Quotation Marks

 
Exception: If you do need to use the @charset rule, use double quotation
 marks—single quotation marks are not permitted.

 
-
/* Not recommended */
+
/* Not recommended */
 @import url("https://www.google.com/css/maia.css");
 
 html {
@@ -908,7 +909,7 @@ 
CSS Quotation Marks

 }
 

 
-
/* Recommended */
+
/* Recommended */
 @import url(https://www.google.com/css/maia.css);
 
 html {
@@ -916,16 +917,16 @@ 
CSS Quotation Marks

 }
 

 
-
CSS Meta Rules

+
CSS Meta Rules

 
-
Section Comments

+
Section Comments

 
 
Group sections by a section comment (optional).

 
 
If possible, group style sheet sections together by using comments. Separate
 sections with new lines.

 
-
/* Header */
+
/* Header */
 
 .adw-header {}
 
diff --git a/include/styleguide.css b/include/styleguide.css
index b78b8f98f..0c61d9da1 100644
--- a/include/styleguide.css
+++ b/include/styleguide.css
@@ -69,7 +69,7 @@ pre {
 }
 
 pre.prettyprint {
-  padding:6px 10px !important;
+  /* padding:6px 10px !important; */
   border:1px solid #bbb !important;
 }
 
diff --git a/javaguide.css b/javaguide.css
index 19f2fa3c7..1c652c3d7 100644
--- a/javaguide.css
+++ b/javaguide.css
@@ -433,7 +433,7 @@ pre {
 }
 
 pre.prettyprint {
-  padding: 6px 10px !important;
+  /* padding: 6px 10px !important; */
   border: 1px solid #bbb !important;
 }
 
@@ -463,11 +463,11 @@ pre.badcode {
 
 @media print {
   .str {
-    color: #060;
+    color: rgb(0, 255, 0);
   }
 
   .kwd {
-    color: #006;
+    color: rgb(44, 44, 241);
     font-weight: bold;
   }
 
@@ -482,7 +482,7 @@ pre.badcode {
   }
 
   .lit {
-    color: #044;
+    color: rgb(0, 255, 255);
   }
 
   .pun,
@@ -496,7 +496,7 @@ pre.badcode {
   }
 
   .tag {
-    color: #006;
+    color: rgb(70, 70, 255);
     font-weight: bold;
   }
 
@@ -505,7 +505,9 @@ pre.badcode {
   }
 
   .atv {
-    color: #060;
+    color: rgb(0, 255, 0);
+    font-weight: bold;
+    font-size: 10px;
   }
 
   h1 {