feat(a11y): forward a heading level to section titles

CLAUDE.md

@@ -178,7 +178,8 @@ When `.hugo.html` components call Hugo partials, they pass a dict with kebab-cas
 ## Key Constraints
 
 - **Bookshop live editing**: Components must access arguments directly (not through helper partials)
-- **Dual parameter names**: Support both snake_case (CloudCannon) and kebab-case (Hugo) using `(or .snake_case (index . "kebab-case"))`
+- **Dual parameter names**: Support both snake_case (CloudCannon) and kebab-case (Hugo) using `(or .snake_case (index . "kebab-case"))`. For arguments where `0` or `false` is a meaningful value (such as `heading_level`), test key presence instead: `(cond (isset . "snake_case") .snake_case (index . "kebab-case"))`
+- **Heading injection contract**: `page/blocks.html` injects a heading level only into blocks whose component sidecar (`component-library/components/<name>/<name>.yml`) declares a `heading-level` argument. A component that renders a section title but omits that entry silently keeps rendering `<div>` titles instead of failing validation
 - **Hugo version**: Requires Hugo Extended 0.147.6+
 - **Conventional Commits**: All commits must follow the specification (enforced by commitlint + husky)
 - **Semantic versioning**: Releases are automated via semantic-release on the `main` branch

component-library/components/about/about.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/about/about.hugo.html

@@ -39,8 +39,9 @@
 	{{ $ratio := index $settings "ratio" | default "auto" }}
 
 	{{/* Generate the hero */}}
-	{{ $raw := partial "assets/hero.html"  (dict 
+	{{ $raw := partial "assets/hero.html"  (dict
 		"page"         $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
 		"heading"      (merge (dict "arrangement" "above" "width" 8) .heading)
 		"illustration" (merge (dict "ratio" $ratio) .illustration)
 		"order"        .order

component-library/components/approach/approach.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/approach/approach.hugo.html

@@ -71,10 +71,11 @@
 	{{ if $split }}
 		{{/* Split layout: heading left, elements stacked right (50-50 on md+). */}}
 		{{ $title := partial "assets/section-title.html" (dict
-			"page"    $page
-			"heading" (merge (dict "size" 5) (or .heading dict))
-			"justify" .justify
-			"class"   "text-start mb-0"
+			"page"          $page
+			"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+			"heading"       (merge (dict "size" 5) (or .heading dict))
+			"justify"       .justify
+			"class"         "text-start mb-0"
 		) }}
 
 		{{ $items := "" }}
@@ -140,10 +141,11 @@
 		{{ end}}
 
 		{{- $raw = printf "%s%s" $raw (partial "assets/section-title.html" (dict
-			"page"    $page
-			"heading" .heading
-			"justify" .justify
-			"class"   (printf "pb-%d" $padding.y)))
+			"page"          $page
+			"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+			"heading"       .heading
+			"justify"       .justify
+			"class"         (printf "pb-%d" $padding.y)))
 		-}}
 
 		{{/* Add featured illustration */}}

component-library/components/articles/articles.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/articles/articles.hugo.html

@@ -103,10 +103,11 @@
 	{{/* Main code */}}
 	{{ if or (gt (len $pages) 0) (not .hide_empty) }}
 		{{- $raw = printf "%s%s" $raw (partial "assets/section-title.html" (dict
-			"page"    $page
-			"heading" .heading
-			"justify" .justify
-			"class"   (printf "pb-%d" $padding.y)))
+			"page"          $page
+			"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+			"heading"       .heading
+			"justify"       .justify
+			"class"         (printf "pb-%d" $padding.y)))
 		-}}
 
 		{{ $partial := "assets/card-group.html" }}

component-library/components/cards/cards.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/cards/cards.hugo.html

@@ -53,10 +53,11 @@
 
 	{{/* Main code */}}
 	{{- $raw = printf "%s%s" $raw (partial "assets/section-title.html" (dict
-		"page"    $page
-		"heading" .heading
-		"justify" .justify
-		"class"   (printf "pb-%d" $padding.y)))
+		"page"          $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+		"heading"       .heading
+		"justify"       .justify
+		"class"         (printf "pb-%d" $padding.y)))
 	-}}
 
 	{{/* Init base arguments for card group */}}

component-library/components/contact-form/contact-form.bookshop.yml

@@ -16,6 +16,7 @@ blueprint:
     content:
     align:
     width:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/contact-form/contact-form.hugo.html

@@ -61,9 +61,10 @@
     {{ if .illustration }}
         {{/* Embed the form in a horizontal hero with an illustration */}}
         {{ $width := sub 12 (.illustration.width | default 6) }}
-        {{ $raw = partial "assets/hero.html"  (dict 
+        {{ $raw = partial "assets/hero.html"  (dict
             "page"         $page
             "raw"          (printf `<div class="p-0 pt-%d"></div>%s` $padding.y $form)
+            "heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
             "heading"      (merge .heading (dict "width" $width))
             "illustration" (merge .illustration (dict "width" 12))
             "order"        .order
@@ -75,10 +76,11 @@
         }}
     {{ else }}
         {{- $raw = partial "assets/section-title.html" (dict
-            "page"    $page
-            "heading" .heading
-            "justify" .justify
-            "class"   (printf "pb-%d" $padding.y))
+            "page"          $page
+            "heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+            "heading"       .heading
+            "justify"       .justify
+            "class"         (printf "pb-%d" $padding.y))
         -}}
         {{ $raw = printf "%s%s" $raw $form }}
     {{ end }}

component-library/components/cta/cta.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/cta/cta.hugo.html

@@ -42,9 +42,10 @@
 		{{ end }}
 	{{ end }}
 
-	{{ $raw := partial "assets/contact.html" (dict 
+	{{ $raw := partial "assets/contact.html" (dict
 		"page"         $page
 		"orientation"  "horizontal"
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
 		"heading"      .heading
 		"contact"      .contact
 		"caption-url"  (or .caption_url (index . "caption-url"))

component-library/components/faq/faq.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/faq/faq.hugo.html

@@ -38,10 +38,11 @@
 	{{ $color := "" }}
 	{{ if .contrast }}{{ $color = "white" }}{{ end }}
 	{{- $raw := partial "assets/section-title.html" (dict
-		"page"    $page
-		"heading" .heading
-		"justify" .justify
-		"class"   (printf "pb-%d" $padding.y))
+		"page"          $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+		"heading"       .heading
+		"justify"       .justify
+		"class"         (printf "pb-%d" $padding.y))
 	-}}
 
 	{{ $class := "" }}

component-library/components/featured/featured.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/featured/featured.hugo.html

@@ -31,8 +31,9 @@
 {{ $page := or ._page page }}
 
 {{ if not $error }}
-	{{ $raw := partial "assets/hero.html"  (dict 
+	{{ $raw := partial "assets/hero.html"  (dict
 		"page"         $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
 		"heading"      (merge (dict "width" 8) (or .heading dict))
 		"illustration" (merge (dict "ratio" "auto") (or .illustration dict))
 		"order"        .order

component-library/components/heading/heading.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/heading/heading.hugo.html

@@ -43,9 +43,10 @@
 
 	{{/* Main code */}}
 	{{- $raw := partial "assets/section-title.html" (dict
-		"page"    $page
-		"heading" .heading
-		"justify" .justify)
+		"page"          $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+		"heading"       .heading
+		"justify"       .justify)
 	-}}
 
 	{{ if $raw }}

component-library/components/hero/hero.bookshop.yml

@@ -18,6 +18,7 @@ blueprint:
     arrangement:
     width: 8
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/hero/hero.hugo.html

@@ -32,17 +32,18 @@
 
 {{ if not $error }}
 	{{ $raw := partial "assets/hero.html"  (dict
-		"page"         $page
-		"breadcrumb"   .breadcrumb
-		"heading"      .heading
-		"illustration" .illustration
-		"align"        .align
-		"order"        .order
-		"link-type"    (or .link_type (index . "link-type"))
-		"links"        .links
-		"orientation"  .orientation
-		"width"        .width
-		"cover"        .cover
+		"page"          $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+		"breadcrumb"    .breadcrumb
+		"heading"       .heading
+		"illustration"  .illustration
+		"align"         .align
+		"order"         .order
+		"link-type"     (or .link_type (index . "link-type"))
+		"links"         .links
+		"orientation"   .orientation
+		"width"         .width
+		"cover"         .cover
 		)
 	}}
 

component-library/components/list/list.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/list/list.hugo.html

@@ -86,10 +86,11 @@
 	{{ $hideEmpty := or .hide_empty (index . "hide-empty") }}
 	{{ if or (gt (len $pages) 0) (not $hideEmpty) }}
 		{{- $raw := partial "assets/section-title.html" (dict
-			"page"    $page
-			"heading" .heading
-			"justify" .justify
-			"class"   (printf "pb-%d" $padding.y))
+			"page"          $page
+			"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+			"heading"       .heading
+			"justify"       .justify
+			"class"         (printf "pb-%d" $padding.y))
 		-}}
 		{{ if gt (len $pages) 0 }}
 			{{ $content := "" }}

component-library/components/menu/menu.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/menu/menu.hugo.html

@@ -36,10 +36,11 @@
 
 	{{/* Main code */}}
 	{{- $raw := partial "assets/section-title.html" (dict
-		"page"    $page
-		"heading" .heading
-		"justify" .justify
-		"class"   (printf "pb-%d" $padding.y))
+		"page"          $page
+		"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+		"heading"       .heading
+		"justify"       .justify
+		"class"         (printf "pb-%d" $padding.y))
 	-}}
 
 	{{- $raw = printf "%s%s" $raw (partial "assets/menu.html" (dict 

component-library/components/panels/panels.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/panels/panels.hugo.html

@@ -79,10 +79,11 @@
 
     {{/* Main code */}}
     {{- $raw := partial "assets/section-title.html" (dict
-        "page"    $page
-        "heading" .heading
-        "justify" .justify
-        "class"   (printf "pb-%d" $padding.y))
+        "page"          $page
+        "heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+        "heading"       .heading
+        "justify"       .justify
+        "class"         (printf "pb-%d" $padding.y))
     -}}
 
     {{- $raw = printf "%s%s" $raw (partial "assets/nav.html" (dict 

component-library/components/preview/preview.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/preview/preview.hugo.html

@@ -49,6 +49,7 @@
 	{{/* Main code */}}
 	{{ $raw := partial "assets/preview.html" (dict
 		"page"               $page
+		"heading-level"      (cond (isset . "heading_level") .heading_level (index . "heading-level"))
 		"url"                .url
 		"device"             .device
 		"controls-placement" (or .controls_placement (index . "controls-placement"))

component-library/components/team/team.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color:

component-library/components/team/team.hugo.html

@@ -83,10 +83,11 @@
 	{{ $hideEmpty := or .hide_empty (index . "hide-empty") }}
 	{{ if or (gt (len $pages) 0) (not $hideEmpty) }}
 		{{- $raw := partial "assets/section-title.html" (dict
-			"page"    $page
-			"heading" .heading
-			"justify" .justify
-			"class"   (printf "pb-%d" $padding.y))
+			"page"          $page
+			"heading-level" (cond (isset . "heading_level") .heading_level (index . "heading-level"))
+			"heading"       .heading
+			"justify"       .justify
+			"class"         (printf "pb-%d" $padding.y))
 		-}}
 
 		{{ $partial := "assets/card-group.html" }}

component-library/components/testimonials/testimonials.bookshop.yml

@@ -17,6 +17,7 @@ blueprint:
     arrangement:
     width:
     size:
+  heading_level:
   background:
     backdrop:
     color: