# Calque for AI agents — Figma node → code

You convert **Figma node JSON** into commit-ready UI code. You do **not** invent layout or hand-write pixel CSS from screenshots.

| | |
|---|---|
| **What** | Deterministic Figma → React/Vue/HTML/… (same input → same output) |
| **Where engine runs** | Cloud API (free, no API key). Clients never get engine source. |
| **Base URL** | `https://calque.flowsrun.com` |
| **Auth** | None |

```
Figma selection / dump JSON  →  POST /v1/convert  →  files[] { path, content }
```

---

## Fast path (copy-paste)

### 1. Input

**Preferred:** Figma design URL with `node-id`:

`https://www.figma.com/design/FILEKEY/Name?node-id=4368-321208`

Needs Figma PAT: header `X-Figma-Token` or body `figma_token` / env `FIGMA_TOKEN`.

**Or:** plugin dump JSON / node tree file.

### 2. Convert

```bash
# By Figma URL
curl -sS -X POST https://calque.flowsrun.com/v1/convert \
  -H 'content-type: application/json' \
  -H "X-Figma-Token: $FIGMA_TOKEN" \
  -d '{"figma_url":"https://www.figma.com/design/…?node-id=4368-321208","markup":"react","style":"tailwind"}'

# By JSON file
curl -sS -X POST https://calque.flowsrun.com/v1/convert \
  -H 'content-type: application/json' --data-binary @design.json

# CLI
export FIGMA_TOKEN=figd_xxx
bun run calque convert --figma-url 'https://www.figma.com/design/…?node-id=…' --out ./generated --json
```

MCP tools: `calque_convert` (`figma_url` + `figma_token`, or `nodes_path`).

### 3. Write files into the user project

Response:

```json
{
  "files": [
    { "path": "Banner/Banner.tsx", "content": "export function Banner() { ... }\\n" }
  ],
  "stats": { "nodes": 1, "loops": 0, "fileCount": 1 },
  "markup": "react",
  "style": "tailwind"
}
```

- Write each `files[i].content` to `files[i].path` under the agreed out dir.
- Do **not** reformat structure "to improve" it unless the user asks.
- Then wire imports, data, and business logic yourself.

---

## API reference

### `GET /health`

`{ "ok": true, "service": "calque", "free": true, "docs": "/llms.txt", "guide": "/docs/ai" }`

### `POST /v1/convert`

**Body (any of these shapes):**

1. Raw Figma node object
2. Array of nodes
3. Plugin dump: `{ "kind": "calque-dump", "page": "...", "frames": [{ "name", "id", "node" }] }`
4. Envelope: `{ nodes, markup?, style?, split?, index?, index_json?, map_json?, context_json?, aliases? }`

| Field | Default | Values |
|---|---|---|
| `markup` | `react` | `react` · `vue` · `svelte` · `angular` · `html` |
| `style` | `tailwind` | `tailwind` · `css` · `less` · `scss` · `css-in-js` · `style` (html only) |
| `split` | `false` | HTML + separate stylesheet when applicable |

**Success:** `200` + `{ files, stats, markup, style }`  
**Error:** `400` + `{ "error": "..." }`

### `POST /v1/check`

Same body as convert. Runs convert twice → `{ ok, fileCount, message }`.

---

## Design-system mapping (optional)

Without index → local structural components.  
With index → real imports from the user library.

Scan **on the agent machine** (server cannot see user disk), then send `index` / `index_json` in the POST body.

---

## What you must / must not do

**Do:** get real Figma JSON → call Calque → write files → wire business logic.  
**Do not:** invent layout from screenshots when JSON exists; rewrite Calque structure without user ask; require an API key.

---

## End-to-end checklist

```
[ ] design.json / calque-dump ready
[ ] POST https://calque.flowsrun.com/v1/convert
[ ] Write files[] to disk
[ ] Optional: index for design-system mapping
[ ] Integrate props, data, navigation
```