Соглашения команды и руководство по стилю

Без согласованных соглашений проекты Tailwind постепенно становятся непоследовательными. Один разработчик везде пишет p-4, другой использует px-4 py-4. Один активно применяет @apply, другой полностью его избегает. Командное руководство по стилю фиксирует принятые решения, чтобы все писали Tailwind одинаково, а проверка кода проходила быстрее и кодовую базу было проще поддерживать.

Даже если плагин Prettier автоматически соблюдает порядок, в руководстве по стилю следует объяснить, почему используется канонический порядок и как он выглядит, чтобы разработчики понимали его, а не просто слепо ему следовали. Укажите порядок групп: компоновка, размеры, отступы, типографика, визуальные свойства и интерактивность. Тогда участники команды смогут предсказать, где должен находиться класс.

Частая причина разногласий — вопрос о том, когда выносить утилиты с помощью @apply. Определите чёткое правило: например, используйте @apply только если шаблон повторяется более трёх раз в разных компонентах И не может быть реализован с помощью общего компонента JSX или шаблона. Это предотвращает преждевременную абстракцию и помогает выявлять действительно повторяющийся код.

Синтаксис Tailwind со скобками, например w-[347px], очень мощный, но может привести к распространению трудно поддерживаемых магических чисел. В руководстве по стилю следует требовать, чтобы произвольные значения были обоснованы в комментарии, а значения, встречающиеся более одного раза, вместо этого добавлялись в блок extend темы как именованные токены.

Каждая запись в safelist увеличивает стоимость каждой сборки. В руководстве по стилю следует требовать, чтобы для каждого класса в списке разрешённых был комментарий с объяснением, почему его нельзя обнаружить статически. Создайте график проверки списка разрешённых классов, например ежеквартальный, чтобы удалять записи для удалённых или переработанных функций.

Если Ваш проект использует @apply для создания классов компонентов, установите соглашение об именовании. Имена в стиле BEM, например .btn-primary и .card-body, являются распространённым вариантом. Зафиксируйте используемый командой шаблон именования и убедитесь, что пользовательские классы компонентов никогда не конфликтуют с собственными утилитами Tailwind.

Документируйте подход команды к адаптивному дизайну. Распространённые соглашения включают постоянный подход mobile-first (базовые стили предназначены для мобильных устройств, а префиксы добавляют поведение для больших экранов), использование только части контрольных точек (например, только md и lg) и запрет на применение префикса без определения базового случая, чтобы стили корректно наследовались.

Выберите и задокументируйте одну стратегию тёмного режима для всего проекта — либо стратегию классов, либо медиастратегию, — и никогда не смешивайте их. Укажите, каким элементам всегда нужен вариант для тёмного режима (фонам, тексту, границам), а какие могут наследовать стили. Добавьте контрольный список для проверки новых компонентов на полноту поддержки тёмного режима перед слиянием.

Включите соглашения Tailwind в процесс проверки PR. Короткий список в шаблоне PR напомнит автору и проверяющему проверить ключевые правила. В него можно включить следующие пункты: классы отсортированы, динамическое создание классов без списка разрешённых не используется, произвольные значения снабжены комментарием, варианты тёмного режима полны, противоречащие утилиты отсутствуют.

Напишите руководство по стилю в файле STYLE_GUIDE.md и добавьте его в репозиторий. Храните его рядом с кодом, а не в отдельной вики, которая может устареть. Для каждого соглашения укажите краткое обоснование, чтобы новые участники команды понимали зачем оно нужно и могли легче его принять и соблюдать. Проверяйте руководство ежеквартально и обновляйте его по мере развития проекта.

Руководство по стилю эффективно только в том случае, если новые разработчики его читают. Добавьте ссылку на руководство по стилю Tailwind в README проекта и в список шагов адаптации новых участников команды. Можно также добавить небольшой тест или упражнение, в котором новые разработчики применят соглашения к учебному компоненту до начала работы с рабочим кодом.

В этом уроке Вы научились: определять соглашения об использовании @apply и произвольных значений, чтобы предотвращать неправильное применение, включать соглашения в контрольные списки PR для единообразной проверки и документировать руководство по стилю в репозитории, чтобы оно оставалось актуальным. Далее мы создадим полноценный первый экран целевой страницы и навигацию.