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?

Hva burde du ha med?

Når du dokumenterer en komponent, så er det et par hovedområder vi liker å fokusere på:

• Hva er hensikten til komponenten?
• Hvilke muligheter har man til å tilpasse komponenten?
• Hvordan burde man bruke komponenten?
• Hvilke alternative komponenter kan være interessante?

La oss dykke litt dypere i hver av disse spørsmålene.

Hva er hensikten til komponenten?

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.

Hvilke muligheter har man til å tilpasse komponenten?

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.

Det finnes også en del props som er mest relevante for utviklere. Det kan inkludere event-lyttere for klikk eller fokus, eller egne props for å forbedre universell utforming.

Hvis det er visse ting man ikke vil kunne tilpasse på en komponent, kan det også være smart å skrive litt om hvorfor man har gjort det valget. Det vil gjøre det lettere å forstå og tilpasse bruken, eller å finne en annen komponent som tillater det man trenger.

Hvordan burde man bruke komponenten?

Når man vet hva man kan gjøre (og ikke gjøre) med en komponent, er det på tide å vite hvordan den burde brukes. Det gjør at organisasjonen bruker komponenten riktig og konsekvent, og at man unngår bruksmønstre som kan være klønete for sluttbrukere.

Alle retningslinjer burde dokumenteres, enten via eksempler eller via en forklarende tekst.

Vi anbefaler at man legger ved eksempler på hva man skal gjøre og ikke gjøre i visse situasjoner. Her er hvordan Nav gjør det i sitt designsystem, Aksel:

Hvilke alternative komponenter kan være interessante?

I noen situasjoner, så kan det være flere forskjellige komponenter som kan løse utfordringen man har. I de tilfellene, kan det være nyttig å liste opp andre komponenter som kan være potensielle kandidater.

Et av de vanligste eksempler er når man skal velge ett av flere valg. Avhengig av antallet valg man har, så kan man velge en bryter, radiobokser, en select eller en combobox. Da kan det være nyttig å gjøre det enkelt å utforske disse elementene i samme slengen.

Det å dokumentere komponentene dine på riktig måte gjør designsystemet ditt enklere å bruke, mer verdifullt for flere, og raskere å komme i gang med. Så når du først skal dokumentere en komponent, husk å ta med hensikten, tilpasningsmulighetene, retningslinjer for bruk og potensielle alternativer.