From 320111b06b9ae256ade4a44be090daae79c5b62d Mon Sep 17 00:00:00 2001
From: Miranda Limonczenko <miranda.limonczenko@supabase.io>
Date: Fri, 31 Jul 2026 11:25:23 -0700
Subject: [PATCH] fix(docs): replace hardcoded heading tags in 4 shared
 components (#48456)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes DOCS-1261

_WAVE plugin shows headers creating jumps in hierarchy. Preview on the
left:_
<img width="1022" height="417" alt="Screenshot 2026-07-29 at 2 42 07 PM"
src="https://github.com/user-attachments/assets/f5e3bd09-8dbf-45e3-8a7f-70d7334fd25b"
/>

<img width="408" height="663" alt="Screenshot 2026-07-29 at 2 44 33 PM"
src="https://github.com/user-attachments/assets/6b952a81-40e5-4a9d-b08a-190c71575cac"
/>



## Problem

Four shared components in `apps/docs` render a hardcoded heading tag no
matter where they're used:

- `NamedCodeBlock` renders a code block's filename as an `<h6>`
- `ProjectConfigVariables` renders a variable label as an `<h6>`
- `StepHikeCompact.Details` renders a step title as an `<h3>`
- `IconPanel` renders its title as an `<h5>`

Since these are fixed, they often land in the wrong spot in a page's
heading order (like an h6 right after an h2), which breaks navigation
for screen reader users. This showed up in the [header hierarchy triage
report](https://app.notion.com/p/supabase/Playwright-E2E-Triage-Reports-3ab5004b775f81e3bc60d058fa5a02c1)
— fixing these 4 components alone resolves 72 of the 159 heading-order
violations found.

## Solution

Swapped the heading tag in each component for a `<span>` with the same
classes. None of these are really "headings" for the content that
follows, so they shouldn't be in the tag tree at all.

The one wrinkle: this codebase applies heading font weight/family
through a global CSS rule keyed off the tag name (h1-h6), not something
the tag gives you for free. So each span now sets that styling
explicitly, plus a margin to match what was there before. Nothing else
changed — same classes, same layout.

## Manual testing

Staging preview:
https://docs-git-ui-header-hierarchy-supabase.vercel.app

Check that each one still looks right:
-
[NamedCodeBlock](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/self-hosting/docker)
— filenames above the code blocks
-
[ProjectConfigVariables](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/auth/quickstarts/react-native)
— the "Project URL" / "Publishable key" labels (this page also has a
`NamedCodeBlock` inside the numbered steps)
-
[StepHikeCompact](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/database/beekeeper-studio)
— the step titles ("Create a new connection", etc.)
-
[IconPanel](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/resources)
— the "Auth0" / "Firebase Auth" panel titles under "Migrate to Supabase"

I also ran typecheck, lint, and the docs test suite locally — all green.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Style**
* Updated headings and labels across documentation and UI components for
more consistent typography.
* Improved spacing, font weight, and block-level layout for project
variables, step details, code tabs, and icon panels.
  * Preserved existing text content and conditional display behavior.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../ProjectConfigVariables/ProjectConfigVariables.tsx      | 4 +++-
 apps/docs/components/StepHikeCompact/index.tsx             | 6 +++++-
 apps/docs/features/directives/CodeTabs.components.tsx      | 7 +++----
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/apps/docs/components/ProjectConfigVariables/ProjectConfigVariables.tsx b/apps/docs/components/ProjectConfigVariables/ProjectConfigVariables.tsx
index 82f81048105..29c0734eba3 100644
--- a/apps/docs/components/ProjectConfigVariables/ProjectConfigVariables.tsx
+++ b/apps/docs/components/ProjectConfigVariables/ProjectConfigVariables.tsx
@@ -474,7 +474,9 @@ function ProjectConfigVariablesInternal({ variable }: { variable: Variable }) {
 
   return (
     <div className="max-w-[min(100%, 500px)] my-6">
-      <h6 className={cn('mt-0 mb-1', 'text-foreground')}>{prettyFormatVariable[variable]}</h6>
+      <span className={cn('block mt-0 mb-1 font-heading font-semibold', 'text-foreground')}>
+        {prettyFormatVariable[variable]}
+      </span>
       <div className="flex flex-wrap gap-x-6">
         <OrgProjectSelector />
         <BranchSelector />
diff --git a/apps/docs/components/StepHikeCompact/index.tsx b/apps/docs/components/StepHikeCompact/index.tsx
index ef1a7f08af7..7d86f47884a 100644
--- a/apps/docs/components/StepHikeCompact/index.tsx
+++ b/apps/docs/components/StepHikeCompact/index.tsx
@@ -97,7 +97,11 @@ const Details: FC<PropsWithChildren<IDetails>> = ({ children, title, fullWidth =
         fullWidth && 'w-full'
       )}
     >
-      {title && <h3 className="mt-0 text-foreground text-base">{title}</h3>}
+      {title && (
+        <span className="block mt-0 mb-[18px] text-foreground text-base font-heading font-semibold">
+          {title}
+        </span>
+      )}
       {children}
     </div>
   )
diff --git a/apps/docs/features/directives/CodeTabs.components.tsx b/apps/docs/features/directives/CodeTabs.components.tsx
index c18c76aa31b..126974e1734 100644
--- a/apps/docs/features/directives/CodeTabs.components.tsx
+++ b/apps/docs/features/directives/CodeTabs.components.tsx
@@ -1,20 +1,19 @@
 import { type PropsWithChildren } from 'react'
-
 import { cn } from 'ui'
 
 export function NamedCodeBlock({ name, children }: PropsWithChildren<{ name: string }>) {
   return (
     <div className="shiki-wrapper w-full space-y-2">
-      <h6
+      <span
         className={cn(
           'w-fit flex items-center text-center',
           'shadow-xs rounded-sm border border-stronger bg-selection',
           'px-2.5 py-1',
-          'text-xs text-foreground'
+          'text-xs font-heading font-semibold text-foreground'
         )}
       >
         {name}
-      </h6>
+      </span>
       {children}
     </div>
   )