{"id":"25f46bc6-18fb-4d7c-82ad-7edfa26fccdf","shortId":"EDjKtt","kind":"skill","title":"semantic-html-and-seo","tagline":"Semantic HTML5, SEO fundamentals, alt texts, progressive enhancement, SPA considerations, device capability detection, and user context awareness. Good HTML is the foundation of accessibility, SEO, and resilient UI. Use when building any web UI, reviewing markup quality, or optim","description":"# Semantic HTML and SEO\n\nGood 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.\n\n---\n\n## Semantic HTML5\n\nUse the element that describes the content's meaning, not just its appearance.\n\n### Document structure\n```html\n<header>       <!-- site header, logo, primary nav -->\n<nav>          <!-- navigation links -->\n<main>         <!-- primary page content, one per page -->\n<article>      <!-- self-contained content: blog post, product card, news item -->\n<section>      <!-- thematic grouping with a heading -->\n<aside>        <!-- tangentially related content: sidebar, callout -->\n<footer>       <!-- site footer, secondary links, copyright -->\n```\n\n### Headings\nOne `<h1>` per page — the primary topic. Headings form an outline: do not skip levels (`h1` → `h3` without `h2`).\n\n```html\n<h1>Product name</h1>\n  <h2>Features</h2>\n    <h3>Feature detail</h3>\n  <h2>Pricing</h2>\n```\n\n### Interactive elements\n```html\n<button>   <!-- clickable action, submits or triggers JS -->\n<a href>   <!-- navigation to a URL -->\n<input>    <!-- user data entry -->\n<select>   <!-- option selection -->\n<details> / <summary>  <!-- native disclosure/accordion -->\n```\n\nNever use `<div>` or `<span>` as interactive elements without full ARIA annotation — and even then, prefer the native element.\n\n---\n\n## Images and Alt Text\n\nEvery `<img>` needs an `alt` attribute. What goes in it depends on context.\n\n| Image type | Alt text |\n|---|---|\n| Informative (product photo, chart) | Describe content: `alt=\"Red leather sofa, three-seater\"` |\n| Functional (icon button, logo link) | Describe function: `alt=\"Go to homepage\"` |\n| Decorative | Empty: `alt=\"\"` — screen readers skip it |\n| Complex (chart, diagram) | Short alt + longer description nearby or in `<figcaption>` |\n\n```html\n<!-- Informative -->\n<img src=\"sofa.jpg\" alt=\"Red leather sofa, three-seater\">\n\n<!-- Decorative -->\n<img src=\"divider.svg\" alt=\"\">\n\n<!-- With caption -->\n<figure>\n  <img src=\"chart.png\" alt=\"Bar chart showing revenue growth Q1–Q4 2025\">\n  <figcaption>Revenue grew 42% year-on-year in Q4 2025.</figcaption>\n</figure>\n```\n\n---\n\n## SEO Fundamentals\n\n### Title and description\n```html\n<title>Product Name — Short descriptor | Brand</title>\n<meta name=\"description\" content=\"One or two sentences. What this page is, who it is for, what they will find.\">\n```\n\n- Title: 50–60 characters. Most important keyword first.\n- Description: 120–160 characters. Shown in search results — write for the human, not the algorithm.\n\n### Canonical URL\n```html\n<link rel=\"canonical\" href=\"https://example.com/the-definitive-url\">\n```\n\nPrevents duplicate content penalties when the same page is accessible via multiple URLs.\n\n### Open Graph (social sharing)\n```html\n<meta property=\"og:title\" content=\"Page title\">\n<meta property=\"og:description\" content=\"Page description\">\n<meta property=\"og:image\" content=\"https://example.com/og-image.jpg\">\n<meta property=\"og:url\" content=\"https://example.com/page\">\n<meta property=\"og:type\" content=\"website\">\n\n<!-- Twitter/X -->\n<meta name=\"twitter:card\" content=\"summary_large_image\">\n<meta name=\"twitter:title\" content=\"Page title\">\n<meta name=\"twitter:image\" content=\"https://example.com/og-image.jpg\">\n```\n\nOG image: 1200×630px. Appears when the URL is shared on Slack, LinkedIn, Twitter, iMessage.\n\n### Structured Data (JSON-LD)\nMachine-readable content enables rich search results.\n\n```html\n<script type=\"application/ld+json\">\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Product\",\n  \"name\": \"Product Name\",\n  \"description\": \"Product description\",\n  \"image\": \"https://example.com/product.jpg\",\n  \"offers\": {\n    \"@type\": \"Offer\",\n    \"price\": \"49.00\",\n    \"priceCurrency\": \"EUR\"\n  }\n}\n</script>\n```\n\nCommon types: `Product`, `Article`, `BreadcrumbList`, `FAQPage`, `Organization`, `SiteLinksSearchBox`.\n\n---\n\n## Progressive Enhancement\n\nBuild in layers. The core content and function must work without JavaScript. Enhance with CSS. Enhance further with JS.\n\n```\nLayer 1: HTML — content is readable, links work, forms submit\nLayer 2: CSS  — layout, typography, visual design\nLayer 3: JS   — interactivity, animations, dynamic content\n```\n\n**In practice:**\n- Forms must submit via native `<form action>` without JS — JS can intercept and enhance with fetch\n- Navigation links must be real `<a href>` — JS can add transitions\n- Content must be in the HTML — JS can enhance with lazy-load or personalisation\n- Images must have `src` — JS can add lazy loading via `loading=\"lazy\"` (now native)\n\n---\n\n## SPA Considerations\n\nSingle-page applications break browser defaults that SEO and accessibility depend on. Fix them explicitly.\n\n### Server-side rendering or static generation\nClient-rendered HTML is not reliably indexed by search engines. Use SSR (Next.js, Nuxt, SvelteKit) or static generation for any content that needs to be found.\n\n### Title and meta updates\nUpdate `document.title` and meta tags on every route change. Use the framework's `<Head>` component or equivalent.\n\n### Focus management\nOn route change, move focus to the new page's `<h1>` or `<main>` — screen readers do not detect SPA navigation automatically.\n\n```js\n// After route change\ndocument.querySelector('h1')?.focus();\n```\n\n### Scroll restoration\nRestore scroll position to top on navigation, or to the saved position on back navigation. Browser default scroll restoration is disabled in SPAs.\n\n### History API\nUse `pushState` / `replaceState` so back/forward navigation and bookmarking work correctly.\n\n---\n\n## Device Capabilities and User Context\n\nDesign and code should adapt to what the device and user can actually do.\n\n### Input method detection\n```css\n@media (hover: hover) {\n  /* hover states — mouse or trackpad */\n  .btn:hover { background: var(--color-primary-hover); }\n}\n\n@media (hover: none) {\n  /* touch device — no hover, larger targets */\n  .btn { min-height: 44px; }\n}\n```\n\n### Pointer precision\n```css\n@media (pointer: coarse) {\n  /* fat-finger touch — increase target sizes */\n  .interactive { min-height: 44px; min-width: 44px; }\n}\n\n@media (pointer: fine) {\n  /* mouse — precise, can use smaller targets */\n}\n```\n\n### Network conditions\n```html\n<!-- Lazy load images below the fold -->\n<img src=\"product.jpg\" loading=\"lazy\" alt=\"...\">\n\n<!-- Serve modern formats with fallback -->\n<picture>\n  <source srcset=\"image.avif\" type=\"image/avif\">\n  <source srcset=\"image.webp\" type=\"image/webp\">\n  <img src=\"image.jpg\" alt=\"...\">\n</picture>\n```\n\n### User preferences\n```css\n@media (prefers-reduced-motion: reduce) { /* disable animations */ }\n@media (prefers-color-scheme: dark)     { /* dark mode tokens */ }\n@media (prefers-contrast: more)         { /* increase contrast */ }\n@media (forced-colors: active)          { /* Windows high contrast mode */ }\n```\n\n---\n\n## Review Checklist\n\n- [ ] One `<h1>` per page, headings form a logical outline\n- [ ] Semantic elements used: `<main>`, `<nav>`, `<header>`, `<footer>`, `<article>`, `<section>`\n- [ ] Every `<img>` has a meaningful `alt` or `alt=\"\"` for decorative images\n- [ ] `<title>` is unique per page, 50–60 characters, keyword-first\n- [ ] `<meta name=\"description\">` present and 120–160 characters\n- [ ] Open Graph tags present on all shareable pages\n- [ ] `<link rel=\"canonical\">` on pages accessible via multiple URLs\n- [ ] Structured data (JSON-LD) on product, article, and FAQ pages\n- [ ] Forms work without JavaScript\n- [ ] SPA updates `document.title` and meta tags on route change\n- [ ] SPA moves focus on route change\n- [ ] Hover states scoped to `@media (hover: hover)`\n- [ ] Touch targets ≥ 44px on `@media (pointer: coarse)`\n- [ ] Images use `loading=\"lazy\"` below the fold\n- [ ] `prefers-reduced-motion` respected","tags":["semantic","html","and","seo","dembrandt","skills","accessibility","agent-skills","claude-code-skills","claude-skills","cursor-skills","design-system"],"capabilities":["skill","source-dembrandt","skill-semantic-html-and-seo","topic-accessibility","topic-agent-skills","topic-claude-code-skills","topic-claude-skills","topic-cursor-skills","topic-design-system","topic-design-tokens","topic-enterprise-ux","topic-gestalt","topic-skills-sh","topic-typography","topic-ui-design"],"categories":["dembrandt-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/dembrandt/dembrandt-skills/semantic-html-and-seo","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add dembrandt/dembrandt-skills","source_repo":"https://github.com/dembrandt/dembrandt-skills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 9 github stars · SKILL.md body (7,845 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:08:28.380Z","embedding":null,"createdAt":"2026-05-18T13:14:03.717Z","updatedAt":"2026-05-18T19:08:28.380Z","lastSeenAt":"2026-05-18T19:08:28.380Z","tsv":"'1':334 '120':240,706 '1200':277 '160':241,707 '2':344 '2025':219 '3':351 '42':212 '44px':600,618,622,762 '50':232,698 '60':233,699 '630px':278 'access':29,81,266,423,719 'activ':666 'actual':565 'adapt':557 'add':380,403 'algorithm':253 'alt':10,150,155,166,174,188,194,203,688,690 'anim':354,645 'annot':140 'api':537 'appear':98,279 'applic':416 'aria':139 'articl':307,730 'assist':64 'attribut':156 'automat':503 'awar':22 'back':526 'back/forward':542 'background':581 'bookmark':545 'brand':230 'breadcrumblist':308 'break':417 'browser':68,418,528 'btn':579,596 'build':36,314 'button':183 'canon':254 'capabl':17,549 'chang':475,487,507,746,752 'charact':234,242,700,708 'chart':171,200 'checklist':672 'client':437 'client-rend':436 'coars':606,766 'code':555 'color':584,649,665 'color-primary-hov':583 'common':304 'complex':199 'compon':480 'condit':633 'consider':15,412 'content':61,92,173,259,298,319,336,356,382,457 'context':21,163,552 'contract':58 'contrast':658,661,669 'core':318 'correct':71,547 'css':328,345,570,603,637 'dark':651,652 'data':291,724 'decor':192,692 'default':83,419,529 'depend':161,424 'describ':90,172,186 'descript':205,224,239 'descriptor':229 'design':349,553 'detail':126 'detect':18,500,569 'devic':16,548,561,591 'diagram':201 'disabl':533,644 'document':99 'document.queryselector':508 'document.title':468,740 'duplic':258 'dynam':355 'element':88,129,136,147,682 'empti':193 'enabl':299 'engin':63,446 'enhanc':13,75,313,326,329,370,390 'equival':482 'even':142 'everi':152,473,684 'explicit':428 'faq':732 'faqpag':309 'fat':608 'fat-fing':607 'featur':124,125 'fetch':372 'findabl':79 'fine':625 'finger':609 'first':238,703 'fix':426 'focus':483,489,510,749 'fold':773 'forc':664 'forced-color':663 'form':110,341,359,677,734 'found':462 'foundat':27 'framework':478 'full':138 'function':181,187,321 'fundament':9,221 'generat':435,454 'go':189 'goe':158 'good':23,49 'graph':271,710 'grew':211 'h1':117,509 'h2':120 'h3':118 'head':102,109,676 'height':599,617 'high':668 'histori':536 'homepag':191 'hover':572,573,574,580,586,588,593,753,758,759 'html':3,24,46,50,70,101,121,130,209,225,256,274,303,335,387,439,634 'html5':7,85 'human':250 'icon':182 'imag':148,164,276,397,693,767 'imessag':289 'import':236 'increas':611,660 'index':443 'inform':168 'input':567 'interact':128,135,353,614 'intercept':368 'javascript':325,737 'js':332,352,365,366,378,388,401,504 'json':293,726 'json-ld':292,725 'keyword':237,702 'keyword-first':701 'larger':594 'layer':316,333,343,350 'layout':346 'lazi':393,404,408,770 'lazy-load':392 'ld':294,727 'leather':176 'level':116 'link':185,339,374 'linkedin':287 'load':394,405,407,769 'logic':679 'logo':184 'longer':204 'machin':296 'machine-read':295 'make':76 'manag':484 'markup':41,54 'mean':94 'meaning':687 'media':571,587,604,623,638,646,655,662,757,764 'meta':465,470,742 'metadata':72 'method':568 'min':598,616,620 'min-height':597,615 'min-width':619 'mode':653,670 'motion':642,777 'mous':576,626 'move':488,748 'multipl':268,721 'must':322,360,375,383,398 'name':123,227 'nativ':146,363,410 'navig':373,502,519,527,543 'nearbi':206 'need':153,459 'network':632 'never':131 'new':492 'next.js':449 'none':589 'nuxt':450 'og':275 'one':103,673 'open':270,709 'optim':44 'organ':310 'outlin':112,680 'page':105,264,415,493,675,697,716,718,733 'penalti':260 'per':104,674,696 'personalis':396 'photo':170 'pointer':601,605,624,765 'posit':515,524 'practic':358 'precis':602,627 'prefer':144,636,640,648,657,775 'prefers-color-schem':647 'prefers-contrast':656 'prefers-reduced-mot':639,774 'present':704,712 'prevent':257 'price':127 'primari':107,585 'product':122,169,226,306,729 'progress':12,74,312 'pushstat':539 'q4':218 'qualiti':42 'readabl':297,338 'reader':196,497 'real':377 'red':175 'reduc':641,643,776 'reliabl':442 'render':432,438 'replacest':540 'resili':32,78 'respect':778 'restor':512,513,531 'result':246,302 'revenu':210 'review':40,671 'rich':300 'rout':474,486,506,745,751 'save':523 'scheme':650 'scope':755 'screen':195,496 'scroll':511,514,530 'search':62,245,301,445 'seater':180 'semant':2,6,45,69,84,681 'semantic-html-and-seo':1 'seo':5,8,30,48,220,421 'server':430 'server-sid':429 'share':273,284 'shareabl':715 'short':202,228 'shown':243 'side':431 'singl':414 'single-pag':413 'sitelinkssearchbox':311 'size':613 'skill' 'skill-semantic-html-and-seo' 'skip':115,197 'slack':286 'smaller':630 'social':272 'sofa':177 'source-dembrandt' 'spa':14,411,501,738,747 'spas':535 'src':400 'ssr':448 'state':575,754 'static':434,453 'structur':100,290,723 'submit':342,361 'sveltekit':451 'tag':471,711,743 'target':595,612,631,761 'technolog':65 'text':11,151,167 'three':179 'three-seat':178 'titl':222,231,463 'token':654 'top':517 'topic':108 'topic-accessibility' 'topic-agent-skills' 'topic-claude-code-skills' 'topic-claude-skills' 'topic-cursor-skills' 'topic-design-system' 'topic-design-tokens' 'topic-enterprise-ux' 'topic-gestalt' 'topic-skills-sh' 'topic-typography' 'topic-ui-design' 'touch':590,610,760 'trackpad':578 'transit':381 'twitter':288 'type':165,305 'typographi':347 'ui':33,39,77 'uniqu':695 'updat':466,467,739 'url':255,269,282,722 'use':34,86,132,447,476,538,629,683,768 'user':20,551,563,635 'var':582 'via':267,362,406,720 'visual':348 'web':38 'width':621 'window':667 'without':119,137,324,364,736 'work':323,340,546,735 'write':247 'year':214,216 'year-on-year':213","prices":[{"id":"6385b95a-cfcb-4e7c-9182-f5c8ffb041af","listingId":"25f46bc6-18fb-4d7c-82ad-7edfa26fccdf","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"dembrandt","category":"dembrandt-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:03.717Z"}],"sources":[{"listingId":"25f46bc6-18fb-4d7c-82ad-7edfa26fccdf","source":"github","sourceId":"dembrandt/dembrandt-skills/semantic-html-and-seo","sourceUrl":"https://github.com/dembrandt/dembrandt-skills/tree/main/skills/semantic-html-and-seo","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:03.717Z","lastSeenAt":"2026-05-18T19:08:28.380Z"}],"details":{"listingId":"25f46bc6-18fb-4d7c-82ad-7edfa26fccdf","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"dembrandt","slug":"semantic-html-and-seo","github":{"repo":"dembrandt/dembrandt-skills","stars":9,"topics":["accessibility","agent-skills","claude-code-skills","claude-skills","cursor-skills","design-system","design-tokens","enterprise-ux","gestalt","skills-sh","typography","ui-design","ux","wcag"],"license":"mit","html_url":"https://github.com/dembrandt/dembrandt-skills","pushed_at":"2026-05-14T22:34:06Z","description":"UX and design system skills for AI agents based on 20 years of experience","skill_md_sha":"d89d9d441b57158f17cd436cce6d08b0979432dd","skill_md_path":"skills/semantic-html-and-seo/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/dembrandt/dembrandt-skills/tree/main/skills/semantic-html-and-seo"},"layout":"multi","source":"github","category":"dembrandt-skills","frontmatter":{"name":"semantic-html-and-seo","description":"Semantic HTML5, SEO fundamentals, alt texts, progressive enhancement, SPA considerations, device capability detection, and user context awareness. Good HTML is the foundation of accessibility, SEO, and resilient UI. Use when building any web UI, reviewing markup quality, or optimising for search and accessibility."},"skills_sh_url":"https://skills.sh/dembrandt/dembrandt-skills/semantic-html-and-seo"},"updatedAt":"2026-05-18T19:08:28.380Z"}}