Organizacja plików i folderów

W miarę rozrastania się projektów Tailwind zwiększa się liczba plików związanych z konfiguracją CSS — konfiguracją Tailwind, konfiguracją PostCSS, globalnymi arkuszami stylów i stylami na poziomie komponentów. Bez przejrzystej struktury pliki te rozpraszają się po projekcie i stają się trudne do znalezienia. Dobra organizacja plików od razu wskazuje, gdzie dodawać nowe wartości, gdzie znajdują się globalne nadpisania i które reguły CSS należą do danego komponentu.

Pliki konfiguracyjne wpływające na cały proces budowania — tailwind.config.js, postcss.config.js i .prettierrc — znajdują się w katalogu głównym projektu, obok package.json. Są umieszczane na tym poziomie, ponieważ narzędzia budujące odnajdują je zgodnie z przyjętą konwencją. Nie należy umieszczać ich w src/, chyba że używany toolchain jawnie obsługuje wyszukiwanie konfiguracji poza katalogiem głównym.

Umieść wszystkie pliki CSS w dedykowanym katalogu src/styles/. Głównym punktem wejścia jest globals.css, który zawiera trzy dyrektywy @tailwind, nadpisania @layer dla elementów bazowych oraz importy dodatkowych arkuszy stylów. Style właściwe dla komponentów umieszczaj w osobnych plikach, takich jak button.css lub prose-overrides.css, importowanych do globals.css.

Plik globals.css jest punktem wejścia importowanym do głównego pliku aplikacji. Zawiera trzy dyrektywy Tailwind w odpowiedniej kolejności, a następnie importy dodatkowych arkuszy stylów. Unikaj umieszczania w tym pliku niestandardowych stylów poza dyrektywami — dla przejrzystości trzymaj deklaracje własnych warstw w osobnych plikach importowanych tutaj.

W frameworkach opartych na komponentach, takich jak React lub Vue, można umieścić niewielki plik CSS obok pliku komponentu, gdy style są z nim ściśle powiązane. W projektach Tailwind zdarza się to jednak rzadko, ponieważ większość stylów znajduje się bezpośrednio w nazwach klas w znacznikach. Pliki CSS obok komponentów należy rezerwować wyłącznie dla stylów, których rzeczywiście nie da się wyrazić za pomocą utility classes — takich jak złożone selektory :focus-within lub reguły @keyframes.

Gdy plik tailwind.config.js znacznie się rozrośnie, wyodrębnij obiekt theme.extend do osobnego pliku, takiego jak theme/extend.js. Dzięki temu główny plik konfiguracji pozostanie krótki i czytelny, a plik z rozszerzeniem motywu może rozwijać się bez ograniczeń. Zaimportuj rozszerzenie i użyj operatora spread w głównej konfiguracji.

Jeśli projekt korzysta z kilku pluginów Tailwind, a każdy z nich wymaga rozbudowanej konfiguracji, wyodrębnij konfigurację pluginów do osobnych plików w katalogu plugins/. Każdy plik eksportuje skonfigurowany plugin i jest importowany do tablicy plugins głównej konfiguracji. Ułatwia to sprawdzenie, które pluginy są aktywne, oraz niezależne dostosowywanie ich ustawień.

Tokeny projektowe — kolory, typografia i odstępy — najlepiej definiować w osobnym katalogu tokens/, zamiast umieszczać je bezpośrednio w konfiguracji Tailwind. Każda kategoria tokenów znajduje się w osobnym pliku: tokens/colors.js, tokens/typography.js, tokens/spacing.js. Pliki te można jednocześnie współdzielić z narzędziami projektowymi, konfiguracjami Storybooka i konfiguracją Tailwind.

Wzorce glob dla treści powinny być uporządkowane i czytelne. Grupuj je według typu i lokalizacji pliku, zamiast zapisywać jeden ogólny wzorzec przeszukujący zbyt szeroki zakres. Dodaj komentarz do każdego wzorca, wyjaśniający, którą część projektu obejmuje. Aktywnie utrzymuj tę listę — usuwaj stare wzorce po zmianie lub usunięciu katalogów i dodawaj nowe, gdy wprowadzane są nowe typy plików.

Podczas używania @layer do dodawania niestandardowych stylów stosuj spójne nazewnictwo. Używaj @layer base do resetów na poziomie elementów (np. a, h1, input), @layer components do wzorców łączących wiele utility classes i mających znaczące nazwy (.btn, .card), a @layer utilities do utility classes o jednym przeznaczeniu, których nie ma w domyślnym zestawie Tailwind. Nigdy nie łącz tych odpowiedzialności.

Udokumentuj strukturę plików i katalogów w pliku README projektu lub w dedykowanym pliku STYLE_GUIDE.md. Dołącz diagram katalogu src/styles/, wyjaśnij, w którym pliku powinien znaleźć się każdy rodzaj stylu, i wskaż, kto odpowiada za utrzymanie wzorców glob dla treści. Nowi deweloperzy powinni móc zrozumieć, gdzie dodać nowy niestandardowy kolor lub klasę komponentu, czytając jedną stronę dokumentacji.

W tej lekcji nauczyli się Państwo: przechowywania plików konfiguracyjnych w katalogu głównym projektu dla zapewnienia zgodności z toolchainem, organizowania stylów w katalogu src/styles/ z osobnymi plikami dla każdej warstwy oraz wyodrębniania tokenów motywu i pluginów do dedykowanych plików w miarę rozrastania się konfiguracji. Następnie omówimy współistnienie z dotychczasowym kodem CSS w istniejących projektach.