---
name: Docs Site (Figma)
description: Technical documentation site — reading-first, three-pane shell (left nav / article column / right TOC), tuned for long prose, code blocks, and fast scanning.
triggers:
  - docs site
  - documentation site
  - technical docs
  - api reference
  - developer documentation
  - readme site
cd:
  mode: page
  platform: figma-responsive
  scenario: documentation
  preview: figma_frames
  fidelity: high
  speaker_notes: false
  animations: false
  featured: true
  design_system:
    requires: true
    sections: [palette, type, spacing]
  craft:
    requires:
      - typography
      - typography-hierarchy-editorial
      - color
      - anti-ai-slop
      - accessibility-baseline
      - laws-of-ux
  inputs:
    - product (what the docs cover)
    - doc shape (guide vs reference vs both)
    - code language(s) shown in examples
  parameters:
    - canvas (default 1440; also 375 mobile nav-drawer view)
    - dark_mode (default true — docs are often read dark)
  outputs:
    primary: figma_frames
    capabilities_required:
      - figma_execute
  default_for:
    - docs
    - documentation
  example_prompt: "Docs site for a Go logging library — guide + reference, dark-mode first, left nav with collapsible sections"
---

## Docs are for reading, not dazzling

A docs site's one job is to get the reader to the answer. Every visual choice either makes reading faster or gets in the way. Restraint is the whole brief. If you find yourself reaching for a gradient or an illustrated header, you're decorating a utility.

## Three-pane shell

The standard layout for technical docs — proven by Stripe, MDN, Tailwind, Supabase, and almost every successful reference:

- **Left nav** (240–280 wide) — hierarchical section tree with the current page highlighted. Collapsible top-level sections. Search input pinned at the top.
- **Article column** (680–760 wide, centered within its pane) — the prose. Max line length ~70 characters for comfortable reading.
- **Right TOC** (200–240 wide, optional) — in-page H2/H3 jump links, current section tracked via scroll-spy. Drop this pane entirely on pages shorter than ~4 screens.

On mobile (≤ 768), the left nav collapses into a drawer triggered by a top-bar button; the right TOC drops entirely or becomes a "On this page" disclosure above the article.

Top bar (56–64pt tall): product/docs mark on the left, global search, version selector, a theme toggle on the right. Nothing else.

## Typography — the engine of a docs site

The body font is the product. Tune it:

- Body: 16–17px, line-height 1.7, weight 400. Use the DS's body font stack; system fallback must stay legible. Paragraphs have generous margin (24–32) between them.
- Headings: H1 32–40, H2 24–28, H3 20–22, H4 17 (same as body, weight 600). Keep the spacing hierarchy visible — H2 above has more space than H2 below.
- Line length cap: ~70 characters at body size. Wider is harder to read.
- Inline code: monospace, `color.surface-alt` background (or a muted tint), 0.9em size, 2–4pt horizontal padding.
- Code block: full-width within the article column, monospace at 14px, 1.5 line-height, syntax highlighting with 5–7 semantic colors (keyword, string, comment, function, variable, number) drawn from the DS if present or derived in OKLch if not.

Never more than 4 heading levels deep. If you need H5, rethink the section.

## Palette

Docs palettes are quiet:

- `color.bg` across the canvas, `color.surface` for inline code / blockquote / callout backgrounds.
- `color.accent` reserved for: current-nav highlight, inline links, active anchor in the right TOC. Three visible uses per viewport max.
- `color.fg` for body/headings. `color.muted` for metadata (last-updated stamp, breadcrumbs, section eyebrows).
- Callouts (info / warning / error / success) use the DS semantic colors at ~8% opacity for background, full saturation for the left accent border and icon.

Dark-mode-first is often the right default for developer docs. Build dark first, light as a second variant.

## Content components

Three components carry 80% of the weight — get these right:

- **Code block** — header row with language label + copy button, body with scrollable overflow, optional line numbers. No window-chrome decorations (red/yellow/green dots are a cosmetic lie).
- **Callout** — left accent border (3–4 wide), subtle background tint, an icon matching the semantic (info / warning / etc), body text at `color.fg`. Don't nest callouts.
- **API parameter table** — four columns typical: name (monospace), type (muted), required (badge), description. Alternating row shade is usually wrong here — use row spacing + hairline dividers instead.

Diagrams and illustrations are rare in good docs. When present, they're schematic (boxes + arrows, labelled), not decorative.

## Anti-patterns

- Hero banner on the docs home with a gradient and marketing copy. Readers came here to learn, not to be sold. A short intro + a prominent "Get started in 3 minutes" link is enough.
- Emoji as section bullets (🚀 Getting Started, 🔧 API Reference). Use text headings.
- Code blocks with a purple→blue gradient border or a "prettified" shadow. A flat card with `color.surface` is correct.
- Two-column feature grids on the homepage. Docs are not a landing page.
- Accent color used on body text for emphasis. Use weight or background, not hue.
- Scroll-triggered animations on article content. Every animation in a docs site is a tax on the reader.

## Accessibility

- Body contrast ≥ 4.5:1; code-block contrast ≥ 4.5:1 against its surface.
- Skip-to-content link on keyboard focus.
- Nav tree is keyboard-operable (arrow keys, enter to toggle).
- Code block copy button has an accessible label ("Copy code").

## Quality bar

Re-read one full article at 100% zoom. If your eye tires before the end of a long page, line length, font size, or paragraph spacing is wrong. Narrow the column, raise the body size, or widen the paragraph gap — one change, re-read. Run `craft_lint` against the rendered text.