Design system

Come documentare i componenti

Documentare un componente significa scrivere API, stati e limiti in un formato leggibile senza aprire il codice. La struttura che regge, con i numeri del catalogo EneUI.

In sintesi

  • Una scheda utile risponde a cinque domande: scopo, props, stati, tastiera, limiti.
  • react-docgen (MIT) estrae tipi e valori predefiniti, non le intenzioni del componente.
  • Nel catalogo EneUI 403 blocchi su 1.556 hanno sia descrizione sia categoria.

Documentare un componente significa scrivere la sua API, i suoi stati e i suoi limiti in un formato che un altro sviluppatore legge senza aprire il codice. Non è un commento nel file, non è uno screenshot e non è una pagina di catalogo.

Le cinque parti di una scheda

Una scheda utile risponde a cinque domande, sempre nello stesso ordine. Se ne manca una, il lettore torna a leggere il codice.

  • A cosa serve: una frase, senza aggettivi.
  • Props: nome, tipo, valore predefinito, se è obbligatoria.
  • Stati: default, hover, focus, disabled, loading, errore.
  • Contratto da tastiera e ARIA: quali tasti, quale ruolo, quale etichetta.
  • Limiti: cosa il componente non fa e cosa non è supportato.

Il comando: estrarre i tipi

npx react-docgen src/components/Button.tsx

react-docgen è un progetto MIT: legge i tipi TypeScript e i valori predefiniti e restituisce JSON. Ti dà la tabella delle props in automatico; non ti dà la frase che spiega a cosa serve il componente, e quella resta da scrivere.

Un record che documenta bene

Nel catalogo, zoomable image di Fumadocs mostra descrizione, dipendenze, licenza a monte e comando di installazione nello stesso posto. La libreria è Fumadocs, licenza MIT, e il record si raggiunge anche dall'indice dei 111.985 componenti.

La limitazione

Nessuno strumento verifica che la documentazione sia vera. react-docgen estrae i tipi, non i comportamenti: un componente documentato male supera ogni test e ogni lint, e la scheda sbagliata resta online.

Dove continuare

Il formato di un record installabile è in che cos'è un registry. Per le sezioni di una pagina di documentazione leggi blocchi per la documentazione; il confronto tra codice copiato e libreria è in copy-paste o headless.

Domande frequenti

Cosa deve contenere la documentazione di un componente?

Scopo in una frase, props con tipo e valore predefinito, stati visivi, contratto da tastiera e ARIA, limiti dichiarati. Se una di queste parti manca, il lettore deve aprire il codice.

Basta un commento nel codice sorgente?

No. Un commento spiega una scelta a chi già conosce il file; la documentazione serve a chi non lo conosce. Il commento resta utile, ma non sostituisce la scheda.

Serve Storybook per documentare i componenti?

No. Storybook è uno strumento MIT utile per gli stati interattivi, ma una pagina statica con props e immagini degli stati copre la maggior parte dei casi.

Come documento gli stati di un componente?

Un esempio per ogni stato, con lo stesso contenuto: default, hover, focus, disabled, loading, errore. La differenza tra gli esempi deve essere solo lo stato.

Chi scrive la documentazione?

Chi scrive il componente, prima di aprire la pull request. La documentazione scritta dopo, da un'altra persona, descrive ciò che il codice fa e non ciò che dovrebbe fare.