From 55bbdcb08fe182336c7d0093d3b03c079c19e282 Mon Sep 17 00:00:00 2001
From: 0takuc0mrade <junep059@gmail.com>
Date: Fri, 28 Aug 2026 11:24:26 +0100
Subject: [PATCH 1/2] feat(docs): add shared docs foundations

Implement DX-027, DX-030, DX-033, and DX-037 together so the docs app consumes the shared design system, provides responsive reading chrome and ordered navigation, and supports persistent MDX tab groups.\n\nVerified with docs typecheck, 16 focused tests, production build, Pagefind generation, content checks, token enforcement, and changelog validation. The full repository gate remains red on unrelated malformed upstream changelog and web files; publishing is explicitly authorized despite those upstream failures.
---
 .changelog/unreleased/627-docs-foundations.md |   8 ++
 apps/docs/content/meta.json                   |   9 +-
 apps/docs/index.html                          |  16 +++
 apps/docs/package.json                        |   2 +
 apps/docs/scripts/build.ts                    |  22 ++--
 apps/docs/scripts/components.test.tsx         | 120 ++++++++++++++++--
 apps/docs/scripts/content-loader.test.ts      |   6 +
 apps/docs/scripts/navigation.test.tsx         |  60 +++++++++
 apps/docs/scripts/search.test.ts              |  38 ++++--
 apps/docs/src/app/layout.tsx                  |  11 ++
 apps/docs/src/app/main.tsx                    |  53 ++++++++
 apps/docs/src/app/page.tsx                    |  15 +++
 .../components/BreadcrumbStructuredData.tsx   |  21 +++
 apps/docs/src/components/Breadcrumbs.tsx      |  35 +++++
 apps/docs/src/components/DocsLayout.tsx       | 105 +++++++++++++++
 apps/docs/src/components/DocsNavigation.tsx   |  53 ++++++++
 apps/docs/src/components/Pager.tsx            |  51 ++++++++
 apps/docs/src/lib/content.ts                  |  24 ++--
 apps/docs/src/lib/navigation.ts               | 110 ++++++++++++++++
 apps/docs/src/mdx/CodeGroup.tsx               |  48 +++++++
 apps/docs/src/mdx/Tabs.tsx                    |  68 ++++++++++
 apps/docs/src/mdx/components.tsx              |  32 ++++-
 apps/docs/src/mdx/useTabs.ts                  |  75 +++++++++++
 apps/docs/src/styles/globals.css              |   1 +
 apps/docs/vite.config.ts                      |   9 +-
 bun.lock                                      |   2 +
 scripts/check-design-tokens.ts                |  33 +++--
 27 files changed, 963 insertions(+), 64 deletions(-)
 create mode 100644 .changelog/unreleased/627-docs-foundations.md
 create mode 100644 apps/docs/index.html
 create mode 100644 apps/docs/scripts/navigation.test.tsx
 create mode 100644 apps/docs/src/app/layout.tsx
 create mode 100644 apps/docs/src/app/main.tsx
 create mode 100644 apps/docs/src/app/page.tsx
 create mode 100644 apps/docs/src/components/BreadcrumbStructuredData.tsx
 create mode 100644 apps/docs/src/components/Breadcrumbs.tsx
 create mode 100644 apps/docs/src/components/DocsLayout.tsx
 create mode 100644 apps/docs/src/components/DocsNavigation.tsx
 create mode 100644 apps/docs/src/components/Pager.tsx
 create mode 100644 apps/docs/src/lib/navigation.ts
 create mode 100644 apps/docs/src/mdx/CodeGroup.tsx
 create mode 100644 apps/docs/src/mdx/Tabs.tsx
 create mode 100644 apps/docs/src/mdx/useTabs.ts
 create mode 100644 apps/docs/src/styles/globals.css

diff --git a/.changelog/unreleased/627-docs-foundations.md b/.changelog/unreleased/627-docs-foundations.md
new file mode 100644
index 00000000..7078663a
--- /dev/null
+++ b/.changelog/unreleased/627-docs-foundations.md
@@ -0,0 +1,8 @@
+---
+type: added
+area: docs
+pr: 627
+breaking: false
+---
+
+Add shared design-system styling, responsive documentation chrome, navigation breadcrumbs and pagers, and persistent MDX tab groups.
diff --git a/apps/docs/content/meta.json b/apps/docs/content/meta.json
index 7107d95a..dc71e61d 100644
--- a/apps/docs/content/meta.json
+++ b/apps/docs/content/meta.json
@@ -27,11 +27,18 @@
         "reference/data-store",
         "reference/synthetics-reader",
         "reference/order-vault",
+        "reference/contracts.generated",
+        "reference/exchange-router",
         "reference/graphql.generated",
+        "reference/tokens.generated",
+        "reference/errors",
         "reference/glossary"
       ]
     },
-    { "label": "Reference", "pages": ["reference/contracts.generated", "reference/exchange-router", "reference/glossary"] },
+    {
+      "label": "Guides",
+      "pages": ["guides/troubleshooting"]
+    },
     {
       "label": "Resources",
       "pages": [
diff --git a/apps/docs/index.html b/apps/docs/index.html
new file mode 100644
index 00000000..fd75bd80
--- /dev/null
+++ b/apps/docs/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="description"
+      content="Documentation for SO4 markets, contracts, and developer tooling."
+    />
+    <title>SO4 documentation</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/app/main.tsx"></script>
+  </body>
+</html>
diff --git a/apps/docs/package.json b/apps/docs/package.json
index d57289b0..3142def3 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -31,6 +31,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.11.6",
+    "@tailwindcss/vite": "^4.1.18",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/rollup": "^3.1.0",
     "@repo/vitest-config": "workspace:*",
@@ -51,6 +52,7 @@
     "remark-gfm": "^4.0.1",
     "remark-mdx-frontmatter": "^5.2.0",
     "shiki": "^4.4.3",
+    "tailwindcss": "^4.1.18",
     "typescript": "^5.9.3",
     "vite": "^7.3.2"
   }
diff --git a/apps/docs/scripts/build.ts b/apps/docs/scripts/build.ts
index f8d510e4..fd907334 100644
--- a/apps/docs/scripts/build.ts
+++ b/apps/docs/scripts/build.ts
@@ -1,4 +1,4 @@
-import { mkdir, rm } from "node:fs/promises"
+import { mkdir, readdir, rm } from "node:fs/promises"
 import { join } from "node:path"
 
 import { $ } from "bun"
@@ -11,7 +11,7 @@ await $`bun run ${join(appRoot, "../../scripts/generate-design-tokens.ts")} --ch
 await $`bun run ${join(appRoot, "../../scripts/generate-errors-reference.ts")} --check`
 
 const pages = (await loadPages()).filter(
-  (page) => page.frontmatter.status !== "draft",
+  (page) => page.frontmatter.status !== "draft"
 )
 const outputRoot = join(appRoot, ".nitro-static")
 
@@ -26,7 +26,7 @@ function renderInline(value: string) {
   return value
     .replace(
       /<Term id="([a-z0-9-]+)">([^<]+)<\/Term>/g,
-      '<a href="/reference/glossary#$1">$2</a>',
+      '<a href="/reference/glossary#$1">$2</a>'
     )
     .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>')
     .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
@@ -45,25 +45,31 @@ function render(body: string) {
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, "-")
             .replace(/(^-|-$)/g, "")
-        return `<h2 id="${id}">${escape(heading[1])}</h2>`
+        return `<h2 class="mt-10 text-xl font-semibold text-text-primary" id="${id}">${escape(heading[1])}</h2>`
       }
       if (block.startsWith("> "))
-        return `<aside>${renderInline(block.replace(/^> ?/gm, ""))}</aside>`
+        return `<aside class="my-6 rounded-lg bg-warning-subtle p-4 text-sm text-text-primary">${renderInline(block.replace(/^> ?/gm, ""))}</aside>`
       if (block.startsWith("- "))
-        return `<ul>${block
+        return `<ul class="mb-4 list-disc space-y-2 ps-6 text-sm text-text-primary">${block
           .split("\n")
           .map((line) => `<li>${renderInline(line.slice(2))}</li>`)
           .join("")}</ul>`
-      return `<p>${renderInline(block)}</p>`
+      return `<p class="mb-4 text-sm leading-7 text-text-primary">${renderInline(block)}</p>`
     })
     .join("\n")
 }
 
 await rm(outputRoot, { recursive: true, force: true })
+await $`bunx vite build`.cwd(appRoot)
+const stylesheet = (await readdir(join(outputRoot, "assets"))).find(
+  (file) => file.startsWith("index-") && file.endsWith(".css")
+)
+if (!stylesheet) throw new Error("Vite did not emit the docs stylesheet")
+
 for (const page of pages) {
   const directory = join(outputRoot, page.route.slice(1))
   await mkdir(directory, { recursive: true })
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(page.frontmatter.title)} · SO4 docs</title><meta name="description" content="${escape(page.frontmatter.description)}"><style>:root{font:16px/1.65 system-ui;color:#17191d;background:#fff}body{margin:0}header,main{max-width:760px;margin:auto;padding:24px}header{display:flex;justify-content:space-between;border-bottom:1px solid #ddd}a{color:#3156c8}h1{font-size:2.4rem;line-height:1.1}h2{margin-top:2.5rem}aside{border-left:4px solid #d99b16;background:#fff8df;padding:16px}code{background:#eee;padding:2px 5px}@media print{header{display:none}main{max-width:none;padding:0}a{color:inherit;text-decoration:none}aside{break-inside:avoid;background:none;border:1px solid #777}h2{break-after:avoid}}</style></head><body><header data-pagefind-ignore><a href="/">SO4 docs</a><a href="https://so4.market">Open interface</a></header><main data-pagefind-body><h1>${escape(page.frontmatter.title)}</h1>${render(page.body)}</main></body></html>`
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(page.frontmatter.title)} · SO4 docs</title><meta name="description" content="${escape(page.frontmatter.description)}"><link rel="stylesheet" href="/assets/${stylesheet}"></head><body class="bg-surface-canvas text-text-primary"><header class="mx-auto flex h-16 max-w-3xl items-center justify-between border-b border-border px-4" data-pagefind-ignore><a class="text-sm font-semibold text-text-primary" href="/">SO4 docs</a><a class="text-sm font-medium text-text-link" href="https://so4.market">Open interface</a></header><main class="mx-auto max-w-3xl px-4 py-10" data-pagefind-body><h1 class="mb-6 text-2xl font-semibold text-text-primary">${escape(page.frontmatter.title)}</h1>${render(page.body)}</main></body></html>`
   await Bun.write(join(directory, "index.html"), html)
 }
 
diff --git a/apps/docs/scripts/components.test.tsx b/apps/docs/scripts/components.test.tsx
index a6ed3748..4a3cc37b 100644
--- a/apps/docs/scripts/components.test.tsx
+++ b/apps/docs/scripts/components.test.tsx
@@ -1,9 +1,13 @@
 import { GlobalRegistrator } from "@happy-dom/global-registrator"
 
-
-
 import { test, expect, afterEach, afterAll, beforeAll } from "bun:test"
-import { cleanup, render, act } from "@testing-library/react"
+import {
+  cleanup,
+  render,
+  act,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react"
 import { components } from "../src/mdx/components"
 import * as jsxRuntime from "react/jsx-runtime"
 import { compile, run } from "@mdx-js/mdx"
@@ -15,6 +19,8 @@ import {
 } from "@tanstack/react-router"
 import { shikiPlugin } from "../src/lib/rehype-shiki"
 import remarkGfm from "remark-gfm"
+import { DocsLayout } from "../src/components/DocsLayout"
+import { Tab, Tabs as DocsTabs } from "../src/mdx/Tabs"
 
 beforeAll(() => {
   GlobalRegistrator.register()
@@ -26,6 +32,7 @@ afterAll(() => {
 
 afterEach(() => {
   cleanup()
+  window.localStorage.clear()
 })
 
 const mdxFixture = `
@@ -57,7 +64,7 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
     remarkPlugins: [remarkGfm],
     rehypePlugins: [shikiPlugin],
   })
-  
+
   const { default: MDXContent } = await run(String(compiled), {
     ...jsxRuntime,
   })
@@ -65,7 +72,7 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
   const rootRoute = createRootRoute({
     component: () => <MDXContent components={components} />,
   })
-  
+
   const router = createRouter({
     routeTree: rootRoute,
     history: createMemoryHistory(),
@@ -82,7 +89,7 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
   expect(h1).not.toBeNull()
   expect(h1?.className).toContain("text-22")
   expect(h1?.className).toContain("font-semibold")
-  
+
   // Verify blockquote (Callout)
   const callout = container.querySelector("[role='status']")
   expect(callout).not.toBeNull()
@@ -90,7 +97,7 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
 
   // Verify inline code
   const codes = Array.from(container.querySelectorAll("code"))
-  const inlineCode = codes.find(c => c.textContent === "inline code")
+  const inlineCode = codes.find((c) => c.textContent === "inline code")
   expect(inlineCode).not.toBeUndefined()
   expect(inlineCode?.className).toContain("bg-surface-sunken")
 
@@ -98,7 +105,7 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
   const internalLink = container.querySelector("a[href='/foo']")
   expect(internalLink).not.toBeNull()
   expect(internalLink?.className).toContain("hover:underline")
-  
+
   // Verify external link
   const externalLink = container.querySelector("a[href='https://example.com']")
   expect(externalLink).not.toBeNull()
@@ -107,7 +114,9 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
   expect(externalLink?.querySelector("svg")).not.toBeNull() // Arrow icon
 
   // Verify table structure
-  const tableContainer = container.querySelector("[data-slot='table-container']")
+  const tableContainer = container.querySelector(
+    "[data-slot='table-container']"
+  )
   if (!tableContainer) {
     console.log("HTML Output:", container.innerHTML)
   }
@@ -115,3 +124,96 @@ test("MDX components map renders kitchen-sink fixture correctly", async () => {
   expect(tableContainer?.className).toContain("overflow-x-auto")
   expect(tableContainer?.querySelector("table")).not.toBeNull()
 })
+
+function SyncedTabs() {
+  return (
+    <>
+      <DocsTabs groupId="manager">
+        <Tab label="bun">Bun first</Tab>
+        <Tab label="npm">npm first</Tab>
+      </DocsTabs>
+      <DocsTabs groupId="manager">
+        <Tab label="bun">Bun second</Tab>
+        <Tab label="npm">npm second</Tab>
+      </DocsTabs>
+    </>
+  )
+}
+
+test("DocsLayout exposes landmarks and a working skip link", () => {
+  const result = render(
+    <DocsLayout
+      header={<a href="/">SO4 docs</a>}
+      sidebar={<nav aria-label="Documentation">Sidebar</nav>}
+      toc={
+        <ol>
+          <li>
+            <a href="#intro">Introduction</a>
+          </li>
+        </ol>
+      }
+      footer="Footer"
+    >
+      <h1 id="intro">Introduction</h1>
+    </DocsLayout>
+  )
+
+  const main = result.getByRole("main")
+  const skipLink = result.getByRole("link", { name: "Skip to main content" })
+  expect(main.id).toBe("main-content")
+  expect(main.getAttribute("tabindex")).toBe("-1")
+  expect(result.getByRole("contentinfo")).toBeDefined()
+
+  fireEvent.click(skipLink)
+  expect(document.activeElement).toBe(main)
+})
+
+test("MDX tabs sync groups, persist selection, and keep every panel", async () => {
+  const result = render(<SyncedTabs />)
+  const npmTabs = result.getAllByRole("tab", { name: "npm" })
+  fireEvent.click(npmTabs[0])
+
+  await waitFor(() => {
+    expect(npmTabs[0].getAttribute("aria-selected")).toBe("true")
+    expect(npmTabs[1].getAttribute("aria-selected")).toBe("true")
+  })
+  expect(window.localStorage.getItem("so4-docs-tabs:manager")).toBe("npm")
+  expect(result.getByText("npm first")).toBeDefined()
+  expect(result.getByText("npm second")).toBeDefined()
+})
+
+test("MDX tabs restore a persisted selection", async () => {
+  window.localStorage.setItem("so4-docs-tabs:manager", "npm")
+  const result = render(<SyncedTabs />)
+
+  await waitFor(() => {
+    for (const tab of result.getAllByRole("tab", { name: "npm" })) {
+      expect(tab.getAttribute("aria-selected")).toBe("true")
+    }
+  })
+})
+
+test("MDX tabs fall back to the first option when storage is unavailable", async () => {
+  const storage = window.localStorage
+  const originalGetItem = storage.getItem.bind(storage)
+  Object.defineProperty(storage, "getItem", {
+    configurable: true,
+    value: () => {
+      throw new Error("storage disabled")
+    },
+  })
+
+  try {
+    const result = render(<SyncedTabs />)
+    await waitFor(() => {
+      for (const tab of result.getAllByRole("tab", { name: "bun" })) {
+        expect(tab.getAttribute("aria-selected")).toBe("true")
+      }
+    })
+  } finally {
+    Object.defineProperty(storage, "getItem", {
+      configurable: true,
+      value: originalGetItem,
+    })
+  }
+})
diff --git a/apps/docs/scripts/content-loader.test.ts b/apps/docs/scripts/content-loader.test.ts
index e8741089..f0d13bc1 100644
--- a/apps/docs/scripts/content-loader.test.ts
+++ b/apps/docs/scripts/content-loader.test.ts
@@ -11,6 +11,12 @@ describe("content loader — kebab-case validation", () => {
     expect(isKebabCase("a-b-c")).toBe(true)
   })
 
+  test("generated page basenames remain valid after removing their suffix", () => {
+    expect(isKebabCase("tokens.generated".replace(/\.generated$/, ""))).toBe(
+      true
+    )
+  })
+
   test("isKebabCase rejects non-kebab-case names", () => {
     expect(isKebabCase("My Page")).toBe(false)
     expect(isKebabCase("myPage")).toBe(false)
diff --git a/apps/docs/scripts/navigation.test.tsx b/apps/docs/scripts/navigation.test.tsx
new file mode 100644
index 00000000..eb424896
--- /dev/null
+++ b/apps/docs/scripts/navigation.test.tsx
@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test"
+import { contentRoot, loadContentIndex } from "../src/lib/content"
+import {
+  breadcrumbStructuredData,
+  buildNavigation,
+  flattenNavigation,
+  getBreadcrumbs,
+  getPagerLinks,
+  type NavMetaSection,
+} from "../src/lib/navigation"
+
+async function loadActualNavigation() {
+  const meta = (await Bun.file(`${contentRoot}/meta.json`).json()) as {
+    sections: NavMetaSection[]
+  }
+  const index = await loadContentIndex("development")
+  return buildNavigation(meta.sections, index.byRoute)
+}
+
+describe("documentation navigation", () => {
+  test("breadcrumbs and pagers follow every page in sidebar order", async () => {
+    const navigation = await loadActualNavigation()
+    const pages = flattenNavigation(navigation)
+
+    for (const [index, page] of pages.entries()) {
+      const pager = getPagerLinks(navigation, page.route)
+      expect(pager.previous).toEqual(index > 0 ? pages[index - 1] : undefined)
+      expect(pager.next).toEqual(
+        index < pages.length - 1 ? pages[index + 1] : undefined
+      )
+
+      const crumbs = getBreadcrumbs(navigation, page.route)
+      expect(crumbs.at(-1)?.label).toBe(page.title)
+    }
+  })
+
+  test("boundary pages expose only the available pager link", async () => {
+    const navigation = await loadActualNavigation()
+    const pages = flattenNavigation(navigation)
+    const first = getPagerLinks(navigation, pages[0].route)
+    const last = getPagerLinks(navigation, pages.at(-1)!.route)
+
+    expect(first.previous).toBeUndefined()
+    expect(first.next).toBeDefined()
+    expect(last.previous).toBeDefined()
+    expect(last.next).toBeUndefined()
+  })
+
+  test("emits ordered BreadcrumbList structured data", () => {
+    const items = [
+      { label: "Docs", href: "/" },
+      { label: "Developers" },
+      { label: "Architecture" },
+    ]
+    const data = breadcrumbStructuredData(items, "https://docs.so4.market")
+    expect(data["@type"]).toBe("BreadcrumbList")
+    expect(data.itemListElement.map((item) => item.position)).toEqual([1, 2, 3])
+    expect(data.itemListElement[0].item).toBe("https://docs.so4.market/")
+  })
+})
diff --git a/apps/docs/scripts/search.test.ts b/apps/docs/scripts/search.test.ts
index a0f3aa03..f5cbe6c2 100644
--- a/apps/docs/scripts/search.test.ts
+++ b/apps/docs/scripts/search.test.ts
@@ -9,30 +9,44 @@ const appRoot = join(import.meta.dir, "..")
 describe("Search Index", () => {
   test("generates deterministic index", async () => {
     // Build first time
-    await $`bun run scripts/build.ts && bunx --bun pagefind --site .nitro-static`.cwd(appRoot).quiet()
-    const run1 = await $`find .nitro-static/pagefind -type f -exec shasum {} +`.cwd(appRoot).text()
-    
+    await $`bun run scripts/build.ts && bunx --bun pagefind --site .nitro-static`
+      .cwd(appRoot)
+      .quiet()
+    const run1 = await $`find .nitro-static/pagefind -type f -exec shasum {} +`
+      .cwd(appRoot)
+      .text()
+
     // Build second time
-    await $`bun run scripts/build.ts && bunx --bun pagefind --site .nitro-static`.cwd(appRoot).quiet()
-    const run2 = await $`find .nitro-static/pagefind -type f -exec shasum {} +`.cwd(appRoot).text()
-    
+    await $`bun run scripts/build.ts && bunx --bun pagefind --site .nitro-static`
+      .cwd(appRoot)
+      .quiet()
+    const run2 = await $`find .nitro-static/pagefind -type f -exec shasum {} +`
+      .cwd(appRoot)
+      .text()
+
     // Expect outputs to be completely identical
     expect(run1).toEqual(run2)
   }, 15000)
 
   test("draft pages are absent from production index", async () => {
-    const draftPagePath = join(appRoot, ".nitro-static/resources/terms/index.html")
+    const draftPagePath = join(
+      appRoot,
+      ".nitro-static/resources/terms/index.html"
+    )
     expect(existsSync(draftPagePath)).toBe(false)
   })
 
   test("navigation text does not pollute indexed results", async () => {
     // We check that the HTML structure explicitly ignores the header
-    const sampleHtml = await readFile(join(appRoot, ".nitro-static/resources/faq/index.html"), "utf-8")
-    expect(sampleHtml).toContain('<header data-pagefind-ignore>')
-    expect(sampleHtml).toContain('<main data-pagefind-body>')
-    
+    const sampleHtml = await readFile(
+      join(appRoot, ".nitro-static/resources/faq/index.html"),
+      "utf-8"
+    )
+    expect(sampleHtml).toContain("data-pagefind-ignore")
+    expect(sampleHtml).toContain("data-pagefind-body")
+
     // As a result, pagefind will not index "Open interface" (which is in the header)
-    // We can also verify that 'Open interface' is absent in the pagefind index chunks, but 
+    // We can also verify that 'Open interface' is absent in the pagefind index chunks, but
     // relying on pagefind's own directives is the supported way to assert this.
   })
 })
diff --git a/apps/docs/src/app/layout.tsx b/apps/docs/src/app/layout.tsx
new file mode 100644
index 00000000..aea22e71
--- /dev/null
+++ b/apps/docs/src/app/layout.tsx
@@ -0,0 +1,11 @@
+import type { ReactNode } from "react"
+
+import "../styles/globals.css"
+
+export interface RootLayoutProps {
+  children: ReactNode
+}
+
+export function RootLayout({ children }: RootLayoutProps) {
+  return <>{children}</>
+}
diff --git a/apps/docs/src/app/main.tsx b/apps/docs/src/app/main.tsx
new file mode 100644
index 00000000..c7b3eac7
--- /dev/null
+++ b/apps/docs/src/app/main.tsx
@@ -0,0 +1,53 @@
+import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+
+import { DocsLayout } from "../components/DocsLayout"
+import { DocsPlaceholderPage } from "./page"
+import "../styles/globals.css"
+
+const root = document.getElementById("root")
+
+if (!root) throw new Error("Missing docs application root")
+
+createRoot(root).render(
+  <StrictMode>
+    <DocsLayout
+      header={
+        <a href="/" className="text-sm font-semibold text-text-primary">
+          SO4 docs
+        </a>
+      }
+      sidebar={
+        <nav aria-label="Documentation" className="space-y-2 text-sm">
+          <a
+            href="/developers/architecture"
+            className="block text-text-secondary hover:text-text-primary"
+          >
+            Developers
+          </a>
+          <a
+            href="/concepts/risk"
+            className="block text-text-secondary hover:text-text-primary"
+          >
+            Concepts
+          </a>
+          <a
+            href="/reference/data-store"
+            className="block text-text-secondary hover:text-text-primary"
+          >
+            Reference
+          </a>
+          <a
+            href="/resources/faq"
+            className="block text-text-secondary hover:text-text-primary"
+          >
+            Resources
+          </a>
+        </nav>
+      }
+      footer={<p className="text-sm text-text-secondary">SO4 documentation</p>}
+    >
+      <DocsPlaceholderPage />
+    </DocsLayout>
+  </StrictMode>
+)
diff --git a/apps/docs/src/app/page.tsx b/apps/docs/src/app/page.tsx
new file mode 100644
index 00000000..0d10d3b2
--- /dev/null
+++ b/apps/docs/src/app/page.tsx
@@ -0,0 +1,15 @@
+import { Button } from "@workspace/ui/components/button"
+
+export function DocsPlaceholderPage() {
+  return (
+    <section className="mx-auto max-w-3xl px-4 py-16 md:px-6">
+      <h1 className="text-2xl font-semibold text-text-primary">
+        SO4 documentation
+      </h1>
+      <p className="mt-3 max-w-prose text-sm text-text-secondary">
+        Learn how SO4 markets, contracts, and developer tooling work.
+      </p>
+      <Button className="mt-6">Browse documentation</Button>
+    </section>
+  )
+}
diff --git a/apps/docs/src/components/BreadcrumbStructuredData.tsx b/apps/docs/src/components/BreadcrumbStructuredData.tsx
new file mode 100644
index 00000000..5a3122c4
--- /dev/null
+++ b/apps/docs/src/components/BreadcrumbStructuredData.tsx
@@ -0,0 +1,21 @@
+import type { BreadcrumbItem } from "../lib/navigation"
+import { breadcrumbStructuredData } from "../lib/navigation"
+
+interface BreadcrumbStructuredDataProps {
+  items: BreadcrumbItem[]
+  siteUrl?: string
+}
+
+export function BreadcrumbStructuredData({
+  items,
+  siteUrl = "https://docs.so4.market",
+}: BreadcrumbStructuredDataProps) {
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{
+        __html: JSON.stringify(breadcrumbStructuredData(items, siteUrl)),
+      }}
+    />
+  )
+}
diff --git a/apps/docs/src/components/Breadcrumbs.tsx b/apps/docs/src/components/Breadcrumbs.tsx
new file mode 100644
index 00000000..c8136b00
--- /dev/null
+++ b/apps/docs/src/components/Breadcrumbs.tsx
@@ -0,0 +1,35 @@
+import {
+  Breadcrumb,
+  BreadcrumbItem as BreadcrumbPrimitiveItem,
+  BreadcrumbLink,
+  BreadcrumbSeparator,
+} from "@workspace/ui/components/breadcrumb"
+
+import type { BreadcrumbItem } from "../lib/navigation"
+
+interface DocsBreadcrumbsProps {
+  items: BreadcrumbItem[]
+}
+
+export function DocsBreadcrumbs({ items }: DocsBreadcrumbsProps) {
+  return (
+    <Breadcrumb className="mb-6">
+      {items.map((item, index) => {
+        const isCurrent = index === items.length - 1
+        return (
+          <BreadcrumbPrimitiveItem
+            key={`${item.label}-${index}`}
+            isCurrent={isCurrent}
+          >
+            {item.href && !isCurrent ? (
+              <BreadcrumbLink href={item.href}>{item.label}</BreadcrumbLink>
+            ) : (
+              <BreadcrumbLink as="span">{item.label}</BreadcrumbLink>
+            )}
+            {!isCurrent ? <BreadcrumbSeparator /> : null}
+          </BreadcrumbPrimitiveItem>
+        )
+      })}
+    </Breadcrumb>
+  )
+}
diff --git a/apps/docs/src/components/DocsLayout.tsx b/apps/docs/src/components/DocsLayout.tsx
new file mode 100644
index 00000000..7d475fd2
--- /dev/null
+++ b/apps/docs/src/components/DocsLayout.tsx
@@ -0,0 +1,105 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { Menu01Icon } from "@hugeicons/core-free-icons"
+import { Button } from "@workspace/ui/components/button"
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@workspace/ui/components/collapsible"
+import { Icon } from "@workspace/ui/components/icon"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetTitle,
+  SheetTrigger,
+} from "@workspace/ui/components/sheet"
+import { MAIN_CONTENT_ID, SkipLink } from "@workspace/ui/components/skip-link"
+
+export interface DocsLayoutProps {
+  header?: ReactNode
+  sidebar: ReactNode
+  toc?: ReactNode
+  footer?: ReactNode
+  children: ReactNode
+}
+
+export function DocsLayout({
+  header,
+  sidebar,
+  toc,
+  footer,
+  children,
+}: DocsLayoutProps) {
+  return (
+    <div className="min-h-dvh overflow-x-clip bg-surface-canvas text-text-primary">
+      <SkipLink />
+      <header className="sticky top-0 z-40 border-b border-border bg-surface-canvas">
+        <div className="mx-auto flex h-16 max-w-screen-2xl items-center gap-3 px-4 md:px-6 lg:px-8">
+          <div className="lg:hidden">
+            <Sheet>
+              <SheetTrigger
+                render={
+                  <Button
+                    variant="ghost"
+                    size="icon"
+                    aria-label="Open documentation navigation"
+                  />
+                }
+              >
+                <Icon icon={Menu01Icon} size="md" />
+              </SheetTrigger>
+              <SheetContent side="left" className="w-72 p-6">
+                <SheetTitle>Documentation</SheetTitle>
+                <SheetDescription>
+                  Browse documentation sections and pages.
+                </SheetDescription>
+                <div className="mt-6 min-h-0 flex-1 overflow-y-auto">
+                  {sidebar}
+                </div>
+              </SheetContent>
+            </Sheet>
+          </div>
+          <div className="min-w-0 flex-1">{header}</div>
+        </div>
+      </header>
+
+      <div className="mx-auto flex max-w-screen-2xl items-start px-4 md:px-6 lg:px-8">
+        <aside className="sticky top-16 hidden max-h-[calc(100dvh-4rem)] w-56 shrink-0 overflow-y-auto py-8 pe-6 lg:block xl:w-64">
+          {sidebar}
+        </aside>
+
+        <main
+          id={MAIN_CONTENT_ID}
+          tabIndex={-1}
+          className="min-w-0 flex-1 py-8 outline-none lg:px-8 xl:px-12"
+          data-pagefind-body
+        >
+          {toc ? (
+            <Collapsible className="mb-8 xl:hidden">
+              <CollapsibleTrigger className="border-y border-border py-3">
+                On this page
+              </CollapsibleTrigger>
+              <CollapsibleContent className="pt-3">{toc}</CollapsibleContent>
+            </Collapsible>
+          ) : null}
+          <article className="mx-auto max-w-3xl">{children}</article>
+        </main>
+
+        {toc ? (
+          <aside className="sticky top-16 hidden max-h-[calc(100dvh-4rem)] w-56 shrink-0 overflow-y-auto py-8 ps-6 xl:block">
+            <nav aria-label="On this page">{toc}</nav>
+          </aside>
+        ) : null}
+      </div>
+
+      {footer ? (
+        <footer className="border-t border-border px-4 py-8 md:px-6 lg:px-8">
+          <div className="mx-auto max-w-screen-2xl">{footer}</div>
+        </footer>
+      ) : null}
+    </div>
+  )
+}
diff --git a/apps/docs/src/components/DocsNavigation.tsx b/apps/docs/src/components/DocsNavigation.tsx
new file mode 100644
index 00000000..6a90501e
--- /dev/null
+++ b/apps/docs/src/components/DocsNavigation.tsx
@@ -0,0 +1,53 @@
+import { cn } from "@workspace/ui/lib/utils"
+
+import type { NavSection } from "../lib/navigation"
+
+interface DocsNavigationProps {
+  sections: NavSection[]
+  currentRoute?: string
+  onNavigate?: () => void
+  className?: string
+}
+
+export function DocsNavigation({
+  sections,
+  currentRoute,
+  onNavigate,
+  className,
+}: DocsNavigationProps) {
+  return (
+    <nav aria-label="Documentation" className={cn("space-y-6", className)}>
+      {sections.map((section) => (
+        <section key={section.label} aria-labelledby={`nav-${section.label}`}>
+          <h2
+            id={`nav-${section.label}`}
+            className="mb-2 text-xs font-semibold text-text-primary"
+          >
+            {section.label}
+          </h2>
+          <ul className="space-y-1">
+            {section.pages.map((page) => {
+              const isCurrent = page.route === currentRoute
+              return (
+                <li key={page.route}>
+                  <a
+                    href={page.route}
+                    aria-current={isCurrent ? "page" : undefined}
+                    onClick={onNavigate}
+                    className={cn(
+                      "block rounded-md px-2 py-1.5 text-sm text-text-secondary transition-colors hover:bg-surface-interactive hover:text-text-primary focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none",
+                      isCurrent &&
+                        "bg-surface-interactive font-medium text-text-primary"
+                    )}
+                  >
+                    {page.sidebarLabel ?? page.title}
+                  </a>
+                </li>
+              )
+            })}
+          </ul>
+        </section>
+      ))}
+    </nav>
+  )
+}
diff --git a/apps/docs/src/components/Pager.tsx b/apps/docs/src/components/Pager.tsx
new file mode 100644
index 00000000..14212073
--- /dev/null
+++ b/apps/docs/src/components/Pager.tsx
@@ -0,0 +1,51 @@
+import { ArrowLeft01Icon, ArrowRight01Icon } from "@hugeicons/core-free-icons"
+import { Icon } from "@workspace/ui/components/icon"
+import { cn } from "@workspace/ui/lib/utils"
+
+import type { PagerLinks } from "../lib/navigation"
+
+interface PagerProps extends PagerLinks {
+  className?: string
+}
+
+export function Pager({ previous, next, className }: PagerProps) {
+  if (!previous && !next) return null
+
+  return (
+    <nav
+      aria-label="Documentation pagination"
+      className={cn("mt-12 flex gap-4 border-t border-border pt-6", className)}
+    >
+      {previous ? (
+        <a
+          href={previous.route}
+          rel="prev"
+          className="group flex min-w-0 flex-1 items-center gap-3 rounded-lg bg-surface-sunken p-4 text-start transition-colors hover:bg-surface-interactive focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+        >
+          <Icon icon={ArrowLeft01Icon} size="md" className="shrink-0" />
+          <span className="min-w-0">
+            <span className="block text-xs text-text-secondary">Previous</span>
+            <span className="block truncate text-sm font-medium text-text-primary">
+              {previous.title}
+            </span>
+          </span>
+        </a>
+      ) : null}
+      {next ? (
+        <a
+          href={next.route}
+          rel="next"
+          className="group ms-auto flex min-w-0 flex-1 items-center justify-end gap-3 rounded-lg bg-surface-sunken p-4 text-end transition-colors hover:bg-surface-interactive focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+        >
+          <span className="min-w-0">
+            <span className="block text-xs text-text-secondary">Next</span>
+            <span className="block truncate text-sm font-medium text-text-primary">
+              {next.title}
+            </span>
+          </span>
+          <Icon icon={ArrowRight01Icon} size="md" className="shrink-0" />
+        </a>
+      ) : null}
+    </nav>
+  )
+}
diff --git a/apps/docs/src/lib/content.ts b/apps/docs/src/lib/content.ts
index 95660709..ec30f3d7 100644
--- a/apps/docs/src/lib/content.ts
+++ b/apps/docs/src/lib/content.ts
@@ -3,7 +3,7 @@ import { join, relative } from "node:path"
 import { validateFrontmatter } from "./frontmatter"
 import type { Frontmatter } from "./frontmatter"
 
-export const appRoot = import.meta.dir + "/.."
+export const appRoot = import.meta.dir + "/../.."
 export const contentRoot = join(appRoot, "content")
 
 export interface Page {
@@ -29,7 +29,7 @@ async function walk(dir: string): Promise<string[]> {
     entries.map(async (entry) => {
       const path = join(dir, entry.name)
       return entry.isDirectory() ? walk(path) : [path]
-    }),
+    })
   )
   return files.flat()
 }
@@ -49,7 +49,7 @@ function parseMetaSections(meta: MetaConfig): MetaSection[] {
 }
 
 export async function loadContentIndex(
-  mode: "development" | "production" = "production",
+  mode: "development" | "production" = "production"
 ): Promise<PageIndex> {
   const metaRaw = await readFile(join(contentRoot, "meta.json"), "utf8")
   const meta = JSON.parse(metaRaw) as MetaConfig
@@ -62,11 +62,13 @@ export async function loadContentIndex(
   const errors: string[] = []
 
   for (const file of mdxFiles) {
-    const name = file.split("/").pop()!.replace(/\.mdx$/, "")
-    if (!isKebabCase(name)) {
-      errors.push(
-        `${file}: filename "${name}" is not lowercase kebab-case`,
-      )
+    const name = file
+      .split("/")
+      .pop()!
+      .replace(/\.mdx$/, "")
+    const sourceName = name.replace(/\.generated$/, "")
+    if (!isKebabCase(sourceName)) {
+      errors.push(`${file}: filename "${name}" is not lowercase kebab-case`)
       continue
     }
 
@@ -75,9 +77,7 @@ export async function loadContentIndex(
 
     if (byRoute.has(route)) {
       const existing = byRoute.get(route)!
-      errors.push(
-        `duplicate route ${route}: ${existing.file} and ${file}`,
-      )
+      errors.push(`duplicate route ${route}: ${existing.file} and ${file}`)
       continue
     }
 
@@ -116,7 +116,7 @@ export async function loadContentIndex(
   }
 
   const sidebarRoutes = new Set(
-    sections.flatMap((s) => s.pages.map((p) => `/${p}`)),
+    sections.flatMap((s) => s.pages.map((p) => `/${p}`))
   )
 
   for (const route of sidebarRoutes) {
diff --git a/apps/docs/src/lib/navigation.ts b/apps/docs/src/lib/navigation.ts
new file mode 100644
index 00000000..37626681
--- /dev/null
+++ b/apps/docs/src/lib/navigation.ts
@@ -0,0 +1,110 @@
+export interface NavPage {
+  route: string
+  title: string
+  sidebarLabel?: string
+}
+
+export interface NavSection {
+  label: string
+  pages: NavPage[]
+}
+
+export interface NavMetaSection {
+  label: string
+  pages: string[]
+}
+
+interface IndexedPage {
+  route: string
+  frontmatter: {
+    title: string
+    sidebarLabel?: string
+  }
+}
+
+export interface BreadcrumbItem {
+  label: string
+  href?: string
+}
+
+export interface PagerLinks {
+  previous?: NavPage
+  next?: NavPage
+}
+
+export function buildNavigation(
+  metaSections: NavMetaSection[],
+  pagesByRoute: ReadonlyMap<string, IndexedPage>
+): NavSection[] {
+  return metaSections.map((section) => ({
+    label: section.label,
+    pages: section.pages.map((path) => {
+      const route = `/${path}`
+      const page = pagesByRoute.get(route)
+      if (!page) throw new Error(`navigation references missing page ${route}`)
+
+      return {
+        route,
+        title: page.frontmatter.title,
+        sidebarLabel: page.frontmatter.sidebarLabel,
+      }
+    }),
+  }))
+}
+
+export function flattenNavigation(sections: NavSection[]): NavPage[] {
+  return sections.flatMap((section) => section.pages)
+}
+
+export function getPagerLinks(
+  sections: NavSection[],
+  currentRoute: string
+): PagerLinks {
+  const pages = flattenNavigation(sections)
+  const index = pages.findIndex((page) => page.route === currentRoute)
+
+  if (index === -1) return {}
+
+  return {
+    previous: index > 0 ? pages[index - 1] : undefined,
+    next: index < pages.length - 1 ? pages[index + 1] : undefined,
+  }
+}
+
+export function getBreadcrumbs(
+  sections: NavSection[],
+  currentRoute: string
+): BreadcrumbItem[] {
+  for (const section of sections) {
+    const page = section.pages.find((item) => item.route === currentRoute)
+    if (!page) continue
+
+    return [
+      { label: "Docs", href: "/" },
+      { label: section.label },
+      { label: page.title },
+    ]
+  }
+
+  return [{ label: "Docs", href: "/" }]
+}
+
+export function breadcrumbStructuredData(
+  items: BreadcrumbItem[],
+  siteUrl: string
+) {
+  const baseUrl = siteUrl.endsWith("/") ? siteUrl : `${siteUrl}/`
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.label,
+      item: item.href
+        ? new URL(item.href.slice(1), baseUrl).toString()
+        : undefined,
+    })),
+  }
+}
diff --git a/apps/docs/src/mdx/CodeGroup.tsx b/apps/docs/src/mdx/CodeGroup.tsx
new file mode 100644
index 00000000..75e3f775
--- /dev/null
+++ b/apps/docs/src/mdx/CodeGroup.tsx
@@ -0,0 +1,48 @@
+import {
+  Children,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from "react"
+
+import { Tab, Tabs } from "./Tabs"
+
+interface TitledCodeBlockProps {
+  title?: string
+  "data-title"?: string
+  children?: ReactNode
+}
+
+export interface CodeGroupProps {
+  groupId: string
+  children: ReactNode
+}
+
+function getCodeTitle(
+  child: ReactElement<TitledCodeBlockProps>,
+  index: number
+) {
+  return (
+    child.props.title ?? child.props["data-title"] ?? `Example ${index + 1}`
+  )
+}
+
+export function CodeGroup({ groupId, children }: CodeGroupProps) {
+  const blocks = Children.toArray(children).filter(
+    (child): child is ReactElement<TitledCodeBlockProps> =>
+      isValidElement<TitledCodeBlockProps>(child)
+  )
+
+  return (
+    <Tabs groupId={groupId} aria-label="Code examples">
+      {blocks.map((block, index) => {
+        const title = getCodeTitle(block, index)
+        return (
+          <Tab key={`${title}-${index}`} label={title} value={title}>
+            {block}
+          </Tab>
+        )
+      })}
+    </Tabs>
+  )
+}
diff --git a/apps/docs/src/mdx/Tabs.tsx b/apps/docs/src/mdx/Tabs.tsx
new file mode 100644
index 00000000..f3664f9c
--- /dev/null
+++ b/apps/docs/src/mdx/Tabs.tsx
@@ -0,0 +1,68 @@
+"use client"
+
+import {
+  Children,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from "react"
+import {
+  Tabs as TabsPrimitive,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "@workspace/ui/components/tabs"
+
+import { useTabs } from "./useTabs"
+
+export interface TabProps {
+  label: string
+  value?: string
+  children: ReactNode
+}
+
+export function Tab({ children }: TabProps) {
+  return <>{children}</>
+}
+
+export interface TabsProps {
+  groupId: string
+  children: ReactNode
+  "aria-label"?: string
+}
+
+export function Tabs({
+  groupId,
+  children,
+  "aria-label": ariaLabel = "Options",
+}: TabsProps) {
+  const tabs = Children.toArray(children).filter(
+    (child): child is ReactElement<TabProps> => isValidElement<TabProps>(child)
+  )
+  const values = tabs.map((tab) => tab.props.value ?? tab.props.label)
+  const { value, select } = useTabs(groupId, values)
+
+  if (tabs.length === 0) return null
+
+  return (
+    <TabsPrimitive value={value} onValueChange={select} className="my-6">
+      <TabsList variant="line" aria-label={ariaLabel}>
+        {tabs.map((tab, index) => (
+          <TabsTrigger key={values[index]} value={values[index]}>
+            {tab.props.label}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {tabs.map((tab, index) => (
+        <TabsContent
+          key={values[index]}
+          value={values[index]}
+          keepMounted
+          className="mt-4 text-sm print:block"
+        >
+          {tab.props.children}
+        </TabsContent>
+      ))}
+    </TabsPrimitive>
+  )
+}
diff --git a/apps/docs/src/mdx/components.tsx b/apps/docs/src/mdx/components.tsx
index 6a63fb94..73985ce7 100644
--- a/apps/docs/src/mdx/components.tsx
+++ b/apps/docs/src/mdx/components.tsx
@@ -14,6 +14,8 @@ import {
   TableHead,
   TableCell,
 } from "@workspace/ui/components/table"
+import { CodeGroup } from "./CodeGroup"
+import { Tab, Tabs } from "./Tabs"
 
 export const components: MDXComponents = {
   h1: (props) => <Heading level={1} {...props} />,
@@ -32,7 +34,7 @@ export const components: MDXComponents = {
       <code
         {...props}
         className={cn(
-          "font-mono text-[0.875em] bg-surface-sunken px-1.5 py-0.5 rounded text-text-primary",
+          "rounded bg-surface-sunken px-1.5 py-0.5 font-mono text-sm text-text-primary",
           props.className
         )}
       />
@@ -61,7 +63,7 @@ export const components: MDXComponents = {
         <Link
           to={href}
           preload="intent"
-          className="text-primary hover:underline font-medium"
+          className="font-medium text-primary hover:underline"
           {...props}
         >
           {children}
@@ -73,23 +75,39 @@ export const components: MDXComponents = {
         href={href}
         target="_blank"
         rel="noopener noreferrer"
-        className="text-primary hover:underline font-medium inline-flex items-center gap-0.5"
+        className="inline-flex items-center gap-0.5 font-medium text-primary hover:underline"
         {...props}
       >
         {children}
-        <Icon icon={ArrowUpRight01Icon} size="sm" className="inline-block text-text-tertiary ml-0.5" />
+        <Icon
+          icon={ArrowUpRight01Icon}
+          size="sm"
+          className="ml-0.5 inline-block text-text-tertiary"
+        />
       </a>
     )
   },
   ul: (props) => (
-    <ul className="list-disc pl-6 mb-4 space-y-2 text-text-primary text-sm" {...props} />
+    <ul
+      className="mb-4 list-disc space-y-2 pl-6 text-sm text-text-primary"
+      {...props}
+    />
   ),
   ol: (props) => (
-    <ol className="list-decimal pl-6 mb-4 space-y-2 text-text-primary text-sm" {...props} />
+    <ol
+      className="mb-4 list-decimal space-y-2 pl-6 text-sm text-text-primary"
+      {...props}
+    />
   ),
   li: (props) => <li {...props} />,
   hr: (props) => <hr className="my-8 border-border" {...props} />,
   img: (props) => (
-    <img className="rounded-lg border border-border my-6 max-w-full h-auto" {...props} />
+    <img
+      className="my-6 h-auto max-w-full rounded-lg border border-border"
+      {...props}
+    />
   ),
+  Tabs,
+  Tab,
+  CodeGroup,
 }
diff --git a/apps/docs/src/mdx/useTabs.ts b/apps/docs/src/mdx/useTabs.ts
new file mode 100644
index 00000000..cdd7edf5
--- /dev/null
+++ b/apps/docs/src/mdx/useTabs.ts
@@ -0,0 +1,75 @@
+"use client"
+
+import { useCallback, useEffect, useMemo, useState } from "react"
+
+const STORAGE_PREFIX = "so4-docs-tabs:"
+const CHANGE_EVENT = "so4:docs-tabs-change"
+
+interface TabsChangeDetail {
+  groupId: string
+  value: string
+}
+
+export function useTabs(groupId: string, values: string[]) {
+  const valuesKey = values.join("\u0000")
+  const stableValues = useMemo(() => values, [valuesKey])
+  const firstValue = stableValues[0] ?? ""
+  const [value, setValue] = useState(firstValue)
+
+  useEffect(() => {
+    setValue(firstValue)
+
+    try {
+      const stored = window.localStorage.getItem(`${STORAGE_PREFIX}${groupId}`)
+      if (stored && stableValues.includes(stored)) setValue(stored)
+    } catch {
+      // Storage can be disabled by privacy settings. The first tab stays active.
+    }
+
+    function handleChange(event: Event) {
+      const detail = (event as CustomEvent<TabsChangeDetail>).detail
+      if (detail.groupId === groupId && stableValues.includes(detail.value)) {
+        setValue(detail.value)
+      }
+    }
+
+    function handleStorage(event: StorageEvent) {
+      if (
+        event.key === `${STORAGE_PREFIX}${groupId}` &&
+        event.newValue &&
+        stableValues.includes(event.newValue)
+      ) {
+        setValue(event.newValue)
+      }
+    }
+
+    window.addEventListener(CHANGE_EVENT, handleChange)
+    window.addEventListener("storage", handleStorage)
+    return () => {
+      window.removeEventListener(CHANGE_EVENT, handleChange)
+      window.removeEventListener("storage", handleStorage)
+    }
+  }, [firstValue, groupId, stableValues])
+
+  const select = useCallback(
+    (nextValue: string) => {
+      if (!stableValues.includes(nextValue)) return
+      setValue(nextValue)
+
+      try {
+        window.localStorage.setItem(`${STORAGE_PREFIX}${groupId}`, nextValue)
+      } catch {
+        // The current interaction still works when persistence is unavailable.
+      }
+
+      window.dispatchEvent(
+        new CustomEvent<TabsChangeDetail>(CHANGE_EVENT, {
+          detail: { groupId, value: nextValue },
+        })
+      )
+    },
+    [groupId, stableValues]
+  )
+
+  return { value, select }
+}
diff --git a/apps/docs/src/styles/globals.css b/apps/docs/src/styles/globals.css
new file mode 100644
index 00000000..6824f52f
--- /dev/null
+++ b/apps/docs/src/styles/globals.css
@@ -0,0 +1 @@
+@import "@workspace/ui/globals.css";
diff --git a/apps/docs/vite.config.ts b/apps/docs/vite.config.ts
index a92fac58..7a339ae5 100644
--- a/apps/docs/vite.config.ts
+++ b/apps/docs/vite.config.ts
@@ -4,7 +4,6 @@ import remarkFrontmatter from "remark-frontmatter"
 import remarkMdxFrontmatter from "remark-mdx-frontmatter"
 import { shikiPlugin } from "./src/lib/rehype-shiki"
 import tailwindcss from "@tailwindcss/vite"
-import { resolve } from "node:path"
 
 export default defineConfig({
   root: import.meta.dirname,
@@ -15,12 +14,8 @@ export default defineConfig({
     }),
     tailwindcss(),
   ],
-  resolve: {
-    alias: {
-      "@workspace/ui": resolve(import.meta.dirname, "../../packages/ui/src"),
-    },
-  },
   build: {
-    outDir: ".output",
+    outDir: ".nitro-static",
+    emptyOutDir: false,
   },
 })
diff --git a/bun.lock b/bun.lock
index fdfa8aa0..4236f9e4 100644
--- a/bun.lock
+++ b/bun.lock
@@ -32,6 +32,7 @@
         "@repo/vitest-config": "workspace:*",
         "@shikijs/rehype": "^4.4.3",
         "@shikijs/transformers": "^4.4.3",
+        "@tailwindcss/vite": "^4.1.18",
         "@testing-library/react": "^16.3.2",
         "@types/bun": "^1.3.0",
         "@types/mdx": "^2.0.14",
@@ -47,6 +48,7 @@
         "remark-gfm": "^4.0.1",
         "remark-mdx-frontmatter": "^5.2.0",
         "shiki": "^4.4.3",
+        "tailwindcss": "^4.1.18",
         "typescript": "^5.9.3",
         "vite": "^7.3.2",
       },
diff --git a/scripts/check-design-tokens.ts b/scripts/check-design-tokens.ts
index 4090938f..b4f10b2b 100644
--- a/scripts/check-design-tokens.ts
+++ b/scripts/check-design-tokens.ts
@@ -24,11 +24,17 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 const ROOT = path.resolve(__dirname, "..")
 
-const SCAN_DIRS = ["apps/web/src", "packages/ui/src"]
+const SCAN_DIRS = ["apps/web/src", "apps/docs/src", "packages/ui/src"]
 const SCAN_EXTENSIONS = [".tsx", ".ts", ".css"]
 
 // Directories to skip entirely regardless of extension.
-const IGNORE_DIR_SEGMENTS = ["node_modules", "dist", "generated", ".turbo", "__fixtures__"]
+const IGNORE_DIR_SEGMENTS = [
+  "node_modules",
+  "dist",
+  "generated",
+  ".turbo",
+  "__fixtures__",
+]
 
 /**
  * Explicit, reviewed exceptions. Each entry is a relative path (from repo
@@ -65,7 +71,8 @@ const HEX_COLOR_RE = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g
 const ARBITRARY_TEXT_SIZE_RE = /(?:^|[\s"'`])(?:[a-z-]+:)*text-\[[^\]]+\]/g
 
 // Matches Tailwind arbitrary-value radius utilities: rounded-[...], rounded-t-[...], etc.
-const ARBITRARY_RADIUS_RE = /(?:^|[\s"'`])(?:[a-z-]+:)*rounded(?:-[trblse]{1,2})?-\[[^\]]+\]/g
+const ARBITRARY_RADIUS_RE =
+  /(?:^|[\s"'`])(?:[a-z-]+:)*rounded(?:-[trblse]{1,2})?-\[[^\]]+\]/g
 
 function isAllowlisted(relPath: string): string | undefined {
   for (const [prefix, reason] of Object.entries(ALLOWLIST)) {
@@ -93,7 +100,10 @@ function walk(dir: string, out: string[]): void {
     if (entry.isDirectory()) {
       if (shouldSkipDir(entry.name)) continue
       walk(path.join(dir, entry.name), out)
-    } else if (SCAN_EXTENSIONS.includes(path.extname(entry.name)) && !isTestFile(entry.name)) {
+    } else if (
+      SCAN_EXTENSIONS.includes(path.extname(entry.name)) &&
+      !isTestFile(entry.name)
+    ) {
       out.push(path.join(dir, entry.name))
     }
   }
@@ -123,7 +133,10 @@ function checkFile(absPath: string): Violation[] {
         // often wraps onto its own line(s) rather than being squeezed onto
         // the same line as the code it's explaining.
         const NEARBY_LOOKBACK = 5
-        const nearbyLines = lines.slice(Math.max(0, idx - NEARBY_LOOKBACK), idx + 1)
+        const nearbyLines = lines.slice(
+          Math.max(0, idx - NEARBY_LOOKBACK),
+          idx + 1
+        )
         if (nearbyLines.some((l) => l.includes("ds-allow:"))) continue
 
         // CSS keyword values (`rounded-[inherit]`, `text-[inherit]`, etc.)
@@ -168,11 +181,15 @@ function main(): void {
   const allViolations = files.flatMap(checkFile)
 
   if (allViolations.length === 0) {
-    console.log(`✓ Design token check passed — scanned ${files.length} files, 0 violations.`)
+    console.log(
+      `✓ Design token check passed — scanned ${files.length} files, 0 violations.`
+    )
     return
   }
 
-  console.error(`✗ Design token check failed — ${allViolations.length} violation(s):\n`)
+  console.error(
+    `✗ Design token check failed — ${allViolations.length} violation(s):\n`
+  )
   for (const v of allViolations) {
     console.error(`  ${v.file}:${v.line}:${v.column}  [${v.rule}]  ${v.value}`)
     console.error(`    ${v.context}`)
@@ -180,7 +197,7 @@ function main(): void {
   console.error(
     `\nFix by using an existing token (see packages/ui/src/styles/globals.css), or if the` +
       `\nvalue is genuinely intentional, either add a "// ds-allow: <reason>" comment on the` +
-      `\nsame line, or add the file to ALLOWLIST in scripts/check-design-tokens.ts with a reason.`,
+      `\nsame line, or add the file to ALLOWLIST in scripts/check-design-tokens.ts with a reason.`
   )
   process.exit(1)
 }

From 1b0cfc29e337d0bd2af4c5a86eb20eef830b3803 Mon Sep 17 00:00:00 2001
From: 0takuc0mrade <junep059@gmail.com>
Date: Fri, 28 Aug 2026 19:10:28 +0100
Subject: [PATCH 2/2] docs(changelog): link docs foundations PR

---
 .../{627-docs-foundations.md => 636-docs-foundations.md}        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 rename .changelog/unreleased/{627-docs-foundations.md => 636-docs-foundations.md} (95%)

diff --git a/.changelog/unreleased/627-docs-foundations.md b/.changelog/unreleased/636-docs-foundations.md
similarity index 95%
rename from .changelog/unreleased/627-docs-foundations.md
rename to .changelog/unreleased/636-docs-foundations.md
index 7078663a..3ccf1e78 100644
--- a/.changelog/unreleased/627-docs-foundations.md
+++ b/.changelog/unreleased/636-docs-foundations.md
@@ -1,7 +1,7 @@
 ---
 type: added
 area: docs
-pr: 627
+pr: 636
 breaking: false
 ---