From 56e91e1f7c2d46b4c8ef11705fed22e2734f641e Mon Sep 17 00:00:00 2001
From: Guido X Jansen <x@gui.do>
Date: Sat, 14 Feb 2026 10:50:39 +0100
Subject: [PATCH] feat(web): Homepage + Category Pages (Phase 4 M4) (#5)

* feat(web): add homepage and category pages (Phase 4 M4)

Implement the first real forum pages with full component library:

- API client with TypeScript types matching barazo-api schemas
- MSW mock handlers for testing (Tier 3 hand-written)
- ForumLayout with header, sidebar, footer, skip links
- Pagination component (WCAG 2.2 AA, aria-current)
- Breadcrumbs with JSON-LD BreadcrumbList structured data
- TopicCard/TopicList components with reply/reaction counts
- CategoryNav with hierarchical tree display
- Homepage (/) with recent topics, category sidebar, JSON-LD WebSite
- Category page (/c/[slug]) with filtered topics, breadcrumbs
- FocusOnNavigate hook for client-side route transitions
- Switch from static export to standalone SSR output
- 62 tests passing across 10 test files with axe a11y checks

* fix(ci): update accessibility audit for standalone output

- Add try-catch error handling to homepage for API unavailability
- Update CI workflow to use standalone server instead of static serve
- Fix build artifact paths for standalone output
- Use polling wait instead of fixed sleep for server readiness

* fix(a11y): add underline to footer link for link-in-text-block rule

Links within text blocks must be visually distinguished from
surrounding text using more than just color (WCAG 2.2 AA).
---
 .github/workflows/ci.yml                    |  22 +-
 next.config.ts                              |  19 +-
 src/app/c/[slug]/page.test.tsx              | 101 +++++++++
 src/app/c/[slug]/page.tsx                   | 103 ++++++++++
 src/app/page.test.tsx                       |  86 ++++++++
 src/app/page.tsx                            | 214 ++++++++------------
 src/components/breadcrumbs.test.tsx         |  57 ++++++
 src/components/breadcrumbs.tsx              |  66 ++++++
 src/components/category-nav.test.tsx        |  43 ++++
 src/components/category-nav.tsx             |  82 ++++++++
 src/components/layout/forum-layout.test.tsx |  99 +++++++++
 src/components/layout/forum-layout.tsx      | 123 +++++++++++
 src/components/pagination.test.tsx          |  52 +++++
 src/components/pagination.tsx               | 135 ++++++++++++
 src/components/topic-card.test.tsx          |  46 +++++
 src/components/topic-card.tsx               |  87 ++++++++
 src/components/topic-list.test.tsx          |  29 +++
 src/components/topic-list.tsx               |  34 ++++
 src/hooks/use-focus-on-navigate.ts          |  28 +++
 src/lib/api/client.test.ts                  |  83 ++++++++
 src/lib/api/client.ts                       | 132 ++++++++++++
 src/lib/api/types.ts                        | 181 +++++++++++++++++
 src/lib/format.ts                           |  39 ++++
 src/mocks/data.ts                           | 200 ++++++++++++++++++
 src/mocks/handlers.ts                       |  68 +++++++
 src/mocks/server.ts                         |   8 +
 src/test/setup.ts                           |  12 +-
 src/test/vitest-axe.d.ts                    |   9 +
 tsconfig.json                               |   1 +
 29 files changed, 2018 insertions(+), 141 deletions(-)
 create mode 100644 src/app/c/[slug]/page.test.tsx
 create mode 100644 src/app/c/[slug]/page.tsx
 create mode 100644 src/app/page.test.tsx
 create mode 100644 src/components/breadcrumbs.test.tsx
 create mode 100644 src/components/breadcrumbs.tsx
 create mode 100644 src/components/category-nav.test.tsx
 create mode 100644 src/components/category-nav.tsx
 create mode 100644 src/components/layout/forum-layout.test.tsx
 create mode 100644 src/components/layout/forum-layout.tsx
 create mode 100644 src/components/pagination.test.tsx
 create mode 100644 src/components/pagination.tsx
 create mode 100644 src/components/topic-card.test.tsx
 create mode 100644 src/components/topic-card.tsx
 create mode 100644 src/components/topic-list.test.tsx
 create mode 100644 src/components/topic-list.tsx
 create mode 100644 src/hooks/use-focus-on-navigate.ts
 create mode 100644 src/lib/api/client.test.ts
 create mode 100644 src/lib/api/client.ts
 create mode 100644 src/lib/api/types.ts
 create mode 100644 src/lib/format.ts
 create mode 100644 src/mocks/data.ts
 create mode 100644 src/mocks/handlers.ts
 create mode 100644 src/mocks/server.ts
 create mode 100644 src/test/vitest-axe.d.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 71026e9..9cfb1e2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -115,7 +115,9 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: build
-          path: dist/
+          path: |
+            .next/standalone/
+            .next/static/
           retention-days: 7
 
   accessibility:
@@ -143,17 +145,29 @@ jobs:
       - name: Build application
         run: pnpm build
 
+      - name: Prepare standalone server
+        run: |
+          cp -r .next/static .next/standalone/.next/static
+          cp -r public .next/standalone/public
+
       - name: Install axe-core CLI
         run: pnpm add -g @axe-core/cli
 
       - name: Sync Chrome and ChromeDriver versions
         run: npx browser-driver-manager install chrome
 
-      - name: Serve build
-        run: npx serve dist -l 3000 &
+      - name: Start standalone server
+        run: node .next/standalone/server.js &
+        env:
+          PORT: '3000'
+          HOSTNAME: '0.0.0.0'
 
       - name: Wait for server
-        run: sleep 5
+        run: |
+          for i in $(seq 1 30); do
+            curl -s http://localhost:3000 > /dev/null 2>&1 && break
+            sleep 1
+          done
 
       - name: Run axe accessibility check
         run: axe http://localhost:3000 --exit
diff --git a/next.config.ts b/next.config.ts
index 404e929..0001eb1 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -2,16 +2,25 @@ import type { NextConfig } from 'next'
 
 /**
  * Next.js Configuration for Barazo Web
+ * Uses standalone output for Docker deployment with SSR.
  * @see https://nextjs.org/docs/api-reference/next.config.js/introduction
  */
 const nextConfig: NextConfig = {
-  // Static export for Docker deployment
-  output: 'export',
-  distDir: 'dist',
+  // Standalone output for Docker (includes Node.js server)
+  output: 'standalone',
 
-  // Image optimization (static export requires unoptimized images)
+  // Image optimization
   images: {
-    unoptimized: true,
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: '*.bsky.social',
+      },
+      {
+        protocol: 'https',
+        hostname: 'cdn.bsky.app',
+      },
+    ],
   },
 
   // Trailing slashes for SEO consistency
diff --git a/src/app/c/[slug]/page.test.tsx b/src/app/c/[slug]/page.test.tsx
new file mode 100644
index 0000000..3d63d9d
--- /dev/null
+++ b/src/app/c/[slug]/page.test.tsx
@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+
+// Mock API client
+vi.mock('@/lib/api/client', () => ({
+  getCategoryBySlug: vi.fn(),
+  getCategories: vi.fn(),
+  getTopics: vi.fn(),
+}))
+
+// Mock next-themes
+vi.mock('next-themes', () => ({
+  useTheme: () => ({ theme: 'dark', setTheme: vi.fn() }),
+  ThemeProvider: ({ children }: { children: React.ReactNode }) => children,
+}))
+
+// Mock next/image
+vi.mock('next/image', () => ({
+  default: (props: Record<string, unknown>) => {
+    // eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text
+    return <img {...props} />
+  },
+}))
+
+// Mock next/link
+vi.mock('next/link', () => ({
+  default: ({
+    children,
+    href,
+    ...props
+  }: { children: React.ReactNode; href: string } & Record<string, unknown>) => (
+    <a href={href} {...props}>
+      {children}
+    </a>
+  ),
+}))
+
+import { getCategoryBySlug, getCategories, getTopics } from '@/lib/api/client'
+import { mockCategories, mockCategoryWithTopicCount, mockTopics } from '@/mocks/data'
+import CategoryPage from './page'
+
+const mockGetCategoryBySlug = vi.mocked(getCategoryBySlug)
+const mockGetCategories = vi.mocked(getCategories)
+const mockGetTopics = vi.mocked(getTopics)
+
+beforeEach(() => {
+  mockGetCategoryBySlug.mockResolvedValue(mockCategoryWithTopicCount)
+  mockGetCategories.mockResolvedValue({ categories: mockCategories })
+  mockGetTopics.mockResolvedValue({
+    topics: mockTopics.filter((t) => t.category === 'general'),
+    cursor: null,
+  })
+})
+
+const params = Promise.resolve({ slug: 'general' })
+
+describe('CategoryPage', () => {
+  it('renders category name as heading', async () => {
+    const page = await CategoryPage({ params })
+    render(page)
+    expect(
+      screen.getByRole('heading', { level: 1, name: mockCategoryWithTopicCount.name })
+    ).toBeInTheDocument()
+  })
+
+  it('renders category description', async () => {
+    const page = await CategoryPage({ params })
+    render(page)
+    expect(screen.getByText(mockCategoryWithTopicCount.description!)).toBeInTheDocument()
+  })
+
+  it('renders breadcrumbs', async () => {
+    const page = await CategoryPage({ params })
+    render(page)
+    expect(screen.getByRole('navigation', { name: /breadcrumb/i })).toBeInTheDocument()
+  })
+
+  it('renders topic list for category', async () => {
+    const page = await CategoryPage({ params })
+    render(page)
+    const articles = screen.getAllByRole('article')
+    expect(articles.length).toBeGreaterThan(0)
+  })
+
+  it('renders topic count', async () => {
+    const page = await CategoryPage({ params })
+    render(page)
+    expect(screen.getByText(`${mockCategoryWithTopicCount.topicCount} topics`)).toBeInTheDocument()
+  })
+
+  it('includes JSON-LD BreadcrumbList', async () => {
+    const page = await CategoryPage({ params })
+    const { container } = render(page)
+    const scripts = container.querySelectorAll('script[type="application/ld+json"]')
+    const breadcrumbScript = Array.from(scripts).find((s) => {
+      const data = JSON.parse(s.textContent!)
+      return data['@type'] === 'BreadcrumbList'
+    })
+    expect(breadcrumbScript).toBeTruthy()
+  })
+})
diff --git a/src/app/c/[slug]/page.tsx b/src/app/c/[slug]/page.tsx
new file mode 100644
index 0000000..8947258
--- /dev/null
+++ b/src/app/c/[slug]/page.tsx
@@ -0,0 +1,103 @@
+/**
+ * Category page - Shows topics for a specific category.
+ * URL: /c/{slug}
+ * Server-side rendered with SEO metadata and JSON-LD.
+ * @see specs/prd-web.md Section 3.1
+ */
+
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+import { getCategoryBySlug, getCategories, getTopics, ApiError } from '@/lib/api/client'
+
+export const dynamic = 'force-dynamic'
+import { ForumLayout } from '@/components/layout/forum-layout'
+import { TopicList } from '@/components/topic-list'
+import { CategoryNav } from '@/components/category-nav'
+import { Breadcrumbs } from '@/components/breadcrumbs'
+import { Pagination } from '@/components/pagination'
+
+interface CategoryPageProps {
+  params: Promise<{ slug: string }>
+  searchParams?: Promise<{ page?: string }>
+}
+
+export async function generateMetadata({ params }: CategoryPageProps): Promise<Metadata> {
+  const { slug } = await params
+  try {
+    const category = await getCategoryBySlug(slug)
+    return {
+      title: category.name,
+      description: category.description ?? `Topics in ${category.name}`,
+      openGraph: {
+        title: category.name,
+        description: category.description ?? `Topics in ${category.name}`,
+        type: 'website',
+      },
+    }
+  } catch {
+    return { title: 'Category Not Found' }
+  }
+}
+
+const TOPICS_PER_PAGE = 20
+
+export default async function CategoryPage({ params, searchParams }: CategoryPageProps) {
+  const { slug } = await params
+  const resolvedSearchParams = searchParams ? await searchParams : {}
+  const page = Math.max(1, parseInt(resolvedSearchParams.page ?? '1', 10) || 1)
+
+  let category
+  try {
+    category = await getCategoryBySlug(slug)
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      notFound()
+    }
+    throw error
+  }
+
+  const [categoriesResult, topicsResult] = await Promise.all([
+    getCategories(),
+    getTopics({
+      category: slug,
+      limit: TOPICS_PER_PAGE,
+    }),
+  ])
+
+  const totalPages = Math.max(1, Math.ceil(category.topicCount / TOPICS_PER_PAGE))
+
+  const breadcrumbItems = [
+    { label: 'Home', href: '/' },
+    { label: category.name, href: `/c/${slug}` },
+  ]
+
+  return (
+    <ForumLayout
+      sidebar={<CategoryNav categories={categoriesResult.categories} currentSlug={slug} />}
+    >
+      {/* Breadcrumbs (includes JSON-LD BreadcrumbList) */}
+      <Breadcrumbs items={breadcrumbItems} />
+
+      {/* Category header */}
+      <div className="mb-6">
+        <h1 className="text-2xl font-bold text-foreground">{category.name}</h1>
+        {category.description && (
+          <p className="mt-1 text-muted-foreground">{category.description}</p>
+        )}
+        <p className="mt-2 text-sm text-muted-foreground">
+          {category.topicCount} {category.topicCount === 1 ? 'topic' : 'topics'}
+        </p>
+      </div>
+
+      {/* Topic list */}
+      <TopicList topics={topicsResult.topics} />
+
+      {/* Pagination */}
+      {totalPages > 1 && (
+        <div className="mt-6">
+          <Pagination currentPage={page} totalPages={totalPages} baseUrl={`/c/${slug}`} />
+        </div>
+      )}
+    </ForumLayout>
+  )
+}
diff --git a/src/app/page.test.tsx b/src/app/page.test.tsx
new file mode 100644
index 0000000..048372b
--- /dev/null
+++ b/src/app/page.test.tsx
@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+
+// Mock API client
+vi.mock('@/lib/api/client', () => ({
+  getCategories: vi.fn(),
+  getTopics: vi.fn(),
+}))
+
+// Mock next-themes
+vi.mock('next-themes', () => ({
+  useTheme: () => ({ theme: 'dark', setTheme: vi.fn() }),
+  ThemeProvider: ({ children }: { children: React.ReactNode }) => children,
+}))
+
+// Mock next/image
+vi.mock('next/image', () => ({
+  default: (props: Record<string, unknown>) => {
+    // eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text
+    return <img {...props} />
+  },
+}))
+
+// Mock next/link
+vi.mock('next/link', () => ({
+  default: ({
+    children,
+    href,
+    ...props
+  }: { children: React.ReactNode; href: string } & Record<string, unknown>) => (
+    <a href={href} {...props}>
+      {children}
+    </a>
+  ),
+}))
+
+import { getCategories, getTopics } from '@/lib/api/client'
+import { mockCategories, mockTopics } from '@/mocks/data'
+import HomePage from './page'
+
+const mockGetCategories = vi.mocked(getCategories)
+const mockGetTopics = vi.mocked(getTopics)
+
+beforeEach(() => {
+  mockGetCategories.mockResolvedValue({ categories: mockCategories })
+  mockGetTopics.mockResolvedValue({ topics: mockTopics, cursor: null })
+})
+
+describe('HomePage', () => {
+  it('renders page heading', async () => {
+    const page = await HomePage()
+    render(page)
+    expect(screen.getByRole('heading', { level: 1 })).toBeInTheDocument()
+  })
+
+  it('renders recent topics', async () => {
+    const page = await HomePage()
+    render(page)
+    expect(screen.getByText('Welcome to Barazo Forums')).toBeInTheDocument()
+  })
+
+  it('renders category navigation', async () => {
+    const page = await HomePage()
+    render(page)
+    const navs = screen.getAllByRole('navigation', { name: /categories/i })
+    expect(navs.length).toBeGreaterThan(0)
+  })
+
+  it('renders category links', async () => {
+    const page = await HomePage()
+    render(page)
+    const generalLinks = screen.getAllByRole('link', { name: 'General Discussion' })
+    expect(generalLinks.length).toBeGreaterThan(0)
+    const devLinks = screen.getAllByRole('link', { name: 'Development' })
+    expect(devLinks.length).toBeGreaterThan(0)
+  })
+
+  it('renders JSON-LD structured data', async () => {
+    const page = await HomePage()
+    const { container } = render(page)
+    const script = container.querySelector('script[type="application/ld+json"]')
+    expect(script).toBeInTheDocument()
+    const jsonLd = JSON.parse(script!.textContent!)
+    expect(jsonLd['@type']).toBe('WebSite')
+  })
+})
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 9795e85..192554e 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,143 +1,95 @@
-import { SkipLinks } from '@/components/skip-links'
-import { ThemeToggle } from '@/components/theme-toggle'
-import Image from 'next/image'
+/**
+ * Homepage - Forum landing page.
+ * Shows recent topics, category sidebar, and community overview.
+ * Server-side rendered for SEO.
+ * @see specs/prd-web.md Section 3.1
+ */
 
-export default function Home() {
-  return (
-    <div className="min-h-screen bg-background">
-      <SkipLinks />
+import type { Metadata } from 'next'
+import { getCategories, getTopics } from '@/lib/api/client'
+import { ForumLayout } from '@/components/layout/forum-layout'
+import { TopicList } from '@/components/topic-list'
+import { CategoryNav } from '@/components/category-nav'
+import type { CategoriesResponse, TopicsResponse } from '@/lib/api/types'
 
-      {/* Header */}
-      <header className="sticky top-0 z-40 w-full border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
-        <div className="container flex h-14 items-center justify-between">
-          <div className="flex items-center gap-2">
-            <Image
-              src="/barazo-logo-light.svg"
-              alt="Barazo"
-              width={120}
-              height={32}
-              className="h-8 w-auto dark:hidden"
-              priority
-            />
-            <Image
-              src="/barazo-logo-dark.svg"
-              alt="Barazo"
-              width={120}
-              height={32}
-              className="hidden h-8 w-auto dark:block"
-              priority
-            />
-          </div>
-          <div className="flex items-center gap-4">
-            <ThemeToggle />
-          </div>
-        </div>
-      </header>
+export const dynamic = 'force-dynamic'
 
-      {/* Main Content */}
-      <main id="main-content" className="container py-8" tabIndex={-1}>
-        <section className="mx-auto max-w-3xl space-y-8">
-          <div className="space-y-4 text-center">
-            <h1 className="text-4xl font-bold tracking-tight text-foreground sm:text-5xl">
-              Community Forums on the <span className="text-primary">AT Protocol</span>
-            </h1>
-            <p className="mx-auto max-w-2xl text-lg text-muted-foreground">
-              Portable identity. User data ownership. Cross-community reputation. The forum platform
-              built for the decentralized web.
-            </p>
-          </div>
+export const metadata: Metadata = {
+  title: 'Barazo - Community Forums on the AT Protocol',
+  description:
+    'Federated community forums with portable identity, user data ownership, and cross-community reputation.',
+}
 
-          {/* Design System Demo */}
-          <div className="grid gap-6 rounded-lg border border-border bg-card p-6">
-            <h2 className="text-2xl font-semibold text-card-foreground">Design System Active</h2>
+export default async function HomePage() {
+  let categoriesResult: CategoriesResponse = { categories: [] }
+  let topicsResult: TopicsResponse = { topics: [], cursor: null }
+  let apiError = false
 
-            {/* Color Palette Demo */}
-            <div className="space-y-3">
-              <h3 className="text-sm font-medium text-muted-foreground">
-                Color Palette (Radix Colors + Flexoki)
-              </h3>
-              <div className="flex flex-wrap gap-2">
-                <div className="flex items-center gap-2">
-                  <div className="h-8 w-8 rounded bg-primary" />
-                  <span className="text-xs text-muted-foreground">Primary</span>
-                </div>
-                <div className="flex items-center gap-2">
-                  <div className="h-8 w-8 rounded bg-secondary" />
-                  <span className="text-xs text-muted-foreground">Secondary</span>
-                </div>
-                <div className="flex items-center gap-2">
-                  <div className="h-8 w-8 rounded bg-success" />
-                  <span className="text-xs text-muted-foreground">Success</span>
-                </div>
-                <div className="flex items-center gap-2">
-                  <div className="h-8 w-8 rounded bg-warning" />
-                  <span className="text-xs text-muted-foreground">Warning</span>
-                </div>
-                <div className="flex items-center gap-2">
-                  <div className="h-8 w-8 rounded bg-destructive" />
-                  <span className="text-xs text-muted-foreground">Error</span>
-                </div>
-              </div>
-            </div>
+  try {
+    ;[categoriesResult, topicsResult] = await Promise.all([
+      getCategories(),
+      getTopics({ limit: 20, sort: 'latest' }),
+    ])
+  } catch {
+    apiError = true
+  }
 
-            {/* Typography Demo */}
-            <div className="space-y-3">
-              <h3 className="text-sm font-medium text-muted-foreground">
-                Typography (Source Sans 3)
-              </h3>
-              <div className="space-y-1">
-                <p className="text-2xl font-bold">Heading 2XL - Bold</p>
-                <p className="text-xl font-semibold">Heading XL - Semibold</p>
-                <p className="text-lg font-medium">Heading LG - Medium</p>
-                <p className="text-base">Body text - Regular</p>
-                <p className="text-sm text-muted-foreground">Small text - Muted</p>
-              </div>
-            </div>
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    name: 'Barazo',
+    url: 'https://barazo.forum',
+    potentialAction: {
+      '@type': 'SearchAction',
+      target: {
+        '@type': 'EntryPoint',
+        urlTemplate: 'https://barazo.forum/search?q={search_term_string}',
+      },
+      'query-input': 'required name=search_term_string',
+    },
+  }
 
-            {/* Code Font Demo */}
-            <div className="space-y-3">
-              <h3 className="text-sm font-medium text-muted-foreground">
-                Monospace (Source Code Pro)
-              </h3>
-              <code className="rounded bg-input px-2 py-1 font-mono text-sm">
-                const barazo = &quot;AT Protocol Forum&quot;;
-              </code>
-            </div>
+  return (
+    <ForumLayout
+      sidebar={
+        categoriesResult.categories.length > 0 ? (
+          <CategoryNav categories={categoriesResult.categories} />
+        ) : undefined
+      }
+    >
+      {/* JSON-LD */}
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
 
-            {/* Button Variants */}
-            <div className="space-y-3">
-              <h3 className="text-sm font-medium text-muted-foreground">Button Styles</h3>
-              <div className="flex flex-wrap gap-3">
-                <button className="inline-flex h-10 items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-sm transition-colors hover:bg-primary-hover focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
-                  Primary Button
-                </button>
-                <button className="inline-flex h-10 items-center justify-center rounded-md bg-secondary px-4 py-2 text-sm font-medium text-secondary-foreground shadow-sm transition-colors hover:bg-secondary-hover focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
-                  Secondary Button
-                </button>
-                <button className="inline-flex h-10 items-center justify-center rounded-md border border-border bg-card px-4 py-2 text-sm font-medium text-card-foreground shadow-sm transition-colors hover:bg-card-hover focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
-                  Outline Button
-                </button>
-                <button className="inline-flex h-10 items-center justify-center rounded-md bg-destructive px-4 py-2 text-sm font-medium text-destructive-foreground shadow-sm transition-colors hover:bg-destructive-hover focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
-                  Destructive
-                </button>
-              </div>
+      {/* Welcome / Stats */}
+      <div className="mb-6">
+        <h1 className="text-2xl font-bold text-foreground">Welcome to the Community</h1>
+        <p className="mt-1 text-muted-foreground">
+          Discussions powered by the AT Protocol. Your identity, your data.
+        </p>
+      </div>
+
+      {apiError ? (
+        <div className="rounded-lg border border-border bg-card p-8 text-center">
+          <p className="text-muted-foreground">
+            Unable to connect to the forum API. Please try again later.
+          </p>
+        </div>
+      ) : (
+        <>
+          {/* Category cards (mobile) */}
+          {categoriesResult.categories.length > 0 && (
+            <div className="mb-6 lg:hidden">
+              <CategoryNav categories={categoriesResult.categories} />
             </div>
-          </div>
+          )}
 
-          {/* Footer */}
-          <footer className="text-center text-sm text-muted-foreground">
-            <p>
-              Powered by Barazo v0.1.0 |{' '}
-              <a
-                href="https://github.com/barazo-forum"
-                className="text-primary underline hover:text-primary-hover"
-              >
-                GitHub
-              </a>
-            </p>
-          </footer>
-        </section>
-      </main>
-    </div>
+          {/* Recent Topics */}
+          <TopicList topics={topicsResult.topics} heading="Recent Topics" />
+        </>
+      )}
+    </ForumLayout>
   )
 }
diff --git a/src/components/breadcrumbs.test.tsx b/src/components/breadcrumbs.test.tsx
new file mode 100644
index 0000000..cbea09e
--- /dev/null
+++ b/src/components/breadcrumbs.test.tsx
@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'vitest-axe'
+import { Breadcrumbs } from './breadcrumbs'
+
+describe('Breadcrumbs', () => {
+  const items = [
+    { label: 'Home', href: '/' },
+    { label: 'Development', href: '/c/development' },
+    { label: 'Frontend', href: '/c/development/frontend' },
+  ]
+
+  it('renders all breadcrumb items', () => {
+    render(<Breadcrumbs items={items} />)
+    expect(screen.getByText('Home')).toBeInTheDocument()
+    expect(screen.getByText('Development')).toBeInTheDocument()
+    expect(screen.getByText('Frontend')).toBeInTheDocument()
+  })
+
+  it('renders links for non-current items', () => {
+    render(<Breadcrumbs items={items} />)
+    const homeLink = screen.getByRole('link', { name: 'Home' })
+    expect(homeLink).toHaveAttribute('href', '/')
+  })
+
+  it('marks last item as current page', () => {
+    render(<Breadcrumbs items={items} />)
+    const current = screen.getByText('Frontend')
+    expect(current).toHaveAttribute('aria-current', 'page')
+  })
+
+  it('has accessible navigation landmark', () => {
+    render(<Breadcrumbs items={items} />)
+    expect(screen.getByRole('navigation', { name: /breadcrumb/i })).toBeInTheDocument()
+  })
+
+  it('renders separator between items', () => {
+    render(<Breadcrumbs items={items} />)
+    const separators = screen.getAllByText('/')
+    expect(separators).toHaveLength(2)
+  })
+
+  it('includes JSON-LD structured data', () => {
+    const { container } = render(<Breadcrumbs items={items} />)
+    const script = container.querySelector('script[type="application/ld+json"]')
+    expect(script).toBeInTheDocument()
+    const jsonLd = JSON.parse(script!.textContent!)
+    expect(jsonLd['@type']).toBe('BreadcrumbList')
+    expect(jsonLd.itemListElement).toHaveLength(3)
+  })
+
+  it('passes axe accessibility check', async () => {
+    const { container } = render(<Breadcrumbs items={items} />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
diff --git a/src/components/breadcrumbs.tsx b/src/components/breadcrumbs.tsx
new file mode 100644
index 0000000..30f8ad1
--- /dev/null
+++ b/src/components/breadcrumbs.tsx
@@ -0,0 +1,66 @@
+/**
+ * Breadcrumbs component with JSON-LD structured data.
+ * WCAG 2.2 AA: nav landmark, aria-current, semantic list.
+ * @see https://schema.org/BreadcrumbList
+ */
+
+import Link from 'next/link'
+
+export interface BreadcrumbItem {
+  label: string
+  href: string
+}
+
+interface BreadcrumbsProps {
+  items: BreadcrumbItem[]
+}
+
+export function Breadcrumbs({ items }: BreadcrumbsProps) {
+  if (items.length === 0) return null
+
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: item.label,
+      item: `https://barazo.forum${item.href}`,
+    })),
+  }
+
+  return (
+    <nav aria-label="Breadcrumb" className="mb-4">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <ol className="flex items-center gap-1 text-sm text-muted-foreground">
+        {items.map((item, index) => {
+          const isLast = index === items.length - 1
+          return (
+            <li key={item.href} className="flex items-center gap-1">
+              {index > 0 && (
+                <span aria-hidden="true" className="text-muted-foreground">
+                  /
+                </span>
+              )}
+              {isLast ? (
+                <span aria-current="page" className="font-medium text-foreground">
+                  {item.label}
+                </span>
+              ) : (
+                <Link
+                  href={item.href}
+                  className="transition-colors hover:text-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 rounded-sm px-1"
+                >
+                  {item.label}
+                </Link>
+              )}
+            </li>
+          )
+        })}
+      </ol>
+    </nav>
+  )
+}
diff --git a/src/components/category-nav.test.tsx b/src/components/category-nav.test.tsx
new file mode 100644
index 0000000..c4e9fac
--- /dev/null
+++ b/src/components/category-nav.test.tsx
@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'vitest-axe'
+import { CategoryNav } from './category-nav'
+import { mockCategories } from '@/mocks/data'
+
+describe('CategoryNav', () => {
+  it('renders navigation landmark', () => {
+    render(<CategoryNav categories={mockCategories} />)
+    expect(screen.getByRole('navigation', { name: /categories/i })).toBeInTheDocument()
+  })
+
+  it('renders top-level categories', () => {
+    render(<CategoryNav categories={mockCategories} />)
+    expect(screen.getByRole('link', { name: 'General Discussion' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Development' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: /feedback/i })).toBeInTheDocument()
+  })
+
+  it('renders subcategories', () => {
+    render(<CategoryNav categories={mockCategories} />)
+    expect(screen.getByRole('link', { name: 'Frontend' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Backend' })).toBeInTheDocument()
+  })
+
+  it('links categories to their slug URL', () => {
+    render(<CategoryNav categories={mockCategories} />)
+    const generalLink = screen.getByRole('link', { name: 'General Discussion' })
+    expect(generalLink).toHaveAttribute('href', '/c/general')
+  })
+
+  it('links subcategories with parent path', () => {
+    render(<CategoryNav categories={mockCategories} />)
+    const frontendLink = screen.getByRole('link', { name: 'Frontend' })
+    expect(frontendLink).toHaveAttribute('href', '/c/development/frontend')
+  })
+
+  it('passes axe accessibility check', async () => {
+    const { container } = render(<CategoryNav categories={mockCategories} />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
diff --git a/src/components/category-nav.tsx b/src/components/category-nav.tsx
new file mode 100644
index 0000000..6d56605
--- /dev/null
+++ b/src/components/category-nav.tsx
@@ -0,0 +1,82 @@
+/**
+ * CategoryNav - Hierarchical category navigation.
+ * Renders category tree with proper accessibility.
+ * Used in sidebar and as standalone navigation.
+ * @see specs/prd-web.md Section 4 (Navigation)
+ */
+
+import Link from 'next/link'
+import { Folder, FolderOpen } from '@phosphor-icons/react/dist/ssr'
+import type { CategoryTreeNode } from '@/lib/api/types'
+import { cn } from '@/lib/utils'
+
+interface CategoryNavProps {
+  categories: CategoryTreeNode[]
+  currentSlug?: string
+  className?: string
+}
+
+export function CategoryNav({ categories, currentSlug, className }: CategoryNavProps) {
+  return (
+    <nav aria-label="Categories" className={className}>
+      <h2 className="mb-3 text-sm font-semibold uppercase tracking-wider text-muted-foreground">
+        Categories
+      </h2>
+      <ul className="space-y-1">
+        {categories.map((category) => (
+          <CategoryItem key={category.id} category={category} currentSlug={currentSlug} depth={0} />
+        ))}
+      </ul>
+    </nav>
+  )
+}
+
+interface CategoryItemProps {
+  category: CategoryTreeNode
+  currentSlug?: string
+  depth: number
+  parentSlug?: string
+}
+
+function CategoryItem({ category, currentSlug, depth, parentSlug }: CategoryItemProps) {
+  const isActive = currentSlug === category.slug
+  const hasChildren = category.children.length > 0
+  const categoryPath = parentSlug ? `/c/${parentSlug}/${category.slug}` : `/c/${category.slug}`
+
+  return (
+    <li>
+      <Link
+        href={categoryPath}
+        aria-current={isActive ? 'page' : undefined}
+        className={cn(
+          'flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
+          'hover:bg-card-hover focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+          isActive
+            ? 'bg-primary-muted font-medium text-primary'
+            : 'text-muted-foreground hover:text-foreground',
+          depth > 0 && 'ml-4'
+        )}
+      >
+        {hasChildren ? (
+          <FolderOpen className="h-4 w-4 shrink-0" weight="regular" aria-hidden="true" />
+        ) : (
+          <Folder className="h-4 w-4 shrink-0" weight="regular" aria-hidden="true" />
+        )}
+        <span className="truncate">{category.name}</span>
+      </Link>
+      {hasChildren && (
+        <ul className="mt-0.5 space-y-0.5">
+          {category.children.map((child) => (
+            <CategoryItem
+              key={child.id}
+              category={child}
+              currentSlug={currentSlug}
+              depth={depth + 1}
+              parentSlug={category.slug}
+            />
+          ))}
+        </ul>
+      )}
+    </li>
+  )
+}
diff --git a/src/components/layout/forum-layout.test.tsx b/src/components/layout/forum-layout.test.tsx
new file mode 100644
index 0000000..819f38d
--- /dev/null
+++ b/src/components/layout/forum-layout.test.tsx
@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'vitest-axe'
+import { ForumLayout } from './forum-layout'
+
+// Mock next-themes
+vi.mock('next-themes', () => ({
+  useTheme: () => ({ theme: 'dark', setTheme: vi.fn() }),
+  ThemeProvider: ({ children }: { children: React.ReactNode }) => children,
+}))
+
+// Mock next/image
+vi.mock('next/image', () => ({
+  default: (props: Record<string, unknown>) => {
+    // eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text
+    return <img {...props} />
+  },
+}))
+
+// Mock next/link
+vi.mock('next/link', () => ({
+  default: ({
+    children,
+    href,
+    ...props
+  }: { children: React.ReactNode; href: string } & Record<string, unknown>) => (
+    <a href={href} {...props}>
+      {children}
+    </a>
+  ),
+}))
+
+describe('ForumLayout', () => {
+  it('renders header with logo', () => {
+    render(
+      <ForumLayout>
+        <p>Content</p>
+      </ForumLayout>
+    )
+    const logos = screen.getAllByAltText('Barazo')
+    expect(logos.length).toBeGreaterThan(0)
+  })
+
+  it('renders main content area', () => {
+    render(
+      <ForumLayout>
+        <p>Test content</p>
+      </ForumLayout>
+    )
+    expect(screen.getByText('Test content')).toBeInTheDocument()
+  })
+
+  it('renders header landmark', () => {
+    render(
+      <ForumLayout>
+        <p>Content</p>
+      </ForumLayout>
+    )
+    expect(screen.getByRole('banner')).toBeInTheDocument()
+  })
+
+  it('renders main landmark', () => {
+    render(
+      <ForumLayout>
+        <p>Content</p>
+      </ForumLayout>
+    )
+    expect(screen.getByRole('main')).toBeInTheDocument()
+  })
+
+  it('renders footer', () => {
+    render(
+      <ForumLayout>
+        <p>Content</p>
+      </ForumLayout>
+    )
+    expect(screen.getByRole('contentinfo')).toBeInTheDocument()
+  })
+
+  it('renders skip links', () => {
+    render(
+      <ForumLayout>
+        <p>Content</p>
+      </ForumLayout>
+    )
+    expect(screen.getByText('Skip to main content')).toBeInTheDocument()
+  })
+
+  it('passes axe accessibility check', async () => {
+    const { container } = render(
+      <ForumLayout>
+        <h1>Page Title</h1>
+        <p>Content</p>
+      </ForumLayout>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
diff --git a/src/components/layout/forum-layout.tsx b/src/components/layout/forum-layout.tsx
new file mode 100644
index 0000000..6ba0ea3
--- /dev/null
+++ b/src/components/layout/forum-layout.tsx
@@ -0,0 +1,123 @@
+/**
+ * Forum Layout (CommunityLayout)
+ * Wraps all forum pages with header, sidebar, main content area, and footer.
+ * Header: logo, search placeholder, theme toggle, user menu placeholder.
+ * @see specs/prd-web.md Section 4 (Layout Components)
+ */
+
+import Link from 'next/link'
+import Image from 'next/image'
+import { SkipLinks } from '@/components/skip-links'
+import { ThemeToggle } from '@/components/theme-toggle'
+import { MagnifyingGlass } from '@phosphor-icons/react/dist/ssr'
+
+interface ForumLayoutProps {
+  children: React.ReactNode
+  sidebar?: React.ReactNode
+}
+
+export function ForumLayout({ children, sidebar }: ForumLayoutProps) {
+  return (
+    <div className="min-h-screen bg-background">
+      <SkipLinks />
+
+      {/* Header */}
+      <header className="sticky top-0 z-40 w-full border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+        <div className="container flex h-14 items-center justify-between gap-4">
+          {/* Logo */}
+          <Link href="/" className="flex shrink-0 items-center gap-2">
+            <Image
+              src="/barazo-logo-light.svg"
+              alt="Barazo"
+              width={120}
+              height={32}
+              className="h-8 w-auto dark:hidden"
+              priority
+            />
+            <Image
+              src="/barazo-logo-dark.svg"
+              alt="Barazo"
+              width={120}
+              height={32}
+              className="hidden h-8 w-auto dark:block"
+              priority
+            />
+          </Link>
+
+          {/* Search */}
+          <div className="hidden flex-1 sm:flex sm:max-w-md">
+            <Link
+              href="/search"
+              className="flex h-9 w-full items-center gap-2 rounded-md border border-border bg-card px-3 text-sm text-muted-foreground transition-colors hover:bg-card-hover focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"
+            >
+              <MagnifyingGlass className="h-4 w-4" weight="regular" aria-hidden="true" />
+              <span>Search topics...</span>
+            </Link>
+          </div>
+
+          {/* Actions */}
+          <div className="flex items-center gap-2">
+            {/* Mobile search */}
+            <Link
+              href="/search"
+              aria-label="Search"
+              className="inline-flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-card-hover hover:text-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 sm:hidden"
+            >
+              <MagnifyingGlass className="h-5 w-5" weight="regular" aria-hidden="true" />
+            </Link>
+            <ThemeToggle />
+          </div>
+        </div>
+      </header>
+
+      {/* Main layout */}
+      <div className="container flex gap-8 py-6">
+        {/* Main content */}
+        <main id="main-content" className="min-w-0 flex-1" tabIndex={-1}>
+          {children}
+        </main>
+
+        {/* Sidebar */}
+        {sidebar && (
+          <aside className="hidden w-64 shrink-0 lg:block" aria-label="Sidebar">
+            {sidebar}
+          </aside>
+        )}
+      </div>
+
+      {/* Footer */}
+      <footer className="border-t border-border bg-background">
+        <div className="container flex items-center justify-between py-6 text-sm text-muted-foreground">
+          <p>
+            Powered by{' '}
+            <Link
+              href="https://barazo.forum"
+              className="text-primary underline decoration-primary/50 hover:text-primary-hover hover:decoration-primary"
+            >
+              Barazo
+            </Link>
+          </p>
+          <nav aria-label="Footer">
+            <ul className="flex gap-4">
+              <li>
+                <Link href="/accessibility" className="transition-colors hover:text-foreground">
+                  Accessibility
+                </Link>
+              </li>
+              <li>
+                <Link href="/legal/privacy" className="transition-colors hover:text-foreground">
+                  Privacy
+                </Link>
+              </li>
+              <li>
+                <Link href="/legal/terms" className="transition-colors hover:text-foreground">
+                  Terms
+                </Link>
+              </li>
+            </ul>
+          </nav>
+        </div>
+      </footer>
+    </div>
+  )
+}
diff --git a/src/components/pagination.test.tsx b/src/components/pagination.test.tsx
new file mode 100644
index 0000000..cbf4806
--- /dev/null
+++ b/src/components/pagination.test.tsx
@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'vitest-axe'
+import { Pagination } from './pagination'
+
+describe('Pagination', () => {
+  it('renders page numbers', () => {
+    render(<Pagination currentPage={1} totalPages={5} baseUrl="/c/general" />)
+    expect(screen.getByText('1')).toBeInTheDocument()
+    expect(screen.getByText('5')).toBeInTheDocument()
+  })
+
+  it('marks current page with aria-current', () => {
+    render(<Pagination currentPage={3} totalPages={5} baseUrl="/c/general" />)
+    const currentLink = screen.getByText('3')
+    expect(currentLink).toHaveAttribute('aria-current', 'page')
+  })
+
+  it('renders previous and next links', () => {
+    render(<Pagination currentPage={2} totalPages={5} baseUrl="/c/general" />)
+    expect(screen.getByLabelText('Previous page')).toBeInTheDocument()
+    expect(screen.getByLabelText('Next page')).toBeInTheDocument()
+  })
+
+  it('disables previous on first page', () => {
+    render(<Pagination currentPage={1} totalPages={5} baseUrl="/c/general" />)
+    const prev = screen.getByLabelText('Previous page')
+    expect(prev).toHaveAttribute('aria-disabled', 'true')
+  })
+
+  it('disables next on last page', () => {
+    render(<Pagination currentPage={5} totalPages={5} baseUrl="/c/general" />)
+    const next = screen.getByLabelText('Next page')
+    expect(next).toHaveAttribute('aria-disabled', 'true')
+  })
+
+  it('has accessible navigation landmark', () => {
+    render(<Pagination currentPage={1} totalPages={5} baseUrl="/c/general" />)
+    expect(screen.getByRole('navigation', { name: /pagination/i })).toBeInTheDocument()
+  })
+
+  it('does not render when totalPages is 1', () => {
+    const { container } = render(<Pagination currentPage={1} totalPages={1} baseUrl="/c/general" />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('passes axe accessibility check', async () => {
+    const { container } = render(<Pagination currentPage={2} totalPages={5} baseUrl="/c/general" />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
diff --git a/src/components/pagination.tsx b/src/components/pagination.tsx
new file mode 100644
index 0000000..dde1c44
--- /dev/null
+++ b/src/components/pagination.tsx
@@ -0,0 +1,135 @@
+/**
+ * Pagination component with WCAG 2.2 AA compliance.
+ * Uses aria-current="page" and proper navigation landmark.
+ */
+
+import Link from 'next/link'
+import { CaretLeft, CaretRight } from '@phosphor-icons/react/dist/ssr'
+import { cn } from '@/lib/utils'
+
+interface PaginationProps {
+  currentPage: number
+  totalPages: number
+  baseUrl: string
+}
+
+function pageUrl(baseUrl: string, page: number): string {
+  if (page === 1) return baseUrl
+  return `${baseUrl}?page=${page}`
+}
+
+export function Pagination({ currentPage, totalPages, baseUrl }: PaginationProps) {
+  if (totalPages <= 1) return null
+
+  const pages = getPageNumbers(currentPage, totalPages)
+
+  return (
+    <nav aria-label="Pagination" className="flex items-center justify-center gap-1">
+      {/* Previous */}
+      {currentPage <= 1 ? (
+        <span
+          aria-label="Previous page"
+          aria-disabled="true"
+          className="inline-flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground opacity-50"
+        >
+          <CaretLeft className="h-4 w-4" weight="bold" aria-hidden="true" />
+        </span>
+      ) : (
+        <Link
+          href={pageUrl(baseUrl, currentPage - 1)}
+          aria-label="Previous page"
+          className={cn(
+            'inline-flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors',
+            'hover:bg-card-hover hover:text-foreground',
+            'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2'
+          )}
+        >
+          <CaretLeft className="h-4 w-4" weight="bold" aria-hidden="true" />
+        </Link>
+      )}
+
+      {/* Page numbers */}
+      {pages.map((page, index) =>
+        page === '...' ? (
+          <span
+            key={`ellipsis-${index}`}
+            className="inline-flex h-10 w-10 items-center justify-center text-sm text-muted-foreground"
+            aria-hidden="true"
+          >
+            ...
+          </span>
+        ) : (
+          <Link
+            key={page}
+            href={pageUrl(baseUrl, page)}
+            aria-current={page === currentPage ? 'page' : undefined}
+            aria-label={`Page ${page}`}
+            className={cn(
+              'inline-flex h-10 w-10 items-center justify-center rounded-md text-sm font-medium transition-colors',
+              'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+              page === currentPage
+                ? 'bg-primary text-primary-foreground'
+                : 'text-muted-foreground hover:bg-card-hover hover:text-foreground'
+            )}
+          >
+            {page}
+          </Link>
+        )
+      )}
+
+      {/* Next */}
+      {currentPage >= totalPages ? (
+        <span
+          aria-label="Next page"
+          aria-disabled="true"
+          className="inline-flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground opacity-50"
+        >
+          <CaretRight className="h-4 w-4" weight="bold" aria-hidden="true" />
+        </span>
+      ) : (
+        <Link
+          href={pageUrl(baseUrl, currentPage + 1)}
+          aria-label="Next page"
+          className={cn(
+            'inline-flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors',
+            'hover:bg-card-hover hover:text-foreground',
+            'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2'
+          )}
+        >
+          <CaretRight className="h-4 w-4" weight="bold" aria-hidden="true" />
+        </Link>
+      )}
+    </nav>
+  )
+}
+
+/**
+ * Generates page numbers with ellipsis for large page counts.
+ * Always shows first, last, and pages around current.
+ */
+function getPageNumbers(currentPage: number, totalPages: number): (number | '...')[] {
+  if (totalPages <= 7) {
+    return Array.from({ length: totalPages }, (_, i) => i + 1)
+  }
+
+  const pages: (number | '...')[] = [1]
+
+  if (currentPage > 3) {
+    pages.push('...')
+  }
+
+  const start = Math.max(2, currentPage - 1)
+  const end = Math.min(totalPages - 1, currentPage + 1)
+
+  for (let i = start; i <= end; i++) {
+    pages.push(i)
+  }
+
+  if (currentPage < totalPages - 2) {
+    pages.push('...')
+  }
+
+  pages.push(totalPages)
+
+  return pages
+}
diff --git a/src/components/topic-card.test.tsx b/src/components/topic-card.test.tsx
new file mode 100644
index 0000000..55e15da
--- /dev/null
+++ b/src/components/topic-card.test.tsx
@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'vitest-axe'
+import { TopicCard } from './topic-card'
+import { mockTopics } from '@/mocks/data'
+
+const topic = mockTopics[0]!
+
+describe('TopicCard', () => {
+  it('renders topic title as a link', () => {
+    render(<TopicCard topic={topic} />)
+    const link = screen.getByRole('link', { name: topic.title })
+    expect(link).toBeInTheDocument()
+  })
+
+  it('renders author handle', () => {
+    render(<TopicCard topic={topic} />)
+    expect(screen.getByText(topic.authorDid)).toBeInTheDocument()
+  })
+
+  it('renders category', () => {
+    render(<TopicCard topic={topic} />)
+    expect(screen.getByText(topic.category)).toBeInTheDocument()
+  })
+
+  it('renders reply count', () => {
+    render(<TopicCard topic={topic} />)
+    expect(screen.getByText(String(topic.replyCount))).toBeInTheDocument()
+  })
+
+  it('renders reaction count', () => {
+    render(<TopicCard topic={topic} />)
+    expect(screen.getByText(String(topic.reactionCount))).toBeInTheDocument()
+  })
+
+  it('renders as an article element', () => {
+    render(<TopicCard topic={topic} />)
+    expect(screen.getByRole('article')).toBeInTheDocument()
+  })
+
+  it('passes axe accessibility check', async () => {
+    const { container } = render(<TopicCard topic={topic} />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
diff --git a/src/components/topic-card.tsx b/src/components/topic-card.tsx
new file mode 100644
index 0000000..62b89e5
--- /dev/null
+++ b/src/components/topic-card.tsx
@@ -0,0 +1,87 @@
+/**
+ * TopicCard - Displays a single topic in a list view.
+ * Shows title, author, category, reply/reaction counts, last activity.
+ * @see specs/prd-web.md Section 4 (Topic Components)
+ */
+
+import Link from 'next/link'
+import { ChatCircle, Heart, Clock } from '@phosphor-icons/react/dist/ssr'
+import type { Topic } from '@/lib/api/types'
+import { cn } from '@/lib/utils'
+import { formatRelativeTime } from '@/lib/format'
+
+interface TopicCardProps {
+  topic: Topic
+  className?: string
+}
+
+export function TopicCard({ topic, className }: TopicCardProps) {
+  const topicUrl = `/t/${topic.rkey}`
+
+  return (
+    <article
+      className={cn(
+        'flex items-start gap-4 rounded-lg border border-border bg-card p-4 transition-colors hover:bg-card-hover',
+        className
+      )}
+      aria-labelledby={`topic-title-${topic.rkey}`}
+    >
+      {/* Content */}
+      <div className="min-w-0 flex-1">
+        {/* Title */}
+        <h3 id={`topic-title-${topic.rkey}`} className="mb-1">
+          <Link
+            href={topicUrl}
+            className="text-base font-semibold text-foreground hover:text-primary focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 rounded-sm"
+          >
+            {topic.title}
+          </Link>
+        </h3>
+
+        {/* Metadata */}
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+          {/* Author */}
+          <span>{topic.authorDid}</span>
+
+          {/* Category */}
+          <Link
+            href={`/c/${topic.category}`}
+            className="rounded-full bg-primary-muted px-2 py-0.5 text-xs font-medium text-primary transition-colors hover:bg-primary hover:text-primary-foreground"
+          >
+            {topic.category}
+          </Link>
+
+          {/* Tags */}
+          {topic.tags?.map((tag) => (
+            <Link
+              key={tag}
+              href={`/tag/${tag}`}
+              className="text-xs text-muted-foreground hover:text-foreground"
+            >
+              #{tag}
+            </Link>
+          ))}
+        </div>
+      </div>
+
+      {/* Stats */}
+      <div className="flex shrink-0 items-center gap-4 text-sm text-muted-foreground">
+        <span className="flex items-center gap-1" aria-label={`${topic.replyCount} replies`}>
+          <ChatCircle className="h-4 w-4" weight="regular" aria-hidden="true" />
+          {topic.replyCount}
+        </span>
+        <span className="flex items-center gap-1" aria-label={`${topic.reactionCount} reactions`}>
+          <Heart className="h-4 w-4" weight="regular" aria-hidden="true" />
+          {topic.reactionCount}
+        </span>
+        <span
+          className="hidden items-center gap-1 sm:flex"
+          aria-label={`Last activity ${formatRelativeTime(topic.lastActivityAt)}`}
+        >
+          <Clock className="h-4 w-4" weight="regular" aria-hidden="true" />
+          {formatRelativeTime(topic.lastActivityAt)}
+        </span>
+      </div>
+    </article>
+  )
+}
diff --git a/src/components/topic-list.test.tsx b/src/components/topic-list.test.tsx
new file mode 100644
index 0000000..46b42d7
--- /dev/null
+++ b/src/components/topic-list.test.tsx
@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { TopicList } from './topic-list'
+import { mockTopics } from '@/mocks/data'
+
+describe('TopicList', () => {
+  it('renders all topics', () => {
+    render(<TopicList topics={mockTopics} />)
+    const articles = screen.getAllByRole('article')
+    expect(articles).toHaveLength(mockTopics.length)
+  })
+
+  it('renders topic titles', () => {
+    render(<TopicList topics={mockTopics} />)
+    for (const topic of mockTopics) {
+      expect(screen.getByRole('link', { name: topic.title })).toBeInTheDocument()
+    }
+  })
+
+  it('renders empty state when no topics', () => {
+    render(<TopicList topics={[]} />)
+    expect(screen.getByText(/no topics yet/i)).toBeInTheDocument()
+  })
+
+  it('renders with heading', () => {
+    render(<TopicList topics={mockTopics} heading="Recent Topics" />)
+    expect(screen.getByRole('heading', { name: 'Recent Topics' })).toBeInTheDocument()
+  })
+})
diff --git a/src/components/topic-list.tsx b/src/components/topic-list.tsx
new file mode 100644
index 0000000..b610bfd
--- /dev/null
+++ b/src/components/topic-list.tsx
@@ -0,0 +1,34 @@
+/**
+ * TopicList - Paginated list of TopicCard components.
+ * Renders topics with optional heading and empty state.
+ * @see specs/prd-web.md Section 4 (Topic Components)
+ */
+
+import type { Topic } from '@/lib/api/types'
+import { TopicCard } from './topic-card'
+
+interface TopicListProps {
+  topics: Topic[]
+  heading?: string
+}
+
+export function TopicList({ topics, heading }: TopicListProps) {
+  return (
+    <section>
+      {heading && <h2 className="mb-4 text-xl font-semibold text-foreground">{heading}</h2>}
+      {topics.length === 0 ? (
+        <div className="rounded-lg border border-border bg-card p-8 text-center">
+          <p className="text-muted-foreground">
+            No topics yet. Be the first to start a discussion!
+          </p>
+        </div>
+      ) : (
+        <div className="space-y-3">
+          {topics.map((topic) => (
+            <TopicCard key={topic.uri} topic={topic} />
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}
diff --git a/src/hooks/use-focus-on-navigate.ts b/src/hooks/use-focus-on-navigate.ts
new file mode 100644
index 0000000..99be6b1
--- /dev/null
+++ b/src/hooks/use-focus-on-navigate.ts
@@ -0,0 +1,28 @@
+/**
+ * Focus management for client-side navigation.
+ * Next.js does NOT move focus after route transitions.
+ * This hook moves focus to the main content area after navigation.
+ * @see WCAG 2.4.3 (Focus Order), standards/frontend.md
+ */
+
+'use client'
+
+import { usePathname } from 'next/navigation'
+import { useEffect, useRef } from 'react'
+
+export function useFocusOnNavigate() {
+  const pathname = usePathname()
+  const previousPathname = useRef(pathname)
+
+  useEffect(() => {
+    if (previousPathname.current !== pathname) {
+      previousPathname.current = pathname
+
+      // Focus the main content area after navigation
+      const main = document.getElementById('main-content')
+      if (main) {
+        main.focus({ preventScroll: false })
+      }
+    }
+  }, [pathname])
+}
diff --git a/src/lib/api/client.test.ts b/src/lib/api/client.test.ts
new file mode 100644
index 0000000..69459df
--- /dev/null
+++ b/src/lib/api/client.test.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest'
+import { getCategories, getCategoryBySlug, getTopics, ApiError } from './client'
+import { http, HttpResponse } from 'msw'
+import { server } from '@/mocks/server'
+import { mockCategories } from '@/mocks/data'
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000'
+
+describe('API client', () => {
+  describe('getCategories', () => {
+    it('returns category tree', async () => {
+      const result = await getCategories()
+      expect(result.categories).toHaveLength(mockCategories.length)
+      expect(result.categories[0]!.name).toBe('General Discussion')
+    })
+
+    it('includes nested children', async () => {
+      const result = await getCategories()
+      const dev = result.categories.find((c) => c.slug === 'development')
+      expect(dev?.children).toHaveLength(2)
+      expect(dev?.children[0]!.name).toBe('Frontend')
+    })
+  })
+
+  describe('getCategoryBySlug', () => {
+    it('returns a single category with topic count', async () => {
+      const result = await getCategoryBySlug('general')
+      expect(result.name).toBe('General Discussion')
+      expect(result.topicCount).toBeGreaterThan(0)
+    })
+
+    it('throws ApiError for unknown slug', async () => {
+      await expect(getCategoryBySlug('nonexistent')).rejects.toThrow(ApiError)
+    })
+  })
+
+  describe('getTopics', () => {
+    it('returns paginated topics', async () => {
+      const result = await getTopics()
+      expect(result.topics.length).toBeGreaterThan(0)
+      expect(result.topics[0]).toHaveProperty('uri')
+      expect(result.topics[0]).toHaveProperty('title')
+    })
+
+    it('filters by category', async () => {
+      const result = await getTopics({ category: 'general' })
+      for (const topic of result.topics) {
+        expect(topic.category).toBe('general')
+      }
+    })
+
+    it('respects limit parameter', async () => {
+      const result = await getTopics({ limit: 2 })
+      expect(result.topics.length).toBeLessThanOrEqual(2)
+    })
+  })
+
+  describe('error handling', () => {
+    it('throws ApiError on server error', async () => {
+      server.use(
+        http.get(`${API_URL}/api/categories`, () => {
+          return HttpResponse.json({ error: 'Internal server error' }, { status: 500 })
+        })
+      )
+      await expect(getCategories()).rejects.toThrow(ApiError)
+    })
+
+    it('includes status code in ApiError', async () => {
+      server.use(
+        http.get(`${API_URL}/api/categories`, () => {
+          return HttpResponse.json({ error: 'Not found' }, { status: 404 })
+        })
+      )
+      try {
+        await getCategories()
+        expect.fail('Should have thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ApiError)
+        expect((error as ApiError).status).toBe(404)
+      }
+    })
+  })
+})
diff --git a/src/lib/api/client.ts b/src/lib/api/client.ts
new file mode 100644
index 0000000..7f18f4f
--- /dev/null
+++ b/src/lib/api/client.ts
@@ -0,0 +1,132 @@
+/**
+ * Type-safe API client for barazo-api.
+ * Server-side: uses fetch directly with the internal API URL.
+ * Client-side: uses fetch with the public API URL.
+ */
+
+import type {
+  CategoriesResponse,
+  CategoryWithTopicCount,
+  CommunitySettings,
+  CommunityStats,
+  TopicsResponse,
+  RepliesResponse,
+  PaginationParams,
+} from './types'
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000'
+
+interface FetchOptions {
+  headers?: Record<string, string>
+  signal?: AbortSignal
+}
+
+class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+async function apiFetch<T>(path: string, options: FetchOptions = {}): Promise<T> {
+  const url = `${API_URL}${path}`
+  const response = await fetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+    signal: options.signal,
+  })
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => 'Unknown error')
+    throw new ApiError(response.status, `API ${response.status}: ${body}`)
+  }
+
+  return response.json() as Promise<T>
+}
+
+function buildQuery(params: Record<string, string | number | undefined>): string {
+  const entries = Object.entries(params).filter(
+    (entry): entry is [string, string | number] => entry[1] !== undefined
+  )
+  if (entries.length === 0) return ''
+  return '?' + new URLSearchParams(entries.map(([k, v]) => [k, String(v)])).toString()
+}
+
+// --- Category endpoints ---
+
+export function getCategories(options?: FetchOptions): Promise<CategoriesResponse> {
+  return apiFetch<CategoriesResponse>('/api/categories', options)
+}
+
+export function getCategoryBySlug(
+  slug: string,
+  options?: FetchOptions
+): Promise<CategoryWithTopicCount> {
+  return apiFetch<CategoryWithTopicCount>(`/api/categories/${encodeURIComponent(slug)}`, options)
+}
+
+// --- Topic endpoints ---
+
+export interface GetTopicsParams extends PaginationParams {
+  category?: string
+  sort?: 'latest' | 'popular'
+}
+
+export function getTopics(
+  params: GetTopicsParams = {},
+  options?: FetchOptions
+): Promise<TopicsResponse> {
+  const query = buildQuery({
+    limit: params.limit,
+    cursor: params.cursor,
+    category: params.category,
+    sort: params.sort,
+  })
+  return apiFetch<TopicsResponse>(`/api/topics${query}`, options)
+}
+
+// --- Reply endpoints ---
+
+export function getReplies(
+  topicUri: string,
+  params: PaginationParams = {},
+  options?: FetchOptions
+): Promise<RepliesResponse> {
+  const query = buildQuery({
+    limit: params.limit,
+    cursor: params.cursor,
+  })
+  return apiFetch<RepliesResponse>(
+    `/api/topics/${encodeURIComponent(topicUri)}/replies${query}`,
+    options
+  )
+}
+
+// --- Community endpoints ---
+
+export function getCommunitySettings(options?: FetchOptions): Promise<CommunitySettings> {
+  return apiFetch<CommunitySettings>('/api/admin/settings', {
+    ...options,
+    headers: { ...options?.headers },
+  })
+}
+
+export function getCommunityStats(
+  accessToken: string,
+  options?: FetchOptions
+): Promise<CommunityStats> {
+  return apiFetch<CommunityStats>('/api/admin/stats', {
+    ...options,
+    headers: {
+      ...options?.headers,
+      Authorization: `Bearer ${accessToken}`,
+    },
+  })
+}
+
+export { ApiError }
diff --git a/src/lib/api/types.ts b/src/lib/api/types.ts
new file mode 100644
index 0000000..172f134
--- /dev/null
+++ b/src/lib/api/types.ts
@@ -0,0 +1,181 @@
+/**
+ * API response types matching barazo-api schemas.
+ * These mirror the Zod-validated responses from the API.
+ * @see ~/Documents/Git/barazo-forum/barazo-api/src/routes/
+ */
+
+// --- Categories ---
+
+export interface Category {
+  id: string
+  slug: string
+  name: string
+  description: string | null
+  parentId: string | null
+  sortOrder: number
+  communityDid: string
+  maturityRating: MaturityRating
+  createdAt: string
+  updatedAt: string
+}
+
+export interface CategoryTreeNode extends Category {
+  children: CategoryTreeNode[]
+}
+
+export interface CategoryWithTopicCount extends Category {
+  topicCount: number
+}
+
+export interface CategoriesResponse {
+  categories: CategoryTreeNode[]
+}
+
+// --- Topics ---
+
+export interface Topic {
+  uri: string
+  rkey: string
+  authorDid: string
+  title: string
+  content: string
+  contentFormat: string | null
+  category: string
+  tags: string[] | null
+  communityDid: string
+  cid: string
+  replyCount: number
+  reactionCount: number
+  lastActivityAt: string
+  createdAt: string
+  indexedAt: string
+}
+
+export interface TopicsResponse {
+  topics: Topic[]
+  cursor: string | null
+}
+
+// --- Replies ---
+
+export interface Reply {
+  uri: string
+  rkey: string
+  authorDid: string
+  content: string
+  contentFormat: string | null
+  rootUri: string
+  rootCid: string
+  parentUri: string
+  parentCid: string
+  communityDid: string
+  cid: string
+  depth: number
+  reactionCount: number
+  createdAt: string
+  indexedAt: string
+}
+
+export interface RepliesResponse {
+  replies: Reply[]
+  cursor: string | null
+}
+
+// --- Reactions ---
+
+export interface Reaction {
+  uri: string
+  rkey: string
+  authorDid: string
+  subjectUri: string
+  subjectCid: string
+  type: string
+  communityDid: string
+  cid: string
+  createdAt: string
+}
+
+export interface ReactionsResponse {
+  reactions: Reaction[]
+  cursor: string | null
+}
+
+// --- Search ---
+
+export interface SearchResult {
+  type: 'topic' | 'reply'
+  uri: string
+  rkey: string
+  authorDid: string
+  title: string | null
+  content: string
+  category: string | null
+  communityDid: string
+  replyCount: number | null
+  reactionCount: number
+  createdAt: string
+  rank: number
+  rootUri: string | null
+  rootTitle: string | null
+}
+
+export interface SearchResponse {
+  results: SearchResult[]
+  cursor: string | null
+  total: number
+  searchMode: 'fulltext' | 'hybrid'
+}
+
+// --- Community ---
+
+export interface CommunitySettings {
+  id: string
+  initialized: boolean
+  communityDid: string | null
+  adminDid: string | null
+  communityName: string
+  maturityRating: MaturityRating
+  reactionSet: string[]
+  communityDescription: string | null
+  communityLogoUrl: string | null
+  primaryColor: string | null
+  accentColor: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface CommunityStats {
+  topicCount: number
+  replyCount: number
+  userCount: number
+  categoryCount: number
+  reportCount: number
+  recentTopics: number
+  recentReplies: number
+  recentUsers: number
+}
+
+// --- Auth ---
+
+export interface AuthSession {
+  accessToken: string
+  expiresAt: string
+  did: string
+  handle: string
+}
+
+export interface AuthUser {
+  did: string
+  handle: string
+}
+
+// --- Shared ---
+
+export type MaturityRating = 'safe' | 'mature' | 'adult'
+
+// --- Pagination ---
+
+export interface PaginationParams {
+  limit?: number
+  cursor?: string
+}
diff --git a/src/lib/format.ts b/src/lib/format.ts
new file mode 100644
index 0000000..91119fb
--- /dev/null
+++ b/src/lib/format.ts
@@ -0,0 +1,39 @@
+/**
+ * Formatting utilities for display values.
+ */
+
+/**
+ * Formats an ISO date string as a relative time (e.g., "2h ago", "3d ago").
+ */
+export function formatRelativeTime(isoDate: string): string {
+  const date = new Date(isoDate)
+  const now = new Date()
+  const diffMs = now.getTime() - date.getTime()
+  const diffSeconds = Math.floor(diffMs / 1000)
+
+  if (diffSeconds < 60) return 'just now'
+
+  const diffMinutes = Math.floor(diffSeconds / 60)
+  if (diffMinutes < 60) return `${diffMinutes}m ago`
+
+  const diffHours = Math.floor(diffMinutes / 60)
+  if (diffHours < 24) return `${diffHours}h ago`
+
+  const diffDays = Math.floor(diffHours / 24)
+  if (diffDays < 30) return `${diffDays}d ago`
+
+  const diffMonths = Math.floor(diffDays / 30)
+  if (diffMonths < 12) return `${diffMonths}mo ago`
+
+  const diffYears = Math.floor(diffMonths / 12)
+  return `${diffYears}y ago`
+}
+
+/**
+ * Formats a number with compact notation (e.g., 1.2k, 3.4M).
+ */
+export function formatCompactNumber(n: number): string {
+  if (n < 1000) return String(n)
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1).replace(/\.0$/, '')}k`
+  return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`
+}
diff --git a/src/mocks/data.ts b/src/mocks/data.ts
new file mode 100644
index 0000000..2cfec07
--- /dev/null
+++ b/src/mocks/data.ts
@@ -0,0 +1,200 @@
+/**
+ * Mock data for testing. Realistic AT Protocol forum data
+ * matching barazo-api response schemas.
+ */
+
+import type { CategoryTreeNode, CategoryWithTopicCount, Topic } from '@/lib/api/types'
+
+const COMMUNITY_DID = 'did:plc:test-community-123'
+const NOW = '2026-02-14T12:00:00.000Z'
+const YESTERDAY = '2026-02-13T12:00:00.000Z'
+const TWO_DAYS_AGO = '2026-02-12T12:00:00.000Z'
+
+// --- Users ---
+
+export const mockUsers = [
+  { did: 'did:plc:user-alice-001', handle: 'alice.bsky.social' },
+  { did: 'did:plc:user-bob-002', handle: 'bob.bsky.social' },
+  { did: 'did:plc:user-carol-003', handle: 'carol.example.com' },
+  { did: 'did:plc:user-dave-004', handle: 'dave.bsky.social' },
+  { did: 'did:plc:user-eve-005', handle: 'eve.forum.example' },
+] as const
+
+// --- Categories ---
+
+export const mockCategories: CategoryTreeNode[] = [
+  {
+    id: 'cat-general',
+    slug: 'general',
+    name: 'General Discussion',
+    description: 'Talk about anything related to the community',
+    parentId: null,
+    sortOrder: 0,
+    communityDid: COMMUNITY_DID,
+    maturityRating: 'safe',
+    createdAt: TWO_DAYS_AGO,
+    updatedAt: TWO_DAYS_AGO,
+    children: [],
+  },
+  {
+    id: 'cat-dev',
+    slug: 'development',
+    name: 'Development',
+    description: 'Technical discussions, code, and project updates',
+    parentId: null,
+    sortOrder: 1,
+    communityDid: COMMUNITY_DID,
+    maturityRating: 'safe',
+    createdAt: TWO_DAYS_AGO,
+    updatedAt: TWO_DAYS_AGO,
+    children: [
+      {
+        id: 'cat-frontend',
+        slug: 'frontend',
+        name: 'Frontend',
+        description: 'UI, UX, and frontend frameworks',
+        parentId: 'cat-dev',
+        sortOrder: 0,
+        communityDid: COMMUNITY_DID,
+        maturityRating: 'safe',
+        createdAt: TWO_DAYS_AGO,
+        updatedAt: TWO_DAYS_AGO,
+        children: [],
+      },
+      {
+        id: 'cat-backend',
+        slug: 'backend',
+        name: 'Backend',
+        description: 'APIs, databases, and server infrastructure',
+        parentId: 'cat-dev',
+        sortOrder: 1,
+        communityDid: COMMUNITY_DID,
+        maturityRating: 'safe',
+        createdAt: TWO_DAYS_AGO,
+        updatedAt: TWO_DAYS_AGO,
+        children: [],
+      },
+    ],
+  },
+  {
+    id: 'cat-feedback',
+    slug: 'feedback',
+    name: 'Feedback & Ideas',
+    description: 'Suggestions and feature requests',
+    parentId: null,
+    sortOrder: 2,
+    communityDid: COMMUNITY_DID,
+    maturityRating: 'safe',
+    createdAt: TWO_DAYS_AGO,
+    updatedAt: TWO_DAYS_AGO,
+    children: [],
+  },
+  {
+    id: 'cat-meta',
+    slug: 'meta',
+    name: 'Meta',
+    description: 'About this community',
+    parentId: null,
+    sortOrder: 3,
+    communityDid: COMMUNITY_DID,
+    maturityRating: 'safe',
+    createdAt: TWO_DAYS_AGO,
+    updatedAt: TWO_DAYS_AGO,
+    children: [],
+  },
+]
+
+export const mockCategoryWithTopicCount: CategoryWithTopicCount = {
+  ...mockCategories[0]!,
+  topicCount: 12,
+}
+
+// --- Topics ---
+
+export const mockTopics: Topic[] = [
+  {
+    uri: `at://${mockUsers[0]!.did}/forum.barazo.topic.post/3kf1abc`,
+    rkey: '3kf1abc',
+    authorDid: mockUsers[0]!.did,
+    title: 'Welcome to Barazo Forums',
+    content: 'This is the first topic on our new federated forum platform.',
+    contentFormat: null,
+    category: 'general',
+    tags: ['welcome', 'introduction'],
+    communityDid: COMMUNITY_DID,
+    cid: 'bafyreib1',
+    replyCount: 5,
+    reactionCount: 12,
+    lastActivityAt: NOW,
+    createdAt: TWO_DAYS_AGO,
+    indexedAt: TWO_DAYS_AGO,
+  },
+  {
+    uri: `at://${mockUsers[1]!.did}/forum.barazo.topic.post/3kf2def`,
+    rkey: '3kf2def',
+    authorDid: mockUsers[1]!.did,
+    title: 'Building with the AT Protocol',
+    content: 'A deep dive into building applications on the AT Protocol.',
+    contentFormat: null,
+    category: 'development',
+    tags: ['atproto', 'tutorial'],
+    communityDid: COMMUNITY_DID,
+    cid: 'bafyreib2',
+    replyCount: 8,
+    reactionCount: 23,
+    lastActivityAt: YESTERDAY,
+    createdAt: TWO_DAYS_AGO,
+    indexedAt: TWO_DAYS_AGO,
+  },
+  {
+    uri: `at://${mockUsers[2]!.did}/forum.barazo.topic.post/3kf3ghi`,
+    rkey: '3kf3ghi',
+    authorDid: mockUsers[2]!.did,
+    title: 'Feature Request: Dark Mode Improvements',
+    content: 'I would love to see more theme customization options.',
+    contentFormat: null,
+    category: 'feedback',
+    tags: ['feature-request', 'ui'],
+    communityDid: COMMUNITY_DID,
+    cid: 'bafyreib3',
+    replyCount: 3,
+    reactionCount: 7,
+    lastActivityAt: YESTERDAY,
+    createdAt: YESTERDAY,
+    indexedAt: YESTERDAY,
+  },
+  {
+    uri: `at://${mockUsers[3]!.did}/forum.barazo.topic.post/3kf4jkl`,
+    rkey: '3kf4jkl',
+    authorDid: mockUsers[3]!.did,
+    title: 'Understanding Portable Identity',
+    content: 'How does identity work across federated services?',
+    contentFormat: null,
+    category: 'general',
+    tags: ['identity', 'federation'],
+    communityDid: COMMUNITY_DID,
+    cid: 'bafyreib4',
+    replyCount: 15,
+    reactionCount: 31,
+    lastActivityAt: NOW,
+    createdAt: YESTERDAY,
+    indexedAt: YESTERDAY,
+  },
+  {
+    uri: `at://${mockUsers[4]!.did}/forum.barazo.topic.post/3kf5mno`,
+    rkey: '3kf5mno',
+    authorDid: mockUsers[4]!.did,
+    title: 'Self-Hosting Guide',
+    content: 'Step-by-step guide to running your own Barazo instance.',
+    contentFormat: null,
+    category: 'meta',
+    tags: ['self-hosting', 'guide'],
+    communityDid: COMMUNITY_DID,
+    cid: 'bafyreib5',
+    replyCount: 2,
+    reactionCount: 9,
+    lastActivityAt: NOW,
+    createdAt: NOW,
+    indexedAt: NOW,
+  },
+]
diff --git a/src/mocks/handlers.ts b/src/mocks/handlers.ts
new file mode 100644
index 0000000..3591e77
--- /dev/null
+++ b/src/mocks/handlers.ts
@@ -0,0 +1,68 @@
+/**
+ * MSW request handlers for API mocking during tests.
+ * Tier 3: Hand-written handlers matching barazo-api response shapes.
+ * @see plans/2026-02-09-mvp-implementation.md API Mock Strategy
+ */
+
+import { http, HttpResponse } from 'msw'
+import { mockCategories, mockCategoryWithTopicCount, mockTopics } from './data'
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000'
+
+export const handlers = [
+  // GET /api/categories
+  http.get(`${API_URL}/api/categories`, () => {
+    return HttpResponse.json({ categories: mockCategories })
+  }),
+
+  // GET /api/categories/:slug
+  http.get(`${API_URL}/api/categories/:slug`, ({ params }) => {
+    const slug = params['slug'] as string
+    const findCategory = (
+      nodes: typeof mockCategories
+    ): (typeof mockCategories)[number] | undefined => {
+      for (const node of nodes) {
+        if (node.slug === slug) return node
+        const found = findCategory(node.children)
+        if (found) return found
+      }
+      return undefined
+    }
+    const category = findCategory(mockCategories)
+    if (!category) {
+      return HttpResponse.json({ error: 'Category not found' }, { status: 404 })
+    }
+    return HttpResponse.json({ ...category, topicCount: mockCategoryWithTopicCount.topicCount })
+  }),
+
+  // GET /api/topics
+  http.get(`${API_URL}/api/topics`, ({ request }) => {
+    const url = new URL(request.url)
+    const category = url.searchParams.get('category')
+    const limitParam = url.searchParams.get('limit')
+    const limit = limitParam ? parseInt(limitParam, 10) : 20
+
+    let topics = mockTopics
+    if (category) {
+      topics = topics.filter((t) => t.category === category)
+    }
+
+    const limited = topics.slice(0, limit)
+    const hasMore = topics.length > limit
+
+    return HttpResponse.json({
+      topics: limited,
+      cursor: hasMore ? 'mock-cursor-next' : null,
+    })
+  }),
+
+  // GET /api/topics/:uri
+  http.get(`${API_URL}/api/topics/:uri`, ({ params }) => {
+    const uri = decodeURIComponent(params['uri'] as string)
+    const topic = mockTopics.find((t) => t.uri === uri)
+    if (!topic) {
+      return HttpResponse.json({ error: 'Topic not found' }, { status: 404 })
+    }
+    return HttpResponse.json(topic)
+  }),
+]
diff --git a/src/mocks/server.ts b/src/mocks/server.ts
new file mode 100644
index 0000000..ad61f30
--- /dev/null
+++ b/src/mocks/server.ts
@@ -0,0 +1,8 @@
+/**
+ * MSW server setup for Node.js test environment.
+ */
+
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
diff --git a/src/test/setup.ts b/src/test/setup.ts
index 4e2b5ce..62dfa73 100644
--- a/src/test/setup.ts
+++ b/src/test/setup.ts
@@ -1 +1,11 @@
-// Test setup file
+import { expect, afterAll, afterEach, beforeAll } from 'vitest'
+import * as matchers from '@testing-library/jest-dom/matchers'
+import * as axeMatchers from 'vitest-axe/matchers'
+import { server } from '@/mocks/server'
+
+expect.extend(matchers)
+expect.extend(axeMatchers)
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
diff --git a/src/test/vitest-axe.d.ts b/src/test/vitest-axe.d.ts
new file mode 100644
index 0000000..76256b0
--- /dev/null
+++ b/src/test/vitest-axe.d.ts
@@ -0,0 +1,9 @@
+import 'vitest'
+import type { AxeMatchers } from 'vitest-axe/matchers'
+
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Assertion extends AxeMatchers {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface AsymmetricMatchersContaining extends AxeMatchers {}
+}
diff --git a/tsconfig.json b/tsconfig.json
index cf9c65d..7d85f4b 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,6 +13,7 @@
     "isolatedModules": true,
     "jsx": "react-jsx",
     "incremental": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"],
     "plugins": [
       {
         "name": "next"
-- 
2.51.2