semantic-html-and-seo

Files (1)

• SKILL.md

SKILL.md (first lines)

# Semantic HTML and SEO

Good HTML is not just markup — it is the contract between your content, search engines, assistive technologies, and the browser. Semantic HTML, correct metadata, and progressive enhancement make UI resilient, findable, and accessible by default.

---

## Semantic HTML5

Use the element that describes the content's meaning, not just its appearance.

### Document structure
```html
<header>       <!-- site header, logo, primary nav -->
<nav>          <!-- navigation links -->
<main>         <!-- primary page content, one per page -->
<article>      <!-- self-contained content: blog post, product card, news item -->
<section>      <!-- thematic grouping with a heading -->
<aside>        <!-- tangentially related content: sidebar, callout -->
<footer>       <!-- site footer, secondary links, copyright -->
```

### Headings
One `<h1>` per page — the primary topic. Headings form an outline: do not skip levels (`h1` → `h3` without `h2`).

```html
<h1>Product name</h1>
  <h2>Features</h2>
    <h3>Feature detail</h3>
  <h2>Pricing</h2>
```

### Interactive elements
```html
<button>   <!-- clickable action, submits or triggers JS -->
<a href>   <!-- navigation to a URL -->
<input>    <!-- user data entry -->
<select>   <!-- option selection -->
<details> / <summary>  <!-- native disclosure/accordion -->
```

Never use `<div>` or `<span>` as interactive elements without full ARIA annotation — and even then, prefer the native element.

---

## Images and Alt Text

Every `<img>` needs an `alt` attribute. What goes in it depends on context.

| Image type | Alt text |
|---|---|
| Informative (product photo, chart) | Describe content: `alt="Red leather sofa, three-seater"` |
| Functional (icon button, logo link) | Describe function: `alt="Go to homepage"` |
| Decorative | Empty: `alt=""` — screen readers skip it |
| Complex (chart, diagram) | Short alt + longer description nearby or in `<figcaption>` |

```html
<!-- Informative -->
<img src="sofa.jpg" alt="Red leather sofa, three-seater">

<!-- Decorative -->
<img src="divider.svg" alt="">

<!-- With caption -->
<figure>
  <img src="chart.png" alt="Bar chart showing revenue growth Q1–Q4 2025">
  <figcaption>Revenue grew 42% year-on-year in Q4 2025.</figcaption>
</figure>
```

---

## SEO Fundamentals

### Title and description
```html
<title>Product Name — Short descriptor | Brand</title>
<meta name="description" content="One or two sentences. What this page is, who it is for, what they will find.">
```

- Title: 50–60 characters. Most important keyword first.
- Description: 120–160 characters. Shown in search results — write for the human, not the algorithm.

### Canonical URL
```html
<link rel="canonical" href="https://example.com/the-definitive-url">
```

Prevents duplicate content penalties when the same page is accessible via multiple URLs.

### Open Graph (social sharing)
```html
<meta property="og:title" content="Page title">
<meta property="og:description" content="Page description">
<meta property="og:image" content="https://example.com/og-image.jpg">
<meta property="og:url" content="https://example.com/page">
<meta property="og:type" content="website">

<!-- Twitter/X -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page title">
<meta name="twitter:image" content="https://example.com/og-image.jpg">
```

OG image: 1200×630px. Appears when the URL is shared on Slack, LinkedIn, Twitter, iMessage.

**The card's headline is the reader's phrase, not the article's insight.** A feed supplies no context, so a line that needs the article to make sense reads as nonsense to a scrolling stranger. Put the plain promise they are already looking for on the card, in the vocabulary of the platform they are on, and keep the clever line for the page.

**Adapt a card to a platform by mode, not by shade.** Against a light feed a dark card reads as an ad banner; the fix is a light card on that platform's own ground, not a warmer navy or a softer blue. A hue nudge is invisible next to the platform's chrome and costs a round trip for nothing. Tone tweaks come after the mode is right.

### Structured Data (JSON-LD)
Machine-readable content enables rich search results.

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product Name",
  "description": "Product description",

From dembrandt/dembrandt-skills, MIT.

More from dembrandt/dembrandt-skills