Integrasjon av dokumentasjon og stilguide

Vis den minste mengden HTML som trengs for å bruke hver komponent: <app-button variant="primary">Save</app-button>. Vis varianter (primary, secondary, danger), tilstander (loading, disabled) og spesialtilfeller (lang tekst, med ikon, full bredde). Eksempler som kan kopieres og limes inn nøyaktig på en ekte side, er det teamene faktisk bruker.

Den beste dokumentasjonen gjengir eksempelet ved siden av kildekoden. Storybook gjør dette innebygd, mens mdx-deck, Docusaurus og Astro Starlight støtter MDX med live JSX. Når De ser det faktiske resultatet mens De leser markuppen, forsvinner tvilen om «fungerer dette?»

Dokumenter tilgjengelighetsoppførselen som er innebygd i hver komponent: hvilke tastaturinteraksjoner, hvilke ARIA-roller og hvilken fokusstyring. Forbrukere som tar i bruk komponenten, får tilgjengelighetsløsningen med på kjøpet, og kontrollører kan bekrefte at de ikke bryter kontrakten.

Vis tydelige ant mønstre: «Ikke bruk Modal for viktig, kortvarig tilbakemelding – bruk Toast i stedet». Et negativt eksempel er ofte mer minneverdig enn et positivt. Knytt et tydelig «ikke gjør» til hvert «gjør» for å synliggjøre feilmodusene.

Dokumenter navnemønstrene: BEM, atomic CSS, CSS Modules og sammensetting av Tailwind-verktøyklasser. Skriv tydelig ned reglene for klassenavn, navn på egendefinerte egenskaper og filbaner. Konsistente navn reduserer den kognitive belastningen, mens inkonsistente navn koster hver utvikler tid for alltid.

Dokumenter hvorfor beslutningene ble tatt, ikke bare hva de var. «Vi valgte React fremfor Vue fordi …» bevarer konteksten for fremtidige bidragsytere. ADR-er (Architecture Decision Records) i Markdown ved siden av koden er et lettvektsformat som tåler utskiftinger i teamet.

Nye teammedlemmer bør kunne levere sin første komponent på én dag. En sjekkliste kan være: sett opp repoet, installer avhengighetene, kjør Storybook, finn riktig komponentmal, skriv dokumentasjonen og åpne en PR. Følg med på tiden frem til første PR som en måling – kortere tid er bedre.

Den beste dokumentasjonen er enkel å finne både for nye som søker, og for erfarne utviklere. Bruk et dokumentsnettsted med søk (Algolia for Docusaurus, innebygd søk for Starlight). Merk komponenter med flere aliaser – «Modal» bør også kunne finnes ved søk etter Dialog, Popup og Overlay.

Kombiner dokumentasjon med visuell regresjon: Chromatic tar øyeblikksbilder av hver Storybook-story ved hver PR og viser visuelle forskjeller. En sammenslått PR som ved et uhell endrer utseendet på Button i hele dokumentasjonen, blokkerer dermed seg selv. Dette kombinerer dokumentasjon med aktiv testing av designsystemet.

Dokumenter det bare vedlikeholderen kjenner til: fallgruvene, de halvferdige abstraksjonene og hackene som venter på å bli ryddet opp i. Fremtidige De (eller erstatteren Deres) vil takke dagens Dem for å ha tatt vare på denne organisasjonskunnskapen før den blir glemt.

Dokumentasjon forsterker verdien av et designsystem. Bruk levende dokumentasjon (Storybook, Histoire og Ladle) som importerer den faktiske komponentkoden. Vis eksempler som er minst mulig, men likevel komplette, dokumenter tilgjengelighet, ta vare på beslutninger, skriv par med «gjør» og «ikke gjør», og kombiner med tester for visuell regresjon. Behandle dokumentasjon som en førsteklasses leveranse, ikke som noe som kommer i etterkant.