html | SkillBundle

OverviewHistoryStatsSecurity

npx skills add ...

Documentation

SKILL.md

html | SkillBundle

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

npx skills add mindrally/skills --skill html

Documentation

SKILL.mdView source

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