/understand-figma

Analyse un fichier Figma et produit un graphe de connaissances de design interactif dans le tableau de bord existant.

Prérequis

• FIGMA_TOKEN variable d'environnement — un token d'accès personnel Figma (créez-en un sur https://www.figma.com/settings). S'il est manquant, ARRÊTEZ et dites à l'utilisateur :

  Définissez d'abord un token Figma : créez-en un sur figma.com/settings, puis export FIGMA_TOKEN=<token>.

• Node ≥ 22, pnpm ≥ 10.

Sécurité : le token est lu uniquement depuis l'environnement et transitera uniquement dans l'en-tête de requête X-Figma-Token. Ne l'écrivez jamais dans le graphe, meta.json, les logs ou les fichiers intermédiaires. Cette skill effectue des appels sortants vers api.figma.com — contrairement à /understand, elle n'est pas entièrement hors ligne. Dites-le à l'utilisateur une fois.

Phase 0 — Pré-vol

1. Analysez $ARGUMENTS pour une URL Figma ou une clé de fichier brute (le token sans flag) et un optionnel --language <lang>.
2. Résolvez PROJECT_ROOT vers le répertoire de travail courant. Résolvez le répertoire de données $UA_DIR une fois et réutilisez-le pour chaque lecture et écriture ci-dessous : UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)" — l'héritage .understand-anything/ s'il existe déjà, sinon le nouveau .ua/. Puisque chaque phase peut s'exécuter dans un shell frais, reportez $UA_DIR en avant comme $PROJECT_ROOT, en le re-résolvant avec la même ligne si un bloc de commande ultérieur en a besoin.
3. Résolvez PLUGIN_ROOT et assurez-vous que le core est construit (même logique que /understand Phase 0.1.5). Si packages/core/dist/figma/index.js est manquant, exécutez :

   cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build

4. mkdir -p $UA_DIR/intermediate.

Phase 1 — FETCH & PARSE (déterministe)

Exécutez le script de scan fourni (<SKILL_DIR> est le répertoire de cette skill) :

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

Il écrit $UA_DIR/intermediate/scan-manifest.json et affiche les comptages de nœuds. Relayez les comptages à l'utilisateur. S'il se termine avec un code non-zéro, relayez stderr et ARRÊTEZ.

Si le scan affiche UP_TO_DATE, rapportez « Le graphe de design est déjà à jour pour cette version de fichier Figma » et ARRÊTEZ. Pour forcer une reconstruction complète, relancez avec UNDERSTAND_FIGMA_FORCE=1 défini dans l'environnement.

Phase 2 — ANALYZE (enrichissement LLM)

1. Lisez scan-manifest.json. Groupez les nœuds par lots d'environ 15, groupés par page autant que possible.
2. Pour chaque lot, déployez un sous-agent en utilisant la définition d'agent design-analyzer (agents/design-analyzer.md). Passez :
   • le lot de nœuds (id, type, name, figmaMeta, noms des enfants, utilisation de tokens),
   • la liste complète des IDs de nœuds existants,
   • $INTERMEDIATE_DIR = $UA_DIR/intermediate,
   • le numéro du lot pour le nommage de la sortie. L'agent écrit analysis-batch-<N>.json. Ajoutez $LANGUAGE_DIRECTIVE si --language a été fourni (réutilisez le texte de la directive de /understand).
3. Exécutez jusqu'à 5 lots en parallèle. Si un lot échoue, enregistrez un avertissement et continuez — le manifeste est une base solide.

Phase 3 — MERGE

node <SKILL_DIR>/figma-merge.mjs "$PROJECT_ROOT"

Il combine scan-manifest.json + analysis-batch-*.json, exécute mergeDesignGraph (valide, rattache kind:"design"), et écrit knowledge-graph.json + meta.json. Relayez les statistiques affichées et tout problème autre que auto-corrected.

Phase 4 — SAVE & LAUNCH

1. Nettoyez les fichiers intermédiaires sauf scan-manifest.json :

   INTER="$UA_DIR/intermediate"
   find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-manifest.json' -exec rm -rf {} +

2. Rapportez un résumé : nom du projet, comptages par type de nœud, arêtes par type, couches, étapes de visite et le chemin $UA_DIR/knowledge-graph.json.
3. Lancez automatiquement le tableau de bord en invoquant la skill /understand-dashboard.