Suggest specifying font-size and margin-block on h1 (#37827)

* Suggest specifying font-size and margin-block on h1 See whatwg/html#7867 * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Chris Mills <[email protected]> * Update files/en-us/web/html/element/heading_elements/index.md Co-authored-by: Simon Pieters <[email protected]> * Update files/en-us/web/html/element/heading_elements/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Chris Mills <[email protected]> Co-authored-by: Estelle Weyl <[email protected]>
mdn · Jan 29, 2025 · 28b9521 · 28b9521
1 parent 11611c3
commit 28b9521
Showing 1 changed file with 25 additions and 0 deletions.
diff --git a/files/en-us/web/html/element/heading_elements/index.md b/files/en-us/web/html/element/heading_elements/index.md
@@ -36,6 +36,31 @@ While using multiple `<h1>` elements on one page is allowed by the HTML standard
 
 Prefer using only one `<h1>` per page and [nest headings](#nesting) without skipping levels.
 
+### Specifying a uniform font size for `<h1>`
+
+The [HTML standard](https://html.spec.whatwg.org/multipage/rendering.html#sections-and-headings) specifies that `<h1>` elements in a `<section>`, `<article>`, `<aside>`, or `<nav>` element should render as an `<h2>` (smaller {{cssxref("font-size")}} with an adjusted {{cssxref("margin-block")}}), or as an `<h3>` if nested another level, and so on.
+
+> [!NOTE]
+> There is a [proposal](https://github.com/whatwg/html/issues/7867) to remove this special default style, so that `<h1>` always has the same default style. This proposal is currently [implemented in Firefox Nightly](/en-US/docs/Mozilla/Firefox/Experimental_features#ua_styles_for_h1_nested_in_sectioning_elements).
+
+To ensure consistent `<h1>` rendering, use the following style rule:
+
+```css
+h1 {
+  margin-block: 0.67em;
+  font-size: 2em;
+}
+```
+
+Alternatively, to avoid overwriting other style rules that target `<h1>` you can use {{cssxref(":where()"}}, which has zero specificity:
+
+```css
+:where(h1) {
+  margin-block: 0.67em;
+  font-size: 2em;
+}
+```
+
 ## Accessibility
 
 ### Navigation