Use this skill when:

Building a docs site for a component library or design system
Creating API reference pages with interactive examples
Need tabbed preview/code views like shadcn/ui docs
Want copy-paste ready code examples with syntax highlighting

Do NOT use when:

Simple static documentation (use MDX or plain markdown)
No need for live component previews
Not using Next.js App Router or React

Prerequisites:

Next.js 13+ with App Router (app/ directory)
Tailwind CSS configured
shadcn/ui initialized (npx shadcn@latest init)

Quick Start

1. Directory Structure

src/app/docs/
├── layout.tsx                    # Root docs layout
├── page.tsx                      # Introduction page
├── _components/
│   ├── docs.tsx                  # Core UI components
│   ├── docs-sidebar.tsx          # Navigation sidebar
│   ├── docs-toc.tsx              # Table of contents
│   ├── component-preview.tsx     # Server-side preview wrapper
│   ├── component-preview-client.tsx  # Client-side preview tabs
│   ├── code-block.tsx            # Code display
│   ├── copy-button.tsx           # Clipboard utility
│   └── examples/                 # Live example components
└── [route]/page.tsx              # Documentation pages

2. Install Dependencies

npm install shiki
npx shadcn@latest add sidebar table card tabs

3. Create Core Components

See references/COMPONENTS.md for complete component implementations.

Page Structure Pattern

Every documentation page follows this structure:

import { Metadata } from "next";
import { DocsLayout, DocsSection, DocsPropTable } from "../_components/docs";
import { ComponentPreview } from "../_components/component-preview";
import { getExampleSource } from "@/lib/get-example-source";
import { MyExample } from "../_components/examples/my-example";

export const metadata: Metadata = { title: "Page Title" };

export default function PageName() {
  const exampleSource = getExampleSource("my-example.tsx");

  return (
    <DocsLayout
      title="Page Title"
      description="Brief description of this page"
      prev={{ title: "Previous", href: "/docs/previous" }}
      next={{ title: "Next", href: "/docs/next" }}
      toc={[
        { title: "Overview", slug: "overview" },
        { title: "Usage", slug: "usage" },
        { title: "API Reference", slug: "api-reference" },
      ]}
    >
      <DocsSection>
        <p>Introduction paragraph.</p>
      </DocsSection>

      <DocsSection title="Overview">
        <p>Section content here.</p>
      </DocsSection>

      <DocsSection title="Usage">
        <ComponentPreview code={exampleSource}>
          <MyExample />
        </ComponentPreview>
      </DocsSection>

      <DocsSection title="API Reference">
        <DocsPropTable
          props={[
            {
              name: "propName",
              type: "string",
              default: "undefined",
              description: "Description of the prop",
            },
          ]}
        />
      </DocsSection>
    </DocsLayout>
  );
}

Example Component Pattern

Create example components in _components/examples/:

// Client-side example (with state)
"use client";

import { useState } from "react";
import { MyComponent } from "@/registry/my-component";

export function InteractiveExample() {
  const [value, setValue] = useState("initial");

  return (
    <div className="h-[400px] w-full">
      <MyComponent value={value} onChange={setValue} />
    </div>
  );
}

// Server-side example (no state)
import { MyComponent } from "@/registry/my-component";

export function SimpleExample() {
  return (
    <div className="h-[400px] w-full">
      <MyComponent />
    </div>
  );
}

Key pattern: Always wrap examples in a fixed-height container (h-[400px]) for consistent preview rendering.

Navigation Configuration

Define navigation in docs-navigation.ts:

import { BookOpen, Code, Settings } from "lucide-react";

export const docsNavigation = {
  groups: [
    {
      title: "Getting Started",
      items: [
        { title: "Introduction", href: "/docs", icon: BookOpen },
        { title: "Installation", href: "/docs/installation", icon: Code },
      ],
    },
    {
      title: "Components",
      items: [
        { title: "Button", href: "/docs/button", icon: Settings },
        // Add more components...
      ],
    },
  ],
};

Code Highlighting Setup

Create lib/highlight.ts:

import { codeToHtml } from "shiki";

export async function highlightCode(code: string, lang = "tsx") {
  return codeToHtml(code, {
    lang,
    themes: {
      light: "github-light",
      dark: "github-dark",
    },
  });
}

Create lib/get-example-source.ts:

import fs from "fs";
import path from "path";

export function getExampleSource(filename: string): string {
  const filePath = path.join(
    process.cwd(),
    "src/app/docs/_components/examples",
    filename
  );

  let content = fs.readFileSync(filePath, "utf-8");

  // Transform import paths for user copy-paste
  content = content.replace(
    /@\/registry\//g,
    "@/components/ui/"
  );

  return content;
}

UI Components

The docs system uses these core components:

Component	Purpose
`DocsLayout`	Page wrapper with prev/next nav and TOC
`DocsSection`	Content section with auto-generated slug IDs
`DocsHeader`	Page title and description
`DocsNote`	Highlighted callout boxes
`DocsCode`	Inline code styling
`DocsLink`	Styled links with external support
`DocsPropTable`	API reference tables
`ComponentPreview`	Live preview with code tab
`CodeBlock`	Standalone code display

Preview System Architecture

┌─────────────────────────────────────────────┐
│ ComponentPreview (Server Component)          │
│ - Receives code string                       │
│ - Calls highlightCode() with Shiki           │
│ - Passes highlighted HTML to client          │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│ ComponentPreviewClient (Client Component)    │
│ - Renders tabs: Preview | Code               │
│ - Preview tab: renders children              │
│ - Code tab: shows highlighted code           │
│ - Copy button for code                       │
└─────────────────────────────────────────────┘

Adding a New Documentation Page

Create route directory: src/app/docs/[page-name]/page.tsx
Create example component if needed: _components/examples/[name]-example.tsx
Add to navigation in docs-navigation.ts
Update prev/next links on adjacent pages

Best Practices

Keep examples focused - One concept per example
Use fixed heights - h-[400px] for consistent previews
Transform imports - Change internal paths for user copy-paste
Include API tables - Document all props with types and defaults
Add TOC items - List all major sections for scroll tracking
Mobile-first - Test sidebar collapse and responsive layouts

Common Mistakes

Mistake	Fix
Calling `highlightCode` in Client Component	Move to Server Component - Shiki requires server-side execution
Missing fixed height on examples	Add `h-[400px]` wrapper for consistent preview rendering
Using internal import paths in examples	Use `getExampleSource()` to transform `@/registry/` to `@/components/ui/`
Forgetting to update navigation	Always add new pages to `docs-navigation.ts`
Not updating prev/next links	Check adjacent pages when adding/removing docs

Troubleshooting

Problem	Solution
shadcn/ui not installed	Run `npx shadcn@latest init` first, then add components
Shiki SSR errors	Ensure `highlightCode` is only called in Server Components
Dark mode not working	Add `defaultColor: false` to Shiki config and use CSS `[data-theme]` selectors
Preview height inconsistent	Always use fixed height (`h-[400px]`) on example wrappers
Copy button not working	Ensure HTTPS or localhost (clipboard API requirement)

Prerequisites Check

Before using this skill, verify:

Next.js 13+ with App Router (app/ directory)
Tailwind CSS configured
cn() utility from shadcn/ui (lib/utils.ts)

If missing shadcn/ui:

npx shadcn@latest init

File Reference

references/COMPONENTS.md - Complete component implementations
references/LAYOUT.md - Layout and sidebar setup
scripts/create-doc-page.sh - Generate new doc pages

mapcn-docs

mapcn-docs

Overview

When to Use