OpenPencil Design
Erstelle produktionsreife Vektordesigns, indem du PenNode JSON-Bäume schreibst. Verwende die op CLI oder MCP Tools, um Knoten auf der OpenPencil-Leinwand zu erstellen, zu lesen, zu aktualisieren und zu löschen.
Wann verwenden
- Erstellen oder Ändern von UI-Designs in
.op-Dateien - Verwenden der
opCLI zum Skripten von Designoperationen - Entwerfen über MCP Tools (
batch_design,insert_node,design_skeleton) - Referenz für PenNode-Schema, Rollen oder Layoutregeln benötigt
Kurzreferenz — op CLI
# App-Steuerung
op start [--desktop|--web] # App starten
op stop # Laufende Instanz stoppen
op status # Prüfen, ob die App läuft
# Dokument
op open [datei.op] # Datei öffnen oder mit Live-Leinwand verbinden
op save <datei.op> # Aktuelles Dokument speichern
op get [--depth N] [--pretty] # Dokumentbaum abrufen
op selection [--depth N] # Aktuelle Leinwandauswahl abrufen
op read-nodes [id...] [--depth N] [--vars] # Knoten-Unterbäume mit optionaler Variablenauflösung lesen
op layout [--parent P] [--depth N] # Layoutbaum mit berechneten Positionen abrufen
op find-space [--direction D] [--width N] [--height N] # Leeren Platz auf der Leinwand finden
# Knotenoperationen
op insert '<json>' [--parent P] # Knoten einfügen (--index N, --post-process)
op update <id> '<json>' # Knoten aktualisieren
op delete <id> # Knoten löschen
op move <id> <parent> [index] # Knoten verschieben
op copy <id> <parent> # Knoten tiefenkopieren
op replace <id> '<json>' # Knoten ersetzen
# Batch-Design
op design '<dsl>' # Batch-Design DSL (inline, @datei, oder stdin) [--canvas-width N]
op design @ui.js # JavaScript-Skript in Sandbox: I(parent, obj) + Schleifen (.js/.mjs impliziert --script)
op design '<js>' --script # Gleiches, inline/stdin (Flag MUSS der Nutzlast FOLGEN)
# Gestaffelter Workflow
op design:skeleton '<json>' # Abschnittsstruktur erstellen
op design:content <id> '<json>' # Abschnittsinhalt befüllen
op design:refine --root-id <id> # Validieren + automatisch korrigieren (löst Icons auf) [--canvas-width N]
# Import
op import:svg <datei.svg> [--parent P] # SVG als bearbeitbare Knoten importieren
op import:figma <datei.fig> [--out ausgabe.op] # Figma .fig in .op-Dokument konvertieren
# Seiten
op page list # Alle Seiten auflisten
op page add [--name N] # Neue Seite hinzufügen
op page remove <id> # Seite entfernen
op page rename <id> '<name>' # Seite umbenennen
op page reorder <id> <index> # Seite an Position verschieben
op page duplicate <id> # Seite mit neuen IDs klonen
# Variablen & Themes
op vars / op vars:set '<json>' # Variablen (--replace, um alle zu ersetzen)
op themes / op themes:set '<json>' # Themes (--replace, um alle zu ersetzen)
op theme:save <datei.optheme> # Aktuelles Theme als Vorgabedatei speichern
op theme:load <datei.optheme> # Theme-Vorgabedatei laden
op theme:list <verzeichnis> # .optheme-Vorgaben in Verzeichnis auflisten
# Codegen-Pipeline
op codegen:plan '<json>' # Codegen-Plan einreichen (Framework, rootIds, Optionen)
op codegen:submit '<json>' # Code-Chunk für einen Knoten einreichen
op codegen:assemble [--framework F] # Alle eingereichten Chunks zu endgültiger Ausgabe zusammenfügen
op codegen:clean # Codegen-Status löschen
Globale Flags: --file <pfad>, --page <id>, --pretty. Eingaben: Inline-String, @dateipfad oder - (stdin).
Designs erstellen — Drei Ansätze
Ansatz 1: op insert (Empfohlen)
Der zuverlässigste Weg, Designs zu erstellen. Verwende --parent, um den übergeordneten Knoten anzugeben. Erfasse die zurückgegebene nodeId, um später darauf zu verweisen. Beende immer mit design:refine, um Icons aufzulösen und das Layout zu validieren.
# Root-Frame erstellen, ID erfassen
ROOT=$(op insert '{"type":"frame","name":"Page","width":375,"height":812,"layout":"vertical"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")
# Kinder mit --parent einfügen
op insert --parent "$ROOT" '{"type":"text","content":"Hello","fontSize":28,"fontWeight":700}'
# Nachbearbeitung: Icons auflösen, Layout validieren
op design:refine --root-id "$ROOT"
Ansatz 2: Batch-Design DSL
Eine Operation pro Zeile. Ergebnisse mit name= für spätere Referenz binden. Am besten für einfache, flache Strukturen.
Einschränkung: Der DSL-Parser kann tief verschachteltes JSON nicht verarbeiten (z. B.
children-Arrays mit verschachtelten Objekten oder mehrere Ebenen von Array-Verschachtelung). Halte jedenI()-Aufruf auf einer einzelnen Verschachtelungsebene. Für komplexe Knoten mit Kindern verwende separateI()-Aufrufe für Eltern und Kinder oderop insert --parent.
root=I(null, { "type": "frame", "width": 1200, "layout": "vertical" })
nav=I(root, { "type": "frame", "role": "navbar", "height": 72 })
U(nav, { "fill": [{"type": "solid", "color": "#FFFFFF"}] })
card2=C(card1, grid, { "name": "Card 2" })
M(sidebar, main, 0)
D(old_section)
R(old_btn, { "type": "rectangle", "role": "button" })
| Op | Syntax | Aktion |
|---|---|---|
I | name=I(parent, { knoten }) | Einfügen |
U | U(ref, { aktualisierungen }) | Aktualisieren |
C | name=C(quelle, parent, { überschreibungen }) | Kopieren |
R | name=R(ref, { knoten }) | Ersetzen |
M | M(ref, parent, index?) | Verschieben |
D | D(ref) | Löschen |
G | name=G(parent, "suche", "abfrage") | Bild über Suche generieren |
DSL-sicheres Muster — Eltern und Kinder immer separat einfügen:
btn=I(form, {"type":"rectangle","role":"button","width":"fill_container","height":50,"cornerRadius":12,"fill":[{"type":"solid","color":"#111111"}],"layout":"horizontal","justifyContent":"center","alignItems":"center"})
I(btn, {"type":"text","content":"Submit","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]})
Ansatz 3: Skriptmodus (Schleifen & datengesteuert — EMPFOHLEN für wiederholte Strukturen)
op design @ui.js # .js / .mjs-Datei impliziert Skriptmodus
op design '<js-code>' --script # inline oder stdin; --script MUSS der Nutzlast FOLGEN
Über MCP: rufe batch_design mit dem script-Argument auf (genau EINES von nodes_json | operations | script pro Aufruf). Dies ist das GLEICHE Protokoll, das die internen Design-Agenten von OpenPencil verwenden; befolge denselben Vertrag:
Schreibe ein JavaScript-Programm (kein Prosa, keine Markdown-Umrandungen), das das Design durch Aufrufe der globalen Funktion I(parent, knoten) erstellt:
const id = I(parent, { ...knoten... }); // fügt Knoten ein, GIBT seine ID zurück (ein String)
parent ist null für einen Root-Frame, ansonsten eine ID, die von einem FRÜHEREN I(...)-Aufruf zurückgegeben wurde. Ein Knoten ist nur dann ein Kind von X, wenn du I(X, {...}) aufrufst.
I(...) ist die EINZIG verfügbare Funktion — es gibt keine Konsole und keinen anderen Builder. Rufe keine console.log oder andere Hilfsfunktionen auf; rufe einfach I(...) auf. Der Skriptmodus ist nur zum Einfügen; verwende die DSL-Ops (Ansatz 2) zum Aktualisieren/Verschieben/Löschen.
VERWENDE ECHTES JAVASCRIPT — const/let, Daten-Arrays und for...of / .forEach-Schleifen — um wiederholte Strukturen (Tabellenzeilen, Navigationselemente, Karten, Listenelemente) durch Iteration über ein Daten-Array zu erzeugen. BEVORZUGT eine Schleife gegenüber dem Kopieren/Einfügen nahezu identischer I(...)-Aufrufe.
Jedes Knotenobjekt beginnt mit type ("frame"/"text"/"rectangle"/"ellipse"/"path"/"icon_font") und verwendet camelCase-Eigenschaften (cornerRadius, fontSize, fontWeight, justifyContent, alignItems, clipContent). Setze KEIN x/y auf Kinder innerhalb von Layout-Frames.
Beispiel:
const sec = I(null, {type:"frame", name:"Clients", layout:"vertical", width:"fill_container", gap:0});
const tbl = I(sec, {type:"frame", layout:"vertical", width:"fill_container"});
const rows = [{name:"Alice Chen", status:"Active"}, {name:"Bob Ito", status:"VIP"}];
for (const r of rows) {
const row = I(tbl, {type:"frame", layout:"horizontal", width:"fill_container", padding:[12,16]});
const c1 = I(row, {type:"frame", width:"fill_container"}); I(c1, {type:"text", content:r.name});
const c2 = I(row, {type:"frame", width:"fill_container"}); I(c2, {type:"text", content:r.status});
}
Generiere JEDE Zeile/Karte/jedes Element mit realistischen Werten. Gib NUR das JavaScript-Programm aus.
CLI/MCP-Hinweise:
- Verschachtelte
children-Arrays sind HIER SICHER — die Engine serialisiert jedes Objekt zu perfektem einzeiligem JSON, sodass die Einschränkung der einzelnen Verschachtelungsebene des DSL nicht zutrifft. Bevorzuge trotzdem separateI()-Aufrufe, wenn du die Elternbindung benötigst. - Knoten-IDs werden beim Einfügen neu zugeordnet — verweise nach dem Aufruf nicht auf eine erstellte
"id"; nur die zurückgegebene Bindung ist sinnvoll, und nur innerhalb dieses Skripts. - Grenzen: 256 KiB Quelle, 4096 Einfügungen, 8 MiB aufgezeichnete Ausgabe, 2 s CPU, 64 MiB Speicher. Ein in der Mitte einer Anweisung abgeschnittenes Skript wird nach bestem Wissen und Gewissen repariert (das vollständige Präfix wird trotzdem ausgeführt).
STRENGE JSON-Regeln
Wenn du PenNode JSON ausgibst (über op insert, op design, batch_design, insert_node), MUSST du strikt gültiges JSON erstellen. Häufige Fehler, die das Parsing unterbrechen:
- Jede Eigenschaft MUSS sowohl einen Schlüssel als auch einen Wert haben. Gib NIEMALS
": 50oder: 50ohne Schlüsselnamen aus. Dies passiert oft beim Kürzen/Neuformatieren — doppelt prüfen. - Jeder Schlüssel MUSS ein doppelt-angeführter, nicht leerer String sein.
fillist IMMER ein Array:"fill": [{"type": "solid", "color": "#hex"}]. Die Kurzform"fill": "#hex"funktioniert, aber die Array-Form ist die kanonische Form.strokeist ein Objekt mit einemfill-Array:"stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}. NIEMALS"stroke": {"thickness": 1, "color": "#hex"}oder"stroke": "#hex"(der Parser konvertiert diese automatisch, aber die korrekte Form wird bevorzugt).- KEINE abschließenden Kommas vor
}oder]. - KEINE Kommentare innerhalb von JSON (
//oder/* */). - Verwende gerade doppelte Anführungszeichen
", keine typografischen/geschweiften Anführungszeichen. contentfür Text, NICHTtext:{"type": "text", "content": "Hallo"}.iconFontNamefür Icons, NICHTiconNameodericon:{"type": "icon_font", "iconFontName": "schloss"}.- Bevor du das JSON finalisierst, überprüfe gedanklich: Jeder Schlüssel hat einen Wert, jeder Wert hat einen Schlüssel, alle Klammern passen.
PenNode-Schema
Gemeinsame Eigenschaften
{
"type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
"name": "Anzeigename",
"role": "semantische-rolle",
"x": 0, "y": 0,
"rotation": 0, "opacity": 1, "visible": true
}
Container-Eigenschaften (frame, rectangle, group, ellipse)
{
"width": 400, // Zahl | "fill_container" | "fit_content"
"height": 300,
"layout": "vertical", // "none" | "vertical" | "horizontal"
"gap": 16,
"padding": [16, 24], // Zahl | [v, h] | [oben, rechts, unten, links]
"justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
"alignItems": "center", // "start" | "center" | "end"
"clipContent": true,
"cornerRadius": 12, // Zahl | [ol, or, ur, ul]
"fill": [{ "type": "solid", "color": "#FFFFFF" }],
"stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }], "align": "inside", "dashPattern": [5, 3] },
"effects": [{ "type": "shadow", "offsetX": 0, "offsetY": 4, "blur": 12, "spread": 0, "color": "rgba(0,0,0,0.08)" }],
"children": []
}
Text
{
"type": "text",
"content": "Hallo", // String oder StyledTextSegment[]
"fontSize": 16, "fontFamily": "Inter", "fontWeight": 600,
"textAlign": "center", // "left" | "center" | "right"
"textGrowth": "fixed-width", // "auto" | "fixed-width" | "fixed-width-height"
"lineHeight": 1.5, "letterSpacing": 0,
"fill": [{ "type": "solid", "color": "#111111" }]
}
Rich-Text: "content": [{ "text": "Fett ", "fontWeight": "bold" }, { "text": "normal" }]
Icons — Zwei Optionen
Option A: icon_font (EMPFOHLEN — rendert direkt, keine Nachbearbeitung erforderlich)
{ "type": "icon_font", "name": "Schloss-Symbol", "iconFontName": "schloss",
"width": 20, "height": 20,
"fill": [{ "type": "solid", "color": "#6B7280" }] }
Das Feld ist iconFontName (NICHT iconName, NICHT icon). Werte sind Lucide-Namen in Kleinbuchstaben mit Bindestrich: mail, lock, eye, eye-off, chrome, apple, message-circle, x, arrow-right, search, heart, star, check, plus, bell, home, user, settings, chevron-right, download, globe, layers, zap, shield, play.
Funktioniert in ALLEN Kontexten: CLI, MCP-Tools oder direkte .op-Dateien — kein design:refine erforderlich.
Option B: path (erfordert Nachbearbeitung)
{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
PascalCase + "Icon"-Suffix. Wird während der Nachbearbeitung automatisch aus dem Lucide-Set aufgelöst.
Pfad-Icons benötigen Nachbearbeitung. Führe nach dem Einfügen von Pfad-Knoten
op design:refine --root-id <id>aus oder verwendeop insert --post-process. Ohne dies werden Pfad-Icons nicht visuell dargestellt. Der eigenständige MCP-Server (verwendet von ACP-Agenten) hat KEINE registrierten Hook-Implementierungen, sodass Pfad-Icons dort NICHT aufgelöst werden — bevorzugeicon_fontin MCP-Kontexten.
Bild
{ "type": "image", "src": "https://example.com/photo.jpg", "width": 400, "height": 300,
"objectFit": "crop", "cornerRadius": 12 }
KI-Bildplatzhalter (aufgelöst durch design:refine):
{ "type": "image", "width": 400, "height": 300,
"imagePrompt": "Ein moderner Büroarbeitsplatz mit natürlichem Licht",
"imageSearchQuery": "moderner Büroarbeitsplatz" }
Bildanpassungen (alle -100 bis 100): exposure, contrast, saturation, temperature, tint, highlights, shadows.
Polygon
{ "type": "polygon", "polygonCount": 6, "width": 80, "height": 80, "cornerRadius": 4,
"fill": [{ "type": "solid", "color": "#6366F1" }] }
Icon-Schriftart
{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
Linie
{ "type": "line", "x2": 200, "y2": 0,
"stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }
Fülltypen
{ "type": "solid", "color": "#3B82F6" }
{ "type": "lin| Gradient | Bild | Keine }
Rollen
Frühe Identifikation von Mustern unterstützt durch Vorschläge:
| Rolle | Beschreibung | Kind-Layout |
|---|---|---|
navbar | Horizontale Navigationsleiste | horizontal |
sidebar | Vertikales Seitenmenü | vertical |
card | Karten-Container | vertical |
button | Klickbares Element | horizontal |
input | Texteingabefeld | horizontal |
list | Vertikale Liste | vertical |
table | Tabellenstruktur | vertical |
modal | Overlay-Dialog | vertical |
tooltip | Kleiner Infotipp | horizontal |
badge | Kleine Statusmarkierung | horizontal |
avatar | Profilbild-Container | vertical |
divider | Trennlinie | horizontal |
header | Seitenkopf | horizontal |
footer | Seitenfuß | horizontal |
hero | Großer Werbebereich | vertical |
stats | Statistikkarten-Bereich | horizontal |
pricing | Preistabelle | horizontal |
faq | Fragen & Antworten | vertical |
testimonial | Kundenbewertung | vertical |
cta | Handlungsaufforderung | horizontal |
logo | Logo-Bereich | horizontal |
search | Suchleiste | horizontal |
menu | Menü/Liste von Optionen | vertical |
Layout-Regeln
Flexbox-ähnliches Layout. Jeder Frame definiert eine Richtung (vertical oder horizontal) und verteilt Kinder gemäß justifyContent und alignItems.
- Hauptachse = Layout-Richtung.
justifyContentsteuert die Verteilung entlang der Hauptachse. - Querachse = Senkrecht zur Layout-Richtung.
alignItemssteuert die Ausrichtung entlang der Querachse. flex-Eigenschaft auf Kindern, um proportionalen Raum zu beanspruchen:"flex": 1.grow/shrinksteuern das Dehnungs-/Schrumpfverhalten.
fill_container vs fit_content
fill_container— Dehnt sich auf die Größe des Containers (abzüglich Abständen/Polstern) in der Querachse aus.fit_content— Schrumpft auf die Größe des größten Kindes entlang der Haupt- und Querachse.
Polster- und Abstands-Kurzschrift
"padding": 16 // Alle Seiten
"padding": [16, 24] // [oben/unten, links/rechts]
"padding": [16, 24, 32] // [oben, links/rechts, unten]
"padding": [16, 24, 32, 40] // [oben, rechts, unten, links]
gap: Abstand zwischen den Kindern (einzelne Zahl).- Abstände werden auf der Hauptachse angewendet.
Positionierung außerhalb des Layouts
Setze x / y auf einem Frame, um die absolute Position zu erzwingen. Nur verfügbar, wenn der übergeordnete Frame "layout": "none" verwendet (absolute Positionierung).
{ "type": "frame", "width": 100, "height": 100,
"layout": "none", "x": 200, "y": 300 }
Wenn "layout": "none" für den übergeordneten Frame festgelegt ist, werden Kinder über ihren x/y-Koordinaten positioniert. Standardmäßig wird layout-basiertes Layout verwendet.
Wichtig: Ein Knoten mit einem
layout-Wert, der nicht"none"ist, verwendet die Layout-Engine, um Kinder gemäß den Flexbox-Regeln zu positionieren. Um die manuelle Positionierung zu aktivieren, setze"layout": "none"auf dem übergeordneten Knoten.
Semantischer Inhalt (Rich-Text)
content-Feld auf dem Knotentyp "text":
"content": [
{ "text": "Willkommen, " },
{ "text": "Benutzer", "fontWeight": "bold" },
{ "text": " — " },
{ "text": "Hier ist Ihr Dashboard", "fontWeight": 500, "fill": [{"type": "solid", "color": "#6B7280"}] }
]
Kurzschrift & Vereinfachungen
Diese Kurzformen werden automatisch in die vollständige Form erweitert:
| Kurzschrift | Wird zu |
|---|---|
"fill": "#hex" | [{"type":"solid","color":"#hex"}] |
"stroke": "#hex" | {"thickness":1,"fill":[{"type":"solid","color":"#hex"}]} |
"stroke": N | {"thickness":N,"fill":[{"type":"solid","color":"#000000"}]} |
Tipps
design:refinefinalisiert Designs — validiert das Layout, löst Pfad-Icons auf und generiert KI-Bilder aus Aufforderungen. Führeop design:refine --root-id <id>nach dem Einfügen von Pfad-Icons,imagePrompt- oderimageSearchQuery-Bildern aus.op read-nodesmit--varszeigt Variablen gebunden statt aufgelöst an.- Verwende
--prettyfür menschenlesbare JSON-Ausgabe. - Der Skriptmodus (
op design @file.js) ist einschränkend, aber sicher — es gibt keine globalen Objekte außerI(). Kein Dateizugriff, kein Netzwerk. - Füge keine
op-Befehle in Design-Skripte ein — verwende separate Shell-Schritte. op designmit DSL liest zuerst vollständig von stdin — leite immer die vollständige Eingabe vor dem Ausführen weiter.- Für UI-Komponentenbibliotheken — halte eine
.op-Datei mit Komponenten-Frames undop copyvon dort. - Überspringe
confirm-Aufforderungen durch Exportieren vonOPENPENCIL_SESSION_TOKEN. - Wenn du das Layout änderst, nachdem Kinder vorhanden sind, passe die Kinder an die neue Ausrichtung an (z. B. nach dem Wechsel von horizontal zu vertical müssen die Kinder
width:"fill_container"statt fixer Breiten haben). - Gib beim Erstellen ganzer Seiten Vorlagen den Vorzug —
design:skeleton+design:contenthilft, das Layout von den Inhalten zu trennen.
Dateiformat-Referenz: .op
Ein .op-Dokument enthält einen einzelnen JSON-Baum mit dem Schema:
{
"version": "2.0",
"name": "Mein Design",
"variables": {},
"themes": [],
"pages": [
{
"id": "page-abc123",
"name": "Seite 1",
"root": { /* PenNode */ }
}
]
}
Explizite IDs in Knoten ("id": "mein-widget") bleiben beim Bearbeiten erhalten, werden aber beim op copy neu zugewiesen. Es ist sicherer, IDs vom System zuweisen zu lassen und stattdessen Variablenbindungen zu verwenden.