Tailwind CSS: Styling Without Writing Custom CSS

Close-up of a keyboard illuminated in blue and purple
Photo by Irina Iriser on Unsplash. Visual editorial reference, not a verified screenshot of the software discussed. · View original image

I resisted Tailwind for years. The argument that long utility class lists make HTML look messy sounded reasonable to me—until I used it on a real project. I realized I had been confusing the appearance of the markup with the productivity of the workflow.

Conceptual illustration of Tailwind CSS design tokens, spacing, colors, and utilities.
Original editorial illustration of the article's design-token concepts.

The Wrong Argument

“Utility classes clutter HTML”—they do make markup longer, but compare them with a button that already needs class="btn btn-primary btn-large". With Tailwind, you do not have to open button.css, variants.css, and layout.css to understand the button’s styling. The relevant decisions are visible in the element itself.

<!-- Before -->
<button class="btn btn-primary btn-lg">

<!-- With Tailwind -->
<button class="px-4 py-2 rounded-md bg-teal-500 text-white font-semibold hover:-translate-y-0.5 transition-transform">

The classes are longer, but they are self-describing. You do not need to maintain a parallel glossary of custom class names.

Extracting Design Tokens from a Reference Site

For this blog, I wanted to study the visual language of craftzdog/craftzdog-homepage. Its original stack uses Next.js and Chakra UI, so copying its CSS classes would not make sense. Instead, I could extract the design tokens from its lib/theme.js file:

const styles = {
  global: props => ({
    body: { bg: mode('#f0e7db', '#202023')(props) }
  })
}
const colors = { grassTeal: '#88ccca' }
const fonts = { heading: "'M PLUS Rounded 1c'" }

Then I could represent the same design decisions in my tailwind.config.mjs:

colors: {
  surface: {
    light: '#f0e7db',
    dark: '#202023',
  },
  grassTeal: '#88ccca',
  link: {
    light: '#3d7aed',
    dark: '#ff63c3',
  },
},
fontFamily: {
  heading: ['"M PLUS Rounded 1c"', 'system-ui', 'sans-serif'],
},
borderRadius: {
  craftz: '12px',  // Reference image radius
},

Now utilities such as bg-surface-light, text-link-dark, rounded-craftz, and bg-grassTeal can be used across the project, keeping the design consistent with the reference.

Dark Mode with the Class Strategy

For the dark/light theme toggle, I used Tailwind’s class strategy. An inline script in the document head adds or removes the dark class on <html> before the first paint. This helps avoid a visible flash of the wrong theme:

<script is:inline>
  (function () {
    const stored = localStorage.getItem('theme');
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    document.documentElement.classList.toggle('dark', stored === 'dark' || (!stored && prefersDark));
  })();
</script>

Tailwind’s dark: variants handle the rest. There is no need for a separate theming framework.

Consistent Image Corners in Markdown

One detail I liked about the reference site was its consistent border-radius: 12px across images. To bring that detail into Markdown content, I added a global rule for images in the prose layer:

.prose :where(img) {
  @apply rounded-craftz;
  @apply border border-black/5 dark:border-white/10;
}

This gives images inserted through Markdown the same rounded corners as the rest of the design.

Conclusion

Tailwind is not the right answer for every project. But for a medium-sized site such as a personal blog, its productivity benefits are hard to ignore. The key is to configure it deliberately: extract the design tokens you want, define them in tailwind.config.mjs, and let the utility classes do their job.