docs(tutorial): improve a11y of layout component (#32539)

* docs(tutorial): improve a11y of layout component

* docs(tutorial): add tip about unique query names

docs/docs/tutorial/part-2/index.mdx

@@ -490,25 +490,27 @@ In the browser, the actual DOM elements will look something like this:
 
 Follow the steps below to create a `Layout` component and add it to your Home and About pages.
 
-1. Create a new file called `src/components/layout.js`. Insert the following code to define your `Layout` component. This component will render a `<main>` element that includes a dynamic page title and heading (from the `pageTitle` prop), a list of navigation links, and the contents passed in with the `children` prop.
+1. Create a new file called `src/components/layout.js`. Insert the following code to define your `Layout` component. This component will render a dynamic page title and heading (from the `pageTitle` prop), a list of navigation links, and the contents passed in with the `children` prop. To improve accessibility, there's also a `<main>` element wrapping the page-specific elements (the `<h1>` heading and the contents from `children`).
 
 ```js:title=src/components/layout.js
 import * as React from 'react'
 import { Link } from 'gatsby'
 
 const Layout = ({ pageTitle, children }) => {
   return (
-    <main>
+    <div>
       <title>{pageTitle}</title>
       <nav>
         <ul>
           <li><Link to="/">Home</Link></li>
           <li><Link to="/about">About</Link></li>
         </ul>
       </nav>
-      <h1>{pageTitle}</h1>
-      {children}
-    </main>
+      <main>
+        <h1>{pageTitle}</h1>
+        {children}
+      </main>
+    </div>
   )
 }
 
@@ -652,7 +654,7 @@ Follow the steps below to style your `Layout` component using CSS Modules.
 }
 ```
 
-3. Then import that class into your `Layout` component `.js` file, and use the `className` prop to assign it to the `<main>` element:
+3. Then import that class into your `Layout` component `.js` file, and use the `className` prop to assign it to the top-level `<div>` element:
 
 ```js:title=src/components/layout.js
 import * as React from 'react'
@@ -661,17 +663,19 @@ import { container } from './layout.module.css' // highlight-line
 
 const Layout = ({ pageTitle, children }) => {
   return (
-    <main className={container}> // highlight-line
+    <div className={container}> // highlight-line
       <title>{pageTitle}</title>
       <nav>
         <ul>
           <li><Link to="/">Home</Link></li>
           <li><Link to="/about">About</Link></li>
         </ul>
       </nav>
-      <h1>{pageTitle}</h1>
-      {children}
-    </main>
+      <main>
+        <h1>{pageTitle}</h1>
+        {children}
+      </main>
+    </div>
   )
 }
 
@@ -737,7 +741,7 @@ import {
 
 const Layout = ({ pageTitle, children }) => {
   return (
-    <main className={container}>
+    <div className={container}>
       <title>{pageTitle}</title>
       <nav>
         <ul className={navLinks}> // highlight-line
@@ -753,9 +757,11 @@ const Layout = ({ pageTitle, children }) => {
           </li>
         </ul>
       </nav>
-      <h1 className={heading}>{pageTitle}</h1> // highlight-line
-      {children}
-    </main>
+      <main>
+        <h1 className={heading}>{pageTitle}</h1> // highlight-line
+        {children}
+      </main>
+    </div>
   )
 }
 

docs/docs/tutorial/part-4/index.mdx

@@ -412,10 +412,10 @@ const Layout = ({ pageTitle, children }) => {
   `)
 
   return (
-    <main className={container}>
+    <div className={container}>
       {/* highlight-start */}
       <title>{pageTitle} | {data.site.siteMetadata.title}</title>
-      <p>{data.site.siteMetadata.title}</p>
+      <header>{data.site.siteMetadata.title}</header>
       {/* highlight-end */}
       <nav>
         <ul className={navLinks}>
@@ -431,9 +431,11 @@ const Layout = ({ pageTitle, children }) => {
           </li>
         </ul>
       </nav>
-      <h1 className={heading}>{pageTitle}</h1>
-      {children}
-    </main>
+      <main>
+        <h1 className={heading}>{pageTitle}</h1>
+        {children}
+      </main>
+    </div>
   )
 }
 
@@ -451,6 +453,7 @@ export default Layout
   font-size: 3rem;
   color: gray;
   font-weight: 700;
+  margin: 3rem 0;
 }
 ```
 
@@ -480,10 +483,10 @@ const Layout = ({ pageTitle, children }) => {
   `)
 
   return (
-    <main className={container}>
+    <div className={container}>
       <title>{pageTitle} | {data.site.siteMetadata.title}</title>
       {/* highlight-next-line */}
-      <p className={siteTitle}>{data.site.siteMetadata.title}</p>
+      <header className={siteTitle}>{data.site.siteMetadata.title}</header>
       <nav>
         <ul className={navLinks}>
           <li className={navLinkItem}>
@@ -498,8 +501,10 @@ const Layout = ({ pageTitle, children }) => {
           </li>
         </ul>
       </nav>
-      <h1 className={heading}>{pageTitle}</h1>
-      {children}
+      <main>
+        <h1 className={heading}>{pageTitle}</h1>
+        {children}
+      </main>
     </main>
   )
 }
@@ -560,9 +565,9 @@ const Layout = ({ pageTitle, children }) => {
   `)
 
   return (
-    <main className={container}>
+    <div className={container}>
       <title>{pageTitle} | {data.site.siteMetadata.title}</title>
-      <p className={siteTitle}>{data.site.siteMetadata.title}</p>
+      <header className={siteTitle}>{data.site.siteMetadata.title}</header>
       <nav>
         <ul className={navLinks}>
           <li className={navLinkItem}>
@@ -584,9 +589,11 @@ const Layout = ({ pageTitle, children }) => {
           {/* highlight-end */}
         </ul>
       </nav>
-      <h1 className={heading}>{pageTitle}</h1>
-      {children}
-    </main>
+      <main>
+        <h1 className={heading}>{pageTitle}</h1>
+        {children}
+      </main>
+    </div>
   )
 }
 
@@ -773,6 +780,8 @@ export default BlogPage
 
 **Note:** By default, the query you build in GraphiQL will have a query name, like `MyQuery`. You may see an error if you have more than one query with the same name, so after you copy your query over from GraphiQL to your component, delete the name (as in the code example below).
 
+Alternatively, you can give each of your queries a unique name. Query names can be useful for debugging errors that show up in your console when Gatsby executes your queries at build time.
+
 </Announcement>
 
 ```js:title=src/pages/blog.js