Anvil - Da Codice a Figma

Il problema che volevo risolvere

Esiste uno scenario comune e fastidioso: hai un design system che vive nel codice (costruito nel tempo, ereditato da un progetto precedente, o generato da zero) e ad un certo punto hai bisogno di portarlo su Figma per collaborare con un team di design, per presentarlo a un cliente o per documentarlo visivamente senza doverlo ricostruire a mano componente per componente.

La domanda che mi sono posto è questa: Claude Code e figma-console-mcp possono automatizzare questo passaggio: da un sistema documentato in HTML a un design system vivo e utilizzabile su Figma?

Questo è un tentativo. Non una soluzione. Il verdetto è onesto.

Il setup

Ho chiamato il sistema Anvil (incudine), perché l'idea era forgiare qualcosa di solido usando l'AI come strumento industriale. Mi sono dato due giorni, partendo da zero, con Claude Code come unico strumento di generazione.

Lo scenario concreto che ho immaginato: un designer-developer con un sistema già in codice che vuole il corrispettivo Figma senza rifarlo a mano.

Il flow pianificato era lineare:

1. Generare il design system in HTML con Claude Code
2. Documentarlo con una logica token-based rigorosa
3. Importarlo su Figma via figma-console-mcp con figma-desktop-bridge
4. Valutare se il risultato è utilizzabile

Fase 1 — Generare il sistema con Claude Code

Le prime sessioni sono andate meglio del previsto. Ho impostato un'architettura a token su due livelli (primitivi e semantici) e Claude Code ha rispettato la struttura con una coerenza sorprendente. Ogni componente consumava solo token semantici, mai primitivi direttamente.

In due giorni e sette fasi di iterazione il sistema ha raggiunto una copertura ampia: tipografia, colori, spaziatura, bordi, oltre venti componenti tra navigazione, form, feedback e layout. Non era un prototipo era un sistema con una logica interna solida.

Il vero lavoro non era generare i componenti. Era guidare Claude nelle correzioni. Ogni fase aveva problemi specifici: valori hardcoded sopravvissuti, riferimenti diretti ai primitivi in alcuni stati, touch target sotto i 44px, contrasto dello shimmer insufficiente. Li trovavo, li documentavo, li correggevo con Claude.

Claude Code non ha generato un design system lo abbiamo costruito insieme, con me nel ruolo di design director e lui nel ruolo di esecutore. La differenza non è sottile.

Lo strumento più utile dell'intero processo è stato il file di audit che ho scritto prima dell'import un documento con criteri precisi che Claude leggeva, eseguiva e restituiva con i risultati.

## Pre-MCP Audit Checklist

### Token Enforcement
- [ ] Zero valori hardcoded nei componenti
- [ ] Nessun riferimento diretto a token primitivi
- [ ] Alias migration completa e documentata

### Accessibilità
- [ ] Touch target minimo 44px via --sp-touch
- [ ] Focus ring su tutti gli interattivi via --c-state-focus
- [ ] Shimmer contrast AA compliant

### Figma Mapping
- [ ] Naming pattern: color/{group}/{role}/{state}
- [ ] Naming pattern: space/{scale}
- [ ] Tabelle di mapping complete per ogni categoria

Fase 2 — L'import su Figma via figma-console-mcp

Qui il tentativo ha incontrato i suoi limiti reali.

Per l'import ho usato figma-console-mcp con figma-desktop-bridge non il server MCP ufficiale di Figma, ma il tool community più diffuso e capace. A differenza del server ufficiale, che è principalmente in lettura, figma-console-mcp accede direttamente al plugin API di Figma e può scrivere, creare componenti e modificare variabili. Era lo strumento con più possibilità disponibile. Se non ha funzionato qui, non è un problema di scelta del tool.

Il risultato dell'import non era inutilizzabile in senso assoluto ma era lontano dall'obiettivo. Ecco cosa ha funzionato e cosa no:

Cosa è arrivato correttamente: le variabili sono state importate, i componenti hanno le loro varianti, la struttura è riconoscibile.

Cosa non ha funzionato: le variabili importate non sono collegate ai componenti. Colori, font e spaziatura nei layer sono valori hardcoded le variabili esistono nel file ma non vengono usate. La separazione primitivi → semantici, rigorosa nel codice, è completamente assente in Figma. I componenti sono visivamente imprecisi rispetto alla documentazione HTML.

Il problema non era tecnico nel senso stretto il tool funzionava. Il problema era concettuale: anche il tool MCP più potente disponibile non è pensato per costruire un design system da zero partendo dal codice. Il flow mainstream è Figma → Claude Code, non il contrario.

Usarlo al contrario è possibile. Ma il risultato richiede un lavoro manuale di collegamento variabili e correzione componenti paragonabile a ricostruire il sistema da zero direttamente in Figma.

Il verdetto

Questo tentativo risponde alla domanda di partenza in modo netto: il passaggio code → Figma via MCP non è automatizzabile oggi, almeno non con la qualità necessaria per un design system professionale.

Il lavoro manuale rimanente dopo l'import è troppo per giustificare il processo. Collegare le variabili ai componenti uno per uno, correggere i layer, ricostruire la gerarchia primitivi → semantici in Figma, a quel punto conviene partire da Figma direttamente.

Ma il tentativo ha prodotto alcune risposte utili:

Claude Code per generare e documentare un sistema funziona, con riserve precise. Funziona se sei tu il design director, se definisci la struttura, scrivi il file di audit, guidi le correzioni. Non funziona se ti aspetti output autonomo di qualità professionale.

Il tempo risparmiato c'è, ma non dove pensavo. La generazione è veloce. La revisione rimane umana.

Il ruolo del designer si sposta. Meno produzione, più direzione. Meno disegno di componenti, più definizione di regole e audit.

Se dovessi affrontare lo scenario originale (un sistema in codice da portare su Figma) oggi userei Claude Code per estrarre i token e ricreare le variabili Figma in modo semi-automatico, ma costruirei i componenti direttamente sulla canvas. Il MCP lo terrei per quello per cui è pensato: portare contesto di design nel codice durante lo sviluppo.

Il design system Anvil esiste, è documentato, ha una logica solida. Vive nel codice, non su Figma. E per ora va bene così.

La documentazione HTML

Vuoi esplorare la documentazione HTML generata da Claude Code?
Vedi il sito statico Anvil v.1.0.0 in una nuova scheda