a11y(docs): add proper heading structure

src/app/docs/Section.test.tsx

@@ -0,0 +1,58 @@
+import { render } from "@testing-library/react";
+import { DocsSection } from "./Section";
+
+function getHeadingOutline(container: HTMLElement) {
+  const headings = Array.from(
+    container.querySelectorAll("h1, h2, h3, h4, h5, h6"),
+  );
+  return headings.map((h) => parseInt(h.tagName[1], 10));
+}
+
+function assertValidOutline(levels: number[]) {
+  if (levels.length === 0) return;
+  for (let i = 1; i < levels.length; i++) {
+    const prev = levels[i - 1];
+    const curr = levels[i];
+    expect(curr).toBeLessThanOrEqual(prev + 1);
+  }
+}
+
+describe("DocsSection heading outline", () => {
+  it("forms a valid outline without skipping levels (single section page)", () => {
+    const { container } = render(
+      <main>
+        <h1>Title</h1>
+        <DocsSection heading="A">
+          <p>content</p>
+        </DocsSection>
+      </main>,
+    );
+    const outline = getHeadingOutline(container);
+    assertValidOutline(outline);
+    expect(outline).toEqual([1, 2]);
+  });
+
+  it("forms a valid outline without skipping levels (deeply nested section)", () => {
+    const { container } = render(
+      <main>
+        <h1>Title</h1>
+        <DocsSection heading="A">
+          <DocsSection heading="A.1">
+            <DocsSection heading="A.1.1">
+              <DocsSection heading="A.1.1.1">
+                <DocsSection heading="A.1.1.1.1">
+                  <DocsSection heading="A.1.1.1.1.1">
+                    <p>content</p>
+                  </DocsSection>
+                </DocsSection>
+              </DocsSection>
+            </DocsSection>
+          </DocsSection>
+        </DocsSection>
+      </main>,
+    );
+    const outline = getHeadingOutline(container);
+    assertValidOutline(outline);
+    expect(outline).toEqual([1, 2, 3, 4, 5, 6, 6]);
+  });
+});

src/app/docs/Section.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import React from "react";
+
+// Context to track the current heading level
+export const LevelContext = React.createContext<number>(2);
+
+interface DocsSectionProps {
+  heading: React.ReactNode;
+  children: React.ReactNode;
+}
+
+export function DocsSection({ heading, children }: DocsSectionProps) {
+  const level = React.useContext(LevelContext);
+  const HeadingTag = `h${Math.min(level, 6)}` as keyof JSX.IntrinsicElements;
+
+  return (
+    <section>
+      <HeadingTag className="font-mono text-sm font-medium">{heading}</HeadingTag>
+      <div className="mt-1 text-sm text-neutral-700 dark:text-neutral-300">
+        <LevelContext.Provider value={level + 1}>
+          {children}
+        </LevelContext.Provider>
+      </div>
+    </section>
+  );
+}

src/app/docs/page.test.tsx

@@ -21,6 +21,24 @@ describe('DocsPage', () => {
     expect(screen.getByText(/GET \/api\/v1\/quote/i)).toBeInTheDocument();
   });
 
+  it('forms a valid heading outline without skipping levels', () => {
+    const { container } = render(<DocsPage />);
+    const headings = Array.from(
+      container.querySelectorAll('h1, h2, h3, h4, h5, h6')
+    );
+    const levels = headings.map((h) => parseInt(h.tagName[1], 10));
+
+    expect(levels.length).toBeGreaterThan(0);
+    expect(levels[0]).toBe(1); // Page starts with h1
+
+    for (let i = 1; i < levels.length; i++) {
+      const prev = levels[i - 1];
+      const curr = levels[i];
+      // A heading can be any level up to prev + 1
+      expect(curr).toBeLessThanOrEqual(prev + 1);
+    }
+  });
+
   it('marks openapi.json as an external link', () => {
     render(<DocsPage />);
     const link = screen.getByRole('link', { name: /openapi\.json/i });

src/app/docs/page.tsx

@@ -1,10 +1,11 @@
 import type { Metadata } from 'next';
 import { OpenApiLink } from './OpenApiLink';
+import { DocsSection } from "./Section";
 
 export const dynamic = 'force-static';
 
 export const metadata: Metadata = {
-  title: 'Docs',
+  title: 'Docs — StableRoute',
   description: 'Short reference for the StableRoute HTTP API common endpoints.',
 };
 
@@ -42,16 +43,13 @@ export default function DocsPage() {
         Companion to <OpenApiLink /> (opens external API spec) — short prose for
         the most common endpoints.
       </p>
-      <dl className="space-y-4">
+      <div className="space-y-4">
         {sections.map((s) => (
-          <div key={s.h}>
-            <dt className="font-mono text-sm font-medium">{s.h}</dt>
-            <dd className="mt-1 text-sm text-neutral-700 dark:text-neutral-300">
-              {s.p}
-            </dd>
-          </div>
+          <DocsSection key={s.h} heading={s.h}>
+            <p>{s.p}</p>
+          </DocsSection>
         ))}
-      </dl>
+      </div>
     </main>
   );
 }