Correcting heading levels for accessibility

I've been struggling with choosing the right headings for certain elements since I mostly use React and want to focus on reusable code.

Since I always organize my code with the following hierarchy:

route (h2)
section inside route (h3)
article inside section (h4)
hero section (h1)

I thought this approach would be appropriate. Otherwise, I wouldn’t know how to distinguish between them while respecting their order.

Here is my example

    <div className='page'>
      <div className='page__wrapper'>
        <main>
          <section className='home-route'>
            <div class='home-route__wrapper'>
              <h2 className='sr-only'>Home route</h2>
              <div className='home-route__content'>
                <section className='hero sr-only'>
                  <h1 className='hero__title'>Pick your courses/articles for learning</h1>
                </section>
                <section className='cards-section'>
                  <div className='cards-section__wrapper'>
                    <h3 className='sr-only'>Cards</h3>
                    <div className='cards-section__content'>
                      {
                        cards.map((card, index) => (
                          <Card key={index} item={card}></Card>
                        ))
                      }
                    </div>
                  </div>
                </section>
              </div>
            </div>
          </section>
        </main>
      </div>
    </div>

How I structure website:

div [page] (wrap whole content - '/' route)
div [layout] (for some route + e.g. navigation - '/users')
section [route] (home, contact, user ... e.g. /users/userId)
section (some section inside that route)
article (some article inside that section)

Solution

Headings are for giving the current document an outline, not for informing users of their current location within a website's directory structure (or a SPA's routes).

If you want to provide users context of where they are within the structure of your website or SPA, use breadcrumbs instead.

Using a modified example from the repo you linked to in the comments, here's the markup of what an "add new player" page should look like:

<header>
  <nav aria-label="Main">[...]</nav>
</header>
<nav aria-label="Breadcrumbs">
  <ol>
    <li><a href="/">home</a></li>
    <li><a href="/players">players</a></li>
    <li><a href="/players/new" aria-current="page">add new player</a></li>
  </ol>
</nav>
<main>
  <h1>Add new player</h1>
  <form>[...]</form>
</main>

"Home" and "Players" should not be headings on the "Add New Player" page. There's not a "Home" section of content on this page, or a "Players" section of content on this page, so they shouldn't be headings.