Docs-Style Developer Site

---
name: developer-docs-site
description: Apply the Docs-Style Developer Site visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Docs-Style Developer Site, mentions docs layout, three-pane docs, API documentation style, or describes sidebar + content + TOC three-pane layout, tinted code blocks with copy buttons, callout admonitions (note/warning/tip) — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Docs-Style Developer Site Design System

The canonical three-pane developer documentation layout: fixed sidebar navigation, a readable prose column, and a sticky on-page table of contents, set in a quiet blue-accented light palette with tinted code blocks, copy buttons, and colored callout admonitions. Optimized for scanning, deep-linking, and long reading sessions.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values are representative interpretations of the aesthetic, not an official spec. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Docs-Style Developer Site.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (docs layout, three-pane docs, API documentation style, developer documentation UI), or describes its traits: sidebar + content + TOC three-pane layout; tinted code blocks with copy buttons; callout admonitions (note/warning/tip); quiet blue link accent; 1.6 body leading; keyboard-first search (⌘K).

## Design tokens

### Color palette

- Content background: `#ffffff` (--color-bg)
- Code blocks, sidebar wash, table headers: `#f6f8fa` (--color-surface)
- Primary prose ink: `#1f2328` (--color-text)
- Metadata, breadcrumbs, secondary labels: `#59636e` (--color-text-muted)
- Links, active nav items, focus rings: `#0969da` (--color-accent)
- Pane dividers, table rules, input edges: `#d0d7de` (--color-border)
- Tip callouts and success badges: `#1a7f37` (--color-success)
- Warning callouts: `#9a6700` (--color-warning)
- Danger callouts and destructive labels: `#cf222e` (--color-danger)

### Dark mode overrides

When building dark mode, override these roles (all other tokens stay the same):

- Dark content background: `#0d1117` (--color-bg)
- Dark code blocks and sidebar: `#161b22` (--color-surface)
- Dark-mode prose ink: `#e6edf3` (--color-text)
- Dark-mode secondary text: `#8d96a0` (--color-text-muted)
- Dark-mode link blue: `#4493f8` (--color-accent)
- Dark-mode dividers: `#30363d` (--color-border)

### Typography

- Display / headings: Inter (fallback: -apple-system, Segoe UI, sans-serif) (ideal: System UI stack (SF Pro / Segoe UI), premium — use Inter as the free substitute)
- Body: Inter (fallback: -apple-system, Segoe UI, sans-serif) (ideal: System UI stack (SF Pro / Segoe UI), premium — use Inter as the free substitute)
- Mono / data: JetBrains Mono (fallback: SFMono-Regular, Menlo, monospace) (ideal: Geist Mono, premium — use JetBrains Mono as the free substitute)
- Type scale: 1.25 ratio, base 16px — computed steps: 16px / 20px / 25px / 31px / 39px / 49px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 600, line-height 1.25, letter-spacing -0.01em
- Body: line-height 1.6, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 12, 16, 24, 32, 48, 64 — Reading-optimized: 1.6 leading and 24–32px between blocks in the prose column; nav and TOC panes are compact with 32px rows.
- Border radius: sm 6px, md 8px — 6px on code blocks, buttons, and callouts; nothing rounder — this is a utilitarian surface.
- Border treatment: 1px solid #d0d7de — Hairlines divide the three panes and rule tables; headings get an optional bottom hairline in long reference pages.

### Shadows

- none: `none` — Default — docs surfaces are flat
- popover: `0 8px 24px rgba(140,149,159,0.2)` — Search modal and dropdown menus only

### Layout

- Max content width: 1440px
- 240px fixed left nav tree with collapsible sections
- Prose column capped near 700px for measure; code blocks may extend wider
- Sticky right TOC with scroll-spy active state
- Previous/Next pagination links at page bottom
- Breadcrumb plus version/language switchers in the header

### Effects

- Copy-to-clipboard buttons appearing on code-block hover
- Syntax highlighting on the #f6f8fa tinted block
- Heading anchor links (#) revealed on hover
- ⌘K search modal with keyboard navigation

### Motion

- Easing: ease-out; durations 100ms / 180ms / 250ms
- Motion is nearly absent: hover states, accordion expands, and modal fades only
- Scroll-spy TOC highlight moves instantly, no smooth animation
- Sidebar sections expand at base duration without bounce

## CSS variables (drop-in)

```css
:root {
  --color-bg: #ffffff;
  --color-surface: #f6f8fa;
  --color-text: #1f2328;
  --color-text-muted: #59636e;
  --color-accent: #0969da;
  --color-border: #d0d7de;
  --color-success: #1a7f37;
  --color-warning: #9a6700;
  --color-danger: #cf222e;
  --radius-sm: 6px;
  --radius-md: 8px;
  --shadow-popover: 0 8px 24px rgba(140,149,159,0.2);
  --border-default: 1px solid #d0d7de;
  --font-display: Inter, -apple-system, "Segoe UI", sans-serif;
  --font-body: Inter, -apple-system, "Segoe UI", sans-serif;
  --font-mono: "JetBrains Mono", SFMono-Regular, Menlo, monospace;
  --text-base: 16px;
  --leading-heading: 1.25;
  --leading-body: 1.6;
  --tracking-heading: -0.01em;
  --tracking-body: 0;
  --ease: ease-out;
  --duration-fast: 100ms;
  --duration-base: 180ms;
  --duration-slow: 250ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** Slim top bar with logo, version picker, and a bordered ⌘K search input; left pane holds the nav tree with 14px labels and accent-colored active row
- **Hero:** Docs landing: plain 600-weight title, one-sentence description, bordered quick-start cards in a 2–3 column grid — no decorative hero imagery
- **Card:** White fill, 1px #d0d7de border, 8px radius, 16–24px padding; used for quick-start tiles and API endpoint summaries
- **Button (primary):** Solid #0969da, white 600 text, 6px radius, 32–36px tall; darkens on hover
- **Button (secondary):** #f6f8fa fill, 1px border, #1f2328 text; used for copy buttons and secondary actions
- **Form fields:** White fill, 1px border, 6px radius; focus shows a 3px #0969da ring at 30% — search inputs show a kbd '⌘K' hint on the right

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The three-pane frame itself: a 240px fixed nav tree left, ~700px prose column center, and a sticky right-hand 'On this page' TOC that highlights the active heading as you scroll. Spend boldness here; keep everything else quiet.

## Do

- Cap the prose measure near 700px and keep 1.6 leading — reading endurance is the product
- Give every code block a copy button and every heading an anchor link
- Use the four callout colors semantically and consistently (note/tip/warning/danger)
- Ship dark mode from day one; developers expect the #0d1117 counterpart

## Don't

- No decorative heroes, mesh gradients, or marketing flourishes inside the docs frame
- Don't let code blocks force horizontal page scroll — scroll inside the block
- Never hide the nav tree behind a hamburger on desktop widths
- Don't use accent blue for non-interactive emphasis; reserve it strictly for links and active states

## Accessibility notes

- All primary pairs pass AA (#0969da on white ~5.2:1, #59636e on white ~6:1); keep the warning #9a6700 for icon-plus-text callout labels, not standalone small text
- Scroll-spy and hover-revealed anchors must remain keyboard-accessible; anchor links need visible focus states
- Syntax-highlighting themes need their own contrast audit — many popular themes fail AA on #f6f8fa

## Reference sites

- Stripe Docs: https://docs.stripe.com
- Tailwind CSS docs: https://tailwindcss.com/docs
- Mintlify: https://mintlify.com
- Vercel Docs: https://vercel.com/docs

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip developer-docs-site.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/developer-docs-site.json

Settings → Capabilities → Skills → Upload skill → developer-docs-site.zip