design.md: come usare il file di Vercel per togliere l’AI slop dalle interfacce create con Claude Code e Codex

design.md è un file Markdown che dà agli agenti AI regole di design precise: colori, font, dimensioni, bordi, spacing, struttura delle sezioni, uso delle immagini e, soprattutto, cosa non fare. Se lo metti nel progetto, Claude Code e Codex smettono di generare la solita pagina "fatta dall’AI" e seguono un linguaggio visivo coerente.

Ho fatto la prova su due landing page, entrambe costruite con Claude Code. La prima senza regole di design. La seconda con un file design.md. La differenza si vede a colpo d’occhio, ed è il motivo per cui oggi lo uso.

Cos’è l’AI slop nelle interfacce?

L’AI slop è l’insieme dei pattern che fanno capire subito che un sito l’ha generato un’AI. Nelle web app i più riconoscibili sono:

• card tutte uguali, ripetute in griglia;
• gradienti viola messi ovunque.

Quando chiedi a Claude Code "fammi una bella pagina", il modello riempie i vuoti con le scelte più frequenti che ha visto. Il risultato è corretto, ma anonimo. Ed è uguale a quello di tutti gli altri che hanno scritto lo stesso prompt.

Da dove arriva design.md?

Il file design.md non l’ho inventato io. Sta diventando sempre più popolare nello sviluppo di prodotti, e una spinta forte è arrivata da Vercel, l’azienda dietro il framework Next.js e molto attenta allo sviluppo con agenti AI.

Il 31 agosto 2026 Vercel ha pubblicato come usa design.md: un unico file pubblico che qualsiasi agente può caricare per creare pagine coerenti con il brand di Vercel. Il file guida l’agente su gerarchia, testi, layout, tipografia e colore, e elenca i pattern da design generato che il team non vuole mai vedere.

Vercel ha anche misurato l’effetto. Nel suo test su sei pagine, quelle create con design.md avevano 39 errori noti, contro 91 senza: circa il 57% in meno. Il team stesso precisa che sei pagine sono un campione piccolo e che il test conta solo errori già documentati. Il segnale però è chiaro: regole scritte battono una descrizione generica.

Cosa scrivere dentro design.md?

Dentro design.md definisci tutte le regole che vuoi far rispettare agli agenti AI:

• colori: palette, colori di accento, quando usarli;
• font e dimensioni: famiglie, pesi, scala tipografica;
• bordi e spacing: raggi, margini, distanze tra blocchi;
• sezioni: come vanno costruite e in che ordine;
• immagini: quando usarle e in che formato.

La parte più utile è la lista di ciò che non vuoi vedere. Scrivere esplicitamente "niente card tutte uguali, niente gradienti viola" toglie all’agente le scorciatoie che producono l’AI slop. Anche Vercel ha scelto di nominare i pattern vietati, invece di limitarsi a descrivere lo stile desiderato.

Come si crea un design.md senza essere designer?

Per creare un design.md non devi essere un designer. Il metodo che consiglio è questo:

1. scegli un sito o un’app che ti piace;
2. manda il link a Claude Code o Codex;
3. chiedi qualcosa come: "Creami un file design.md con le regole di design di questa web app e ricrea il suo linguaggio visivo.";
4. aspetta che l’agente generi il file e salvalo nel progetto.

Da quel momento gli agenti AI lo seguono a ogni pagina che costruiscono. Se il risultato non ti convince, correggi il file, non la singola pagina: la regola vale per tutte le volte successive.

Perché un file di regole cambia il risultato?

Con design.md smetti di chiedere all’agente "fammi una bella pagina" e gli dai regole strutturali da seguire. È lo stesso principio dello spec-driven development applicato al design: più la richiesta è specifica, meno l’agente deve indovinare.

Per chi costruisce software con l’AI senza essere sviluppatore, questo conta molto. Il design è la prima cosa che un utente vede, e un’interfaccia generica comunica poca cura anche quando il prodotto funziona bene. Ne parlo anche nella guida su come costruire software con l’AI senza saper programmare.

Se stai costruendo una web app con Claude Code o Codex, un design.md è il passo più rapido per dare alle tue pagine un’identità riconoscibile. Il momento di provarlo è al prossimo progetto.