SKILL.md
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 names
aria-describedbyfor additional descriptions
aria-hiddenfor decorative elements
aria-expandedfor expandable sections
aria-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">