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.
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.