Team Conventions and Style Guide

Without agreed conventions, Tailwind projects drift into inconsistency. One developer writes p-4 everywhere, another uses px-4 py-4. One uses @apply liberally, another avoids it entirely. A team style guide documents the decisions your team has made so that everyone writes Tailwind the same way, making code reviews faster and the codebase easier to maintain.

Even with the Prettier plugin enforcing order automatically, your style guide should document why the canonical order is used and what it looks like so developers understand it rather than just following it blindly. Include the group order — layout, sizing, spacing, typography, visual, interactive — so team members can predict where a class belongs.

A common source of disagreement is when to extract utilities with @apply. Define a clear rule: for example, use @apply only when a pattern repeats more than three times across different components AND cannot be solved with a shared JSX or template component. This prevents premature abstraction while catching genuine duplication.

Tailwind's bracket notation like w-[347px] is powerful but can lead to a proliferation of magic numbers that are hard to maintain. Your style guide should require that arbitrary values be justified in a comment, and that values appearing more than once be added to the theme's extend block as a named token instead.

Every entry in the safelist adds cost to every build. Your style guide should require that safelisted classes include a comment explaining why they cannot be statically detected. Create a safelist audit schedule — for example, quarterly — to remove entries for features that have been removed or refactored.

If your project uses @apply to create component classes, establish a naming convention. BEM-inspired names like .btn-primary and .card-body are a common choice. Document which naming pattern your team uses and ensure custom component classes never conflict with Tailwind's own utility names.

Document how your team handles responsive design. Common conventions include mobile-first always (base styles are mobile, prefixes add larger-screen behavior), using only a subset of breakpoints (e.g., md and lg only), and never applying a prefix without also defining the base case so styles cascade correctly.

Choose and document one dark mode strategy for the entire project — either the class strategy or the media strategy — and never mix them. Specify which elements always need a dark variant (backgrounds, text, borders) and which can inherit. Include a checklist for reviewing new components for dark mode completeness before merging.

Embed Tailwind conventions into your PR review process. A short checklist in the PR template reminds both author and reviewer to verify key conventions. Items might include: classes are sorted, no unsafed dynamic class construction, arbitrary values have a comment, dark mode variants are complete, and no contradicting utilities are present.

Write the style guide in a STYLE_GUIDE.md file committed to the repository. Keep it close to the code, not in a separate wiki that goes stale. Each convention should include a brief rationale so new team members understand the why, making it easier to accept and follow. Review the guide quarterly and update it as the project evolves.

A style guide is only effective if new developers read it. Include a link to the Tailwind style guide in your project's README and in the onboarding checklist for new team members. Consider adding a short quiz or exercise that lets new developers apply the conventions on a practice component before touching production code.

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

In this lesson you learned: defining @apply and arbitrary value conventions to prevent misuse, embedding conventions into PR checklists for consistent review, and documenting the style guide in the repository so it stays up to date. Next up we build a complete landing page hero and navigation section.