Figma to Claude Code — Contesto Design Strutturato per la CLI di Anthropic

L'istruzione "non re-implementare componenti che esistono già" è importante quando l'inventario dei componenti è condiviso. Claude Code può leggere design/components/inventory.json per identificare quali componenti sono già implementati e importarli piuttosto che rigenerarli.

Collegamento dei design token

Il tokens.json esportato da figmascope usa una struttura annidata W3C-ish con campi $value e $type:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

Chiedi a Claude Code di generare un blocco di estensione del tema tailwind.config.ts da questo file come primo passo, prima di implementare qualsiasi schermata. In questo modo tutte le implementazioni successive delle schermate possono usare gli alias dei token Tailwind in modo coerente:

claude --print "Leggi design/tokens.json e genera un blocco theme.extend per tailwind.config.ts.
Mappa i token colore su theme.extend.colors,
i token spaziatura su theme.extend.spacing, e la tipografia su
theme.extend.fontFamily / fontSize. Emetti solo l'oggetto di configurazione."

Vedi Esportazione Token Design per Agenti AI per un approfondimento sul formato dei token e il fallback per inferenza di frequenza che figmascope usa quando le Variabili Figma non sono configurate.

Gestione del livello delle stringhe

Ogni nodo di testo nel file Figma ottiene uno slot in strings.json. Le chiavi usano notazione a punto derivata dalla gerarchia dei frame:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

Istruisci Claude Code a usare queste chiavi come identificatori i18n. Invece di codificare la stringa "Everything you need" in JSX, il componente generato chiama t('home.hero.title') (o l'equivalente della tua libreria i18n). Il file di risorse è già in strings.json — devi solo importarlo o collegarlo alla tua configurazione i18n.

Se figmascope rileva una collisione — due nodi che generano la stessa chiave — emette un avviso strings-collision in _meta.json e aggiunge un suffisso numerico per disambiguare. Controlla _meta.json prima di avviare una sessione così sai cosa aspettarti.

Integrazione con CLAUDE.md

Se usi un file di contesto progetto CLAUDE.md, aggiungi una breve sezione che punta l'agente alla directory design. Questo si abbina bene all'approccio descritto in Consegna Design AI e complementa perché figmascope differisce dai plugin Figma inspector.

Aggiungi una sezione design come questa:

## Contesto design

Design token, IR del layout, render di riferimento e stringhe sono in `design/`.
Leggi sempre `design/CONTEXT.md` prima di implementare qualsiasi schermata.
I valori dei token sono in `design/tokens.json` — non codificare mai colori o spaziature.
I nomi canonici dei componenti sono in `design/components/inventory.json`.

Questo significa che ogni sessione di Claude Code nel progetto avrà automaticamente il contesto del design come parte della sua conoscenza operativa, senza che tu debba ripeterlo in ogni prompt.

Cosa l'agente ottiene davvero correttamente

Con il contesto strutturato, Claude Code ottiene in modo affidabile:

• Valori di spaziatura — perché sono in tokens.json come spacing.4 → 16px, non indovinati da uno screenshot
• Colori — valori hex esatti, non "sembra un arancione caldo"
• Tipografia — famiglia di font, dimensione, peso, altezza di riga, tutto tipizzato
• Direzione del layout — i nodi stack hanno un campo esplicito direction e gap
• Denominazione dei componenti — inventory.json è la fonte canonica, quindi nessun nome inventato
• Testo — strings.json impedisce all'agente di parafrasare o inventare testo segnaposto

Cosa richiede ancora la revisione umana: stati di interazione (hover, focus, active) non visibili nei frame Figma statici, timing delle animazioni, e breakpoint responsive che non erano esplicitamente progettati nel file. L'IR cattura il layout statico; il comportamento dinamico è fuori ambito.

Usare --dangerously-skip-permissions in ambienti controllati

Per pipeline automatizzate dove vuoi che Claude Code operi senza prompt di approvazione interattivi — per esempio in un passo CI che genera stub di componenti dopo un aggiornamento del design — puoi usare --dangerously-skip-permissions. Appropriato solo in ambienti sandboxed senza credenziali di produzione.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Leggi design/CONTEXT.md. Genera file stub di componenti per tutti i componenti
in design/components/inventory.json che non esistono già in src/components/.
Usa il formato TypeScript + React functional component. Includi un commento TODO
per ogni componente che fa riferimento al JSON della schermata rilevante.
EOF
)"

Nei flussi di lavoro degli sviluppatori di produzione, lascia i permessi interattivi. I prompt esistono per una buona ragione — Claude Code può e scriverà file, e vuoi sapere quali prima che lo faccia.

Controlla gli avvisi dell'export prima di inviare il prompt

figmascope emette avvisi in _meta.json per condizioni che potrebbero influenzare la qualità dell'output. Controllali prima di avviare una sessione Claude Code:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

Due avvisi a cui prestare attenzione:

• layout-mode-none-inferred — un frame non aveva auto-layout impostato. figmascope ha dedotto il layout dalle posizioni assolute dei figli, che è meno affidabile. Segnala la schermata rilevante nel tuo prompt: "Questa schermata usa posizionamento assoluto; genera di conseguenza."
• strings-collision — due nodi di testo hanno prodotto la stessa chiave di risorsa. figmascope disambigua con un suffisso numerico, ma dovresti verificare che le stringhe in strings.json siano corrette prima che l'agente generi chiamate i18n.

Flussi di lavoro Android e iOS

Claude Code non è limitato ai framework web. Il bundle di contesto è agnostico rispetto al framework — l'IR del layout e i token sono dati, non CSS. Per Jetpack Compose:

claude --print "$(cat <<'EOF'
Leggi design/CONTEXT.md e design/tokens.json.

Implementa design/screens/Home.json come schermata Jetpack Compose.
- Mappa i token colore su un MaterialTheme ColorScheme
- Mappa i token spaziatura su valori Dp (rimuovi il suffisso 'px', usa .dp)
- Mappa i token tipografia su MaterialTheme.typography
- Usa i nomi dei componenti da design/components/inventory.json come nomi Composable
- Fai riferimento a design/screens/Home.png per l'accuratezza visiva
EOF
)"

I nodi stack dell'IR si mappano naturalmente a Column (direzione: vertical) e Row (direzione: horizontal) in Compose. I nodi leaf con type: "text" diventano composable Text; type: "image" diventa Image o un segnaposto. Vedi Jetpack Compose da Figma per il pattern completo.

Versionamento del bundle di design

Tratta la directory design/ come qualsiasi altra dipendenza del progetto. Quando il design cambia significativamente, riesporta da figmascope.dev, committa, e nota il cambiamento nella PR:

# Controlla quando il bundle è stato esportato l'ultima volta vs quando il file Figma è stato modificato
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'AVVISO: Il file Figma è stato modificato {delta} dopo l\'ultimo export')
else:
    print('Il bundle è aggiornato')
"

Un bundle obsoleto significa che l'agente sta lavorando da un design superato. Il controllo del timestamp rileva questo prima che tu spenda tempo su una sessione di generazione di codice basata su specifiche superate.