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 href attribute on links
• Never use <div> or <span> for clickable elements

Forms

• Use <form> with proper action and method attributes
• Associate labels with inputs using for attribute
• 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 alt attribute for images
• Use descriptive alt text for informational images
• Use empty alt="" for decorative images
• Use srcset and sizes for responsive images
• Include width and height to prevent layout shift

Video and Audio

• Provide captions and transcripts
• Include multiple source formats for compatibility
• Use poster attribute 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-label for accessible names
• aria-describedby for additional descriptions
• aria-hidden for decorative elements
• aria-expanded for expandable sections
• aria-live for 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-post attributes for server requests
• Leverage hx-target to specify update targets
• Use hx-swap to control how content is inserted
• Implement hx-confirm for critical actions
• Use hx-push-url for 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 defer or async when appropriate
• Use loading="lazy" for below-fold images
• Preload critical resources with <link rel="preload">