From 8d68477008fd21d742cc678280e9c1045a6d3841 Mon Sep 17 00:00:00 2001
From: Navya Singh <navyasingh@microsoft.com>
Date: Tue, 30 Jun 2026 16:22:37 -0700
Subject: [PATCH] fix(a11y): add H1 and correct heading structure on TSConfig
 Reference page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug: https://devdiv.visualstudio.com/DevDiv/_workitems/edit/2201717

- Add <h1>TSConfig Reference</h1> as visible page heading
  (all other content pages have explicit H1; this page was missing one)
- Fix heading skip H2→H4 in showCategories: section group headings
  now render as <h3> (or no heading for root-level groups, which use
  <h3> directly for categories — eliminating H2→H4 skip)
- Fix heading skip H2→H5 for category names: now <h4> under sections,
  <h3> at root level
- Fix heading skip H3→H5 in extends.md: ##### Example → #### Example
  (en.md is regenerated from this source at build time)
- Update tsconfig.scss to match new heading element selectors

axe heading-order rule: 0 violations (was 2)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/tsconfig-reference/copy/en/options/extends.md    | 2 +-
 packages/typescriptlang-org/src/templates/tsconfig.scss   | 8 ++++++--
 .../src/templates/tsconfigReference.tsx                   | 7 +++++--
 3 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/tsconfig-reference/copy/en/options/extends.md b/packages/tsconfig-reference/copy/en/options/extends.md
index 085d194bbd4f..b29043def126 100644
--- a/packages/tsconfig-reference/copy/en/options/extends.md
+++ b/packages/tsconfig-reference/copy/en/options/extends.md
@@ -13,7 +13,7 @@ base config file, and that circularity between configuration files is not allowe
 
 Currently, the only top-level property that is excluded from inheritance is [`references`](#references).
 
-##### Example
+#### Example
 
 `configs/base.json`:
 
diff --git a/packages/typescriptlang-org/src/templates/tsconfig.scss b/packages/typescriptlang-org/src/templates/tsconfig.scss
index 229fd10d9cfe..ca543ef25f78 100644
--- a/packages/typescriptlang-org/src/templates/tsconfig.scss
+++ b/packages/typescriptlang-org/src/templates/tsconfig.scss
@@ -1,5 +1,9 @@
 @import "../style/globals.scss";
 
+.tsconfig-page-title {
+  margin-bottom: 1.5rem;
+}
+
 .tsconfig {
   margin-bottom: 6rem;
   // Drastically reduce the padding and margins to make it fit phones
@@ -53,7 +57,7 @@
     margin-left: -1rem;
     padding-left: 1rem;
 
-    h4 {
+    h3 {
       font-weight: normal;
       margin-bottom: 0.1rem;
       a {
@@ -67,7 +71,7 @@
       @media (max-width: $screen-md) {
         flex-direction: column;
       }
-      h5 {
+      h3, h4 {
         width: 160px;
         flex: 0 0 auto;
       }
diff --git a/packages/typescriptlang-org/src/templates/tsconfigReference.tsx b/packages/typescriptlang-org/src/templates/tsconfigReference.tsx
index ab8b719b5ee1..6da7c726b7f0 100644
--- a/packages/typescriptlang-org/src/templates/tsconfigReference.tsx
+++ b/packages/typescriptlang-org/src/templates/tsconfigReference.tsx
@@ -151,11 +151,12 @@ const TSConfigReferenceTemplateComponent = (props: Props) => {
   }
 
   const showCategories = (categories: Category[], sectionName?: string) => {
+    const CategoryHeading = sectionName ? "h4" : "h3"
     return <div className={sectionName ? "tsconfig-quick-nav grouped" : "tsconfig-quick-nav"}>
-      {sectionName ? <h4><code><a href={`#${sectionName}`}>"{sectionName}"</a></code></h4> : <div />}
+      {sectionName ? <h3><code><a href={`#${sectionName}`}>"{sectionName}"</a></code></h3> : <div />}
       {
         categories.map(c => <div className="tsconfig-quick-nav-category" key={c.display}>
-          <h5 id={`quick-nav-${c.anchor}`}>{c.display}</h5>
+          <CategoryHeading id={`quick-nav-${c.anchor}`}>{c.display}</CategoryHeading>
           <ol aria-labelledby={`quick-nav-${c.anchor}`}>
             {c.options.map(o => <li key={o.name}><code><a href={anchor(sectionName, o.anchor)}>{o.anchor}</a>{joiner(c.options, o)}</code></li>)}
           </ol>
@@ -178,6 +179,8 @@ const TSConfigReferenceTemplateComponent = (props: Props) => {
   return (
     <Layout title={i("tsconfig_title")} description={i("tsconfig_description")} lang={props.pageContext.locale}>
 
+      <h1 className="tsconfig-page-title">TSConfig Reference</h1>
+
       <div className={`tsconfig raised main-content-block markdown button ${openInfo ? "open" : "closed"}`} >
         <a href="#" onClick={toggleInfoState} aria-expanded={openInfo} role="button">
           <h2>