All docs
Everyone· 5 min

Inspiration — the shadcn docs page

Anatomy of why the shadcn docs page works. The patterns to steal for our own component tabs.

Captured 2026-05-26 from the live shadcn/ui Button docs page. We're modeling our component-tab presentation after this. The principles here matter more than the pixel measurements.

What's quietly excellent about it

It does the boring thing extremely well. There's no aesthetic flourish — no gradient, no glass, no playful illustration. What you get instead is a three-column layout, generous whitespace, sans throughout, hairline dividers, and content arranged so that you always know where you are and what's available next. Every decision earns its place by reducing friction.

Three principles worth stealing wholesale:

  1. Whitespace is the structure. Sections aren't framed in cards — they're separated by ~64–80px of vertical space and a single H2. No borders between Installation / Usage / Examples. Your eye groups by rhythm, not by chrome.
  2. The preview is the hero, code is teased. Each example renders inside a bordered preview frame at generous min-height with the component centered. Below the preview, you see ~3 lines of the source code under a "View Code" overlay. The signal: here's the result; the code is there if you want it, but it doesn't compete.
  3. Page-level utilities live in the header, not buried at the bottom. Top-right of the H1 you have: a Copy Page button (with dropdown), prev/next arrow buttons between adjacent component pages. These tiny affordances mean you're never hunting.

Layout map

┌──────────────────────────────────────────────────────────────────────────┐
│  TOP BAR — logomark · Docs / Components / Blocks / Charts · search ·    │
│  GH stars · theme toggle · + New (dark pill, top-right CTA)             │
├──────────────┬──────────────────────────────────┬─────────────────────────┤
│              │                                  │                          │
│  LEFT NAV    │   MAIN CONTENT                   │   RIGHT RAIL            │
│  ~240px      │   ~680px centered                │   ~240px                 │
│              │                                  │                          │
│  Sections    │   H1 component name              │   On This Page           │
│  ┌─────────  │   short description              │   - Installation         │
│  Components  │   [Copy Page] [◀][▶]             │   - Usage                │
│  Installation│                                  │   - Cursor               │
│  Theming     │   ── Radix UI │ Base UI ──┐ [□]  │   - Examples             │
│  CLI         │                                  │     - Size               │
│  ...         │   ┌─────────────────────────┐   │     - Default            │
│              │   │                         │   │     - Outline            │
│  Components  │   │  [LIVE PREVIEW]         │   │     - ...                │
│  Accordion   │   │                         │   │                          │
│  Alert       │   │  ─── 3 lines of code ── │   │   ┌──────────────────┐  │
│  Button      │   │  [View Code overlay]    │   │   │  Deploy on       │  │
│  ...         │   └─────────────────────────┘   │   │  Vercel sponsor  │  │
│              │                                  │   └──────────────────┘  │
│              │   ## Installation                │                          │
│              │   (code block + copy button)    │                          │
│              │                                  │                          │
│              │   ## Usage                       │                          │
│              │   ...                            │                          │
└──────────────┴──────────────────────────────────┴─────────────────────────┘

Pixel-honest approximations:

  • Page background: very light cool neutral (~oklch 0.98)
  • Main content max-width: ~680px (long lines of code wrap, body stays readable)
  • Sidebars: ~240px each, sticky to viewport
  • Vertical spacing between H2 sections: ~64px
  • Preview frame: 1px border, rounded ~8px, ~32px internal padding, min-height ~280px
  • Inline code: subtle light-gray bg, rounded ~4px, no border, mono font

Component-page anatomy (the part we'll copy)

Header block:

  • Big H1 (~36–40px, semibold, tight tracking)
  • One-line description in body size, muted color
  • Inline action row top-right: Copy Page ▾ ◀ ▶

Variant switcher (Radix UI / Base UI):

  • Two text tabs with a 2px underline on active
  • Right end of the same row: small icon (view mode toggle)

The preview frame — single most important pattern:

  • Outer card: 1px border, rounded, white bg
  • Component renders centered in a ~280px tall area
  • At the bottom of the same frame: 3 lines of dimmed source code
  • A "View Code" pill overlay sits on top of the code preview — click reveals full source

Section flow:

  • Installation → terminal command in a horizontal code block, copy button top-right of the block
  • Usage → 1–2 inline import + usage snippets, each its own bordered code block
  • Cursor (or other context section) → flowing prose with inline code and links
  • Examples → series of ### sub-headings with their own preview frames. Each example variant gets its own framed preview.

Variant grid (e.g. "Size"):

  • Four buttons side by side (Extra Small / Small / Default / Large)
  • Each has a small ↗ link button next to it — opens a focused view of that variant
  • The full grid is a single preview frame; the ↗ per-button affordance is the navigation surprise

Code-block style notes

Light theme by default. Background looks like off-white (~neutral-50 or -100). 1px hairline border. Line numbers in muted gray on the left. Syntax highlighting is restrained — keywords in a quiet red/orange, defaults in dark gray. Copy icon top-right, ghost button.

The choice to keep code blocks in the SAME light-on-light register as the rest of the page is intentional. Dark code blocks would punch a hole in the visual rhythm. The hairline border is enough to delineate the block.

Right rail — "On This Page"

  • Tiny On This Page label at top
  • Text-only links, one per line, ~13px
  • Sub-headings indented by ~16px
  • Active item is bold (no background pill, no color shift) — minimum chrome
  • Sticky to viewport; updates via IntersectionObserver as you scroll

Below the TOC is a sponsor card with its own bordered card treatment. It's the only "card" thing in the rail — and it earns the chrome because it's a different content type (promotion vs navigation).

Left sidebar nav

  • Two top-level groups visible: Sections (Introduction, Components, Installation, Theming, CLI, RTL, Skills, MCP Server, Registry, Forms, Changelog) and Components (alphabetical list)
  • Section labels: small, uppercase, muted, well-tracked
  • Items: regular weight, ~14px, muted text
  • Active item: bold + subtle background pill (looks like neutral-100/200)
  • "New" indicator: a small colored dot to the right of recently-added items (Registry, Changelog show this in our capture)
  • Very tight item height (~32px each) — high density without feeling cramped

What to steal for our playground

For the component tabs (Buttons, Inputs & Forms, etc.) — Milestone 5/6:

  1. Preview frame as the dominant unit. A bordered, generously-padded frame with the component centered. ~280px min-height so previews don't squish on small examples.
  2. "View Code" overlay pattern. Show a few lines of source under the preview; click to expand the full source. We'll need a small client component for the expand interaction.
  3. One preview per variant. Don't cram all variants into one frame. Size variants get their own framed preview; Outline gets its own; etc. The user scans each example as a discrete unit.
  4. Sub-section headings (### Size, ### Default) at ~18–20px semibold, generous space above (~48px). Quiet, predictable rhythm.

For the playground's app shell:

  1. Add a right rail with "On This Page" to component tabs. Sticky, text-only, indented for sub-sections, bold active. Use an IntersectionObserver to update active.
  2. Add page-level utilities at the H1. Copy-link-to-page on Foundations, prev/next between component tabs. Tiny affordance, huge "I always know how to move" payoff.
  3. Keep code light, not dark. Our current Prose component uses dark code blocks; consider switching to a hairline-bordered light block to match the docs page rhythm. Reduces visual punching.

For Foundations (already mostly in this direction):

We're already doing the right thing — no card chrome, sans throughout, soft hairlines. The shadcn docs page validates the direction. The thing we don't have yet that they do: page-level utilities in the H1 area (copy-link, prev/next). Worth adding.

What NOT to copy

  • The sponsor card placement — we're not selling anything, that real estate is better used as another "On This Page" group or just left empty.
  • The top-bar density (lots of nav items + search + GH stars + theme toggle + CTA). Our top bar can stay sidebar-only; we don't need a top bar at all.
  • The mid-page width is tight (~680px). For showcasing a lot of side-by-side variants (sizes × states × variants), our main content could go slightly wider — ~800–900px. We're showing more density than a single component page.

TL;DR — the lesson

This page is what happens when someone designed for the reader's job, not the designer's portfolio. It refuses to be impressive. It does the small things right (whitespace, hierarchy, code presentation, page-level navigation utilities) and lets the content do the work. That's the standard for our library — every page should let the components be the show.