Communitygithub.com

OpenPencil Design

Compétence LLM pour concevoir avec OpenPencil via l'interface CLI `op` et les outils MCP.

Qu'est-ce que OpenPencil Design ?

Cette compétence permet aux agents IA, comme Claude Code ou Codex, de générer des designs vectoriels de qualité production en écrivant des arbres JSON PenNode. Elle est utile pour les développeurs et designers qui souhaitent automatiser la création et la modification d'interfaces utilisateur directement depuis la ligne de commande ou via des outils MCP (Modèle-Client-Protocole). La compétence prend en charge trois approches principales : l'insertion de nœuds individuels avec `op insert`, le langage DSL par lots pour des opérations simples, et un mode script JavaScript pour des structures de données répétitives et complexes. Elle fournit également des schémas stricts pour les nœuds PenNode, y compris les types de remplissage, les traits, les effets et les propriétés de mise en page, garantissant que le JSON produit soit valide et fonctionnel. La compétence couvre également la gestion des pages, des thèmes, des variables, l'importation depuis SVG et Figma, et un pipeline de génération de code. Elle recommande l'utilisation de `icon_font` au lieu de chemins d'icônes dans les contextes MCP pour éviter les problèmes de post-traitement. En suivant les règles JSON strictes et les exemples fournis, les agents peuvent créer des designs complexes et cohérents sans intervention manuelle.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add ZSeven-W/openpencil-skill

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Conception OpenPencil

Générez des designs vectoriels de qualité production en écrivant des arbres JSON PenNode. Utilisez l'interface CLI op ou les outils MCP pour créer, lire, mettre à jour et supprimer des nœuds sur le canevas OpenPencil.

Quand l'utiliser

  • Créer ou modifier des designs d'interface utilisateur dans des fichiers .op.
  • Utiliser l'interface CLI op pour scripter des opérations de design.
  • Concevoir via les outils MCP (batch_design, insert_node, design_skeleton).
  • Besoin de référence pour le schéma PenNode, les rôles ou les règles de mise en page.

Référence rapide — CLI op

# Contrôle de l'application
op start [--desktop|--web]           # Lancer l'application
op stop                              # Arrêter l'instance en cours
op status                            # Vérifier si elle est en cours d'exécution

# Document
op open [file.op]                    # Ouvrir un fichier ou se connecter au canevas en direct
op save <file.op>                    # Sauvegarder le document actuel
op get [--depth N] [--pretty]        # Obtenir l'arborescence du document
op selection [--depth N]             # Obtenir la sélection actuelle du canevas
op read-nodes [id...] [--depth N] [--vars]  # Lire les sous-arbres de nœuds avec résolution facultative des variables
op layout [--parent P] [--depth N]   # Instantané de l'arbre de mise en page avec les positions calculées
op find-space [--direction D] [--width N] [--height N]  # Trouver un espace vide sur le canevas

# Opérations sur les nœuds
op insert '<json>' [--parent P]     # Insérer un nœud (--index N, --post-process)
op update <id> '<json>'              # Mettre à jour un nœud
op delete <id>                       # Supprimer un nœud
op move <id> <parent> [index]        # Déplacer un nœud
op copy <id> <parent>                # Copie profonde d'un nœud
op replace <id> '<json>'             # Remplacer un nœud

# Conception par lots
op design '<dsl>'                    # DSL de conception par lots (en ligne, @fichier ou stdin) [--canvas-width N]
op design @ui.js                     # Script JavaScript en bac à sable : I(parent, obj) + boucles (.js/.mjs implique --script)
op design '<js>' --script            # Identique, en ligne/stdin (l'indicateur DOIT SUIVRE la charge utile)

# Flux de travail en couches
op design:skeleton '<json>'          # Créer la structure des sections
op design:content <id> '<json>'      # Remplir le contenu de la section
op design:refine --root-id <id>      # Valider + corriger automatiquement (résout les icônes) [--canvas-width N]

# Importation
op import:svg <file.svg> [--parent P]       # Importer un SVG en tant que nœuds modifiables
op import:figma <file.fig> [--out out.op]   # Convertir un fichier Figma .fig en document .op

# Pages
op page list                         # Lister toutes les pages
op page add [--name N]               # Ajouter une nouvelle page
op page remove <id>                  # Supprimer une page
op page rename <id> '<name>'         # Renommer une page
op page reorder <id> <index>         # Déplacer une page vers une position
op page duplicate <id>               # Cloner une page avec de nouveaux identifiants

# Variables et thèmes
op vars / op vars:set '<json>'       # Variables (--replace pour tout remplacer)
op themes / op themes:set '<json>'   # Thèmes (--replace pour tout remplacer)
op theme:save <file.optheme>         # Sauvegarder le thème actuel en tant que fichier prédéfini
op theme:load <file.optheme>         # Charger un fichier de thème prédéfini
op theme:list <directory>            # Lister les préréglages .optheme dans un répertoire

# Pipeline de génération de code
op codegen:plan '<json>'             # Soumettre un plan de génération de code (framework, rootIds, options)
op codegen:submit '<json>'           # Soumettre un bloc de code pour un nœud
op codegen:assemble [--framework F]  # Assembler tous les blocs soumis en sortie finale
op codegen:clean                     # Effacer l'état de la génération de code

Indicateurs globaux : --file <chemin>, --page <id>, --pretty. Entrées : chaîne en ligne, @cheminfichier ou - (stdin).

Création de designs — Trois approches

Approche 1 : op insert (Recommandée)

La manière la plus fiable de créer des designs. Utilisez --parent pour spécifier le nœud parent. Capturez le nodeId retourné pour le référencer plus tard. Terminez toujours par design:refine pour résoudre les icônes et valider la mise en page.

# Créer un cadre racine, capturer son ID
ROOT=$(op insert '{"type":"frame","name":"Page","width":375,"height":812,"layout":"vertical"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

# Insérer des enfants en utilisant --parent
op insert --parent "$ROOT" '{"type":"text","content":"Bonjour","fontSize":28,"fontWeight":700}'

# Post-traitement : résoudre les icônes, valider la mise en page
op design:refine --root-id "$ROOT"

Approche 2 : DSL de conception par lots

Une opération par ligne. Liez les résultats avec nom= pour les référencer ultérieurement. Idéal pour les structures simples et plates.

Limitation : L'analyseur DSL ne peut pas gérer le JSON profondément imbriqué (par exemple, les tableaux children avec des objets imbriqués ou plusieurs niveaux d'imbrication de tableaux). Gardez chaque appel I() à un seul niveau d'imbrication. Pour les nœuds complexes avec des enfants, utilisez des appels I() séparés pour le parent et les enfants, ou utilisez op 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" })
OpSyntaxeAction
Inom=I(parent, { nœud })Insérer
UU(ref, { mises_à_jour })Mettre à jour
Cnom=C(source, parent, { substitutions })Copier
Rnom=R(ref, { nœud })Remplacer
MM(ref, parent, index?)Déplacer
DD(ref)Supprimer
Gnom=G(parent, "recherche", "requête")Générer une image par recherche

Motif sûr DSL — insérez toujours le parent et les enfants séparément :

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":"Soumettre","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]})

Approche 3 : Mode script (boucles et piloté par les données — RECOMMANDÉ pour les structures répétées)

op design @ui.js                 # Le fichier .js / .mjs implique le mode script
op design '<code js>' --script   # en ligne ou stdin ; --script DOIT SUIVRE la charge utile

Via MCP : appelez batch_design avec l'argument script (exactement UN de nodes_json | operations | script par appel). Il s'agit du MÊME protocole que celui utilisé par les agents de conception internes d'OpenPencil ; suivez le même contrat :

Écrivez un programme JavaScript (pas de prose, pas de balises markdown) qui construit le design en appelant la fonction globale I(parent, node) :

const id = I(parent, { ...node... });   // insère un nœud, RETOURNE son id (une chaîne)

parent est null pour un cadre racine, sinon un id retourné par un appel ANTÉRIEUR à I(...). Un nœud est un enfant de X uniquement si vous appelez I(X, {...}).

I(...) est la SEULE fonction disponible — il n'y a pas de console et aucun autre constructeur. N'appelez pas console.log ou une aide ; appelez simplement I(...). Le mode script est réservé à l'insertion ; utilisez les opérations DSL (Approche 2) pour la mise à jour/déplacement/suppression.

UTILISEZ DU JAVASCRIPT RÉEL — const/let, tableaux de données et boucles for...of / .forEach — pour générer des structures répétées (lignes de tableau, éléments de navigation, cartes, éléments de liste) en bouclant sur un tableau de données. PRÉFÉREZ une boucle au copier-coller d'appels I(...) quasi identiques.

Chaque objet nœud commence par type ("frame"/"text"/"rectangle"/"ellipse"/"path"/"icon_font") et utilise des propriétés en camelCase (cornerRadius, fontSize, fontWeight, justifyContent, alignItems, clipContent). Ne définissez PAS x/y sur les enfants dans les cadres de mise en page.

Exemple :

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:"Actif"}, {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});
}

Générez CHAQUE ligne/carte/élément avec des valeurs réalistes. Produisez UNIQUEMENT le programme JavaScript.

Notes CLI/MCP :

  • Les tableaux children imbriqués sont SÛRS ici — le moteur sérialise chaque objet en JSON parfait sur une seule ligne, donc la limitation de l'imbrication unique du DSL ne s'applique pas. Préférez des appels I() séparés de toute façon lorsque vous avez besoin de la liaison parent.
  • Les identifiants de nœud sont remappés lors de l'insertion — ne référencez pas un "id" créé après l'appel ; seule la liaison retournée est significative, et uniquement à l'intérieur de ce script.
  • Limites : Source de 256 Ko, 4096 insertions, sortie enregistrée de 8 Mo, CPU 2 s, mémoire 64 Mo. Un script tronqué au milieu d'une instruction est réparé au mieux (le préfixe complet est toujours exécuté).

Règles JSON strictes

Lorsque vous émettez du JSON PenNode (via op insert, op design, batch_design, insert_node), vous DEVEZ produire du JSON strictement valide. Les erreurs courantes qui cassent l'analyse :

  • Chaque propriété DOIT avoir à la fois une clé et une valeur. N'émettez JAMAIS ": 50 ou : 50 sans nom de clé. Cela se produit souvent lorsque vous tronquez/ reformatez — revérifiez.
  • Chaque clé DOIT être une chaîne non vide entre guillemets.
  • fill est TOUJOURS un tableau : "fill": [{"type": "solid", "color": "#hex"}]. La forme abrégée "fill": "#hex" fonctionne mais la forme tableau est la forme canonique.
  • stroke est un objet avec un tableau fill : "stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}. JAMAIS "stroke": {"thickness": 1, "color": "#hex"} ou "stroke": "#hex" (l'analyseur les convertit automatiquement mais la forme correcte est préférée).
  • PAS de virgules de fin avant } ou ].
  • PAS de commentaires dans le JSON (// ou /* */).
  • Utilisez des guillemets droits ", pas de guillemets intelligents/curls.
  • content pour le texte, PAS text : {"type": "text", "content": "Hello"}.
  • iconFontName pour les icônes, PAS iconName ou icon : {"type": "icon_font", "iconFontName": "lock"}.
  • Avant de finaliser le JSON, vérifiez mentalement : chaque clé a une valeur, chaque valeur a une clé, toutes les parenthèses correspondent.

Schéma PenNode

Propriétés communes

{
  "type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
  "name": "Nom d'affichage",
  "role": "rôle-sémantique",
  "x": 0, "y": 0,
  "rotation": 0, "opacity": 1, "visible": true
}

Propriétés du conteneur (frame, rectangle, group, ellipse)

{
  "width": 400,              // nombre | "fill_container" | "fit_content"
  "height": 300,
  "layout": "vertical",      // "none" | "vertical" | "horizontal"
  "gap": 16,
  "padding": [16, 24],       // nombre | [v, h] | [haut, droite, bas, gauche]
  "justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
  "alignItems": "center",    // "start" | "center" | "end"
  "clipContent": true,
  "cornerRadius": 12,        // nombre | [hg, hd, bd, bg]
  "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": []
}

Texte

{
  "type": "text",
  "content": "Bonjour",          // chaîne ou 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" }]
}

Texte enrichi : "content": [{ "text": "Gras ", "fontWeight": "bold" }, { "text": "normal" }]

Icônes — Deux options

Option A : icon_font (RECOMMANDÉE — rendu direct, aucun post-traitement nécessaire)

{ "type": "icon_font", "name": "Icône de verrouillage", "iconFontName": "lock",
  "width": 20, "height": 20,
  "fill": [{ "type": "solid", "color": "#6B7280" }] }

Le champ est iconFontName (PAS iconName, PAS icon). Les valeurs sont des noms Lucide en kebab-case minuscules : 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.

Fonctionne dans TOUS les contextes : CLI, outils MCP ou fichiers .op directs — aucun design:refine requis.

Option B : path (nécessite un post-traitement)

{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
  "fill": [{ "type": "solid", "color": "#111111" }] }

PascalCase + suffixe "Icon". Résolu automatiquement à partir de l'ensemble Lucide lors du post-traitement.

Les icônes de chemin ont besoin d'un post-traitement. Après avoir inséré des nœuds de chemin, exécutez op design:refine --root-id <id> ou utilisez op insert --post-process. Sans cela, les icônes de chemin ne s'afficheront pas visuellement. Le serveur MCP autonome (utilisé par les agents ACP) n'a PAS d'implémentations de hooks enregistrées, donc les icônes de chemin ne seront PAS résolues là-bas — préférez icon_font dans les contextes MCP.

Image

{ "type": "image", "src": "https://exemple.com/photo.jpg", "width": 400, "height": 300,
  "objectFit": "crop", "cornerRadius": 12 }

Espaces réservés d'images IA (résolus par design:refine) :

{ "type": "image", "width": 400, "height": 300,
  "imagePrompt": "Un espace de travail moderne avec lumière naturelle",
  "imageSearchQuery": "espace de travail moderne" }

Ajustements d'image (tous de -100 à 100) : exposure, contrast, saturation, temperature, tint, highlights, shadows.

Polygone

{ "type": "polygon", "polygonCount": 6, "width": 80, "height": 80, "cornerRadius": 4,
  "fill": [{ "type": "solid", "color": "#6366F1" }] }

Police d'icône

{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
  "fill": [{ "type": "solid", "color": "#111111" }] }

Ligne

{ "type": "line", "x2": 200, "y2": 0,
  "stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }

Types de remplissage

{ "type": "solid", "color": "#3B82F6" }
{ "type": "linear", "angle": 90, "stops": [{"position": 0, "color": "#3B82F6"}, {"position": 1, "color": "#8B5CF6"}] }
{ "type": "radial", "centerX": 0.5, "centerY": 0.5, "stops": [{"position": 0, "color": "#FFFFFF"}, {"position": 1, "color": "#1E3A8A"}] }
{ "type": "image", "src": "https://..." }

Rôles prédéfinis

navbar, hero, card, button, input, search, checkbox, radio, toggle, slider, badge, tab, list, table, modal, tooltip, dropdown, accordion, breadcrumb, pagination, progress_bar, spinner, avatar, chip, divider

Gestion des pages

Les pages sont des cadres racine de niveau supérieur. Les opérations suivantes sont disponibles :

op page list                         # Lister toutes les pages
op page add --name "Paramètres"      # Ajouter une nouvelle page nommée "Paramètres"
op page remove <id>                  # Supprimer une page par ID
op page rename <id> "Nouveau nom"    # Renommer une page
op page reorder <id> <index>         # Réorganiser les pages
op page duplicate <id>               # Dupliquer une page

Variables et thèmes

Les variables et thèmes permettent de gérer des valeurs réutilisables dans tout le document.

# Variables
typeset -l MA_COULEUR_PRIMAIRE="#3B82F6"
op vars:set '{"couleur_principale": "#3B82F6", "espacement": 16}'
op vars:set --replace '{"couleur_principale": "#2563EB"}'    # Remplacer toutes les variables

# Thèmes
op themes:set '{"sombre": {"bg": "#1A1A2E", "text": "#FFFFFF"}, "clair": {"bg": "#FFFFFF", "text": "#111111"}}'
op theme:save mon-theme.optheme     # Sauvegarder le thème actuel
op theme:load mon-theme.optheme     # Charger un thème
op theme:list ./themes              # Lister les thèmes disponibles

Pipeline de génération de code

Le pipeline codegen permet de générer du code à partir de designs PenNode.

# Étape 1 : Planifier la génération
op codegen:plan '{"framework": "react", "rootIds": ["id_du_cadre"], "options": {"typescript": true, "styling": "tailwind"}}'

# Étape 2 : Soumettre des blocs de code pour chaque nœud
op codegen:submit '{"nodeId": "...", "code": "<div>...</div>"}'

# Étape 3 : Assembler le code final
op codegen:assemble --framework react

# Étape 4 : Nettoyer
op codegen:clean

Importation

Importer un SVG

op import:svg icone.svg --parent "$PARENT_ID"   # Importer un SVG en tant qu'enfants modifiables

Importer depuis Figma

op import:figma design.fig --out design.op       # Convertir un fichier Figma .fig en .op

Règles de mise en page

  • Layout vertical : les enfants sont empilés verticalement, la largeur par défaut est fill_container.
  • Layout horizontal : les enfants sont côte à côte, la hauteur par défaut est fill_container.
  • JustifyContent : start, center, end, space_between, space_around.
  • AlignItems : start, center, end.
  • Padding : peut être un nombre unique, un tableau à 2 éléments [v, h] ou à 4 éléments [haut, droite, bas, gauche].
  • Gap : espace entre les enfants dans les conteneurs flexibles.
  • CornerRadius : peut être un nombre unique ou un tableau à 4 éléments [hg, hd, bd, bg].
  • Ne définissez PAS x/y sur les enfants dans les cadres de mise en page ; la mise en page est calculée automatiquement.
  • Utilisez "width": "fill_container" pour que la largeur remplisse le parent, "width": "fit_content" pour s'ajuster au contenu.

Skills associés