paper-to-figma

A paper's figures get redrawn many times: the text is too small at print size, a number no longer matches the table, the PDF turns into black boxes in a reviewer's viewer, a diagram says in sentences what it should show. paper-to-figma hands that work to an agent and holds it to rules measured on figures researchers approved.

Features

• From the paper's text. TeX, Markdown or text extracted from a PDF. prepare indexes captions, tables with addressable cells, and the sketches authors leave inside figure placeholders.

• Every number checked. Each value in a chart cites a table cell or a quoted clause, and must match the paper at the printed precision. Nothing is estimated or smoothed.

• Sized for print. Text, lines and arrows follow a size spec measured on approved figures, judged at the size the figure will be printed. Text never shrinks to fit.

• Editable, not a picture. Every figure is a Figma frame built from auto-layout parts: change a label, move a block, recolour a method.

• Charts that lay themselves out. Line and bar charts, broken and log axes, and radars, fitted to a full-width or a one-column format.

• Diagrams with a visual grammar. Three hierarchy levels, icons for inputs, time axes and duration bars, dashed optional paths, blocked links, state badges only where they tell something.

• Safe PDFs. No clipping masks and no transparency; every export is rendered once more with transparency off and compared.

• Works with your agent. A Claude Code plugin (skill and MCP server), an MCP server for other clients, and a plain CLI.

Related MCP server: figma-mcp

Gallery

All four come from the synthetic example paper in examples/anon-paper: its method and numbers are invented.

How it works

1. prepare indexes the paper into work/<name>/: the text, captions, the authors' figure sketches, and tables with addressable cells.

2. Plan. The agent writes one line per figure: the question it answers, its purpose, its format, what goes in and what stays out. The skill and the principles decide.

3. Draw. Data figures are JSON specs (check, then build); diagrams are short scripts that use the kit.

4. verify exports the PDF and runs every check; the agent then reads the renders against a checklist and repeats until clean.

Quick start

git clone https://github.com/JeonSeongHu/paper-to-figma.git
cd paper-to-figma
bun install && bun run build && bun test
bun run setup            # prints a private pairing code
bun run relay            # keep this terminal open

In Figma desktop: Plugins > Development > Import plugin from manifest, choose plugin/manifest.json, run Paper to Figma, paste the code, Connect. Then try the example:

bun run doctor
bun src/cli.mjs prepare examples/anon-paper --name anchor
bun src/cli.mjs build examples/anon-paper/figures/training-curves.json --paper anchor --page "Figures"
bun src/cli.mjs verify "Anchor Tokens / training curves" --paper anchor --page "Figures" --spec examples/anon-paper/figures/training-curves.json

An existing Talk to Figma setup with an execute_code command also works: set P2F_TRANSPORT=talk-to-figma and P2F_CHANNEL=<channel>. The PDF checks need Python 3.9+ with PyMuPDF and NumPy; Ghostscript enables the strict-viewer render.

Use it from your agent

Claude Code (skill and MCP server together):

claude plugin marketplace add JeonSeongHu/paper-to-figma --scope project
claude plugin install paper-to-figma@paper-to-figma

Codex: codex mcp add paper-to-figma -- bun /path/to/paper-to-figma/src/mcp.mjs, and point it at skills/paper-to-figma/SKILL.md (bun run setup prints both).

Then ask: "Use the paper-to-figma skill to make the figures of work/mypaper/paper.txt on the Figures page and verify each one."

CLI

prepare <paper> --name N       index a paper into work/N/ (text, captions, figure sketches, tables with addressable cells)
check <spec.json> --paper N    fill in the layout, gate the design, check every value against the paper
build <spec.json> --paper N    check, then draw in Figma (a frame with the same name is replaced in place)
script <file.js>               run a figure script with the kit (diagrams, teasers); --spec S passes checked numbers
export | inspect | lint <frame>
qa <file.pdf>                  PDF checks and strict-viewer render
verify <frame> --paper N       export + qa + lint (+ evidence with --spec); writes work/N/verify-<frame>.md

Why the checks exist

Each check comes from a failure in real figures:

• Text shrinks. Language models shrink text until everything fits. The size spec was measured on reviewed figures, where the text had been enlarged until it read well at print size; lint fails text under 1.2 % of the figure width at print size.

• Numbers drift. check refuses any value without a source in the paper, and any value that differs from the printed one at the printed precision. Numbers that appear only in the authors' figure sketches are not evidence.

• PDFs break in some viewers. Figma writes clipping frames and masks as soft masks, which some viewers draw as black boxes; viewers that ignore transparency paint translucent fills solid.

• Layouts stretch. Two chart panels spread over the full width make 2.5 px lines look thin. The layout step keeps plot areas at the approved size and fits one of the two paper formats instead.

• Diagrams drift into prose, or into puzzles. Unchecked, agents write sentences into boxes; told to cut words, they leave icons nobody can decode. lint counts label words against a budget and flags long or repeated labels, unnamed icons, long blocked links, badges on most modules, and lower-level elements drawn larger than higher ones.

• Space goes to waste. A hole check finds empty rectangles, and a coverage measure catches space cut into pieces by thin lines.

• Colours change meaning. check records which method each colour stands for across the paper; diagrams declare their colour meanings and verify compares them.

Repository layout

work/ (papers and their figures) and .private/ (the pairing code) are not tracked.

Roadmap

• A published Figma plugin (the manifest ID is a development placeholder today)

• A labelled horizontal bar part for result panels inside diagrams

• A check that spots words broken across lines inside fixed-width boxes

• More paper sources: LaTeX projects with \input trees, and PDF layout instead of plain text

Limits

• The paper parser does not compile TeX. Tables from PDF text are marked low confidence.

• Charts and radars are laid out automatically. Diagrams are scripts: the kit refuses a diagram that grows past its declared width or format, and lint checks the rest.

• Automated checks do not judge emphasis, wording, whether a mechanism reads, or whether a figure answers the right question. The skill's render checklist covers these; the agent must look at the renders.

Contributing

Issues and pull requests are welcome. Every rule in this repository started as a correction to a real figure; see CONTRIBUTING.md for how to propose a new one or turn it into a check. Please follow the code of conduct, and report security problems as described in SECURITY.md.

Citation

If paper-to-figma helped with the figures of your paper, you can cite it with the metadata in CITATION.cff (GitHub shows a "Cite this repository" button).

Acknowledgements

paper-to-figma extends tex-to-figma-poster from posters to paper figures and reuses its local relay, pairing and plugin design. The Talk to Figma transport works with plugins that expose an execute_code command.

License

MIT