html-markup

Write semantic, accessible HTML5 markup following best practices for structure, SEO, and accessibility. Use when creating HTML templates, fixing markup issues, or building web page structures.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill enables the generation of high-quality, semantic HTML5 markup designed for optimal SEO performance and web accessibility (A11Y). It provides comprehensive templates and best practices for document structure, interactive components, and form validation, ensuring that web projects are both search-engine friendly and inclusive for all users.

Use Cases

  • Developing SEO-optimized web page structures using semantic elements like <header>, <main>, and <article> to improve search engine indexing.
  • Refactoring legacy HTML code to meet modern accessibility standards (WCAG) by implementing proper ARIA roles and heading hierarchies.
  • Creating complex, accessible web forms with integrated validation, descriptive labels, and keyboard navigation support.
  • Implementing responsive and performant media patterns, including <picture> tags and lazy-loading images for better Core Web Vitals.
  • Building interactive UI components such as accessible modals, accordions, and data tables that maintain structural integrity across devices.
namehtml-markup
descriptionWrite semantic, accessible HTML5 markup following best practices for structure, SEO, and accessibility. Use when creating HTML templates, fixing markup issues, or building web page structures.

HTML Markup Skill

Instructions

When writing HTML:

1. Document Structure

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="description" content="Page description for SEO">
  <title>Page Title | Brand</title>

  <!-- Preconnect to external domains -->
  <link rel="preconnect" href="https://fonts.googleapis.com">

  <!-- Critical CSS inline -->
  <style>/* Critical styles */</style>

  <!-- External stylesheets -->
  <link rel="stylesheet" href="styles.css">

  <!-- Favicon -->
  <link rel="icon" href="/favicon.ico" sizes="any">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
</head>
<body>
  <!-- Content -->

  <!-- Scripts at end -->
  <script src="main.js" defer></script>
</body>
</html>

2. Semantic Elements

<header>
  <nav aria-label="Main navigation">
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>
</header>

<main>
  <article>
    <header>
      <h1>Article Title</h1>
      <time datetime="2025-01-15">January 15, 2025</time>
    </header>

    <section>
      <h2>Section Heading</h2>
      <p>Content...</p>
    </section>

    <aside>
      <h3>Related Content</h3>
    </aside>

    <footer>
      <p>Article footer content</p>
    </footer>
  </article>
</main>

<aside aria-label="Sidebar">
  <section>
    <h2>Widget Title</h2>
  </section>
</aside>

<footer>
  <nav aria-label="Footer navigation">
    <!-- Footer links -->
  </nav>
  <p>&copy; 2025 Company Name</p>
</footer>

3. Headings Hierarchy

<!-- Correct hierarchy -->
<h1>Page Title (one per page)</h1>
  <h2>Main Section</h2>
    <h3>Subsection</h3>
      <h4>Sub-subsection</h4>
  <h2>Another Main Section</h2>
    <h3>Subsection</h3>

<!-- Never skip levels -->
<!-- ❌ Bad: h1 → h3 -->
<!-- ✓ Good: h1 → h2 → h3 -->

4. Forms

<form action="/submit" method="POST" novalidate>
  <fieldset>
    <legend>Contact Information</legend>

    <div class="form-group">
      <label for="name">Full Name <span aria-hidden="true">*</span></label>
      <input
        type="text"
        id="name"
        name="name"
        required
        autocomplete="name"
        aria-required="true"
      >
    </div>

    <div class="form-group">
      <label for="email">Email Address</label>
      <input
        type="email"
        id="email"
        name="email"
        required
        autocomplete="email"
        aria-describedby="email-hint"
      >
      <p id="email-hint" class="hint">We'll never share your email.</p>
    </div>

    <div class="form-group">
      <label for="message">Message</label>
      <textarea
        id="message"
        name="message"
        rows="5"
        required
      ></textarea>
    </div>

    <div class="form-group">
      <input type="checkbox" id="newsletter" name="newsletter">
      <label for="newsletter">Subscribe to newsletter</label>
    </div>
  </fieldset>

  <button type="submit">Send Message</button>
</form>

5. Images

<!-- Standard image -->
<img
  src="image.jpg"
  alt="Descriptive alt text"
  width="800"
  height="600"
  loading="lazy"
  decoding="async"
>

<!-- Responsive images -->
<picture>
  <source
    media="(min-width: 1200px)"
    srcset="large.webp"
    type="image/webp"
  >
  <source
    media="(min-width: 800px)"
    srcset="medium.webp"
    type="image/webp"
  >
  <img
    src="small.jpg"
    alt="Description"
    width="400"
    height="300"
    loading="lazy"
  >
</picture>

<!-- Figure with caption -->
<figure>
  <img src="chart.png" alt="Sales growth chart showing 50% increase">
  <figcaption>Fig 1: Sales growth Q1-Q4 2024</figcaption>
</figure>

<!-- Decorative image -->
<img src="decoration.svg" alt="" role="presentation">
<!-- Internal link -->
<a href="/about">About Us</a>

<!-- External link -->
<a href="https://example.com" target="_blank" rel="noopener noreferrer">
  External Site
  <span class="visually-hidden">(opens in new tab)</span>
</a>

<!-- Download link -->
<a href="/file.pdf" download>Download PDF</a>

<!-- Skip link (accessibility) -->
<a href="#main-content" class="skip-link">Skip to main content</a>

<!-- Anchor link -->
<a href="#section-2">Jump to Section 2</a>

7. Lists

<!-- Unordered list -->
<ul>
  <li>Item one</li>
  <li>Item two</li>
</ul>

<!-- Ordered list -->
<ol>
  <li>First step</li>
  <li>Second step</li>
</ol>

<!-- Description list -->
<dl>
  <dt>Term</dt>
  <dd>Definition</dd>

  <dt>Another term</dt>
  <dd>Its definition</dd>
</dl>

<!-- Navigation list -->
<nav>
  <ul role="list">
    <li><a href="/" aria-current="page">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

8. Tables

<table>
  <caption>Monthly Sales Report</caption>
  <thead>
    <tr>
      <th scope="col">Month</th>
      <th scope="col">Sales</th>
      <th scope="col">Growth</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">January</th>
      <td>$10,000</td>
      <td>+5%</td>
    </tr>
    <tr>
      <th scope="row">February</th>
      <td>$12,000</td>
      <td>+20%</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <th scope="row">Total</th>
      <td>$22,000</td>
      <td>—</td>
    </tr>
  </tfoot>
</table>

9. Interactive Elements

<!-- Button -->
<button type="button" onclick="handleClick()">
  Click Me
</button>

<!-- Details/Summary (accordion) -->
<details>
  <summary>Click to expand</summary>
  <p>Hidden content revealed on click.</p>
</details>

<!-- Dialog/Modal -->
<dialog id="modal">
  <h2>Modal Title</h2>
  <p>Modal content</p>
  <button onclick="document.getElementById('modal').close()">
    Close
  </button>
</dialog>

10. Accessibility Checklist

  • All images have alt text
  • Proper heading hierarchy
  • Form inputs have labels
  • Links are descriptive
  • Color isn't only indicator
  • Focus states visible
  • Skip link present
  • ARIA used correctly
  • Keyboard navigable
  • Language declared