tomevault-io HTML Development Guidelines
Core Principles
- Write semantic HTML to improve accessibility and SEO
- Use appropriate elements for their intended purpose
- Ensure proper document structure and hierarchy
- Prioritize accessibility by using ARIA roles and attributes when needed
Semantic Elements
Document Structure
- Use
<header>for introductory content and navigation - Use
<main>for the primary content (one per page) - Use
<footer>for footer content - Use
<nav>for navigation sections - Use
<aside>for tangentially related content
Content Sections
- Use
<article>for self-contained, distributable content - Use
<section>for thematic grouping of content - Use appropriate heading hierarchy (
<h1>through<h6>) - Only one
<h1>per page, representing the main topic
Text Content
- Use
<p>for paragraphs - Use
<ul>,<ol>,<dl>for lists appropriately - Use
<blockquote>for quotations - Use
<figure>and<figcaption>for illustrations
Interactive Elements
Buttons and Links
- Use
<button>for clickable actions that don't navigate - Use
<a>for links that navigate to URLs - Always include
hrefattribute on links - Never use
<div>or<span>for clickable elements
Forms
- Use
<form>with properactionandmethodattributes - Associate labels with inputs using
forattribute - Use appropriate input types (
email,tel,number, etc.) - Group related inputs with
<fieldset>and<legend> - Include validation attributes (
required,pattern,min,max)
Media Elements
Images
- Always include
altattribute for images - Use descriptive alt text for informational images
- Use empty
alt=""for decorative images - Use
srcsetandsizesfor responsive images - Include
widthandheightto prevent layout shift
Video and Audio
- Provide captions and transcripts
- Include multiple source formats for compatibility
- Use
posterattribute for video thumbnails - Consider autoplay impact on user experience
Accessibility (ARIA)
When to Use ARIA
- Use ARIA when native HTML semantics are insufficient
- Prefer native HTML elements over ARIA when possible
- Ensure ARIA attributes match actual element behavior
Common ARIA Attributes
aria-labelfor accessible namesaria-describedbyfor additional descriptionsaria-hiddenfor decorative elementsaria-expandedfor expandable sectionsaria-livefor dynamic content updates
Landmarks
- Use landmark roles to define page regions
- Ensure all content is within a landmark
- Use
role="main",role="navigation", etc., only when semantic elements aren't available
Best Practices
Document Meta
- Include proper
<!DOCTYPE html>declaration - Set language attribute on
<html>element - Include viewport meta tag for responsive design
- Use appropriate meta tags for SEO
Code Quality
- Validate HTML using W3C validator
- Maintain consistent indentation
- Close all tags properly (including self-closing)
- Use lowercase for element names and attributes
Deprecated Elements
- Avoid
<font>,<center>,<b>,<i>for styling - Use CSS for visual presentation
- Use
<strong>and<em>for semantic emphasis
HTMX Integration
When using HTMX for interactivity:
- Use
hx-get,hx-postattributes for server requests - Leverage
hx-targetto specify update targets - Use
hx-swapto control how content is inserted - Implement
hx-confirmfor critical actions - Use
hx-push-urlfor URL updates without full refresh
Bootstrap Integration
When using Bootstrap:
- Leverage Bootstrap's grid system for layouts
- Use Bootstrap components with proper markup structure
- Include necessary ARIA attributes with components
- Use Bootstrap's utility classes for spacing and typography
- Minimize custom CSS by using Bootstrap classes
Performance
- Minimize DOM depth and complexity
- Load scripts with
deferorasyncwhen appropriate - Use
loading="lazy"for below-fold images - Preload critical resources with
<link rel="preload">
Converted and distributed by TomeVault — claim your Tome and manage your conversions.