# TeX to Figma Poster

An agent workflow for turning a paper's **TeX sources and original figures into an editable Figma research poster**.

The repository includes a Codex skill, a local Figma MCP server, a companion Figma plugin, source-inventory tools, layout validation, vector math, and a synthetic example. You provide the paper and optionally a reference poster. The agent checks the evidence, plans the content, builds native objects, then renders the whole poster and each section for review.

**Status: v0.1, development release.** Automated tests cover the MCP transport, scene rules and mocked Figma API behavior. Importing the bundled plugin and reviewing its actual Figma output are still required for a live installation. The example below is an **approximate local preview**, not a Figma screenshot or real research result.

**Reference transfer:** the skill now extracts a content-free Figma layout blueprint and generates a locked region skeleton. A shared validation gate rejects changed columns, missing visual regions and altered typography. See [reference contracts](docs/reference-contract.md). The NeRF live trial exposed a layout mismatch and remains a failed design regression, not proof of a successful automated poster.

![Synthetic poster layout preview](docs/images/demo.svg)

[한국어 설치 안내](docs/quickstart.ko.md) | [Workflow](docs/workflow.md) | [Scene format](docs/scene-format.md) | [Security](SECURITY.md)

To reproduce an existing poster, ask the agent to use **reference-locked mode**, supplying the paper TeX and the exact Figma reference frame. The agent should extract its hierarchy, dense content allocation, table/chart slots and type roles before summarizing the paper. The workflow must not interpret "use this reference" as merely copying colors.

## Workflow

```text
Paper TeX + assets + optional reference poster
                  |
      Source inventory and evidence map
                  |
      Agent content plan and reference profile
                  |
      Validated editable scene JSON
                  |
      Local MCP -> local relay -> Figma plugin
                  |
      Full-poster and section renders -> corrections
                  |
      Editable Figma frame + exports + QA report
```

The agent performs the scientific reading and design decisions. The source scanner is not a LaTeX compiler or an automatic scientific summarizer. This is not a one-command guarantee of publication-ready design.

## Installation

### Prerequisites

- [Git](https://git-scm.com/downloads).
- [Bun](https://bun.sh/docs/installation), version 1.2 or newer. Tests run with Bun 1.3.14.
- Figma desktop with permission to run development plugins and edit the target file.
- A local agent client with filesystem access and STDIO MCP support, such as Codex. Model access belongs to that client; this repository does not ask for an OpenAI API key.
- Fonts used by your reference. The public example uses Inter. Do not replace institutional logos or proprietary fonts with lookalikes.

Install Git and Bun from their official instructions for your operating system. Restart your terminal, then confirm `git --version` and `bun --version` work.

### Repository setup

```sh
git clone https://github.com/JeonSeongHu/tex-to-figma-poster.git
cd tex-to-figma-poster
bun install --frozen-lockfile
bun run build:plugin
bun run setup
```

Setup creates a private pairing code, a client-configuration example, and a project-local skill under `.agents/skills/`. It does **not** rewrite your global Codex/Cursor settings or install a background service. Keep the pairing code private. Run the relay in a separate terminal and leave it open:

```sh
bun run relay
```

### Figma connection

1. Open the intended Figma file in the desktop app.
2. In **Plugins > Development > Import plugin from manifest**, choose this repository's `plugin/manifest.json`.
3. Run **TeX to Figma Poster**, paste the pairing code from setup, and select **Connect**.
4. Keep the plugin open while the agent works.

The manifest's ID is a local development placeholder, not a published Community plugin ID. If your Figma installation requires an assigned ID, use **Create new plugin** to obtain one, put that ID in a local copy of the manifest alongside `code.js` and `ui.html`, and import that copy. Do not publish under the placeholder ID. See the [Figma manifest documentation](https://developers.figma.com/docs/plugins/manifest/).

This bridge uses **127.0.0.1:3056** and its own pairing codes. It does not reuse the channel of Talk to Figma or the official Figma connector. An already installed read-only connector is not sufficient for native object creation. You can keep existing MCP servers installed.

### Agent connection

For Codex, run the exact `codex mcp add` command printed by setup. Its form is:

```sh
codex mcp add paper-poster -- bun "/absolute/path/to/tex-to-figma-poster/src/mcp.mjs"
```

Alternatively add a STDIO server in the client's MCP settings with command `bun` and that absolute script path as its argument. Restart the server/client after configuration. Use `codex mcp list` to check registration. The [official Codex MCP documentation](https://developers.openai.com/codex/mcp/) describes both settings and CLI configuration.

For another MCP client, merge the generated `.private/mcp-client.json` entry into its settings, preserving existing entries. The skill's instructions can be used by another agent, but skill discovery is client-specific; this repository only installs the project-local Codex skill. See [official skill documentation](https://developers.openai.com/codex/skills/).

With the relay and Figma plugin connected:

```sh
bun run doctor
```

Doctor should report `connected: true` and the intended Figma page. Do not run Doctor while another tool call is occupying the same pairing code. If the wrong page is shown, disconnect and open the correct file before writing.

## First poster

Keep unpublished material outside this Git checkout, or inside ignored `work/`. Extract a source archive yourself into a dedicated directory; the tool deliberately does not unpack or execute arbitrary archives.

```sh
bun src/cli.mjs prepare "/path/to/paper-source" --entry main.tex --name my-paper
```

Open this repository as the agent's project, then ask:

```text
Use $tex-to-figma-poster to create an editable research poster.
Paper source: /path/to/paper-source
Entry file: main.tex
Prepared project: work/my-paper
Physical output size: 1400 x 1000 mm, landscape
Reference Figma frame: <frame ID, or say no reference>

Reuse the paper's original figures and preserve their meaning.
Match the reference template, fonts, colors and spacing where appropriate.
Do not alter the reference. Build a new frame.
Verify each claim against the source, then render the whole poster and
every section. Correct layout and readability issues before handing it off.
```

You need to supply the physical dimensions required by the conference. The example canvas is 2800 x 2000 design units; **those units do not automatically export as 1400 x 1000 mm**. Check or rescale the final PDF page size with an appropriate PDF tool before printing.

## Example without a paper or Figma connection

```sh
bun run demo
bun src/cli.mjs validate work/demo/poster.scene.json
bun src/cli.mjs preview work/demo/poster.scene.json
bun src/cli.mjs prepare examples/paper --name sample
bun src/cli.mjs math examples/formula.tex
bun test
```

The demo generates native scene data and a local SVG wireframe under `work/demo/`. It never changes Figma. To test the live bridge, ask the connected agent to validate and build `work/demo/poster.scene.json` in a disposable Figma file, then render it. Test with the example before using unpublished research.

## What stays editable

| Content | Figma representation |
| --- | --- |
| Titles, body, captions | Native text; no artificial glyph stretching |
| Bullet lists | Native Figma list options |
| Tables | Native text and shapes, horizontal rules, one optional method separator |
| New diagrams and chart marks | Native shapes or imported SVG vectors |
| Equations | Editable SVG paths, with original TeX retained for semantic edits |
| Existing paper photos and rendered results | Individual image fills with preserved aspect ratio |
| Original logos | Original vector or individual image assets; no recoloring by default |

An editable SVG equation is **not** a live TeX editor. Original raster paper figures remain raster; the tool does not pretend they contain editable diagram components. It never flattens an entire poster into one image.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `poster_document` | Read the active page and frames |
| `poster_fonts` | Check available font families and styles |
| `poster_inspect` | Read actual node bounds, text and fills |
| `poster_validate` | Check a local scene before writing |
| `poster_build` | Create a new native poster frame, with an idempotent build key |
| `poster_render` | Export actual Figma PNG/PDF/SVG and return PNG for inspection |

Builds are additive. A revised scene gets a new build key and a new frame. The tools do not expose arbitrary code execution, whole-file deletion or reference-frame replacement.

## Troubleshooting

- **Connection refused:** start `bun run relay`, check port 3056, then reopen the Figma plugin. Do not expose the relay on a public interface.
- **Plugin not connected:** the MCP client reached the relay, but no plugin has paired with the same code.
- **Pairing role already occupied:** another CLI/MCP connection is active. Let it finish before reconnecting.
- **Font unavailable:** install that exact family/style or explicitly choose a substitute and recheck layout. The build stops before creating a frame.
- **Text needs more height:** shorten, rewrap or rearrange the section. The tool does not squash type to make it fit.
- **A write timed out:** it may already have completed. Inspect the page and retry with the same build key. Use a new key only for an intentionally new revision.
- **Missing TeX includes/macros:** inspect the source manually. The scanner does not expand macros, `graphicspath`, conditionals or bibliography semantics.
- **PDF/EPS figure:** convert it to a self-contained SVG using a trusted local tool, or use a suitably sized raster export for an existing paper figure. Never silently omit it.

## Development and limitations

Run `bun test` and `bun run build:plugin` after changes. Tests include a real STDIO MCP handshake and a mocked Figma API contract; **mock tests do not validate Figma typography, plugin import, SVG fidelity or print output**. Follow the [live acceptance checklist](docs/workflow.md#live-acceptance-checklist) before claiming a deployment is fully verified. The compiled plugin is included and can be rebuilt from source.

The relay protocol is intentionally small and separate from existing Talk to Figma protocols. The workflow was informed by iterative academic-poster work and the local-bridge approach exemplified by [Talk to Figma](https://github.com/grab/cursor-talk-to-figma-mcp). This project is independently implemented, is not an official Figma/OpenAI product, and is not affiliated with that project.

MIT licensed code and original synthetic examples. Paper sources, figures, trademarks and logos retain their owners' licenses. No user paper or reference screenshot is distributed in this repository.