# Figures & diagrams

The diagram composer: draw shapes and arrows visually or write TikZ by hand, preview the compiled result live, and insert as editable vector code or PNG. Round-trips for later editing.

Draw a diagram on a canvas, refine its TikZ source, and preview the result in the same window. Insert the figure as editable code or a rendered image, with typography that fits your paper.

No API key and no cloud service: the composer runs locally, and once the TikZ packages are cached it works offline. (For AI-generated figures, see [Draw with AI](/docs/ai-figures/).)

## Opening the composer

Click the **Insert diagram** button next to the compile button in the top toolbar, or run **Insert a diagram (manual)** from the search omnibar. The composer opens as a full-height window with your workspace on the left and a live preview on the right.

## The Draw tab

A visual canvas for the common case:

- **Shapes**: drag out rectangles, circles, ellipses, diamonds, and text blocks.
- **Connections**: draw arrows and lines between shapes; they stay attached when you move things.
- **Styling**: fill, border, and text colors per element.
- **Snap to grid** keeps everything aligned; **undo/redo** covers experiments.

As you draw, the composer generates clean TikZ from the canvas. You get GUI speed with LaTeX-native output: vector shapes, and labels typeset in your document's fonts.

## The Code tab

A real LaTeX editor for the TikZ itself, with syntax highlighting and a snippet toolbar for the building blocks (rectangle node, circle node, arrow edge, line edge, scope). Start from a drawing and fine-tune the generated code, or write the whole figure by hand; the **Preview** button compiles exactly what's in the editor.

If a compile fails and you have an AI provider connected, a **Fix with AI** button appears: it sends the TikZ and the compile log for a one-shot repair and recompiles. See [Draw with AI](/docs/ai-figures/).

## The live preview

The preview pane compiles your figure in isolation, in its own build sandbox, so your main document is never touched by a half-finished diagram. For raster output you can pick a 1x, 2x, or 3x PNG scale and a transparent or page-colored background.

Use PNG for raster output. An [image project](#save-as-project) exports a vector PDF, and the saved TikZ remains editable source.

## Inserting

Give the diagram a name and pick how it lands in your document:

- **Insert as code (vector)**: the TikZ goes straight into your document. Infinitely scalable, themeable, and diffable in [Git history](/docs/git-history/) like any other source.
- **Insert as image (PNG)**: an `\includegraphics` of a rendered `figures/<name>.png`, with your chosen scale and background. Right when the figure is heavy enough to slow the main compile.

Either way, the source is preserved as `figures/<name>.tikz`, and the name prompt warns before overwriting an existing figure.

## Round-tripping: figures stay editable

Drawn diagrams embed their model inside the saved `.tikz` file. The composer's **Load** button reopens any of them on the visual canvas, fully editable: move a box, restyle an arrow, re-insert. Imported TikZ can return to the canvas when it uses supported shapes and connections. Keep complex or custom TikZ in the Code tab.

## Save as project

A diagram can also become a standalone **image project** on your library shelf (the **Save as project** option, or start one from the **Diagram / Figure** template). Image projects preview as the figure itself, and their [export menu](/docs/export/) offers PDF (vector) and PNG (raster) directly. Useful for figures you reuse across papers.