Loading...

html

Original：🇺🇸 English

Translated

Guidelines for semantic HTML markup, document structure, forms, accessibility attributes, and modern HTML best practices

2installs

Sourcemindrally/skills

Added on2026-02-08

NPX Install

npx skill4agent add mindrally/skills html

Tags

Translated version includes tags in frontmatter

semantic-html web-accessibility html-best-practices htmx-integration bootstrap-integration

SKILL.md Content

View Translation Comparison →

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