<!-- skill: HTML Foundation | version: 1.0.0 | description: Semantic HTML5 structure, forms, media, meta and email-safe markup | category: Web -->

## Instructions
- Always start from `<!DOCTYPE html>` with `<html lang="en">`, correct `<head>` order: charset, viewport, title, description, OG/Twitter tags, then CSS.
- Use semantic landmarks: one `<main>`, `<header>/<nav>/<footer>`, `<article>/<section>` with headings, never div-soup.
- Maintain strict heading hierarchy: single `<h1>` per page, no skipped levels, headings describe sections not styling.
- Forms: pair every `<input>` with `<label for>`, use correct `type` (email, tel, url, date), `required`, `pattern`, `autocomplete` attributes.
- Prefer native validation (`required`, `minlength`, `type=email`) + `setCustomValidity()` over JS-only checks; always validate server-side too.
- Tables: use `<caption>`, `<thead>/<tbody>`, `<th scope="col|row">`; never use tables for layout.
- Media: `<img alt>` always (empty `alt=""` only for decorative), `width/height` to prevent CLS, `loading="lazy"` below fold, `<figure>/<figcaption>` for captioned media.
- Links vs buttons: `<a href>` navigates, `<button type>` triggers actions; never `href="#"` or div-click handlers.
- Meta/OG: every public page needs `description`, canonical, `og:title/description/image`, `twitter:card`; favicon + `theme-color`.
- Accessibility baseline: `lang` set, 4.5:1 text contrast, visible `:focus-visible`, 44px touch targets, `aria-*` only when native semantics fall short.
- Email-safe HTML: table layout, inline styles, max 600px width, web-safe fonts, no external CSS/JS, always plain-text fallback.
- Never expose sensitive data in comments; keep IDs/classes kebab-case and meaningful.

## Examples
- Marketing landing page: semantic header/hero (`<main>` + sections), feature grid, testimonial `<figure>`, contact `<form>` with native validation, full OG/meta set.
- Accessible data table: product comparison with `<caption>`, `<th scope>`, sticky header, responsive horizontal-scroll wrapper with `role="region" aria-label` + `tabindex="0"`.
- HTML email: order-confirmation template — 600px table shell, inline styles, bulletproof button (VML fallback for Outlook), preheader text, plain-text version.

## Workflows
1. Scaffold boilerplate: doctype, head/meta stack, landmarks, skip-link, header/main/footer shells.
2. Draft content outline as heading hierarchy first, then fill sections with semantic elements.
3. Build forms/table/media in order: markup → native validation/attributes → labels/alt/captions audit.
4. Run checks: W3C validator, keyboard-only walkthrough, axe/Lighthouse, 320px + 1440px viewport test.
5. For email: inline CSS (e.g. juice), test in Outlook/Gmail/Apple Mail + dark mode, verify plain-text fallback.

## Templates
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Acme — Fast Widgets</title>
  <meta name="description" content="Acme builds fast, durable widgets with free shipping.">
  <link rel="canonical" href="https://example.com/">
  <meta property="og:title" content="Acme — Fast Widgets">
  <meta property="og:description" content="Fast, durable widgets with free shipping.">
  <meta property="og:image" content="https://example.com/og.jpg">
  <meta property="og:type" content="website">
  <meta name="twitter:card" content="summary_large_image">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <meta name="theme-color" content="#0f172a">
</head>
<body>
  <a href="#main" class="skip-link">Skip to content</a>
  <header><nav aria-label="Primary"><ul><li><a href="/">Home</a></li></ul></nav></header>
  <main id="main">
    <h1>Fast widgets, shipped free</h1>
    <form action="/contact" method="post">
      <label for="email">Email</label>
      <input id="email" name="email" type="email" required autocomplete="email">
      <button type="submit">Get quote</button>
    </form>
  </main>
  <footer><p>&copy; 2026 Acme</p></footer>
</body>
</html>
```
```html
<!-- Responsive scrollable data table -->
<div role="region" aria-label="Pricing comparison" tabindex="0" style="overflow-x:auto">
<table>
  <caption>Plan comparison</caption>
  <thead><tr><th scope="col">Feature</th><th scope="col">Basic</th><th scope="col">Pro</th></tr></thead>
  <tbody><tr><th scope="row">Storage</th><td>10 GB</td><td>1 TB</td></tr></tbody>
</table>
</div>
```

## Tools
- SARAH `file_write`: scaffold `index.html` from boilerplate above; keep one page per file until a build step is justified.
- SARAH `shell_run`: serve with `python3 -m http.server 8000` for preview; run `npx html-validate index.html` if available.
- SARAH preview pane: any folder with `index.html` renders — verify links/forms visually, not just source.

## Advanced
- Performance: preconnect fonts, `fetchpriority="high"` on LCP hero image, `decoding="async"`, self-host fonts with `font-display: swap`.
- i18n/SEO: one `hreflang`/canonical set per locale, `dir="rtl"` support, descriptive `<title>` under 60 chars per page.
- Troubleshooting: layout jumps mean missing image dimensions; invisible focus means global `outline:none` — restore `:focus-visible`; broken OG usually wrong absolute image URL or missing 1200x630 size.
- Dialogs/menus: use native `<dialog>`, `<details>/<summary>`, `popover` API before custom ARIA widgets.
- Pro tip: add `<meta name="format-detection" content="telephone=no">` when phone-number auto-linking breaks designs; keep preheader hack (`display:none` span) for emails.

## Documentation
- MDN HTML: https://developer.mozilla.org/en-US/docs/Web/HTML
- web.dev Learn HTML: https://web.dev/learn/html
- W3C Validator: https://validator.w3.org
