feat(web): add /docs routes and starter MDX content

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 1chooo

apps/web/app/docs/[...slug]/page.tsx

@@ -0,0 +1,64 @@
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+import { DocsArticle } from '@/components/docs/docs-article'
+import {
+  getAdjacentDocs,
+  getDocsStaticParams,
+  loadDoc,
+} from '@/lib/docs/load'
+import { extractToc } from '@/lib/docs/toc'
+import { docsMdxComponents } from '@/lib/mdx/docs-components'
+import { renderMdx } from '@/lib/mdx/render'
+
+export function generateStaticParams() {
+  return getDocsStaticParams()
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>
+}): Promise<Metadata> {
+  const { slug: slugParts } = await params
+  const slug = slugParts.join('/')
+  const doc = loadDoc(slug)
+  if (!doc) return { title: 'Not found — Tawny' }
+
+  return {
+    title: `${doc.title} — Tawny`,
+    description: doc.description,
+  }
+}
+
+export default async function DocsSlugPage({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>
+}) {
+  const { slug: slugParts } = await params
+  const slug = slugParts.join('/')
+  const doc = loadDoc(slug)
+  if (!doc) notFound()
+
+  const { content, error } = await renderMdx(doc.body, docsMdxComponents)
+  if (error) {
+    console.error('Docs MDX render failed:', error)
+    notFound()
+  }
+
+  const { prev, next } = getAdjacentDocs(slug)
+  const toc = extractToc(doc.body)
+
+  return (
+    <DocsArticle
+      breadcrumbs={[
+        { label: 'Docs', href: '/docs' },
+        { label: doc.title },
+      ]}
+      toc={toc}
+      content={content}
+      prev={prev}
+      next={next}
+    />
+  )
+}

apps/web/app/docs/layout.tsx

@@ -0,0 +1,14 @@
+import { DocsShell } from '@/components/docs/docs-shell'
+import { getDocsSidebar } from '@/lib/docs/load'
+import { getDocsSearchIndex } from '@/lib/docs/search'
+
+export default function DocsLayout({ children }: { children: React.ReactNode }) {
+  const groups = getDocsSidebar()
+  const searchEntries = getDocsSearchIndex()
+
+  return (
+    <DocsShell groups={groups} searchEntries={searchEntries}>
+      {children}
+    </DocsShell>
+  )
+}

apps/web/app/docs/page.tsx

@@ -0,0 +1,44 @@
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+import { DocsArticle } from '@/components/docs/docs-article'
+import { getAdjacentDocs, loadDoc } from '@/lib/docs/load'
+import { extractToc } from '@/lib/docs/toc'
+import { docsMdxComponents } from '@/lib/mdx/docs-components'
+import { renderMdx } from '@/lib/mdx/render'
+
+export async function generateMetadata(): Promise<Metadata> {
+  const doc = loadDoc('')
+  if (!doc) return { title: 'Docs — Tawny' }
+
+  return {
+    title: `${doc.title} — Tawny`,
+    description: doc.description,
+  }
+}
+
+export default async function DocsIndexPage() {
+  const doc = loadDoc('')
+  if (!doc) notFound()
+
+  const { content, error } = await renderMdx(doc.body, docsMdxComponents)
+  if (error) {
+    console.error('Docs MDX render failed:', error)
+    notFound()
+  }
+
+  const { prev, next } = getAdjacentDocs('')
+  const toc = extractToc(doc.body)
+
+  return (
+    <DocsArticle
+      breadcrumbs={[
+        { label: 'Docs', href: '/docs' },
+        { label: doc.title },
+      ]}
+      toc={toc}
+      content={content}
+      prev={prev}
+      next={next}
+    />
+  )
+}

apps/web/content/docs/components/overview.mdx

@@ -0,0 +1,46 @@
+---
+title: Components overview
+description: Browse Tawny UI components and copy source from the gallery.
+---
+
+# Components overview
+
+The components gallery demos navigation patterns and motion primitives from `@tawny/ui` and the marketing site.
+
+## Browse the gallery
+
+Open [/components](/components) to preview live demos. Each card links to a detail page where you can copy source.
+
+## What is included
+
+Typical building blocks:
+
+- Header / navigation demos (Tawny, Art, Dev)
+- Motion primitives (`BlurFade`, `BorderBeam`, `ShimmerButton`, …)
+- Shared utilities via `@tawny/ui`
+
+```tsx
+import { BlurFade } from '@tawny/ui/components/blur-fade'
+import { NoiseTexture } from '@tawny/ui/components/noise-texture'
+
+export function Example() {
+  return (
+    <div className="relative">
+      <NoiseTexture opacity={0.025} />
+      <BlurFade delay={0.05}>
+        <h1>Hello from Tawny</h1>
+      </BlurFade>
+    </div>
+  )
+}
+```
+
+<Callout type="tip" title="Tip">
+  Pair components with a full design — scaffold Art or Dev, then reuse primitives from `@tawny/ui` where it fits.
+</Callout>
+
+## Next steps
+
+- [Getting started](/docs/getting-started)
+- [create-tawny](/docs/create-tawny)
+- [Designs overview](/docs/designs/overview)

apps/web/content/docs/create-tawny.mdx

@@ -0,0 +1,44 @@
+---
+title: create-tawny
+description: Scaffold an Art or Dev project with the create-tawny CLI.
+---
+
+# create-tawny
+
+Use the CLI to generate a new Next.js app from a Tawny template.
+
+## Quick start
+
+```bash
+npx create-tawny@latest
+```
+
+Or pick a template and project name up front:
+
+```bash
+npx create-tawny@latest art my-site
+npx create-tawny@latest dev my-blog
+```
+
+## Package managers
+
+```bash
+pnpm create tawny@latest art my-site
+yarn create tawny art my-site
+bunx create-tawny@latest art my-site
+```
+
+## After scaffolding
+
+1. `cd` into the project directory.
+2. Install dependencies if the CLI did not already.
+3. Run the local Next.js dev server and open the app.
+
+<Callout type="tip" title="Tip">
+  Preview the same templates live on the site before you scaffold: [Art](/designs/art) and [Dev](/designs/dev).
+</Callout>
+
+## Next steps
+
+- [Designs overview](/docs/designs/overview) — what each template includes
+- [Components overview](/docs/components/overview) — reusable UI primitives

apps/web/content/docs/designs/overview.mdx

@@ -0,0 +1,35 @@
+---
+title: Designs overview
+description: Explore the Art and Dev design templates in Tawny.
+---
+
+# Designs overview
+
+Tawny designs are full-site templates you can preview in-product or open as edge-to-edge demos.
+
+## Available designs
+
+### Art
+
+A bilingual bento journal with notes, projects, and location pages. Locale-aware routing (`en` / `zh`) and rich MDX shortcodes.
+
+- Live showcase: [/designs/art](/designs/art)
+- Full preview: [/view/art](/view/art)
+
+### Dev
+
+A mono developer blog with projects and technical posts. English-only, terminal-inspired chrome.
+
+- Live showcase: [/designs/dev](/designs/dev)
+- Full preview: [/view/dev](/view/dev)
+
+## Showcase vs preview
+
+| Path | Chrome | Use when |
+| --- | --- | --- |
+| `/designs/<id>` | Tawny navbar + product frame | Comparing templates in context |
+| `/view/<id>` | None | Reviewing the design as a standalone site |
+
+<Callout type="note" title="Note">
+  Scaffold either template with [create-tawny](/docs/create-tawny) — the CLI copies from the matching `templates/` package.
+</Callout>

apps/web/content/docs/getting-started.mdx

@@ -0,0 +1,30 @@
+---
+title: Getting started
+description: Learn how Tawny designs, components, and scaffolding fit together.
+---
+
+# Getting started
+
+Tawny is a collection of production-ready web designs and UI components for Next.js. Use the marketing site to preview, then scaffold a full project with `create-tawny`.
+
+## How it fits together
+
+1. **Browse** live demos under [Designs](/designs) and [Components](/components).
+2. **Scaffold** a project with [create-tawny](/docs/create-tawny).
+3. **Customize** the generated Next.js app — Tailwind v4, TypeScript, and shadcn-style primitives are already wired.
+
+## What you get
+
+| Surface | What it is |
+| --- | --- |
+| Designs | Full-site templates (Art, Dev) you can preview and scaffold |
+| Components | Navigation patterns and motion primitives with copyable source |
+| CLI | `create-tawny` to generate a starter from a template |
+
+<Callout type="note" title="Note">
+  Design showcases under `/designs` keep Tawny chrome. Full-site previews live under `/view` without the marketing navbar.
+</Callout>
+
+## Next steps
+
+Continue with [create-tawny](/docs/create-tawny) to scaffold your first project.

apps/web/content/docs/index.mdx

@@ -0,0 +1,23 @@
+---
+title: Documentation
+description: Guides for using Tawny designs, components, and the create-tawny CLI.
+---
+
+# Documentation
+
+Welcome to the Tawny docs. These pages help you scaffold a project, explore live designs, and reuse UI building blocks.
+
+## Start here
+
+- [Getting started](/docs/getting-started) — how Tawny fits together
+- [create-tawny](/docs/create-tawny) — scaffold Art or Dev from the CLI
+- [Designs overview](/docs/designs/overview) — Art and Dev showcases
+- [Components overview](/docs/components/overview) — headers and motion primitives
+
+## What you can do
+
+Tawny ships handcrafted web designs and UI components you can preview on the site and scaffold into a new Next.js app.
+
+<Callout type="tip" title="Tip">
+  Prefer learning by example? Open the live [Designs](/designs) and [Components](/components) galleries alongside these docs.
+</Callout>