| name | html-markup |
| description | 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. |
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>© 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">
6. Links
<!-- 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