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 “&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 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