# HTML

> Guidelines for semantic HTML markup, document structure, forms, accessibility attributes, and modern HTML best practices Use when this capability is needed.

- Skill: `tomevault-io/html` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/html`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/html/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/html

---


# 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">`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/mindrally) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->

