Tailwind CSS Do's and Don'ts

Seeing good and bad examples side by side makes best practices concrete. This lesson walks through common Tailwind do's and don'ts across layout, responsiveness, theming, and accessibility.

Why Do's and Don'ts Matter

Tailwind's flexibility means there's rarely a single "correct" way to write a given piece of markup, but some approaches age much better than others as a project grows. This lesson highlights the patterns worth adopting and the ones worth avoiding.

<!-- Do: extend the theme for a recurring brand color -->
<div class="bg-brand-600 text-white">On-brand, reusable</div>

<!-- Don't: repeat a raw hex value everywhere -->
<div class="bg-[#1d4ed8] text-white">Hard to update consistently later</div>

Both examples render identically today, but only the first stays easy to update project-wide.

How to Read This Lesson

Do: <recommended pattern>
Don't: <pattern to avoid>

Each section pairs a recommended approach with a common anti-pattern.
Most "don'ts" aren't broken, they just create maintenance problems as a project scales.
Use these as a quick reference when reviewing pull requests or onboarding new team members.

Do's and Don'ts Quick Reference

A fast-scan summary of the detailed examples below.

Do	Don't
Extend the theme for recurring colors/spacing	Repeat the same arbitrary value everywhere
Use `gap-*` in flex/grid layouts	Add manual margin between every child
Use `focus-visible:ring-*` for focus states	Remove outlines with no accessible replacement
Extract repeated patterns into components	Copy-paste long class lists across many elements
Use real `<button>`/`<a>` elements	Style a `<div onclick>` to act like a button
Add `dark:` variants alongside colors	Ship dark mode without testing text contrast
Use `min-h-screen` for page wrappers	Use `h-screen` and risk clipping tall content
Use semantic HTML with utility classes on top	Use only `<div>`s styled to look like other elements

Theming

Centralizing brand colors and spacing in the theme configuration keeps a project easy to rebrand or adjust later.

Do: Extend the theme for brand colors

theme: { extend: { colors: { brand: "#1d4ed8" } } }

Don't: Repeat raw hex values across markup

<div class="bg-[#1d4ed8]">...</div>
<div class="bg-[#1d4ed8]">...</div>
<div class="bg-[#1d4ed8]">...</div>

Spacing in Flex and Grid Layouts

Native gap support avoids the edge-spacing problems that manual child margins introduce.

Do: Use gap on the parent

<div class="flex gap-4">
  <div>A</div>
  <div>B</div>
</div>

Don't: Add margin to every child

<div class="flex">
  <div class="mr-4">A</div>
  <div class="mr-4">B</div>
</div>

Focus and Accessibility

Removing focus indicators without a replacement makes an interface unusable for keyboard users.

Do: Replace the outline with a visible ring

<button class="focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500">
  Accessible
</button>

Don't: Remove focus styling entirely

<button class="focus:outline-none">
  No visible focus indicator at all
</button>

Common Mistakes

Treating every "don't" as a hard rule rather than understanding the underlying maintenance reasoning.
Applying these patterns inconsistently across a codebase instead of as a team-wide standard.
Ignoring the "do" examples because the "don't" version happens to work fine in a quick prototype.
Not revisiting older code written before these conventions were adopted.
Assuming these do's and don'ts are exhaustive rather than a starting reference.

Key Takeaways

Most Tailwind "don'ts" still render correctly, they just create long-term maintenance costs.
Centralizing theme values beats repeating arbitrary values across markup.
Native gap-* support is more robust than manual margin-based spacing in flex/grid layouts.
Never remove focus indicators without providing an accessible replacement.
Use these patterns as a living reference during code review, not a one-time read.

Pro Tip

Turn this do's and don'ts list into an actual code review checklist for your team; patterns that are only ever read once rarely change real-world habits.