Progettare (e costruire) questo portfolio

Contesto

Un portfolio da UX/UI Designer ha un problema di credibilità intrinseco: dichiara competenze che il sito stesso, di solito, non dimostra. Parla di design system, ma gira su un tema comprato; parla di accessibilità, ma non passa un audit; parla di collaborazione con lo sviluppo, ma è stato messo online da qualcun altro.

Ho preso la direzione opposta: fare del portfolio la prova del metodo che vendo. Ogni cosa che il sito afferma, il sito la esegue. Il design system è reale, l'accessibilità è verificata, e il flusso dal design al codice è quello che uso al lavoro.

Obiettivi

Tre obiettivi, uno per ciascuna competenza che il sito deve dimostrare, non raccontare.

Design system, non tema. Un'identità sistemica costruita su design token, capace di reggere temi multipli, due lingue e crescita futura senza debito visivo.

Accessibilità per costruzione. WCAG 2.2 AA come vincolo di progetto dall'inizio, non come checklist finale: contrasto, focus, target di dimensione minima, navigazione da tastiera, movimento ridotto.

Design-to-code continuo. Un flusso in cui la decisione di design e la sua implementazione non sono due mondi separati con un handoff in mezzo, ma un unico processo AI-driven, con gli agenti AI dentro il flusso.

Il design system a token

Il fondamento è un set di design token conformi allo standard DTCG, scritti come sorgente unica e compilati verso il codice con Terrazzo, poi consumati da Panda CSS. I token sono su due livelli: primitive (la palette grezza, la scala tipografica, spacing e raggi) e semantic (i token con un significato: superfici, testo, bordi, stati), con la condizione _dark che risolve automaticamente il tema.

La direzione visiva è deliberata e riconoscibile: neutri freddi con cast blu-violetto, un accento oltremare riservato ad azioni e stati, e un secondo accento redline vermiglio, il colore delle annotazioni nei file di specifica, usato per gli eyebrow monospace e i marcatori di sezione. È la firma del sito: un registro da foglio di specifica, geometria netta senza raggi sulle superfici principali, tipografia Archivo / IBM Plex Sans / IBM Plex Mono.

Il tema si sposta tra light, dark e system con toggle persistente e uno script anti-flash inline nel layout: nessun lampo di tema sbagliato al primo caricamento, perché la decisione è risolta prima del paint.

Accessibilità per costruzione

L'accessibilità non è un livello di vernice finale: è codificata nei token e nei componenti. I contrasti (4.5:1 sul testo normale, 3:1 su testo grande e componenti UI) sono verificati alla sorgente dei token, non a occhio sul risultato. Ogni elemento interattivo rispetta il target minimo di 24×24px (criterio WCAG 2.2 2.5.8), ha un focus visibile e un ordine di tabulazione che segue l'ordine di lettura.

Il sito offre skip link, landmark semantici, alt text nelle due lingue, aria-label sui controlli e rispetto di prefers-reduced-motion, con le transizioni e i sollevamenti hover disattivati per chi lo richiede. Ogni pagina e ogni componente è passato al vaglio di un audit automatico prima di essere considerato finito.

Il workflow design-to-code

Qui il portfolio dimostra la parte che mi distingue: un flusso di lavoro in cui gli agenti AI sono parte del processo di progettazione, non un giocattolo a lato. Ho costruito il sito con Claude Code, orchestrando agenti e skill dedicate: convenzioni di codice sempre attive, revisori automatici del diff, un locatore di codice per non riscrivere ciò che esiste già.

I contenuti vivono come codice: Keystatic gestisce i case study e le pagine come file versionati nel repo, letti in build via Reader API, con Markdoc per la prosa. La documentazione del design system è docs-as-code (Storybook per i componenti, Docusaurus per i token), rigenerabile e sempre allineata al codice. Sono pubblicati insieme al sito: esplora i componenti su Storybook e leggi la documentazione del progetto su Docusaurus. Ogni modifica lascia una traccia: un log di revisione con stato, file toccati e prossimo passo, così il processo è auditabile quanto il risultato.

Non è "AI che disegna al posto mio". È un metodo in cui la decisione di design resta mia e l'agente comprime la distanza tra quella decisione e il codice che la implementa, documentato e validato per l'accessibilità.

Architettura e stack

Il sito è Astro con isole React solo dove serve interattività (theme toggle, switch lingua), così il grosso resta HTML statico veloce. È bilingue con routing italiano sulla radice (/) e inglese su /en/ e hreflang reciproci; le due lingue di ogni case study sono legate da una translationKey, non duplicate a mano. Lo styling è Panda CSS alimentato dai token; il CMS è Keystatic a storage locale (nessun servizio esterno, i contenuti sono git). Deploy su Netlify da GitHub.

Ogni scelta di stack ha una regola dietro: usare sempre l'ultima versione stabile e verificare la sintassi sulla documentazione ufficiale della versione installata, mai a memoria. Il risultato è un sito che un team di sviluppo può leggere, capire e mantenere.

Impatto

Il portfolio fa ciò che un portfolio raramente fa: si comporta come il suo stesso argomento. Chi lo apre incontra un design system coerente in tre temi e due lingue, un'esperienza accessibile per costruzione, e un processo di build che è la dimostrazione vivente del metodo AI-driven descritto nelle pagine. La credibilità non è affidata alle parole: è nel comportamento del sito.

Sul piano pratico, l'architettura a token e i contenuti-come-codice rendono il sito economico da far evolvere: un nuovo case study è un file, un nuovo tema è un set di token, una nuova lingua è una cartella di rotte. Niente si rompe per aggiungere.

Cosa mi porto da questo progetto

Progettare il proprio portfolio come un prodotto, con gli stessi vincoli di sistema, accessibilità e manutenibilità del lavoro vero, cambia il risultato: smette di essere una vetrina e diventa una prova. E lavorare con agenti AI dentro il processo, non accanto, mi ha convinto che il valore del designer non diminuisce ma si sposta più in alto: dalla produzione dei pixel alla qualità delle decisioni, con il codice, la documentazione e l'accessibilità che seguono a distanza sempre più breve.