Guida pratica alla redazione di un Documento di Specifica Funzionale (DSF) partendo da Figma

In un team di prodotto, un design in Figma è “visibile”, ma non sempre è comprensibile al 100% per chi deve sviluppare e testare. Un Documento di Specifica Funzionale (DSF) serve a questo: trasformare ciò che è disegnato in una descrizione operativa, verificabile e non ambigua.

Questa guida è pensata per un team junior e per l’uso nel Progetto xyz.go.

Glossario minimo (da usare sempre)

Nel DSF useremo pochi termini tecnici, e quando compaiono vanno spiegati subito:

• UX (User Experience – Esperienza Utente): come una persona vive l’uso del prodotto (chiarezza, velocità, frizione, soddisfazione).
• UI (User Interface – Interfaccia Utente): come appare e come si usa l’interfaccia (schermi, pulsanti, campi, messaggi).
• DSF (Documento di Specifica Funzionale): documento che descrive cosa deve fare una feature e come deve comportarsi lato utente.
• Frame (cornice): singola schermata in Figma.
• Flusso (user flow – flusso utente): percorso che l’utente fa da un punto A a un punto B (es. Login → Home).
• Stato (state – stato): variante di una schermata/componente (es. vuoto, caricamento, errore, successo).
• Validazione (validation – controllo): regole che verificano se un dato inserito è corretto.
• Criteri di accettazione (Acceptance Criteria – criteri di accettazione): lista di condizioni misurabili che definiscono quando la feature è “fatta”.
• Edge case (caso limite): situazione rara ma possibile (es. rete assente, input molto lungo, utente già registrato).

Perché il DSF è utile (anche se sembra “lento”)

Un DSF ben scritto:

• riduce domande ripetute tra design e sviluppo
• evita implementazioni “a interpretazione”
• rende i test più rapidi e completi (soprattutto sui casi limite)
• rende tracciabile perché una scelta è stata fatta

In pratica: meno rework, meno conflitti, più velocità.

Quando va scritto un DSF

Scrivi un DSF quando:

• nasce una nuova feature o un nuovo flusso
• si modifica un flusso esistente (anche se “solo UI”)
• si introducono nuove regole (es. validazioni, permessi, limiti)
• cambiano gli stati (loading, errore, empty state)

Per micro-modifiche puramente grafiche (es. cambio colore), può bastare un commento in Figma, ma solo se non cambia il comportamento.

Principi pratici (per scriverlo bene)

• Un DSF descrive comportamento, non solo layout.
• Ogni decisione “ambigua” va resa esplicita. Se può essere interpretata in due modi, nel DSF va scelto un modo.
• La fonte unica di verità (Single Source of Truth – fonte unica di verità) deve essere chiara: link a Figma + versione/ultimo aggiornamento.
• Scrivi per chi non era nella tua testa: sviluppatore, tester e anche un designer nuovo devono capire.

Struttura consigliata del DSF (template)

Questa è una struttura pratica. Puoi copiarla e incollarla in ogni DSF.

1) Intestazione

• Titolo feature
• Codice/ID (se usate una convenzione, es. XYZ-123)
• Autore/i
• Data e versione (es. v1.0)
• Link a Figma (file + pagina + frame principali)

2) Obiettivo

• 2–5 righe: cosa deve ottenere l’utente e perché.

3) Ambito

• Incluso: cosa fa la feature.
• Escluso: cosa non fa (importantissimo per evitare aspettative).

4) Attori e permessi

• Chi usa la feature? (es. ospite, utente registrato, admin)
• Cosa può fare ciascuno?

5) Flussi principali

Per ogni flusso, descrivi:

• Trigger (evento di avvio): cosa fa l’utente per iniziare.
• Passi numerati.
• Uscita: cosa succede alla fine.

6) Specifica schermate (per ogni frame)

Per ogni schermata importante:

• Nome schermata (come in Figma)
• Scopo
• Componenti (campi, bottoni, link)
• Azioni (cosa succede quando clicco/tocco)
• Stati: vuoto, loading, errore, successo, disabled
• Messaggi (microcopy – testi piccoli): errori, helper, conferme

Microcopy (testi piccoli) è un termine inglese: significa i testi brevi che guidano l’utente (es. “Password troppo corta”).

7) Regole e validazioni

• Formati (es. email valida)
• Limiti (min/max caratteri)
• Vincoli (es. password almeno 8 caratteri)

8) Errori e casi limite

• Errori utente (input errato)
• Errori tecnici (rete assente, server non risponde)
• Casi limite (es. email già registrata)

9) Accessibilità

Accessibilità (accessibility – accessibilità) significa rendere il prodotto usabile anche da persone con disabilità. Specifica almeno:

• navigazione da tastiera
• focus visibile (dove sono con la tastiera)
• messaggi di errore chiari
• contrasto del testo

10) Criteri di accettazione

Lista di frasi verificabili (vedi esempio più sotto).

11) Open points (domande aperte)

• Cosa non è deciso e chi deve decidere.

---

Come partire da Figma (procedura in 8 passi)

1. Nomina i frame in modo coerente (es. Auth / Login / Default, Auth / Login / Error).
2. Identifica il flusso (da dove si entra e dove si esce).
3. Elenca i componenti della schermata (campi, bottoni, link).
4. Scrivi le azioni: cosa succede a ogni click.
5. Elenca gli stati (loading, errore, successo, empty state).
6. Definisci regole e validazioni (con esempi di input validi/non validi).
7. Aggiungi casi limite (almeno 5: rete assente, input estremo, utente già esistente, timeout, doppio click).
8. Chiudi con criteri di accettazione (testabili uno a uno).

---

Esempio completo (mini-DSF) – Signup + Login + Recupero password + Pagina Principale (Progetto xyz.go)

Questo esempio serve come riferimento pratico per descrivere in modo testabile ciò che vedete in Figma.

1) Intestazione

• Titolo feature: Autenticazione (Authentication – autenticazione) + Pagina Principale
• Versione: v1.0
• Link a Figma: (incolla qui)
• Frame principali (nomi consigliati):
  • Auth / Signup / Default
  • Auth / Login / Default
  • Auth / Password / Request (richiesta recupero)
  • Auth / Password / Reset (impostazione nuova password)
  • App / Home / Default

2) Obiettivo

Permettere a un visitatore di:

• creare un account (signup)
• accedere (login)
• recuperare la password
• arrivare alla pagina principale (Home/Inizio)

con stati, validazioni e messaggi chiari.

3) Ambito

• Incluso:
  • signup con email + password
  • login con email + password
  • recupero password in due step (richiesta link + reset)
  • Home con stati: caricamento, vuoto, contenuti
• Escluso (se non previsto):
  • login con social (Google, Apple, ecc.)
  • autenticazione a due fattori (Two-Factor Authentication – autenticazione a due fattori, 2FA)

4) Attori e permessi

• Ospite: può usare Signup/Login/Recupero password.
• Utente registrato: può vedere la Home e le aree riservate.

5) Flussi principali

5.1 Signup (registrazione)

1. Apre Auth / Signup / Default.
2. Compila Email e Password (e Conferma password se presente).
3. Clicca Crea account.
4. Il sistema mostra Loading sul bottone.
5. Se successo: reindirizza a App / Home / Default.

5.2 Login (accesso)

1. Apre Auth / Login / Default.
2. Compila Email e Password.
3. Clicca Accedi → Loading.
4. Se successo: Home.

5.3 Recupero password

Richiesta link

1. Da Login, click su Password dimenticata? → Auth / Password / Request.
2. Inserisce email e invia.
3. Mostra un messaggio neutro per privacy (non conferma se l’email esiste).

Reset password 4. L’utente arriva a Auth / Password / Reset tramite link ricevuto via email. 5. Imposta nuova password e conferma. 6. Se successo: mostra conferma e link al login (o login automatico, se definito).

5.4 Pagina Principale (Home/Inizio)

1. Dopo login/signup, atterra su App / Home / Default.
2. Se i dati non sono pronti: stato Loading.
3. Se non ci sono contenuti: stato Empty state (stato vuoto) con invito all’azione.

6) Specifica schermate (cosa descrivere sempre)

Per ogni schermata: Componenti, Azioni, Stati, Messaggi.

6.1 Auth / Signup / Default

• Componenti: Email, Password, (Conferma password), bottone Crea account, link a Login.
• Azioni: click crea account; link “Accedi”.
• Stati: Default, Disabled (disabilitato), Loading, Errore, Successo.

6.2 Auth / Login / Default

• Componenti: Email, Password, bottone Accedi, link Password dimenticata?, link Crea account.
• Stati: Default, Disabled, Loading, Errore.

6.3 Auth / Password / Request

• Componenti: Email, bottone Invia link, link “Torna al login”.
• Messaggio dopo invio: Se l’email è registrata, riceverai un messaggio con le istruzioni.

6.4 Auth / Password / Reset

• Componenti: Nuova password, Conferma, bottone Imposta nuova password.
• Casi: link scaduto; token non valido.

Token (token – gettone/chiave) è un codice temporaneo che autorizza una singola operazione (qui: reimpostare la password).

6.5 App / Home / Default

• Stato Loading: mostra skeleton (skeleton – segnaposto grafico) oppure indicatore.
• Stato vuoto: messaggio + Call To Action (Call To Action – invito all’azione) principale.
• Stato normale: contenuti caricati.

7) Regole e validazioni

• Email: deve contenere @ e un dominio.
• Password:
  • minimo 8 caratteri
  • (opzionale) almeno 1 numero
• Conferma password: deve coincidere.

8) Errori e casi limite

• Email non valida.
• Password troppo corta.
• Password e conferma non coincidono.
• Credenziali errate (login) con messaggio generico.
• Email già registrata (signup).
• Link reset scaduto o token non valido.
• Rete assente / timeout.
• Doppio click sul bottone: non deve creare richieste duplicate.

9) Criteri di accettazione (Acceptance Criteria – criteri di accettazione)

Signup

• Il bottone è disabilitato se mancano i campi obbligatori.
• Se l’email è invalida, vedo un errore chiaro sotto il campo.
• Se password e conferma non coincidono, vedo l’errore dedicato.
• In Loading non posso inviare di nuovo.
• A successo, arrivo alla Home.

Login

• Con credenziali corrette arrivo alla Home.
• Con credenziali errate vedo un messaggio generico.

Recupero password

• Dopo la richiesta, vedo un messaggio neutro (privacy).
• Se il link è scaduto, sono guidato a richiederne uno nuovo.

Home

• Se i dati stanno caricando, vedo Loading.
• Se non ci sono contenuti, vedo uno stato vuoto con un invito all’azione.

10) Open points (domande da chiudere)

• Regole password definitive (solo lunghezza o anche complessità?).
• Dopo reset: login automatico o ritorno a login?
• Contenuti minimi obbligatori della Home.

---

Checklist rapida (prima di consegnare il DSF)

• Ho inserito link Figma e nomi frame coerenti?
• Ho descritto almeno un flusso principale e i flussi alternativi?
• Ho elencato stati (default, loading, errore, successo)?
• Ho scritto regole e validazioni con esempi?
• Ho coperto almeno 5 casi limite?
• Ho definito criteri di accettazione testabili?
• Ho indicato cosa è fuori ambito?

Errori tipici da evitare

• “Si capisce dal design”: spesso non è vero per regole, errori e casi limite.
• Specifiche senza stati: poi ogni persona immagina stati diversi.
• Regole non numeriche (es. “password forte”): serve una regola misurabile.
• Messaggi di errore non definiti: finiscono scritti in fretta e incoerenti.

Conclusione

Un DSF non è burocrazia: è un acceleratore. Se il DSF è chiaro, lo sviluppo procede più veloce e i test diventano più semplici.

Il prossimo passo consigliato è standardizzare un template DSF (copia/incolla) e una convenzione di naming per i frame in Figma, così tutti scrivono nello stesso modo.