Agent skill

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/html-markup

SKILL.md

HTML Markup Skill

Instructions

When writing HTML:

1. Document Structure

html
<!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

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

html
<!-- 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

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

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

6. Links

html
<!-- 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

html
<!-- 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

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

html
<!-- 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

Didn't find tool you were looking for?

Be as detailed as possible for better results