Il documento non ti dice con cosa costruirlo
docs/ux-ui.md ti dice cosa costruire: dieci schermate, il flusso, gli stati. Non dice con cosa. E la domanda da cui parti decide quanto ci metti.
«Qual è la tecnologia migliore?» — domanda senza risposta. Dipende da cose che scoprirai fra sei mesi.
«Con quale arrivo a una demo navigabile in due settimane?» — questa una risposta ce l’ha, ed è una sola.
È il criterio di tutta questa parte: da 0 a 1. Zero è niente. Uno è una cosa che si apre, si naviga e si mostra a qualcuno.
Non vuol dire prendere la prima cosa che funziona. Serve una tecnologia matura, che l’agente sappia già usare e che vada online senza lavoro in più. Perché se il cliente dice sì, quella demo diventa il prodotto — e a quel punto ricominciare da capo costa più di tutto il tempo risparmiato.
Di strumenti che passano questi tre filtri ce n’è più d’uno, e qui non apriamo il confronto: ne scegliamo due, ti dico perché, e alla fine della parte sai cosa stai per installare.
Le scelte sono due, non una
Costruire un’app somiglia ad arredare una casa, e i pezzi da scegliere sono due — diversi tra loro, e non intercambiabili.
- La struttura Dove sta cosa, e come si passa da una schermata all’altra. La dà Next.js.
- I mobili I pezzi che ci vanno dentro, già montati. Li dà la libreria di componenti.
Chi comincia si perde qui, e non perché le opzioni siano tante: perché le due scelte sembrano la stessa. Sono due domande separate, e nelle prossime due sezioni si rispondono una alla volta.
La struttura: Next.js
Sulla struttura la decisione è già presa: Next.js (che sotto usa React). Diffuso e maturo, quindi esempi e risposte ovunque. E pensato per lavorare con gli agenti: il team che lo sviluppa pubblica skill già pronte per Claude Code.
Cosa ti dà, in cose che si vedono
Le schermate hanno un indirizzo. Ogni schermata del documento diventa una pagina raggiungibile: /schede, /match, /profilo. Non devi decidere tu come si organizzano.
Il passaggio da una schermata all’altra è già risolto. Premi un pulsante e cambi schermata, il tasto «indietro» funziona, il link si può mandare a qualcuno. Sono le cose che il cliente prova per prime.
Va online senza lavoro in più. A demo finita, il progetto si pubblica collegandolo a un servizio di hosting — è il lavoro della parte 7, ed è questione di minuti perché è già nel formato giusto.
E non è una scelta da progetto piccolo: ci girano sopra prodotti che usi già.
I mobili: shadcn/ui
I mobili sono shadcn/ui: pulsanti, campi, finestre, menù, tabelle, calendari. Il valore non è che siano tanti — è che sono mantenuti da gente che fa questo di mestiere. Funzionano col dito e con la tastiera, si comportano uguale su Chrome e su Safari, reggono lo schermo piccolo e il testo ingrandito, e continuano a farlo mentre i browser cambiano sotto. Sono i pezzi che tu non stai controllando, e che non ti si rompono in mano davanti al cliente.
Poi c’è la differenza con le altre librerie: non la installi, la copi. Un comando, e il file del componente compare in components/ui/ dentro il tuo progetto. Parti da un pezzo solido fatto da altri e da lì è tuo: lo apri e lo cambi.
Perché conta proprio adesso: quando fra due giorni chiederai a Claude Code di cambiare la forma di un pulsante in tutta l’app, quella modifica tocca un file dentro il tuo progetto — un file che parte già corretto. Con una libreria installata, invece, lo stile arriva da fuori e si combatte a colpi di eccezioni.
Create: la combo che si monta da sola
Fin qui sono due scelte separate, e di solito il lavoro noioso comincia adesso: far parlare tra loro framework, CSS e libreria. Sono le ore che si bruciano prima di poter scrivere la prima schermata.
La cosa che rende questa coppia difficile da battere quando devi andare veloce è che quel lavoro non lo fai: shadcn non ti dà solo i componenti, ti monta il progetto. Si chiama Create, è una pagina del loro sito, e da lì esce un comando solo che tira su Next.js e shadcn/ui già cablati insieme.
- Un progetto Next.js completo, con la sua struttura di cartelle
- Tailwind installato e configurato — lo strumento con cui si scrive lo stile
- I colori del tema come variabili, in un posto solo: si cambiano da lì
- Il primo componente shadcn/ui già dentro il progetto, come file tuo
Un paio di minuti, e il progetto gira sul tuo computer. È questo che intendo con «la tecnologia che ti porta a 1»: non la migliore in assoluto, quella che ti mette in strada mentre gli altri stanno ancora scegliendo.
La decisione è chiusa e non si torna a discuterla. Nella parte 3 si fa: quattro passi, un comando da copiare, e alla fine Claude Code aperto dentro la cartella del progetto.