Un sito con l’agente AI Claude Code e Refero DESIGN.md

Materiali pratici per lavorare con progetti e modelli: documentazione Ailoot.

Perché i siti web creati con Claude Code sembrano template Tailwind?#

Nell’esempio di gennaio descritto, si stava creando un piccolo progetto secondario: un sistema per chiamate a freddo. In un repository vuoto, a Claude Code è stato chiesto di realizzare la home page. Il risultato era generico: sfondo scuro slate-950, accento purple-500, titolo in grassetto sans-serif e tre schede sottostanti con ombre identiche. Lo stesso layout del primo rilascio di ChatGPT, del primo rilascio di Lovable e del primo rilascio di v0. Dopo cinque modifiche al prompt con l’aggiunta di «moderno», «premium» e «diverso da tutti gli altri», non è cambiato nulla. La pagina sembrava ancora uscita da una raccolta di template Tailwind UI.

In altre parole, Claude non «non sa» come creare qualcosa di bello. Sa cosa fanno la maggior parte delle persone e riproduce quella maggioranza. Per ottenere un risultato che non sia una media, l’agente ha bisogno di vincoli specifici: quali colori usare, quali caratteri, quali spaziature e quali componenti considerare canonici.

È qui che entra in gioco un sistema di design come contesto. Non «rendilo bello», ma «realizzalo con questo stile specifico; ecco i suoi parametri».

Refero Styles colma questa distanza con un artefatto già pronto: un file DESIGN.md con i parametri di prodotti reali.

Che cos’è Refero Styles?#

La home page di styles.refero.design lo dice chiaramente: «scopri oltre 2.000 sistemi di design leggibili dagli agenti IA, tratti dai principali siti web di prodotti». Il catalogo include brand che definiscono gli standard visivi: Apple, Linear, Stripe, Notion, Vercel, ElevenLabs, Mercury, PostHog, xAI, Modal, Duolingo. Non vengono estratti manualmente: il team Refero esegue uno script che analizza il CSS e il markup effettivi di un sito e confeziona il risultato in un markdown strutturato. La raccolta di styles.refero.design è gratuita.

La parola chiave è «strutturati». Il file non contiene screenshot né descrizioni come «in stile minimalista». È un markdown con codici colore esadecimali specifici, dimensioni esatte dei caratteri in pt, unità di spaziatura e regole per i componenti. L’agente IA legge il file e lavora con elementi specifici, invece di cercare di descrivere il gusto a parole.

Nella pagina ai-agents, il team Refero indica come strumenti supportati «Cursor, Claude Code, Codex, v0 e Lovable». In altre parole, DESIGN.md è un artefatto universale: un solo file adatto a tutti i principali agenti di sviluppo basati sull’IA.

Che cosa contiene un DESIGN.md?#

Il team Refero descrive così la struttura del file nella pagina design-md-template:

La struttura del file è quindi in genere simile a questa:

Gli autori sottolineano anche un principio che risolve l’80% dei problemi di design con l’IA:

In altre parole, il codice esadecimale #5E6AD2 è più efficace di «come Linear». Il valore esatto font-size: 13px / line-height: 18px è più efficace di «testo compatto». I dettagli specifici prevalgono sull’interpretazione.

DESIGN.md nel repository non è un’immagine per il team. È un elemento costitutivo del contesto permanente del progetto: conoscenza strutturata che l’IA legge a ogni richiesta.

Come creare un sito web nello stile di Linear in 4 passaggi#

Questi quattro passaggi compongono la sequenza descritta per avviare un nuovo sito web. Non «quattro passaggi in generale», ma una sequenza specifica con un’azione per ogni passaggio.

1. Installa Claude Code

   Installazione nativa con un solo comando: curl -fsSL https://claude.ai/install.sh | bash (il metodo consigliato nella documentazione ufficiale). Su macOS funziona brew install --cask claude-code; su Windows, winget install Anthropic.ClaudeCode. Se è già installato, controlla la versione: claude --version (serve la versione 2.1.178 o successiva: questa versione ha introdotto i permessi Tool(param:value) e il blocco dei comandi git pericolosi in modalità automatica). Accedi al tuo account: claude avvia la procedura guidata. Claude Code è incluso in un abbonamento Pro ($17/mese con fatturazione annuale o $20/mese con fatturazione mensile).

2. Apri Refero Styles e scegli un brand

   Visita https://styles.refero.design e apri il catalogo. Il criterio principale di selezione è quanto corrisponde al tuo prodotto, non se «ti piace l’aspetto». Stai creando una dashboard SaaS? Guarda Linear, Vercel e Notion. Stai creando un prodotto fintech? Guarda Stripe, Mercury e Column. Stai creando un prodotto per membri? Guarda Duolingo. Apri la scheda di un brand e fai clic su «Copy DESIGN.md».

3. Inserisci DESIGN.md nel progetto come contesto

   Crea un file docs/DESIGN.md nella radice del progetto e incolla il contenuto copiato. Poi apri CLAUDE.md e aggiungi una riga: @docs/DESIGN.md. È una direttiva di importazione: Claude Code carica i contenuti nel contesto all’avvio di una sessione. Per ulteriori informazioni sugli import in CLAUDE.md, consulta la guida a un unico file di istruzioni per Claude Code, Codex e Cursor.

4. Chiedi una pagina specifica

   Non dire «rendila bella». Sii specifico: «Usando il DESIGN.md presente nel contesto, crea una home page per un prodotto SaaS di gestione delle attività. Struttura: hero con titolo e sottotitolo, due pulsanti CTA (primario e secondario), sotto una sezione con 3 funzionalità e icone, poi una sezione di testimonianze. Usa esattamente i colori e la tipografia di DESIGN.md; non inventarne di tuoi».

Dopo il quarto passaggio, Claude crea la pagina. Nell’esperienza descritta, una home page richiede in media 8–12 minuti e somiglia davvero allo stile del brand selezionato. Non è una copia perfetta al pixel, ma ha un’estetica riconoscibile: gli stessi caratteri, la stessa palette, lo stesso ritmo delle spaziature e le stesse micro-scelte nei pulsanti.

I creatori di Refero descrivono lo stesso principio in tre passaggi, un po’ più brevemente, nella pagina ai-agents/design-resources:

Questa sequenza in quattro passaggi segue la stessa logica, aggiungendo i passaggi espliciti per installare Claude Code e importare il file in CLAUDE.md.

Quale stile scegliere per il tuo prodotto?#

I creatori di Refero danno questo consiglio fin dal primo passaggio della loro guida: scegli un riferimento considerando non solo il nome del brand, ma anche densità, tono e pubblico.

Che cosa significa in pratica? Colori, tipografia, gerarchia e movimento sobrio derivati da Apple possono adattarsi a una dashboard SaaS, mentre gli ampi spazi di una specifica pagina marketing potrebbero non farlo. Esamina il riferimento concreto anziché scegliere dal brand. Per una dashboard contabile definisci righe compatte, spaziatura e densità, mantenendo leggibili numeri e controlli; non copiare invariato un layout da presentazione.

Una semplice guida alla scelta in base al tipo di prodotto:

Se hai ancora dubbi, scegli Linear. Ha le basi più versatili: una palette neutra, tipografia leggibile (Inter / Söhne) e spaziature sobrie. Un sito web basato su Linear avrà un aspetto professionale per 9 tipi di prodotto su 10.

Perché inserire DESIGN.md nel contesto permanente del progetto?#

Nella pratica descritta, DESIGN.md è archiviato accanto a CLAUDE.md in ogni progetto gestito con agenti IA. Il file non è considerato «temporaneo per un singolo compito». È un canone permanente su cui si basano tutte le sessioni future. Tra un mese puoi chiedere a Claude di aggiungere una nuova pagina al progetto: aprirà lo stesso DESIGN.md e la realizzerà con lo stesso stile. Tra sei mesi puoi affidare il progetto a un altro membro del team: potrà avviare Claude e ottenere un risultato coerente, perché DESIGN.md si trova nel repository.

Applicato al design, il principio funziona così: una decisione viene presa una sola volta, per la palette, la tipografia e il ritmo delle spaziature. In seguito, ogni agente IA la considera acquisita.

In altre parole, il design vive come codice (il markdown è codice), non in un file Figma che l’IA non può leggere. Quando il design è un file nel repository, lo leggono Claude Code, Codex e qualsiasi strumento futuro. Quando è in Figma, resta su un piano separato e deve essere tradotto manualmente per ogni sessione.

Nei progetti secondari descritti, è stata usata questa struttura:

project/
├── CLAUDE.md            (importa @docs/DESIGN.md)
├── docs/
│   ├── DESIGN.md        (canone visivo, copiato da Refero)
│   ├── ARCHITECTURE.md  (struttura del progetto)
│   └── BRAND.md         (tono di voce, vocabolario)
└── ...

Questi tre file sono un modo per organizzare il contesto permanente del progetto. DESIGN.md gestisce gli aspetti visivi, ARCHITECTURE.md la struttura e BRAND.md la voce. Qualsiasi agente IA con accesso al repository riceve tutti e tre come contesto.

Che cosa sono Refero MCP e refero_skill?#

Refero Styles è il livello di base (DESIGN.md come file). La fase successiva consiste in integrazioni che rendono l’accesso alla raccolta «nativo» per gli agenti IA.

Refero MCP (ufficiale). È un’API server all’indirizzo https://api.refero.design/mcp, a cui Claude Code si connette con un bearer token. L’agente ottiene quindi accesso a oltre 150.000 schermate e oltre 6.000 flussi utente di prodotti reali. Puoi installarlo con una skill:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

Dopo l’installazione, Claude avvia la «ricerca di design» all’inizio di ogni sessione come passaggio iniziale obbligatorio: esamina quali scelte visive sono adatte al compito e, se necessario, propone tre direzioni collegate al riferimento selezionato. Al 23 giugno 2026, il repository refero_skill conta 67 commit e 135 stelle. È un nuovo prodotto in fase di sviluppo attivo.

La pratica descritta adotta un approccio semplice: apri manualmente il sito, copia DESIGN.md e inseriscilo in un file. MCP è utile quando lavorare con i sistemi di design diventa una routine, per esempio se gestisci diversi progetti per clienti e ogni giorno passi da un canone visivo all’altro. Per saperne di più su come collegare i server MCP a Claude Code, consulta la guida a NotebookLM e MCP.

Quali sono i 4 errori che compromettono il flusso di lavoro?#

Questi quattro errori ricorrono nell’esperienza descritta di lavoro con il contesto di design. Ognuno sembra innocuo, ma ognuno riporta il risultato al template Tailwind standard.

Errore 1. Il prompt «rendilo moderno». È l’errore più comune. Le persone aprono Claude Code e scrivono: «creami un sito SaaS, stile moderno, look premium». Ottengono uno sfondo scuro e un accento viola. Nei dati di addestramento, la parola «moderno» è associata a tutte le landing page del 2022–2024 realizzate con lo stesso template. Senza i parametri esatti di DESIGN.md, «moderno» significa «medio».

Errore 2. Incollare DESIGN.md nella chat come messaggio. A volte le persone copiano DESIGN.md nella finestra di chat di Claude Code e dicono: «ecco lo stile, usalo». Funziona una volta, fino alla fine della sessione. Apri una nuova sessione (o passi a un altro compito, /clear) e il contesto è perso. Se vuoi che lo stile persista, il file deve trovarsi nel repository ed essere importato in CLAUDE.md. Per sapere perché CLAUDE.md è il punto di riferimento del contesto permanente, consulta la guida alla memoria di Claude.

Errore 3. Scegliere uno stile perché «ti piace». Un riferimento marketing Apple arioso può essere inadatto da copiare invariato in una dashboard immobiliare che deve mostrare 30 annunci. Questo non esclude tipografia, palette o gerarchia derivate da Apple: adatta spaziature e densità delle righe, poi verifica le informazioni effettivamente visibili alle dimensioni di schermo previste. Scegli il riferimento concreto per densità, tono e pubblico, non solo per il brand.

Errore 4. Non menzionare DESIGN.md nel prompt stesso. DESIGN.md può trovarsi nel repository, essere importato tramite CLAUDE.md ed essere visibile all’agente. Ma se il prompt dice «crea un sito web», Claude può seguire il percorso standard senza fare esplicitamente riferimento al file. Per ogni prompt di design è utile questa frase: «Usa esattamente i colori, i caratteri e le spaziature di docs/DESIGN.md. Non inventare valori: prendili dal file». Così si assicura che l’agente usi DESIGN.md invece di ignorarlo.

I token esatti sono codici esadecimali, dimensioni dei caratteri in pt e unità di spaziatura in DESIGN.md. Il linguaggio naturale è «moderno», «premium», «pulito» o «come Apple». I token esatti funzionano; le parole libere no.

Che cosa dovresti fare dopo?#

Ora hai il flusso di lavoro di base: Claude Code + DESIGN.md di Refero + 4 passaggi = un sito web non basato su template. Questo copre il 70% delle esigenze. Il restante 30% riguarda i casi in cui servono maggiore precisione, più velocità o una verifica.

Tre direzioni da seguire dopo aver acquisito le basi:

1. Frontend Design Skill. È una skill ufficiale per Claude Code che aggiunge feedback visivo. L’agente acquisisce uno screenshot della pagina assemblata con Puppeteer, la osserva con i suoi «occhi» (un modello visivo), la confronta con DESIGN.md e suggerisce autonomamente correzioni. È un ciclo automatizzato «prompt → codice → screenshot → critica → prompt». Utile quando una pagina è complessa e non riesci a ottenere il risultato giusto in una sola iterazione.

2. Refero MCP in modalità produzione. Quando gestisci 3–5 progetti in parallelo, aggiungere manualmente DESIGN.md per ognuno diventa noioso. Refero MCP può trovare 3 stili adatti in base alla descrizione del progetto e permette di scegliere. Riduce il tempo necessario per avviare un nuovo progetto da 30 minuti a 3.

3. Integrazione con Context Engineering. DESIGN.md è uno degli artefatti di contesto. Accanto ad esso si trovano solitamente ARCHITECTURE.md (struttura del progetto), BRAND.md (tono di voce) e business/audience.md (pubblico di destinazione). Sono tutti importati in CLAUDE.md. Quando Claude crea una pagina, si basa sugli aspetti visivi, sul pubblico e sulla struttura del prodotto. In sostanza, è context engineering: un lavoro sistematico su ciò che fornisci all’agente prima di una richiesta.

Materiali pratici: documentazione Ailoot.

Materiali pratici: documentazione Ailoot.

Altri materiali e strumenti: Ailoot.