html-standards
HTML Standards & Best Practices
Apply these standards when writing HTML markup to ensure accessibility, semantics, maintainability, and security.
Structure & Semantics
1. Use Semantic HTML Elements
Prefer semantic elements over generic divs and spans:
Good:
<header>
<nav>
<ul>
<li><a href="/">Home</a></li>
</ul>
</nav>
</header>
<main>
<article>
<h2>Article Title</h2>
<section>
<p>Content...</p>
</section>
</article>
<aside>
<h3>Related Links</h3>
</aside>
</main>
<footer>
<p>© 2026 Company Name</p>
</footer>
Bad:
<div class="header">
<div class="nav">...</div>
</div>
<div class="main">
<div class="article">...</div>
</div>
2. Document Structure
Always use proper HTML5 document structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Page Title</title>
</head>
<body>
<!-- Content -->
</body>
</html>
3. Heading Hierarchy
- Use headings in logical order (H2, H3, H4, etc.)
- Do NOT use
<h1>(reserved for page title generation) - Don't skip heading levels
Good:
<h2>Main Section</h2>
<h3>Subsection</h3>
<h4>Detail</h4>
Bad:
<h1>Title</h1>
<!-- Don't use H1 -->
<h4>Content</h4>
<!-- Skipped H2, H3 -->
4. Code Organization
- Indent nested elements consistently (2 spaces)
- Use blank lines to separate logical sections
- Keep lines readable (max 120 characters)
Accessibility
5. Images
All images must have descriptive alt text:
<!-- Informative image -->
<img src="chart.png" alt="Sales chart showing 20% increase in Q4 2025" />
<!-- Decorative image -->
<img src="divider.png" alt="" />
6. Forms
Always label form controls:
<form>
<label for="email">Email address</label>
<input type="email" id="email" name="email" required />
<label for="password">Password</label>
<input type="password" id="password" name="password" required />
<button type="submit">Submit</button>
</form>
7. Keyboard Navigation
Ensure interactive elements are keyboard accessible:
<button type="button">Clickable Button</button>
<a href="/page">Link to Page</a>
<!-- Only use tabindex="0" for custom interactive elements -->
<div role="button" tabindex="0" onclick="handleClick()">Custom Button</div>
8. ARIA Attributes
Use ARIA only when native HTML is insufficient:
<!-- Good: Native HTML -->
<button>Click me</button>
<!-- OK: ARIA when needed -->
<button aria-label="Close dialog">×</button>
<!-- Good: ARIA for custom widgets -->
<div role="dialog" aria-labelledby="dialog-title" aria-modal="true">
<h2 id="dialog-title">Dialog Title</h2>
</div>
Maintainability
9. Avoid Inline Styles and Scripts
Keep HTML clean by using external files:
Bad:
<div style="color: red; font-size: 20px;" onclick="alert('clicked')">Content</div>
Good:
<div class="error-text" data-action="show-alert">Content</div>
10. Consistent Naming
Use lowercase, hyphen-separated names:
<div class="main-header"></div>
<nav class="site-navigation"></nav>
<button id="submit-button">Submit</button>
11. Code Comments
Use comments to organize sections:
<!-- Header Section -->
<header>
<!-- Navigation -->
<nav>...</nav>
</header>
<!-- Main Content -->
<main>...</main>
Security
12. Escape User-Generated Content
Never inject raw user data into the DOM:
Bad (XSS vulnerability):
element.innerHTML = userInput
Good:
element.textContent = userInput
// OR use DOMPurify for HTML
element.innerHTML = DOMPurify.sanitize(userInput)
13. Security Meta Tags
Include security headers:
<head>
<meta charset="UTF-8" />
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'" />
<meta http-equiv="X-Content-Type-Options" content="nosniff" />
<meta http-equiv="Strict-Transport-Security" content="max-age=31536000; includeSubDomains" />
</head>
Performance
14. Optimize Images
<!-- Modern formats with fallback -->
<picture>
<source srcset="image.webp" type="image/webp" />
<source srcset="image.jpg" type="image/jpeg" />
<img src="image.jpg" alt="Description" loading="lazy" />
</picture>
<!-- Lazy loading for non-critical images -->
<img src="image.jpg" alt="Description" loading="lazy" />
15. Resource Hints
Use preload and prefetch for critical resources:
<head>
<!-- Preload critical CSS -->
<link rel="preload" href="critical.css" as="style" />
<!-- Prefetch next page -->
<link rel="prefetch" href="/next-page" />
<!-- DNS prefetch for external domains -->
<link rel="dns-prefetch" href="https://api.example.com" />
</head>
Complete Example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Brief page description for SEO" />
<meta http-equiv="Content-Security-Policy" content="default-src 'self'" />
<title>Page Title - Site Name</title>
<link rel="preload" href="styles.css" as="style" />
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<!-- Header -->
<header class="site-header">
<nav class="main-navigation" aria-label="Main navigation">
<ul>
<li><a href="/" aria-current="page">Home</a></li>
<li><a href="/about">About</a></li>
<li><a href="/contact">Contact</a></li>
</ul>
</nav>
</header>
<!-- Main Content -->
<main id="main-content">
<article>
<h2>Article Title</h2>
<section>
<h3>Section Heading</h3>
<p>Content paragraph with <a href="/link">descriptive link text</a>.</p>
<img src="image.jpg" alt="Detailed description of the image" loading="lazy" />
</section>
<section>
<h3>Form Section</h3>
<form action="/submit" method="post">
<label for="name">Full Name</label>
<input type="text" id="name" name="name" required />
<label for="email">Email Address</label>
<input type="email" id="email" name="email" required />
<button type="submit">Send</button>
</form>
</section>
</article>
<aside class="sidebar">
<h3>Related Content</h3>
<ul>
<li><a href="/related-1">Related Article 1</a></li>
<li><a href="/related-2">Related Article 2</a></li>
</ul>
</aside>
</main>
<!-- Footer -->
<footer class="site-footer">
<p>© 2026 Company Name. All rights reserved.</p>
</footer>
<script src="app.js" defer></script>
</body>
</html>
Validation
Tools
- W3C Markup Validator
- Browser DevTools accessibility audits
- axe DevTools
Checklist
- ✅ Valid HTML5 structure
- ✅ Proper DOCTYPE and language attribute
- ✅ Semantic elements used appropriately
- ✅ No H1 in content (reserved for page title)
- ✅ All images have alt text
- ✅ Forms have proper labels
- ✅ Keyboard navigation works
- ✅ Security meta tags included
- ✅ External CSS/JS files used
- ✅ Consistent naming conventions
When to Apply
Apply these standards when:
- Creating HTML pages
- Building templates
- Writing component markup
- Reviewing HTML code
- User asks about HTML best practices
- Working with any HTML-based template engine
More from devbyray/github-copilot-starter
markdown-standards
Documentation and content creation standards for Markdown files. Use when creating or editing .md files, writing documentation, README files, or when the user asks about Markdown formatting, content structure, front matter, or documentation best practices.
6css-standards
Guidelines for writing CSS that is simple, readable, and maintainable. Use when working with .css, .scss, .sass files, CSS-in-JS, styled-components, or when the user asks about CSS organization, selectors, specificity, reusability, performance, or responsive design patterns.
4javascript-typescript-standards
Guidelines for writing JavaScript and TypeScript code that is simple, readable, and maintainable. Use when working with .js, .jsx, .ts, .tsx, .mjs, .cjs files, or when the user asks about JavaScript/TypeScript coding standards, ES2022 features, Node.js modules, async/await patterns, or testing with Vitest.
4nuxt-development
Standards for Nuxt.js 3 development with auto-imports, file-based routing, and SSR/SSG capabilities. Use when working with Nuxt projects, pages/, layouts/, composables/ directories, or when the user asks about Nuxt-specific patterns, server-side rendering, or Nuxt configuration.
3testing-tdd
Test-Driven Development workflow and testing standards. Use when writing tests, implementing TDD, working with Vitest (frontend), xUnit or MsTest (backend), or when the user asks about testing strategies, test coverage, or TDD methodology.
3csharp-standards
C# coding standards and conventions including naming, formatting, and best practices. Use when working with .cs files, writing C# code, or when the user asks about C# naming conventions, code structure, XML documentation, or .NET development patterns.
3