Creare una StyleGuide con KSS

Avete mai avuto bisogno di avere una styleguide di un sito?
Un punto in cui mostrate il dizionario visivo – come se fosse una palette di colori – tutti gli elementi grafici.
Bottoni, Link, Tabelle e tipografia sono elementi visivi che spesso vengono ripetuti.

Senza entrare nel merito di manutenibilità di codice css, vorrei mostrarvi un modo semplice che ho iniziato ad utilizzare (su indicazione di Luca ed in alcuni progetti di GNV) per crearmi una Styleguide degli elementi visivi di un sito.

Si tratta di KSS.

KSS è un engine creato da Kyle Neath che permette di generare HTML da dei commenti messi nel CSS (o nei relativi precompilatori).
http://warpspire.com/kss/ è il sito di riferimento mentre il repository git lo trovate qui.

Ho pensato che il miglior modo per spiegare il potere di questo tool (ed il suo livello di stabilità) fosse questo:

La StyleGuide di GitHub generata con KSS

La StyleGuide di GitHub generata con KSS

Ma andiamo meglio a capire come funziona sporcandoci le mani.
Per potermi far comprendere meglio, ho creato anche un repo di cui potete osservare le commit specifiche: https://github.com/fabiofabbrucci/KSS

 Step 1 – Init of a project

Per prima cosa inizializziamo un progetto con compass:

Non è necessario avere un progetto compass, ma lo trovo comodo per avere il setting iniziale di sass e compilazione del css.

Passiamo poi a creare una index.html che includa il nostro css generato.

Step 2 – KSS Installation

Esistono diversi modi di utilizzare KSS; nello specifico di parser che interpretano il css e generano l’html ce ne sono diversi (qui vedete la lista http://warpspire.com/kss/styleguides/) ma essendo tendenzialmente in ruby o altri linguaggi server-side che richiedono un enviroment particolare, ho preferito la sua versione in nodejs.

High Kennedy, questo australiano, ha scritto il parser in nodejs, eccolo: https://github.com/hughsk/kss-node.
Questo permette abbastanza semplicemente di installarlo e renderlo utilizzabile in quasi ogni progetto.

Creiamo dunque un file package.json nella root con il seguente contenuto:

E subito dopo dalla root lanciamo:

A questo punto per testare se KSS è isntallato correttamente lanciamo:

Step 3 – Using it

Per prima cosa andiamo a creare una cartella styleguide nella root del progetto.

Poi andiamo a generare una nostra prima documentazione. Creiamo un partials nella cartella sass (andrebbe bene anche un semplice file css da importare, oppure lavorare direttamente sul file css unico finale), per lavorare meglio, più puliti.

Nel file inseriamo il seguente codice:

L’utilizzo di come usare i commenti è spiegato in maniera abbastanza esaustiva qui, http://warpspire.com/kss/syntax/, ma a grandi linee possiamo individuare 3 macro sezioni.

La prima è il titolo della sezione che sto documentando (potrebbe essere “I bottoni” o “La Typo”).
La seconda è il markup da generare.
La terza è l’indice della sezione, di modo che si possano ordinare meglio le guide create.

Ora, lanciando il comando di Help scritto sopra notiamo che il binary chiede come argomenti:

  1. La sourcedir dove andare a processare per vedere se ci sono commenti (possono essere css, scss o less)
  2. la destdir dove compilare la styleguide generata
  3. Opzioni
  4. Il file CSS da includere nella styleguide generata (questo file – molto importante – è il file che la nostra app – non kss – genera e compila)

Quindi ora lanciamo:

e come per magia, all’url http://localhost/KSS/styleguide/section-1.html troveremo questo:

Prima styleguide generata

Prima styleguide generata

 

Step 4 – Customization

E’ possibile inoltre personalizzare il tema.
Per farlo basta lanciare:

Il primo comando genererà una cartella styleguide-template che potremo poi andare a personalizzare nell’html, css e js se lo vogliamo.
Il secondo comando invece comunicherà a kss-node di quale template usare (invece di quello suo embedded).
Il risultato:

La mia styleguide personalizzata

La mia styleguide personalizzata

Step 5 – Conclusion

Ora che abbiamo creato la nostra prima styleguide, si tratta solo di popolare i vari partials con il relativo markup e la guida verrà generata in automatico.

Ho cercato di stilare una lista di pro e contro.

Pro

  • Maggiore vicinanza tra markup e css, ergo meno dispersione nella ricerca
  • Accoppiamento più forte tra visual e selettori

Contro

  • Scomodità di generazione manuale – ma esistono dei plugin per grunt che possono automatizzare il tutto, facendo watching della sourcedir

In conclusione trovo questo strumento comodo per generare un ulteriore strumento utile allo sviluppo (scusate il gioco di parole).

Ciao a tutti e a presto.

 

  • ilbonzo

    hai provato anche StyleDocco? Nel caso differenze?

    • fabiofabbrucci

      No Matteo, ma lo avevo considerato.

      Ad oggi, con 5 mesi di differenza da questo articolo, il mio approccio alle Styleguide è cambiato.
      Quello verso cui mi sono avvicinato è più vicino a questo:
      http://bradfrostweb.com/blog/post/atomic-web-design/
      http://patternlab.io/

      Le motivazioni:
      – Template Engine più flessibile rispetto al markdown (un esempio sono le inclusioni di pattern)
      – Routing più flessibile
      – Più valore per il team di sviluppo e per il cliente

      • ilbonzo

        grazie, molto interessante, appena riesco provo un po’ seriamente la cosa.

    • fabiofabbrucci

      Qui trovi il video della mia presentazione sulle Styleguide tenuta al codemotion Roma 2014.
      https://www.youtube.com/watch?v=DpFZhCKBsr4