--- name: html-core description: MUST be used for semantic HTML markup and document structure. Covers landmark elements, head metadata, media (picture, srcset, lazy loading), dialog/details, and data attributes. Load for any .html file, template markup, SFC templates when choosing elements, or when replacing div-soup with semantic structure. license: MIT metadata: sources: - https://developer.mozilla.org/en-US/docs/Web/HTML (MDN HTML) - https://html.spec.whatwg.org/ (HTML Living Standard) version: "1.0.0" compatibility: Modern evergreen browsers (Baseline 2024) --- # HTML Core — Semantic Markup > Prefer native elements over generic containers. Structure communicates meaning to browsers, assistive tech, and crawlers. ## Preferences - Semantic elements (`header`, `main`, `nav`, `article`, `section`, `aside`, `footer`) over nested `div`s - One `

` per page/view; heading levels never skip - Meaningful `lang` on ``; charset and viewport in `` - Native `dialog` / `details` before custom expand/modal markup - `picture` + `srcset` for responsive images; `loading="lazy"` for below-fold media - `data-` for JS hooks — never invent non-standard attributes ## Core Principles - Meaning first: choose the element that matches the content role, then style it. - Document outline: headings and landmarks should make sense with CSS disabled. - Progressive enhancement: HTML works without JS; enhance where needed. - Metadata is content: title, description, and social tags belong in every page. --- ## 1) Document Structure ```html Orders — Acme Hub

``` Rules: - Always set `lang` on ``. - Exactly one `
` per page (skip link target). - Put site-wide chrome in `
` / `
`; put unique content in `
`. - Prefer `
` only when it has a heading; otherwise use `
` for layout only. --- ## 2) Semantic Elements | Need | Prefer | Avoid | |------|--------|-------| | Primary navigation | `
` | styled `
` list | | Standalone content | `
` | generic wrapper | | Thematic group with heading | `
` | unlabeled `div` | | Sidebar / complementary | `
` | float `div` | | Inline emphasis | `` / `` | bold/italic-only spans | | Time / date | `` | plain text | | Abbreviation | `` | unexplained acronyms | | Figure + caption | `
` + `
` | image + orphaned text | ```html

Shipment #4821

Dispatched 11 Jul 2026.

Carrier label preview

``` --- ## 3) Media ```html ``` - Always set `width` and `height` (or CSS aspect-ratio) to reduce CLS. - Decorative images: `alt=""`. Informative images: concise, non-redundant alt. - Use `loading="lazy"` for offscreen images; keep LCP/hero images eager. - Prefer modern formats via ``; keep a JPEG/PNG fallback in ``. --- ## 4) Interactive Disclosure ```html

Shipping rates

Standard: 2–3 days. Express: next day.

Delete this draft?

``` ```js const dialog = document.querySelector('#confirm-dialog') dialog.showModal() ``` - Use `
`/`
` for progressive disclosure without JS. - Use `` with `.showModal()` for modals (native focus trap + Esc). - Prefer `method="dialog"` buttons to close and return a value. --- ## 5) Data Attributes ```html ``` ```js const { action, orderId } = button.dataset ``` - Use `data-` for behavior hooks and non-visible state shared with JS. - Do not store secrets or PII in data attributes. - Prefer boolean presence (`data-open`) or clear string values — avoid JSON blobs in HTML when possible. --- ## 6) Final Self-Check - Landmarks and headings form a clear outline. - No div-soup where a semantic element fits. - Head has charset, viewport, unique title, and useful description. - Media has dimensions, correct alt, and lazy-loading where appropriate. - Custom widgets only when native `dialog`/`details`/`button` are insufficient.