Integration af dokumentation og styleguide

Vis den minimale HTML-mængde, der skal bruges til hver komponent: <app-button variant="primary">Save</app-button>. Vis varianter (primary, secondary, danger), tilstande (loading, disabled) og randtilfælde (lang tekst, med ikon, fuld bredde). Eksempler, der kan kopieres direkte ind på en rigtig side, er dem, teams faktisk bruger.

Den bedste dokumentation gengiver eksemplet ved siden af kildekoden. Storybook gør det indbygget; mdx-deck, Docusaurus og Astro Starlight understøtter MDX med levende JSX. Når du ser det rigtige resultat, mens du læser opmærkningen, forsvinder tvivlen om »virker det?«.

Dokumentér den tilgængelighedsadfærd, der er indbygget i hver komponent: hvilke tastaturinteraktioner, hvilke ARIA-roller og hvilken fokusstyring. Brugere, der tager komponenten i brug, får tilgængeligheden med uden ekstra arbejde, og reviewere kan kontrollere, at de ikke bryder kontrakten.

Vis tydelige antipatterns: »Brug ikke Modal til vigtig, kortvarig tilbagemelding — brug Toast i stedet«. Et negativt eksempel huskes ofte bedre end et positivt. Sæt et tydeligt »Undgå« sammen med hvert »Gør« for at synliggøre, hvordan noget kan gå galt.

Dokumentér navngivningsmønstrene: BEM, atomic CSS, CSS Modules og Tailwind-sammensætning af hjælpeklasser. Beskriv reglerne tydeligt for klassenavne, navne på brugerdefinerede egenskaber og filstier. Konsekvent navngivning reducerer den kognitive belastning; inkonsekvent navngivning koster enhver udvikler tid for altid.

Notér, hvorfor beslutninger blev truffet, ikke kun hvad de var. »Vi valgte React frem for Vue, fordi…« bevarer konteksten for fremtidige bidragydere. ADR'er (Architecture Decision Records) i Markdown ved siden af koden er et letvægtsformat, der overlever udskiftninger på teamet.

Nye teammedlemmer bør kunne levere deres første komponent på én dag. En tjekliste: Sæt kodearkivet op, installér afhængigheder, kør Storybook, find den rigtige komponentskabelon, skriv dokumentationen, og åbn en PR. Mål tiden til den første PR; lavere er bedre.

Den bedste dokumentation er nem at finde for både nye og erfarne brugere. Brug et dokumentationswebsted med søgning (Algolia til Docusaurus, indbygget søgning i Starlight). Mærk komponenter med flere aliaser — »Modal« skal kunne findes med søgninger på Dialog, Popup og Overlay.

Kombinér dokumentation med visuel regressionstest: Chromatic tager et øjebliksbillede af hver Storybook-story ved hver PR og viser visuelle forskelle. En sammenflettet PR, der utilsigtet ændrer Button-stylingen på tværs af dokumentationen, blokerer sig selv. Det kombinerer dokumentation med aktiv testning af designsystemet.

Dokumentér det, som kun vedligeholderen kender: faldgruberne, de halvfærdige abstraktioner og de hacks, der venter på at blive ryddet op. Dit fremtidige jeg (eller din afløser) vil takke dig for at have nedskrevet denne organisatoriske viden, før du glemmer den.

Dokumentation er en multiplikator for værdien af et designsystem. Brug levende dokumentation (Storybook, Histoire, Ladle), der importerer den faktiske komponentkode. Vis minimale, brugbare eksempler, dokumentér tilgængelighed, nedskriv beslutninger, skriv par med »Gør« og »Undgå«, og kombinér med visuelle regressionstests. Behandl dokumentation som en førsteklasses leverance, ikke som en eftertanke.