Designdetails für deinen Coding-Agent
zum Umsetzen, Vergleichen und Verfolgen von Änderungen.
English · Deutsch · Español · Français · 日本語 · 한국어 · Português · 简体中文 · 繁體中文
Start · Demo · Warum · Was der Agent bekommt · Pi · Einschränkungen · Doku
figlens macht aus gespeicherten Figma-Dateien Designkontext, mit dem dein Coding-Agent arbeiten kann—nicht nur einen Screenshot zum Interpretieren.
- **Mit den Quelldetails umsetzen.** Layout, Text, Stile, Variablen sowie Dev-Mode-Anmerkungen und Ready-for-dev-Status lesen; Vektor-Icons als SVG und Bilder als Assets exportieren. `bundle` sammelt Daten, Assets und Referenz-Rendering eines Frames; `verify` meldet fehlende Dateien, Schriftprüfungen und Einschränkungen der Übergabe. MCP `nodes` kann große Node-JSON-Daten mit `out` in eine Datei statt in die Antwort schreiben.
- **Die laufende UI vergleichen.** `compare-image` vergleicht deinen Screenshot mit dem Rendering von figlens und nennt die Ebenen unter abweichenden Bereichen. Prüfe diese Unterschiede und Rendering-Warnungen; das ist keine Garantie für Pixelgenauigkeit.
- **Designänderungen verfolgen.** `diff` vergleicht gespeicherte Versionen; `changes` und `watch` melden Aktualisierungen verfolgter lokaler Bereiche; `freshness` zeigt, wann eine gespeicherte Kopie älter ist als die Online-Datei, und `pull` speichert über deine eigene Browser-Anmeldung eine neue Kopie. Speichere eine neue `.fig` aus Figma, um Designänderungen zu übernehmen—keine Live-Synchronisierung mit Figma. Benannte Konten ordnen jedem Design separate Browserprofile und API-Token-Umgebungsvariablen zu; bestehende Standards bleiben unverändert. `figlens sources init [DIR]`: Lokale `.fig`-Dateien nach `.figlens/sources.json` eintragen, ohne vorhandene Dateien zu überschreiben; Namen stammen aus `meta.json` oder dem Dateinamen. Leere URLs vor dem Pull ausfüllen.
**Offline als Grundlage.** Wähle in Figma **File > Save local copy**. Lege `design.fig` neben deinen Code. Dann genügt ein Figma-Link: Seine Node-ID wählt den Frame. Ohne gespeicherte Kopie kopierst du die Ebenen in Figma (Rechtsklick > Copy) und führst `figlens clipboard screen.fig` aus; eine Kopie enthält keine Bilder oder Vektorumrisse ([so geht's](docs/README-de.md#copy-a-selection)). Ein natives Binary liest die Datei lokal, ohne laufende Figma-App, Login oder Netzwerkaufrufe an Figma; nur die optionale `freshness`-Prüfung (mit einem konfigurierten API-Token; Standard: `FIGMA_TOKEN`) und `pull` (über deine Browser-Anmeldung) erreichen Figma.
## Erste Schritte
**Noch keine Designdatei?** [Prüfe dein Setup mit dem kleinen öffentlichen Beispiel](examples/first-success/README.md): Verifiziere das gewählte Binary, finde einen Frame und prüfe sein Bundle. Kein Modell erforderlich.
Lege `design.fig` in dein Projekt und wähle dann **ein** Setup. Jedes gibt deinem Agent die figlens-Tools und dieselbe eingebaute Anleitung für Planung, Umsetzung und Bildaufbereitung.
| Setup | Geeignet für | Anleitung kommt von |
|---|---|---|
| [Plugin](#setup-plugin) | Claude Code, Codex, Antigravity, Cursor, Kimi Code | der Skill des Plugins und das `workflow`-Tool des Servers |
| [MCP](#setup-mcp) | Claude Code, Cursor, Codex, Gemini CLI und andere MCP-Clients | dem `workflow`-Tool des Servers |
| [Pi](#setup-pi) | Pi 1.3.0+ | dem Paket, das den Skill enthält |
| [OpenCode V2](#setup-opencode) | OpenCode V2 2.2.0 | dem mitgelieferten Skill |
| [OMP](#setup-omp) | OMP 18.13.2 | dem mitgelieferten Skill |
| [Herdr](herdr/README.md) | ein Panel neben deinen Agents in Herdr 0.1.12+: Screen finden und übergeben, den Stand jedes Screens auf einem Board verfolgen | dem Setup des empfangenden Agents |
| [CLI](#setup-cli) | Agents, die nur Shell-Befehle ausführen, Skripte und CI, oder dich | `figlens workflow ` oder dem optionalen [Skill](#setup-skill) |
**Normal vs. fortgeschritten.** Die normale Nutzung braucht kein Setup: `figlens search design.fig "query"` liest die `.fig` und legt nichts an. Ein optionaler lokaler Index entsteht nur auf Ihren Wunsch (`figlens index prepare design.fig --scope 0:0`) und wird danach über Neustarts und Hosts hinweg wiederverwendet. Siehe [Normale Suche und der optionale lokale Index](docs/README-de.md#local-index). Optional und experimentell: `--mode semantic` oder `hybrid` sortiert nach Bedeutung mit einem lokalen Modell, das Sie selbst einrichten; siehe [Optionale semantische Suche](docs/README-de.md#semantic-search).
### Plugin
Eine Installation fügt deinem Agenten den figlens-Skill und den MCP-Server hinzu (Node.js 18+). Der Server ist auf das Release des Plugins festgelegt (`npx -y @runkids/figlens@ mcp`); für eine neue Version aktualisierst du das Plugin.
| Host | Installation |
|---|---|
| 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`, dann das Fenster neu laden |
| Kimi Code | `/plugins install https://github.com/runkids/figlens/tree/main` in einer Sitzung, dann `/reload` |
[skillshare](https://github.com/runkids/skillshare) installiert dasselbe Plugin auf mehreren Hosts zugleich: `skillshare plugin add https://github.com/runkids/figlens.git --target claude --target codex --target cursor -g`; später aktualisieren mit `skillshare plugin update figlens -g`.
Starte den Host neu oder öffne eine neue Sitzung und prüfe, ob die figlens-Tools aufgelistet sind. Eine Plugin-Installation kopiert das Repository: etwa 7 MB, in Codex zusätzlich die Git-Historie (etwa 60 MB). Antigravity lädt nur die ersten 24 KB des Skills; die vollständige Anleitung liefert das `workflow`-Tool des Servers. Muse wird noch nicht unterstützt. [Host-Übersicht und was geprüft wurde](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
```
**Jeder MCP-Client:**
```json
{
"mcpServers": {
"figlens": {
"command": "npx",
"args": ["-y", "@runkids/figlens", "mcp"]
}
}
}
```
Ohne Node.js installierst du das eigenständige Binary ([CLI](#setup-cli)) und verwendest `"command": "figlens", "args": ["mcp"]`. Starte eine neue Session und prüfe, ob die figlens-Tools aufgelistet sind (`/mcp` in Claude Code). Eine separate Skill-Installation ist nicht nötig. Mit `--root ` nach `mcp` begrenzt du, welche Ordner figlens lesen und schreiben darf.
#### MCP-Startargumente
Füge diese Optionen in den `args` deines Clients nach `mcp` ein. Dies sind die einzigen MCP-Startoptionen; beide sind optional und wiederholbar.
| Option | Bedeutung |
|---|---|
| `--root DIR` | Erlaubt Design-Lesezugriffe und Exporte in `DIR` und Unterordnern. Ohne diese Option setzt figlens keine Pfadgrenze; Betriebssystemrechte gelten weiterhin. Weder wird der aktuelle Projektordner vorausgesetzt noch der Rechner durchsucht. |
| `--storage-root DIR` | Erlaubt ausdrücklich gewählten benutzerdefinierten Index-Speicher in `DIR` und Unterordnern. Ändert nicht den Standardspeicherort. |
Verwende absolute Pfade zu vorhandenen Verzeichnissen. Jede Option und jeder Pfad ist ein eigener Array-Eintrag; wiederhole die Option für mehrere Ordner. `--root` ist eine Pfadgrenze, kein Administratorzugriff, und beschränkt nur figlens MCP, nicht andere Agent-Werkzeuge.
Beispiel mit zwei Design-/Ausgabeordnern und zwei erlaubten Speicherwurzeln:
```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"
]
}
}
}
```
`figlens mcp --storage` gibt es nicht. Wähle den tatsächlichen Ort mit dem Argument `storage` des Tools `index` (absoluter Pfad innerhalb einer erlaubten Speicherwurzel) oder per CLI: `figlens index prepare design.fig --storage /absolute/storage-a`. Nach `prepare` merkt sich figlens den Ort dieses Workspace und verwendet ihn über Neustarts und Hosts hinweg ohne erneutes `storage` oder `--storage-root`. Ohne eigene Auswahl gelten die benutzerspezifischen Standardverzeichnisse; kein Speicher-Flag nötig.
Wie du diese Pfade aus einer eingecheckten Konfiguration heraushältst oder Designs über Git-Worktrees hinweg teilst, steht unter [Roots in einer eingecheckten Konfiguration](wiki/mcp.md#roots-in-a-checked-in-config).
Mehrere Speicherwurzeln erweitern nur die erlaubten Orte: Jedes `storage` wählt weiterhin einen Ort. Indizes werden nicht verteilt, synchronisiert oder gesichert. Eine bestehende Workspace-Datenbank lässt sich nicht durch die Angabe einer anderen Wurzel verschieben; figlens verweigert den widersprüchlichen Ort.
### Pi
Ein Paket liefert CLI, MCP, Viewer, `/figlens`-Befehle und Skill:
```sh
pi install npm:@runkids/figlens
```
[Anleitung zur Pi-Erweiterung](docs/README-de.md#pi)
### OpenCode V2
Das Paket in OpenCode V2 installieren:
```sh
opencode plugin add @runkids/figlens
```
Den Host neu starten und `/figlens help` ausführen. [OpenCode V2](opencode/README.md)
### OMP
Dasselbe Paket in OMP installieren:
```sh
omp plugin install @runkids/figlens
```
Den Host neu starten und `/figlens help` ausführen. [OMP](omp/README.md)
### CLI
Über npm ausführen oder das eigenständige Binary installieren:
```sh
npx @runkids/figlens --help # Node.js 18+, ohne Installation
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` führt das Binary der aufgelösten Paketversion aus. Skript-Installationen aktualisierst du mit `figlens update`, Homebrew-Installationen mit `brew upgrade figlens`. Binaries gibt es für macOS (Apple silicon, Intel), Linux (arm64, x86_64) und Windows (x86_64).
Ein Agent, der die CLI nutzt, liest seine Anleitung mit `figlens workflow build` (außerdem `audit`, `images`, `search`, `plan`, `planning-details` und das nur auf ausdrücklichen Wunsch genutzte `yolo`), die immer zur Version des Binarys passt, oder aus dem [Agent-Skill](#setup-skill).
[CLI-Referenz](docs/README-de.md#commands)
Verschiedene Figma-Konten: `figlens pull --login --account work` und optional `"account": "work"` in der Quellenzuordnung. Bisherige Standardsitzungen brauchen keine Migration. [Figma-Konten: Browser-Anmeldung und API-Token](docs/README-de.md#figma-accounts).
`figlens sources init [DIR]`: Lokale `.fig`-Dateien nach `.figlens/sources.json` eintragen, ohne vorhandene Dateien zu überschreiben; Namen stammen aus `meta.json` oder dem Dateinamen. Leere URLs vor dem Pull ausfüllen.
### Agent-Skill (optional)
Der Skill bringt einem Agent denselben Ablauf bei wie die eingebaute Anleitung: Frame finden, das Bundle in kleinen Teilen lesen, den Umfang planen und die laufende UI mit dem Design vergleichen. Er enthält nur Anweisungen, also kombiniere ihn mit der CLI oder MCP. MCP- und Pi-Setups brauchen ihn nicht.
**Empfohlen: [skillshare](https://github.com/runkids/skillshare).** Installiere den Skill einmal und synchronisiere ihn mit jedem Agent, den du nutzt:
```sh
skillshare install github.com/runkids/figlens/skills/figlens
skillshare sync
```
Dasselbe Tool kann für diese Agents auch die figlens-MCP-Verbindung einrichten:
```sh
skillshare mcp add figlens --global --target claude --target codex --target cursor --no-tui -- npx -y @runkids/figlens mcp
skillshare sync mcp --global
```
Weitere Wege, den Skill zu installieren:
```sh
npx skills add runkids/figlens --skill figlens # Skills CLI
```
Oder kopiere `skills/figlens/` aus diesem Repository oder einem Release-Archiv in das Skills-Verzeichnis deines Agents (Claude Code: `~/.claude/skills/`). Ein installierter Skill wird getrennt vom Binary aktualisiert; `figlens workflow` passt immer zum Binary.
Bitte dann um einen Bildschirm:
```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.
```
Der Agent findet den Frame, bündelt Designdaten, Assets und Referenzbild und setzt den Bildschirm mit deinem Stack um. Der gemeinsame Workflow leitet die Prüfung von Schriften und Assets an; fehlende Ressourcen werden gemeldet, während die Layout-Implementierung mit dokumentierten Alternativen weitergeht. Lass dir die geänderten Dateien und einen Browservergleich zeigen.
## Demo: Pi baut einen React-Bildschirm aus einer .fig
[](https://github.com/runkids/figlens/blob/v0.10.1/assets/taskflow-demo.mp4)
Die GIF-Schleife läuft mit der dreifachen Wiedergabegeschwindigkeit des geschnittenen Videos. Anklicken für das vollständige 78-Sekunden-Video.
**[78-Sekunden-Video](https://github.com/runkids/figlens/blob/v0.10.1/assets/taskflow-demo.mp4).** Pi führt `/figlens plan` aus, liest einen Dashboard-Frame aus einer lokalen `.fig`, baut ihn mit React und Tailwind CSS und prüft und korrigiert dann die laufende UI. Geschnittener Zeitraffer, kein Benchmark und kein Pixel-Perfect-Versprechen. Design: [Task Flow von Eymen Eid](https://www.figma.com/community/file/1224268866120711793) · [Aufnahmenotizen](wiki/accuracy.md#taskflow-react-and-tailwind-demo).
**[Von .fig zu editierbarem HTML/CSS](examples/task-list/README.md):** In einer kontrollierten Aufgabenlisten-Studie behielten alle sechs figlens-basierten Versuche alle 19 sichtbaren Textvorkommen als echten DOM-Text und alle vier Icons bei. Auch CLI- und MCP-Extraktion bestanden mit deaktiviertem Docker-Netzwerk. Die Fallstudie enthält Einrichtung, Messwerte und unabhängige Bildvergleiche.
## Warum figlens statt des offiziellen Figma MCP?
Nutze **figlens**, wenn das Design als Datei wandern soll: Remote-Agents, CI, Offline-Arbeit, Übergabe zwischen Agents, unbegrenzt wiederholte Lesezugriffe. Nutze den **offiziellen Figma MCP**, wenn der Agent das Live-Design ohne Export-Schritt sehen muss.
Eine `.fig` zu lesen funktioniert offline. Installieren und Aktualisieren von figlens, `gs://`-Eingaben, der optionale `freshness`-Check und `pull`, dein Modellanbieter und die Abhängigkeiten deines Projekts brauchen weiterhin ein Netzwerk.
[Vollständiger Vergleich](docs/README-de.md#why)
## Was der Agent bekommt
Ein Frame, eine Zip. Struktur zum Bauen, Assets zum Verwenden, ein Bild zum Abgleichen.
[Bundle-Inhalt und Beispiele](docs/README-de.md#bundle) · [Wie nah ist es an Figma?](docs/README-de.md#accuracy)
## Dokumentation
- [Pi-Extension](docs/README-de.md#pi)
- [Ein Design ohne Figma durchsuchen](docs/README-de.md#viewer)
- [MCP-Server und Agent-Skill](docs/README-de.md#mcp-and-skill)
- [CLI-Referenz](docs/README-de.md#commands)
## Einschränkungen
- **Snapshots, keine Live-Synchronisierung.** Exportiere eine neue `.fig`, wenn sich das Design ändert. figlens kann kein Design über eine Figma-URL herunterladen.
- **Undokumentiertes Format.** figlens decodiert das in der Datei eingebettete Schema; neue Figma-Exporte können ein figlens-Update erfordern.
- **Schriften und Text:** Schriftdateien sind nicht enthalten; überschriebener Text kann Figmas gespeichertes Layout behalten. Verwende lizenzierte Projektschriften und vergleiche das Ergebnis.
- **Unterstützungsumfang:** [Rendering-Verbesserungen](https://github.com/runkids/figlens/issues/36) und [Handoff-Semantik](https://github.com/runkids/figlens/issues/37) werden im Issue-Tracker verfolgt. Siehe die [aktuelle semantische Abdeckung](wiki/semantics.md).
- **Prüfe die Ausgabe.** Lies die Bundle-`warnings`, `missing-assets.json` und ungelöste Variablen in `context.md` und vergleiche dann die Implementierung mit dem Design.
- Bekannte sichtbare Render-Grenzen stehen in `_figlens.renderDiagnostics` der Knoten, begrenzten `inspect`-Zusammenfassungen und den `warnings` von Bundle und `export`; `missing-assets.json` enthält nur Asset-Fehler. Auch ohne Warnungen ist Pixeltreue nicht garantiert.
## Hilf figlens zu wachsen
Wenn figlens für dich ein Design in Code verwandelt hat, [gib dem Repo einen Stern](https://github.com/runkids/figlens), damit andere es finden. Eine Datei, die figlens nicht lesen kann? [Eröffne ein Issue](https://github.com/runkids/figlens/issues) mit dem Befehl und deiner Erwartung.
Die Entwicklung führt Rust ausschließlich in Docker aus: `docker compose run --rm dev cargo test`. Siehe [AGENTS.md](AGENTS.md) und das [Wiki](wiki/README.md).
## Lizenz
[MIT](LICENSE). figlens ist ein unabhängiges Projekt und steht in keiner Verbindung zu Figma, wird nicht von Figma unterstützt und nicht von Figma gesponsert. Das `.fig`-Format ist undokumentiert und kann sich ändern; verwende nur Dateien und Assets, auf die du zugreifen und die du teilen darfst.