Creare style guide

Cos’è una style guide?#section1

Per me, una style guide è un documento in costante evoluzione, riguardante il codice: ne descrive in dettaglio i vari elementi e i moduli di un sito o di un’applicazione. Oltre al suo utilizzo per il consolidamento del codice front-end, documentano anche il linguaggio visuale (come ad esempio gli stili del header o la palette di colori) utilizzato per creare il sito. In questo modo, si ha un unico punto di riferimento per l’intero team, dai product owner e product producer ai designer e ai developer, quando si devono discutere dei cambiamenti e delle iterazioni da fare sul sito. Molte aziende hanno messo online le proprie guide: Starbucks è la più nota tra tutte, ma ce ne sono molte altre.

La style guide di Starbucks.

(Dovrei anche dire che alcune persone chiamano pattern library quella che io chiamo style guide. Molte delle guide a cui faccio riferimento usano il termine style guide, ma pattern library si sta diffondendo parecchio).

Quando cominciai a lavorare per Editorially, una delle prime cose che feci fu di venire alle prese con la style guide. Creare la guida fu probabilmente la cosa più utile che avessi mai fatto al momento del mio insediamento in un nuovo posto di lavoro: mi costrinse a leggere ogni singola riga di CSS, per classificarla e per comprendere il modo in cui era stata usata, per poi documentarla per potervi fare riferimento (e perché anche il team potesse usarla in tal modo). Oltre a scoprire inconsistenze ed errori studiando il CSS, se non capivo come erano utilizzate alcune parti di codice, facevo delle annotazioni sulla guida comprensive di domande (a cui i miei compagni di team hanno sempre risposto gentilmente).

Perché dovrei usare una style guide?#section2

Man mano che il vostro team cresce e cambia nel tempo, la vostra style guide vi aiuterà in molti modi. Per prima cosa, creare la guida richiederà un po’ di tempo all’inizio, ma ho scoperto che questo tempo viene compensato da tempistiche più rapide nello sviluppo di nuove sezioni e nuove pagine, perché chiunque si unisca ad un progetto già in corso può far riferimento alla guida per sapere esattamente che stili usare.

Immaginate di cominciare a creare una pagina con informazioni come queste tratte dalla guida del South Tees Hospital: ci vorrebbero pochi secondi per realizzare un box per le donazioni.

In secondo luogo, una guida ci permette di standardizzare il CSS, facendo sì che rimanga di dimensioni contenute e sia rapido da caricare. Usando la guida come un inventario di moduli e codice, sia i designer sia i developer possono capire rapidamente se i nuovi design deviano dagli standard prestabiliti e possono decidere insieme se vale la pena estendere la codebase o se si può facilmente ampliare qualcosa di simile che è già stato scritto. Quando non si hanno guide, tutto ciò è impossibile, il che, nella mia esperienza, vuol quasi sempre dire che si scrivono nuovi stili, creando così un CSS troppo intricato e pieno di regole.

Terzo, è più semplice mantenere consistenza nel design, perché il designer deve guardare solo in un posto per avere dei riferimenti sui componenti del sito e per essere sicuro che ci sia sempre un “look and feel” consistente. Questa cosa è particolarmente utile nei team più grandi e nelle aziende in cui può esserci un intero team di designer al lavoro sul sito. E quando si mantiene consistente un design, anche la codebase è più piccola.

Yelp dice chiaramente come sono usati i pulsanti, mantenendo consistenza negli stili dei pulsanti per tutto il sito.

Quarto, anche la comunicazione diventa più chiara. Quando creai delle pagine all’interno un progetto di grandi dimensioni e le passai alla designer, questa usò il linguaggio delle varie classi presenti nella guida per chiedere dei cambiamenti. Tutto ciò ha permesso che di evitare confusione da entrambe le parti mentre si procedeva di buon passo nelle revisioni. Inoltre, fornì un vocabolario condiviso all’intero team, con ad esempio i nomi dei moduli, che poteva essere usato parlando dei design una volta che erano stati programmati.

L’ultimo vantaggio che ho notato è che potete usare la vostra guida per fare un rapido controllo di QA (Quality Assurance) e passarlo. La guida potrebbe non essere identica alle pagine che alla fine realizzerete, ma può evidenziare dei problemi che si possono avere nei vari browser. Gestendo questi aspetti in anticipo, li si eviterà nei test successivi.

Step per creare una guida#section3

Di seguito, vi guiderò nella creazione della vostra style guide, basandomi sulla mia esperienza nelle prime settimane di lavoro a Editorially (perché quando lavoro su un progetto senza una guida ho un grandissimo bisogno di crearne una. Chiedete ai miei colleghi!).

Assemblate le basi del vostro sito#section4

Cominciate la vostra guida con le fondamenta del vostro sito. Un elemento fondamentale potrebbe includere la palette di colori, il sistema di layout a griglia o il tipo di stili di base per gli header e per il corpo del testo: qualunque cosa riteniate sia un elemento di base per creare una pagina. Nel caso di Editorially, la parte più fondamentale del nostro sito era la color guide, quindi cominciai da quella e andai avanti partendo da essa. Creai un documento HTML con il markup, con un link al CSS dell’applicazione così che ogni cambiamento nel CSS avrebbe automaticamente avuto riscontro nella style guide.

Quando guardate la style guide creata da Yelp, potete vedere come inizia dalle basi: tipografia, griglia e colori, aggiungendo via via più pattern.

Yelp.

Aggiungete più pattern#section5

Un pattern è un insieme autonomo di markup e di stili per creare alcuni degli oggetti di base del vostro sito, come una “call-out box” che viene usata spesso, i pulsanti o il modo in cui si dispone orizzontalmente un elenco di link. In Editorially, ho documentato tutte le possibili variazioni di stile di pulsanti e link. Quindi, dovrete continuare aggiungendo l’esatto markup di cui avete bisogno per ogni elemento della vostra guida.

Per esempio, per un pulsante nella guida di Editorially, ho semplicemente messo <label for="btn" class="btn" href="#">.btn <input type="submit" name="btn" value=".btn" /></label>. E siccome abbiamo un link allo stesso CSS dell’applicazione, il CSS viene mostrato in maniera corretta nella style guide. Se dovessimo cambiare lo stile di .btn, cambierebbe anche la style guide.

Proseguite l’esplorazione del vostro sito e aggiungete tutti i pattern che vedete: potreste usare dei layout particolari più e più volte o un pattern per un media object o un pattern per un elenco verticale. Di seguito potete vedere un altro esempio tratto da South Tees Hospital, che mostra alcuni dei loro pattern per quelli che chiamano “feature blocks”. Cercate cose simili sul vostro sito per documentarle nella guida.

South Tees Hospital.

Eccoci al momento giusto per chiedere al proprio team cos’altro sarebbe utile avere nella style guide. Condividetela, permettete loro di darle un’occhiata e sperate che vi aiutino a riempirla con tutti i pattern e i moduli necessari. Non dimenticatevi di farvi aiutare dall’intero team per completarla, perché si tratta di una risorsa per tutti.

Documentate l’interattività#section6

Se possibile. aggiungete le parti interattive utilizzate dal vostro sito, come i dropdown, le modali o i tooltip, che altro non sono che piccoli “hover” con del testo utile che dà informazioni aggiuntive all’utente. Questo permette al vostro team di vedere non solo le versioni statiche di questi elementi, ma anche le animazioni. Così, quando guarderete la guida e passerete sopra a un oggetto o ci cliccherete, questi funzioneranno proprio come sul vostro sito.

I tooltip nella guida di Editorially.

Rendete semplice il mantenimento#section7

Se dovete fare del lavoro extra per aggiornare la style guide quando fate dei cambiamenti al look and feel, le probabilità che rimanga aggiornata sono piuttosto basse. L’ho già ripetuto altre volta, ma questo è il motivo per cui abbiamo collegato la guida di Editorially allo stesso CSS dell’applicazione: in questo modo non dovevamo aggiornare manualmente la guida. Può essere difficile rendere prioritari gli aggiornamenti alla guida, ma il mantenimento è di vitale importanza. A seconda della rapidità delle vostre iterazioni sul sito o sull’applicazione, dovreste controllare la guida come se fosse un task da ripetere regolarmente, con scadenza settimanale o mensile. Quando fate dei cambiamenti al vostro sito, inserite nel workflow anche l’aggiornamento della style guide.

Iterate sulla vostra guida#section8

Una volta che avete incluso nella guida la maggior parte dei componenti del vostro sito o della vostra applicazione, c’è un’abbondanza di tool per renderla ancora più comoda. Mentre stavo realizzando la style guide per Editorially, un collega mi fece notare il fantastico tool di Filament Group, X-rayHTML, che è una piccola libreria JavaScript che ci aiuta a creare documentazione. X-rayHTML prende gli oggetti che hanno uno stile sulla vostra pagina e genera un blocco di codice ben formattato sotto di essi, senza che voi dobbiate aggiungere altro codice. Potete anche aggiungere prism.js per la “syntax highlighting”, che assegna un colore alle varie parti del codice, per aumentarne la leggibilità.

Uno sguardo alla style guide di Editorially con X-rayHTML all’opera.

Se siete interessati all’automazione, ci sono altri tool che possono rendere ancor più semplice la creazione di una style guide. Due di questi includono KSS e Hologram. Entrambe questi strumenti utilizzano i commenti o YAML all’interno dei vostri fogli di stile in combinazione con qualcosa come Ruby per generare automaticamente la style guide. Ci vorrà un po’ di lavoro per andare a ritroso e fare il retrofitting dei vostri fogli di stile con i commenti appropriati o con YAML per questi approcci, ma risparmierete del tempo sul lungo periodo, perché questi tool rendono il mantenimento molto più semplice. Inoltre, A List Apart ha messo la sua pattern library su GitHub e ha pubblicato un blog post sulla sua creazione, mostrando un altro metodo per creare una style guide. Le possibilità riguardo a ciò che potete fare sono molte di più di quelle che ho evidenziato qui: potete cercare un po’ in giro per vedere quali possano essere più utili per voi e per il vostro team.

Usare la guida#section9

Bene, adesso che avete fatto tutto questo lavoro e avete creato la guida, cosa succede? Come facciamo in modo che tutti la usino? Il primo passo consiste nel parlarne: se un nuovo membro del team si unisce a voi, mostrategli la guida come modo per orientarsi sul sito, dal momento che contiene così tante informazioni sia sul linguaggio visuale sia sul codice del front-end.

Finché iterate su un sito o su un’applicazione, la vostra style guide non sarà mai davvero ultimata. Ma avere da subito qualcosa di documentato e mostrarlo ai colleghi nel vostro team per avere il loro feedback è di grande aiuto. Coinvolgete l’intero team nella creazione della guida, così che sia la guida del team e fate in modo che tutti investano del tempo nel suo mantenimento e la usino regolarmente.

Abbiamo reso disponibile la guida di Editorially sia come public repo su GitHub sia online. È stato veramente un “work in progress” ma ne è risultato un documento interno al nostro team, per cui ci sono anche note, pattern e tanta confusione. Ma la ragione per cui la mostriamo è per rinforzare l’idea che una style guide non deve apparire perfetta per essere utile. Nonostante il disordine, tutto quello che contiene è stato estremamente utile per me e per gli altri membri del team man mano che proseguivamo con il lavoro sull’applicazione.

Allora, vi ho convinto? Vorreste avere una style guide per il vostro sito o per la vostra applicazione? Ne vale davvero la pena: ricavatevi del tempo, coinvolgete il vostro team e cominciate a crearla. La ricompensa sarà un documento che farà accelerare le discussioni e lo sviluppo del vostro sito.

Illustrazioni: {carlok}