HTML Style Guide

This skill applies Google's HTML style guide conventions to ensure clean, semantic, and maintainable HTML code.

Core Principles

Document Structure

Always use HTML5 doctype and UTF-8 encoding:

<!doctype html>
<meta charset="utf-8">
<title>Page Title</title>

Semantic HTML

Use elements according to their purpose:

Headings (h1-h6) for hierarchical structure
p for paragraphs
a for links and navigation
button for interactive actions
Avoid div for clickable elements

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

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

Separation of Concerns

Keep structure (HTML), presentation (CSS), and behavior (JavaScript) strictly separated:

No inline styles (style attribute)
No inline event handlers (onclick, etc.)
Link minimal CSS and JavaScript files

<!-- Not recommended -->
<h1 style="font-size: 1em;">HTML sucks</h1>
<center>Centered content</center>

<!-- Recommended -->
<!doctype html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>

HTML Style Rules

Valid HTML

Use valid HTML code tested with W3C HTML validator
Ensure proper opening and closing tags
Nest elements correctly

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

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

Protocol

Always use HTTPS for embedded resources:

<!-- Not recommended -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

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

Multimedia

Provide alternative content for accessibility:

Use meaningful alt text for images
Provide transcripts/captions for video/audio
Use alt="" for purely decorative images

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

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

Entity References

Do not use entity references (except for special HTML characters):

Exception: <, &, and invisible characters
Use UTF-8 encoding directly

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

<!-- Recommended -->
The currency symbol for the Euro is "€".

Optional Tags

Consider omitting optional tags for file size optimization:

<!-- Not recommended -->
<!doctype html>
<html>
  <head>
    <title>Spending money, spending bytes</title>
  </head>
  <body>
    <p>Sic.</p>
  </body>
</html>

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

Type Attributes

Omit type attributes for CSS and JavaScript (HTML5 defaults):

<!-- Not recommended -->
<link rel="stylesheet" href="styles.css" type="text/css">
<script src="script.js" type="text/javascript"></script>

<!-- Recommended -->
<link rel="stylesheet" href="styles.css">
<script src="script.js"></script>

ID Attributes

Minimize use of id attributes:

Prefer class for styling
Prefer data-* for scripting
When required, always include hyphen (e.g., user-profile not userProfile)
Prevents global window namespace pollution

<!-- Not recommended: window.userProfile conflicts -->
<div id="userProfile"></div>

<!-- Recommended -->
<div aria-describedby="user-profile">
  <div id="user-profile"></div>
</div>

Formatting Rules

Indentation

Indent by 2 spaces (no tabs):

<ul>
  <li>Fantastic
  <li>Great
</ul>

Capitalization

Use only lowercase for:

Element names
Attributes
Attribute values (except text/CDATA)

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

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

Whitespace

Remove trailing whitespace:

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

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

Block Elements

Use new line for every block, list, or table element:

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

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

<table>
  <thead>
    <tr>
      <th scope="col">Income
      <th scope="col">Taxes
  <tbody>
    <tr>
      <td>$ 5.00
      <td>$ 4.50
</table>

Line Wrapping

Break long lines for readability (optional but recommended):

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

Quotation Marks

Use double quotes for attribute values:

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

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

Code Quality Guidelines

Comments

Use comments to explain complex sections:

<!-- TODO: Remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

Action Items

Mark todos with TODO: keyword:

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

Quick Reference

Rule	Convention
Doctype	`<!doctype html>`
Encoding	UTF-8 with `<meta charset="utf-8">`
Protocol	HTTPS for all resources
Indentation	2 spaces
Case	Lowercase only
Quotes	Double quotes (`"`)
Type attributes	Omit for CSS/JS
Semantic elements	Use elements for their purpose
Accessibility	Always provide `alt` for images
IDs	Minimize use, include hyphens

Additional Resources

references/html-detailed.md - Comprehensive HTML patterns and edge cases
W3C HTML Validator
Google HTML/CSS Style Guide

Summary

Write HTML that is:

Valid: Passes W3C validation
Semantic: Uses elements for their intended purpose
Accessible: Includes alt text and proper structure
Separated: No inline styles or scripts
Consistent: Follows formatting conventions
Lowercase: All element/attribute names
Secure: HTTPS for all resources