the-perfect-developer 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 pfor paragraphsafor links and navigationbuttonfor interactive actions- Avoid
divfor clickable elements
<!-- Not recommended -->
<div 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 (
styleattribute) - 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
alttext 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 “&eur;”.
<!-- 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
classfor styling - Prefer
data-*for scripting - When required, always include hyphen (e.g.,
user-profilenotuserProfile) - Prevents global
windownamespace 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