---
name: snapcode-docs
description: Write long-form documentation (guides, tutorials, API references) that use Snapcode-rendered figures — step-by-step code builds, concept diagrams as code, and example walkthroughs. Requires the snapcode base skill for render mechanics.
---

# Snapcode Docs

A recipe skill for long-form documentation that uses Snapcode images well. It assumes the **`snapcode` base skill** is installed — that skill owns render mechanics; this one owns *how tutorials and guides should use code visuals*.

## Document structure that works

1. **Concept first, visual second** — explain the idea in a sentence, then show it as a figure. Never open a section with an unexplained image.
2. **Progressive build-up** — tutorials teach best as a sequence of small steps, each with its own figure, rather than one giant final listing.
3. **Runnable anchors** — every figure's code exists as a real file in `examples/` the reader can run. Figures illustrate the repo; they don't replace it.

## Where each image goes

| Image | Location | Snapcode settings |
|---|---|---|
| Step figure | After each tutorial step's explanation | `--lines` to show just that step's new code; `--highlight` on what changed since the previous step |
| Full example | At the end of a tutorial ("putting it together") | The complete file, `--title <filename>`; this is the one place a longer render is fine |
| Concept snippet | Beside conceptual explanations (what a config block means, how an API payload is shaped) | Minimal chrome, no background noise — the reader is learning structure, not admiring styling |
| Common-error figure | In troubleshooting sections | Show the *wrong* code with a caption saying so, then the fix |

## Rules

- **One idea per figure.** If a figure needs two captions, split it into two figures.
- **Highlight the delta.** In multi-step tutorials each figure should `--highlight` exactly the lines that step introduced — the reader's eye goes straight to the new material.
- **Copy-paste stays text.** Commands, config the reader must type, and anything they need to edit stays in fenced code blocks. Figures are for reading, text is for doing.
- **Consistent theme across a doc.** Pick one theme for the whole document and stick to it — mixed themes read as sloppy.
- **Alt text and captions everywhere.** Figures without alt text fail screen readers; figures without captions fail skimmers.
- **Regenerate on doc updates.** Figures go stale silently. When you edit an `examples/` file, re-render every figure built from it.

## Workflow

1. Write the example code first, as runnable files under `examples/`.
2. Draft the prose around the examples (concept → step → figure).
3. Render each figure from the real files (base skill): `snapcode generate --file examples/step-2.ts --highlight 8-14 --title step-2.ts --out docs/assets/guide-step-2.png`
4. Reference with relative paths, alt text, and a one-line caption per figure.