From 14336c8b60064dd5eaf90bbd7d79de260807a6d1 Mon Sep 17 00:00:00 2001
From: muratclk <muratclk@users.noreply.github.com>
Date: Thu, 9 Apr 2026 03:49:32 +0300
Subject: [PATCH] fix: correct heading hierarchy for accessibility (#18162)

Fix heading structure to follow proper HTML semantic hierarchy:
- Change Navigation from h3 to h2 as a main section heading
- Change h6 subsection headings to h4 under h3 parent headings
- Update CSS to preserve existing visual appearance

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 warehouse/static/sass/blocks/_verified.scss    |  3 ++-
 .../includes/packaging/project-data.html       | 18 +++++++++---------
 warehouse/templates/packaging/detail.html      |  2 +-
 3 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/warehouse/static/sass/blocks/_verified.scss b/warehouse/static/sass/blocks/_verified.scss
index aa7846646b7e..fe22e5cde518 100644
--- a/warehouse/static/sass/blocks/_verified.scss
+++ b/warehouse/static/sass/blocks/_verified.scss
@@ -15,7 +15,8 @@
     padding-bottom: 0;
   }
 
-  h6 {
+  h4 {
+    font-size: 1rem;
     padding-bottom: 5px;
     padding-top: 15px;
   }
diff --git a/warehouse/templates/includes/packaging/project-data.html b/warehouse/templates/includes/packaging/project-data.html
index 9350e20827f8..d4fb1d45a135 100644
--- a/warehouse/templates/includes/packaging/project-data.html
+++ b/warehouse/templates/includes/packaging/project-data.html
@@ -19,7 +19,7 @@ <h3 class="sidebar-section__title">
   </h3>
   <small><i>{% trans href="https://docs.pypi.org/project_metadata/#verified-details" %}These details have been <a href="{{ href }}">verified by PyPI</a>{% endtrans %}</i></small>
   {% if release.urls_by_verify_status(verified=True).values() | contains_valid_uris %}
-    <h6>{% trans %}Project links{% endtrans %}</h6>
+    <h4>{% trans %}Project links{% endtrans %}</h4>
     <ul class="vertical-tabs__list">
       {% for name, url in release.urls_by_verify_status(verified=True).items() %}
         {% if is_valid_uri(url) %}
@@ -33,7 +33,7 @@ <h6>{% trans %}Project links{% endtrans %}</h6>
     </ul>
   {% endif %}
   {% if project.organization %}
-    <h6>Owner</h6>
+    <h4>Owner</h4>
     <ul class="vertical-tabs__list">
       <li>
         <a class="vertical-tabs__tab vertical-tabs__tab--with-icon vertical-tabs__tab--condensed"
@@ -46,7 +46,7 @@ <h6>Owner</h6>
     </ul>
   {% endif %}
   {% if release.verified_github_repo_info_url and release.verified_github_open_issue_info_url %}
-    <h6>{% trans %}GitHub Statistics{% endtrans %}</h6>
+    <h4>{% trans %}GitHub Statistics{% endtrans %}</h4>
     <div class="hidden github-repo-info" data-controller="github-repo-info">
       <ul class="vertical-tabs__list">
         <li>
@@ -97,7 +97,7 @@ <h6>{% trans %}GitHub Statistics{% endtrans %}</h6>
     </div>
   {% endif %}
   {% if release.verified_gitlab_repository %}
-    <h6>{% trans %}GitLab Statistics{% endtrans %}</h6>
+    <h4>{% trans %}GitLab Statistics{% endtrans %}</h4>
     <div class="hidden gitlab-repo-info" data-controller="gitlab-repo-info">
       <ul class="vertical-tabs__list">
         <li>
@@ -148,7 +148,7 @@ <h6>{% trans %}GitLab Statistics{% endtrans %}</h6>
     </div>
   {% endif %}
   {% if maintainers %}
-    <h6>{% trans %}Maintainers{% endtrans %}</h6>
+    <h4>{% trans %}Maintainers{% endtrans %}</h4>
     {% for maintainer in maintainers %}
       {% set alt = gettext("Avatar for {username} from gravatar.com").format(username=maintainer.username) %}
       <span class="sidebar-section__maintainer">
@@ -168,7 +168,7 @@ <h6>{% trans %}Maintainers{% endtrans %}</h6>
   {% endif %}
   {% if release.has_meta and (release.author_email_verified or release.maintainer_email_verified) %}
     <div class="sidebar-section verified">
-      <h6>{% trans %}Meta{% endtrans %}</h6>
+      <h4>{% trans %}Meta{% endtrans %}</h4>
       <ul>
         {% if release.author_email and release.author_email_verified %}
           <li>
@@ -192,7 +192,7 @@ <h6>{% trans %}Meta{% endtrans %}</h6>
   <h3 class="sidebar-section__title">{% trans %}Unverified details{% endtrans %}</h3>
   <small><i>{% trans %}These details have <b>not</b> been verified by PyPI{% endtrans %}</i></small>
   {% if release.urls_by_verify_status(verified=False).values() | contains_valid_uris %}
-    <h6>{% trans %}Project links{% endtrans %}</h6>
+    <h4>{% trans %}Project links{% endtrans %}</h4>
     <ul class="vertical-tabs__list">
       {% for name, url in release.urls_by_verify_status(verified=False).items() %}
         {% if is_valid_uri(url) %}
@@ -207,7 +207,7 @@ <h6>{% trans %}Project links{% endtrans %}</h6>
   {% endif %}
   {% if release.has_meta %}
     <div class="sidebar-section unverified">
-      <h6>{% trans %}Meta{% endtrans %}</h6>
+      <h4>{% trans %}Meta{% endtrans %}</h4>
       <ul>
         {% if release.license_expression %}
           <li>
@@ -293,7 +293,7 @@ <h6>{% trans %}Meta{% endtrans %}</h6>
   {% endif %}
   {% if release.classifiers %}
     <div class="sidebar-section unverified">
-      <h6 class="sidebar-section__title">{% trans %}Classifiers{% endtrans %}</h6>
+      <h4 class="sidebar-section__title">{% trans %}Classifiers{% endtrans %}</h4>
       <ul class="sidebar-section__classifiers">
         {% for classifier_head, classifier_tails in (release.classifiers|format_classifiers()).items() %}
           <li>
diff --git a/warehouse/templates/packaging/detail.html b/warehouse/templates/packaging/detail.html
index 848cccc5a8ad..940f05cc62c9 100644
--- a/warehouse/templates/packaging/detail.html
+++ b/warehouse/templates/packaging/detail.html
@@ -213,7 +213,7 @@ <h1 class="package-header__name">{{ release.project.name }} {{ release.version }
     <div class="vertical-tabs">
       <div class="vertical-tabs__tabs">
         <div class="sidebar-section">
-          <h3 class="sidebar-section__title">{% trans %}Navigation{% endtrans %}</h3>
+          <h2 class="sidebar-section__title">{% trans %}Navigation{% endtrans %}</h2>
           <nav aria-label="{% trans project=release.project.name %}Navigation for {{ project }}{% endtrans %}">
             <ul class="vertical-tabs__list" role="tablist">
               <li role="tab">