Vercel ha pubblicato un file chiamato design.md: un singolo documento Markdown, pubblico, che qualunque agente di coding può caricare per costruire pagine coerenti con il proprio marchio. Dentro ci sono palette, tipografia, spaziature, pattern dei componenti e regole d'uso. Il racconto del metodo sta nei due articoli del loro blog, Teaching agents product design e How our agents build on-brand pages with design.md.
La stessa cosa si può fare in qualsiasi progetto, con Claude Code o Codex, e cambia sensibilmente il risultato: la differenza tra un'interfaccia che «sembra generata» e una che somiglia al resto del prodotto sta quasi tutta lì.
La parte controintuitiva: la lista dei divieti
L'aspetto più interessante del design.md di Vercel è che parla pochissimo di colori. Quello che descrive nel dettaglio è cosa rifiutare. Nell'elenco delle cose da non fare compaiono, tra le altre: testi occhiello tutti in maiuscolo, etichette decorative con spaziatura larga tra le lettere, gradienti decorativi, bagliori, blob, strisce, texture, effetti vetro, griglie di card subito sotto un hero centrato, card annidate, rettangoli arrotondati scuri intorno a grafici e calcolatori.
È esattamente la raccomandazione della guida ufficiale al prompting di Opus 5.5: per il lavoro visuale, nominare le cose specifiche da evitare funziona meglio che chiedere qualcosa di «unico».
Il motivo è semplice: un modello addestrato su tutto il web ha un default statistico — quello che produce quando non gli si dice altro. Elencare i divieti è il modo più diretto per disattivarlo.
Cosa mettere nel file
Un design.md utile, nella pratica, contiene sei blocchi:
- Token — i colori reali del progetto come variabili CSS, non nomi generici. Se il progetto usa già
--color-primary,--radius,--shadow, si riportano quelli - Tipografia — famiglie, pesi, scala dimensionale, interlinea e crenatura. Vercel arriva a specificare la spaziatura negativa tra le lettere dei titoli grandi: è quel livello di dettaglio che rende riconoscibile un'identità
- Spaziature e ritmo — la scala (4, 8, 12, 16, 24…) e soprattutto i valori per il respiro verticale tra sezioni. Nel caso Vercel si parla di 80–120 px e oltre: lo spazio bianco è il progetto
- Componenti — come sono fatti bottone, card, input, navigazione, stati di caricamento, messaggi d'errore; quali varianti esistono e quando si usano
- Regole di layout — quali strutture di pagina sono ammesse e quali no
- Anti-pattern — la lista dei divieti, la parte che fa più lavoro di tutte
Un esempio di partenza
# design.md — regole visuali del progetto
## Token (gia definiti in css/style.css)
--color-primary: #1565c0 --color-danger: #d32f2f
--color-accent: #e65100 --radius: 8px
## Tipografia
Poppins. Titoli 600, corpo 400. Scala: 2.2 / 1.6 / 1.25 / 1rem.
Interlinea corpo 1.6. Mai maiuscoletto nei titoli di sezione.
## Componenti
Bottoni: sempre <button>, mai <div>. Icona + testo con
Material Symbols Outlined. Primario pieno, secondario outlined,
distruttivo #d32f2f.
Dialog: <dialog> nativo con showModal(), chiusura con Escape.
## Da non fare
- gradienti decorativi, glow, blob, effetti vetro
- card annidate dentro altre card
- griglia di tre card subito sotto un hero centrato
- icone emoji al posto delle icone del set
- nuove variabili colore: usare solo i token esistentiCome farlo leggere all'agente
Due modi, complementari. Il primo è citarlo in CLAUDE.md (o AGENTS.md) con una riga secca: «prima di scrivere qualsiasi componente di interfaccia, leggi design.md e rispettalo». Il secondo è richiamarlo esplicitamente nel prompt quando si apre un lavoro di UI. Il primo garantisce la continuità, il secondo alza l'attenzione quando conta.
Il dettaglio che rende il metodo affidabile
Vercel non ha scritto il file una volta sola: il documento è il risultato di oltre duecento cicli di valutazione, generando pagine e correggendo le regole dove il risultato divergeva. È la parte trasferibile del metodo. Un design.md scritto in mezz'ora e mai più toccato serve a poco; lo si migliora ogni volta che l'agente produce qualcosa di sbagliato, aggiungendo la regola che sarebbe servita a evitarlo. Il file diventa così la memoria di tutte le correzioni già fatte — e non c'è bisogno di ripeterle a ogni sessione.