Teamkonvensjoner og stilguide

Uten avtalte konvensjoner blir Tailwind-prosjekter gradvis inkonsistente. Én utvikler skriver p-4 overalt, mens en annen bruker px-4 py-4. Én bruker @apply flittig, mens en annen unngår det fullstendig. En stilguide for teamet dokumenterer beslutningene teamet har tatt, slik at alle skriver Tailwind på samme måte. Det gjør kodegjennomganger raskere og kodebasen enklere å vedlikeholde.

Selv om Prettier-programtillegget håndhever rekkefølgen automatisk, bør stilguiden dokumentere hvorfor den kanoniske rekkefølgen brukes, og hvordan den ser ut, slik at utviklerne forstår den i stedet for å følge den blindt. Ta med grupperekkefølgen – layout, størrelser, avstand, typografi, visuelt og interaktivt – slik at teammedlemmene kan forutsi hvor en klasse hører hjemme.

Et vanlig stridstema er når utilities skal trekkes ut med @apply. Definer en tydelig regel: Bruk for eksempel @apply bare når et mønster gjentas mer enn tre ganger på tvers av ulike komponenter OG ikke kan løses med en delt JSX- eller template-komponent. Dette hindrer for tidlig abstraksjon, samtidig som reell duplisering fanges opp.

Tailwinds hakeparentesnotasjon, som w-[347px], er kraftig, men kan føre til en overflod av magiske tall som er vanskelige å vedlikeholde. Stilguiden bør kreve at vilkårlige verdier begrunnes i en kommentar, og at verdier som forekommer mer enn én gang, i stedet legges til i temaets extend-blokk som et navngitt token.

Hver oppføring i safelist øker kostnaden for hvert bygg. Stilguiden bør kreve at safelistede klasser har en kommentar som forklarer hvorfor de ikke kan oppdages statisk. Opprett en plan for gjennomgang av safelisten – for eksempel kvartalsvis – for å fjerne oppføringer for funksjoner som er fjernet eller refaktorert.

Hvis prosjektet bruker @apply til å opprette komponentklasser, bør dere etablere en navnekonvensjon. BEM-inspirerte navn som .btn-primary og .card-body er et vanlig valg. Dokumenter hvilket navnemønster teamet bruker, og sørg for at egendefinerte komponentklasser aldri kommer i konflikt med Tailwinds egne utility-navn.

Dokumenter hvordan teamet håndterer responsivt design. Vanlige konvensjoner er alltid mobile first (basestiler er for mobil, mens prefikser legger til atferd for større skjermer), å bruke bare et utvalg av bruddpunktene (for eksempel bare md og lg) og aldri å bruke et prefiks uten også å definere basistilfellet, slik at stilene arves riktig.

Velg og dokumenter én strategi for mørk modus i hele prosjektet – enten klassestrategien eller mediestrategien – og bland dem aldri. Angi hvilke elementer som alltid trenger en variant for mørk modus (bakgrunner, tekst og kantlinjer), og hvilke som kan arve. Ta med en sjekkliste for å kontrollere at nye komponenter har full støtte for mørk modus før de merges.

Bygg Tailwind-konvensjonene inn i prosessen for gjennomgang av PR-er. En kort sjekkliste i PR-malen minner både forfatteren og gjennomgåeren på å kontrollere de viktigste konvensjonene. Punktene kan omfatte: klassene er sortert, ingen usikre dynamiske klasser konstrueres, vilkårlige verdier har en kommentar, variantene for mørk modus er komplette, og ingen motstridende utilities finnes.

Skriv stilguiden i filen STYLE_GUIDE.md, og commit den til repositoriet. Hold den nær koden, ikke i en separat wiki som blir utdatert. Hver konvensjon bør ha en kort begrunnelse, slik at nye teammedlemmer forstår hvorfor, noe som gjør det enklere å akseptere og følge den. Gå gjennom guiden hvert kvartal, og oppdater den etter hvert som prosjektet utvikler seg.

En stilguide er bare effektiv hvis nye utviklere leser den. Legg inn en lenke til Tailwind-stilguiden i prosjektets README og i onboarding-sjekklisten for nye teammedlemmer. Vurder å legge til en kort quiz eller øvelse der nye utviklere kan bruke konvensjonene på en øvelseskomponent før de arbeider med produksjonskode.

I denne leksjonen lærte De: å definere konvensjoner for @apply og vilkårlige verdier for å forhindre feilbruk, å bygge inn konvensjoner i sjekklister for pull requests for konsekvent gjennomgang, og å dokumentere stilveiledningen i repositoriet slik at den holdes oppdatert. Neste gang bygger vi en komplett hero- og navigasjonsseksjon for en landingsside.