Detalles de diseño para tu coding agent:
implementar, comparar y seguir los cambios.
English · Deutsch · Español · Français · 日本語 · 한국어 · Português · 简体中文 · 繁體中文
Empezar · Demo · Por qué · Qué recibe el agente · Pi · Limitaciones · Documentación
figlens convierte archivos de Figma guardados en contexto de diseño con el que tu coding agent puede trabajar, no solo una captura que interpretar.
- **Implementar con los detalles de origen.** Lee layout, texto, estilos, variables y las anotaciones y el estado Ready for dev de Dev Mode; exporta iconos vectoriales como SVG e imágenes como recursos. `bundle` reúne los datos, recursos y render de referencia de un frame; `verify` informa de archivos ausentes, comprobaciones de fuentes y limitaciones de la entrega. MCP `nodes` puede guardar JSON de nodos grande en un archivo con `out` en lugar de devolverlo en la respuesta.
- **Comparar la UI en ejecución.** `compare-image` compara tu captura con el render de figlens e identifica las capas bajo las regiones que difieren. Revisa esas diferencias y las advertencias de renderizado; no es una garantía de fidelidad píxel a píxel.
- **Seguir los cambios del diseño.** `diff` compara revisiones guardadas; `changes` y `watch` informan de actualizaciones en ámbitos locales bajo seguimiento; `freshness` indica cuándo una copia guardada es anterior al archivo en línea, y `pull` guarda una copia nueva mediante tu propio inicio de sesión en el navegador. Guarda una nueva `.fig` desde Figma para incorporar cambios; no es sincronización en vivo con Figma. Las cuentas con nombre asignan a cada diseño perfiles de navegador y variables de entorno de tokens API separados; los valores predeterminados no cambian. `figlens sources init [DIR]`: Escanea archivos `.fig` locales y crea `.figlens/sources.json` sin sobrescribirlo; toma los nombres de `meta.json` o del archivo. Completa las URL vacías antes de pull.
**Offline como base.** En Figma, **File > Save local copy**. Coloca `design.fig` junto a tu código. Entonces basta un enlace de Figma: su id de nodo elige el frame. Sin una copia guardada, copia las capas en Figma (clic derecho > Copy) y ejecuta `figlens clipboard screen.fig`; una copia no trae imágenes ni contornos vectoriales ([cómo](docs/README-es.md#copy-a-selection)). Un binario nativo lo lee en local, sin una app de Figma en ejecución, login ni llamadas de red a Figma; solo la comprobación opcional `freshness` (con un token API configurado; por defecto: `FIGMA_TOKEN`) y `pull` (mediante tu inicio de sesión en el navegador) llegan a Figma.
## Primeros pasos
**¿Aún no tienes un archivo de diseño?** [Comprueba tu entorno con el pequeño ejemplo público](examples/first-success/README.md): verifica el binario elegido, encuentra un frame y valida su bundle. No se necesita un modelo.
Pon `design.fig` en tu proyecto y elige **una** configuración. Cada una le da a tu agent las herramientas de figlens y la misma guía integrada para planificar, implementar y preparar imágenes.
| Configuración | Para | La guía viene de |
|---|---|---|
| [Plugin](#setup-plugin) | Claude Code, Codex, Antigravity, Cursor, Kimi Code | el skill del plugin y la herramienta `workflow` del servidor |
| [MCP](#setup-mcp) | Claude Code, Cursor, Codex, Gemini CLI y otros clientes MCP | la herramienta `workflow` del servidor |
| [Pi](#setup-pi) | Pi 1.3.0+ | el paquete, que incluye el skill |
| [OpenCode V2](#setup-opencode) | OpenCode V2 2.2.0 | el skill incluido en el paquete |
| [OMP](#setup-omp) | OMP 18.13.2 | el skill incluido en el paquete |
| [Herdr](herdr/README.md) | un panel junto a tus agentes en Herdr 0.1.12+: encuentra una pantalla y pásala, sigue el avance de cada pantalla en un tablero | la configuración del agente que la recibe |
| [CLI](#setup-cli) | agents que solo ejecutan comandos de shell, scripts y CI, o tú | `figlens workflow `, o el [skill](#setup-skill) opcional |
**Ordinario vs. avanzado.** El uso ordinario no requiere configuración: `figlens search design.fig "query"` lee el `.fig` y no crea nada. Un índice local opcional solo se crea cuando lo pides (`figlens index prepare design.fig --scope 0:0`) y luego se reutiliza entre reinicios y hosts. Consulta [Búsqueda ordinaria e índice local opcional](docs/README-es.md#local-index). Opcional y experimental: `--mode semantic` o `hybrid` ordena por significado con un modelo local que configuras tú; consulta [Búsqueda semántica opcional](docs/README-es.md#semantic-search).
### Plugin
Una sola instalación añade el skill de figlens y el servidor MCP a tu agente (Node.js 18+). El servidor queda fijado a la versión del plugin (`npx -y @runkids/figlens@ mcp`); actualiza el plugin para pasar a una versión nueva.
| Host | Instalación |
|---|---|
| Claude Code | `claude plugin marketplace add runkids/figlens`, `claude plugin install figlens@figlens` |
| Codex | `codex plugin marketplace add runkids/figlens`, `codex plugin add figlens@figlens` |
| Antigravity | `agy plugin install https://github.com/runkids/figlens/tree/main` |
| Cursor | `git clone --depth 1 https://github.com/runkids/figlens ~/.cursor/plugins/local/figlens` y recarga la ventana |
| Kimi Code | `/plugins install https://github.com/runkids/figlens/tree/main` en una sesión y luego `/reload` |
[skillshare](https://github.com/runkids/skillshare) instala el mismo plugin en varios hosts a la vez: `skillshare plugin add https://github.com/runkids/figlens.git --target claude --target codex --target cursor -g`; actualízalo después con `skillshare plugin update figlens -g`.
Reinicia el host o abre una sesión nueva y comprueba que aparecen las herramientas de figlens. La instalación de un plugin copia el repositorio: unos 7 MB, más el historial de Git (unos 60 MB) en Codex. Antigravity carga solo los primeros 24 KB del skill; la herramienta `workflow` del servidor ofrece la guía completa. Muse aún no está soportado. [Tabla de hosts y qué se verificó](wiki/host-plugins.md)
### MCP
**Claude Code** (Node.js 18+, macOS/Linux):
```sh
claude mcp add --transport stdio --scope local figlens -- npx -y @runkids/figlens mcp
```
**Codex CLI** (Node.js 18+, macOS/Linux):
```sh
codex mcp add figlens -- npx -y @runkids/figlens mcp
```
**Cualquier cliente MCP:**
```json
{
"mcpServers": {
"figlens": {
"command": "npx",
"args": ["-y", "@runkids/figlens", "mcp"]
}
}
}
```
Sin Node.js, instala el binario independiente ([CLI](#setup-cli)) y usa `"command": "figlens", "args": ["mcp"]`. Abre una sesión nueva y comprueba que aparecen las herramientas de figlens (`/mcp` en Claude Code). No hace falta instalar el skill por separado. Añade `--root ` después de `mcp` para limitar qué carpetas puede leer y escribir figlens.
#### Argumentos de inicio MCP
Añade estas opciones después de `mcp` en los `args` del cliente. Son las únicas opciones de inicio MCP; ambas son opcionales y repetibles.
| Opción | Significado |
|---|---|
| `--root DIR` | Permite leer diseños y exportar dentro de `DIR` y sus subcarpetas. Sin ella, figlens no añade límites de ruta; siguen aplicándose los permisos del sistema. No se limita al proyecto actual ni escanea el equipo. |
| `--storage-root DIR` | Permite solicitar explícitamente almacenamiento de índices personalizado dentro de `DIR` y sus subcarpetas. No selecciona ni cambia la ubicación predeterminada. |
Usa rutas absolutas a directorios existentes. Cada opción y ruta es un elemento del array; repite la opción para varias carpetas. `--root` es un límite de rutas, no acceso de administrador, y solo restringe figlens MCP, no otras herramientas del agent.
Ejemplo con dos raíces de diseño/salida y dos raíces de almacenamiento permitidas:
```json
{
"mcpServers": {
"figlens": {
"command": "npx",
"args": [
"-y", "@runkids/figlens", "mcp",
"--root", "/absolute/designs",
"--root", "/absolute/project",
"--storage-root", "/absolute/storage-a",
"--storage-root", "/absolute/storage-b"
]
}
}
}
```
No existe `figlens mcp --storage`. Selecciona la ubicación real con el argumento `storage` del tool `index` (ruta absoluta dentro de una raíz permitida), o con CLI: `figlens index prepare design.fig --storage /absolute/storage-a`. Tras `prepare`, figlens recuerda la ubicación del workspace y la reutiliza entre reinicios y hosts sin repetir `storage` ni `--storage-root`. Sin ubicación personalizada se usan los directorios predeterminados del usuario, sin flags de almacenamiento.
Para no fijar estas rutas en una configuración versionada, o para compartir diseños entre worktrees de Git, consulta [roots en una configuración versionada](wiki/mcp.md#roots-in-a-checked-in-config).
Varias raíces de almacenamiento solo amplían las ubicaciones permitidas: cada `storage` elige una sola. No distribuyen, sincronizan ni respaldan índices. No se puede mover una base de datos existente indicando otra raíz; figlens rechaza la ubicación en conflicto.
### Pi
Un solo paquete incluye la CLI, MCP, el viewer, los comandos `/figlens` y el skill:
```sh
pi install npm:@runkids/figlens
```
[Guía de la extensión de Pi](docs/README-es.md#pi)
### OpenCode V2
Instala el paquete en OpenCode V2:
```sh
opencode plugin add @runkids/figlens
```
Reinicia el cliente y ejecuta `/figlens help`. [OpenCode V2](opencode/README.md)
### OMP
Instala el mismo paquete en OMP:
```sh
omp plugin install @runkids/figlens
```
Reinicia el cliente y ejecuta `/figlens help`. [OMP](omp/README.md)
### CLI
Ejecútalo con npm o instala el binario independiente:
```sh
npx @runkids/figlens --help # Node.js 18+, sin instalar
curl -fsSL https://raw.githubusercontent.com/runkids/figlens/main/scripts/install.sh | sh # macOS, Linux
brew install runkids/tap/figlens # Homebrew
irm https://raw.githubusercontent.com/runkids/figlens/main/scripts/install.ps1 | iex # Windows PowerShell
```
`npx` ejecuta el binario de la versión del paquete que resuelve. Las instalaciones por script se actualizan con `figlens update`; las de Homebrew, con `brew upgrade figlens`. Hay binarios para macOS (Apple silicon, Intel), Linux (arm64, x86_64) y Windows (x86_64).
Un agent que usa la CLI lee su guía con `figlens workflow build` (también `audit`, `images`, `search`, `plan`, `planning-details` y `yolo`, que solo se usa si se pide explícitamente), siempre acorde con la versión del binario, o desde el [skill](#setup-skill).
[Referencia de la CLI](docs/README-es.md#commands)
Distintas cuentas Figma: `figlens pull --login --account work` y el campo opcional `"account": "work"` en el mapeo. Las sesiones predeterminadas existentes no necesitan migración. [Cuentas Figma: navegador y tokens API](docs/README-es.md#figma-accounts).
`figlens sources init [DIR]`: Escanea archivos `.fig` locales y crea `.figlens/sources.json` sin sobrescribirlo; toma los nombres de `meta.json` o del archivo. Completa las URL vacías antes de pull.
### Skill para agents (opcional)
El skill enseña a un agent el mismo flujo que la guía integrada: encontrar el frame, leer el bundle por partes, planificar el alcance y comparar la UI en ejecución con el diseño. Solo contiene instrucciones, así que combínalo con la CLI o MCP. Las configuraciones MCP y Pi no lo necesitan.
**Recomendado: [skillshare](https://github.com/runkids/skillshare).** Instala el skill una vez y sincronízalo con cada agent que uses:
```sh
skillshare install github.com/runkids/figlens/skills/figlens
skillshare sync
```
La misma herramienta también puede configurar la conexión MCP de figlens para esos agents:
```sh
skillshare mcp add figlens --global --target claude --target codex --target cursor --no-tui -- npx -y @runkids/figlens mcp
skillshare sync mcp --global
```
Otras formas de instalar el skill:
```sh
npx skills add runkids/figlens --skill figlens # Skills CLI
```
O copia `skills/figlens/` de este repositorio o de un archivo de release al directorio de skills de tu agent (Claude Code: `~/.claude/skills/`). Un skill instalado se actualiza por separado del binario; `figlens workflow` siempre coincide con el binario.
Luego pide una pantalla:
```text
Build the task board from ./design.fig in this project.
Find the matching frame, use this project's components and image workflow,
then compare the running UI with the design and fix confirmed differences.
Report missing assets and any checks you could not run.
```
El agent encuentra el frame, reúne los datos del diseño, los recursos y una imagen de referencia, y construye la pantalla con tu stack. El flujo compartido guía la comprobación de fuentes y recursos; informa de lo que falta mientras continúa la implementación del layout con alternativas documentadas. Pídele los archivos modificados y una comparación en el navegador.
## Demo: Pi construye una pantalla React desde un .fig
[](https://github.com/runkids/figlens/blob/v0.10.1/assets/taskflow-demo.mp4)
El GIF en bucle reproduce el vídeo editado a triple velocidad. Haz clic para ver el vídeo completo de 78 segundos.
**[Video de 78 segundos](https://github.com/runkids/figlens/blob/v0.10.1/assets/taskflow-demo.mp4).** Pi ejecuta `/figlens plan`, lee un frame de dashboard de un `.fig` local, lo construye con React y Tailwind CSS, y luego revisa y corrige la UI en ejecución. Time-lapse editado, no un benchmark ni una promesa de fidelidad pixel-perfect. Diseño: [Task Flow by Eymen Eid](https://www.figma.com/community/file/1224268866120711793) · [notas de la grabación](wiki/accuracy.md#taskflow-react-and-tailwind-demo).
**[De .fig a HTML/CSS editable](examples/task-list/README.md):** en un estudio controlado de una lista de tareas, los seis intentos basados en figlens conservaron las 19 apariciones de texto visible como texto DOM real y los cuatro iconos. La extracción por CLI y MCP también pasó con la red de Docker desactivada. El caso incluye configuración, mediciones y comparaciones de imágenes independientes.
## ¿Por qué figlens en lugar del MCP oficial de Figma?
Usa **figlens** cuando el diseño deba viajar como archivo: agents remotos, CI, trabajo sin conexión, traspaso entre agents, lecturas repetidas sin límite. Usa el **MCP oficial de Figma** cuando el agent deba ver el diseño en vivo sin un paso de exportación.
Leer un `.fig` funciona sin conexión. Instalar y actualizar figlens, las entradas `gs://`, la comprobación opcional `freshness` y `pull`, tu proveedor de modelos y las dependencias de tu proyecto sí necesitan red.
[Comparación completa](docs/README-es.md#why)
## Qué recibe el agent
Un frame, un zip. Estructura para construir, recursos para usar, una imagen para comprobar.
[Contenido del bundle y ejemplos](docs/README-es.md#bundle) · [¿Qué tan cerca está de Figma?](docs/README-es.md#accuracy)
## Documentación
- [Extensión de Pi](docs/README-es.md#pi)
- [Explora un diseño sin Figma](docs/README-es.md#viewer)
- [Servidor MCP y skill para agents](docs/README-es.md#mcp-and-skill)
- [Referencia de la CLI](docs/README-es.md#commands)
## Limitaciones
- **Snapshots, no sincronización en vivo.** Exporta un nuevo `.fig` cuando cambie el diseño. figlens no puede descargar un diseño desde una URL de Figma.
- **Formato no documentado.** figlens decodifica el esquema incrustado en el archivo; las nuevas exportaciones de Figma pueden requerir una actualización de figlens.
- **Fuentes y texto:** no se incluyen archivos de fuentes; el texto con overrides puede conservar el layout guardado de Figma. Usa fuentes autorizadas del proyecto y compara el resultado.
- **Cobertura:** las [mejoras de renderizado](https://github.com/runkids/figlens/issues/36) y la [semántica de entrega](https://github.com/runkids/figlens/issues/37) se siguen en el gestor de issues. Consulta la [cobertura semántica actual](wiki/semantics.md).
- **Revisa la salida.** Lee los `warnings` del bundle, `missing-assets.json` y las variables sin resolver en `context.md`, y luego compara la implementación con el diseño.
- Las limitaciones visibles conocidas aparecen en `_figlens.renderDiagnostics` de los nodos, los resúmenes limitados de `inspect` y los `warnings` del bundle y de `export`; `missing-assets.json` solo contiene fallos de recursos. La ausencia de advertencias no garantiza fidelidad de píxeles.
## Ayuda a que figlens crezca
Si figlens convirtió un diseño en código para ti, [dale una estrella al repo](https://github.com/runkids/figlens) para que otros lo encuentren. ¿Encontraste un archivo que no puede leer? [Abre un issue](https://github.com/runkids/figlens/issues) con el comando y lo que esperabas.
El desarrollo ejecuta Rust solo en Docker: `docker compose run --rm dev cargo test`. Consulta [AGENTS.md](AGENTS.md) y el [wiki](wiki/README.md).
## Licencia
[MIT](LICENSE). figlens es un proyecto independiente, sin afiliación, respaldo ni patrocinio de Figma. El formato `.fig` no está documentado y puede cambiar; usa solo archivos y recursos a los que tengas permiso de acceder y compartir.