Et komplett designsystem kan være helt ubrukelig om ingen vet hvordan man skal bruke det. Men hva er egentlig best practice når man skal dokumentere hvordan komponentene dine fungerer?
—
Et designsystem skal inneholde mye. Det er design tokens, det er tone of voice, animasjonsguidelines og haugevis av andre tematikker som skal lages, dokumenteres og publiseres et sted. Men det vi ser at blir mest brukt på tvers av kundene våre, er komponent-dokumentasjon. Det er komponentene man ofte bruker i hverdagen, og det er de man oftest lurer på noe om.
Men hvordan dokumenterer man egentlig en komponent? Hva skal man skrive om, hvem skal man skrive for og hva burde man inkludere og eventuelt ekskludere? Og hva er det som skiller god dokumentasjon fra dårlig?
Når du dokumenterer en komponent, så er det et par hovedområder vi liker å fokusere på:
La oss dykke litt dypere i hver av disse spørsmålene.
En ting vi ser at mange glemmer, er å definere hva en komponent skal brukes til. Det hjelper leseren (om det er en utvikler, en designer, eller en produktleder som tilfeldigvis elsker dokumentasjon) med å forstå hva intensjonen bak komponenten er, og hvordan den burde brukes.
Av og til kan hensikten være veldig implisitt. En knapp er noe du kan trykke på. Og du trenger ikke skrive mer enn det.
Andre ganger kan hensikten bli tolket forskjellig. Et kort kan være interaktivt i noen designsystemer, og en bakgrunnsflate i andre. Da kan det være nyttig å skrive litt om hvilken rolle kort spiller i ditt designsystem.
Man kan også vurdere å liste opp hva en komponent er egnet til, og hva den ikke er egnet til. Det gjør det enklere å velge riktig komponent.
Komponenter har som regel noen muligheter for tilpasning. En tekstlenke har mulighet for å endre både tekst og lenke (og kanskje om den skal åpnes i et nytt vindu eller ei), mens en modal kan vises som åpen eller lukket, i forskjellige bredder, med og uten knapper osv.
Fra et utviklingsperspektiv så kalles disse tilpasningsmulighetene for props. Figma kaller dem properties. Men felles for dem begge er at det er en liste med navn og verdier, som har forskjellige muligheter. Og for å kunne bruke disse godt, så er det viktig at man dokumenterer både hva en prop påvirker, og hvilke muligheter som finnes.
En knapp kan for eksempel ha fire forskjellige varianter (default, outline, ghost og destructive) og tre størrelser (sm, md og lg). Disse er ofte relevante for både designere og teknologer.