Integration med dokumentation och stilguide

Visa den minsta mängd HTML som krävs för att använda varje komponent: <app-button variant="primary">Save</app-button>. Visa varianter (primary, secondary, danger), tillstånd (loading, disabled) och specialfall (long text, with icon, full-width). Exempel som kan kopieras och klistras in exakt på en riktig sida är de som teamen faktiskt använder.

Den bästa dokumentationen renderar exemplet bredvid källkoden. Storybook gör detta inbyggt, medan mdx-deck, Docusaurus och Astro Starlight stöder MDX med live JSX. Att se det verkliga resultatet medan man läser markupen undanröjer direkt tvivlet ”fungerar detta?”.

Dokumentera det tillgänglighetsbeteende som är inbyggt i varje komponent: vilka tangentbordsinteraktioner, vilka ARIA-roller och vilken fokushantering som används. Konsumenter som använder komponenten får tillgänglighet på köpet, och granskare kan verifiera att de inte bryter mot kontraktet.

Visa tydliga antipattern: ”Använd inte Modal för viktig tillfällig återkoppling – använd Toast i stället”. Ett negativt exempel är ofta mer minnesvärt än ett positivt. Koppla varje rekommendation till ett tydligt exempel på vad som inte ska göras, så att felkällorna blir synliga.

Dokumentera namnmönstren: BEM, atomic CSS, CSS Modules och Tailwind utility composition. Skriv tydligt ut reglerna för klassnamn, namn på custom properties och filsökvägar. Konsekvent namngivning minskar den kognitiva belastningen, medan inkonsekvent namngivning kostar varje utvecklare tid för alltid.

Dokumentera varför besluten fattades, inte bara vilka besluten var. ”Vi valde React i stället för Vue eftersom …” bevarar sammanhanget för framtida bidragsgivare. ADR:er (Architecture Decision Records) i markdown bredvid koden är ett lättviktigt format som överlever personalomsättning.

Nya teammedlemmar bör kunna leverera sin första komponent på en dag. En checklista kan innehålla: konfigurera repot, installera beroenden, köra Storybook, hitta rätt komponentmall, skriva dokumentationen och öppna en PR. Följ upp tiden till den första PR:en som ett mätetal – kortare tid är bättre.

Den bästa dokumentationen är lätt att hitta för både nya användare och erfarna utvecklare. Använd en dokumentationswebbplats med sökning (Algolia för Docusaurus, inbyggd sökning för Starlight). Tagga komponenter med flera alias – ”Modal” hittas vid sökningar på Dialog, Popup och Overlay.

Kombinera dokumentation med visuell regressionstestning: Chromatic tar en bild av varje Storybook story vid varje PR och visar visuella skillnader. En sammanslagen PR som av misstag ändrar stilen på Button i hela dokumentationen blockerar sig själv. På så sätt kombineras dokumentation med aktiv testning av designsystemet.

Dokumentera sådant som bara underhållaren känner till: fallgroparna, de halvfärdiga abstraktionerna och hacken som väntar på att rensas upp. Framtida ni (eller er ersättare) kommer att tacka er för att ni dokumenterade denna organisationskunskap innan ni glömmer den.

Dokumentation multiplicerar värdet av ett designsystem. Använd levande dokumentation (Storybook, Histoire, Ladle) som importerar den faktiska komponentkoden. Visa minsta fungerande exempel, dokumentera tillgänglighet, fånga beslut, skriv par med rekommendationer och avrådanden och kombinera med visuella regressionstester. Behandla dokumentationen som en central leverans, inte som något man gör i efterhand.