· 3 min read
From styled-components to Tailwind CSS: what changed in how I build UIs
I started my Next.js career writing styled-components and moved to Tailwind CSS. Why I switched, how I migrate a real codebase, and the gotchas that still catch people.
Jose Rai
Senior software engineer
My first production Next.js apps were styled with styled-components, and I loved it. Styles lived next to the component, props drove variants, and theming was one provider away. A few years later I write almost everything in Tailwind CSS. This isn't a story about one being bad. It's about what changed in the way React apps are built, and what I learned migrating real codebases.
What styled-components got right
- Co-location. The styles for a component are in the same file, so deleting a component deletes its CSS.
- Props as variants.
primary,sizeanddisabledflow straight into CSS without class juggling. - Theming. A typed theme object made design tokens feel like code.
What started to hurt
The friction grew with the frameworks around it. styled-components generates and injects styles at runtime, so it ships JavaScript to do what CSS can do on its own. In the Next.js App Router, it needs a style registry built on useServerInsertedHTML for server rendering, and every styled component has to be a Client Component. On pages that are otherwise fully server-rendered, that is a lot of JavaScript just for styling.
The softer problems mattered too: naming every wrapper, hunting for which styled block owns a margin, and slow drift between the theme object and what designers actually used.
What Tailwind changed
Tailwind turns the design system into the API. Spacing, colors and type sizes come from one scale, so the easy path is also the consistent one. There's no runtime: the CSS is generated at build time, and it works in Server Components without any setup. Styles still live next to the markup, which was the part of styled-components I didn't want to lose.
Here's the same button both ways. Prop-driven variants become a small map of class strings:
// Before: styled-components
const Button = styled.button<{ $primary?: boolean }>`
padding: 10px 20px;
border-radius: 999px;
font-weight: 600;
background: ${({ $primary, theme }) => ($primary ? theme.colors.accent : theme.colors.fill)};
color: ${({ $primary, theme }) => ($primary ? theme.colors.onAccent : theme.colors.text)};
`;
// After: Tailwind CSS
const variants = {
primary: "bg-accent text-on-accent hover:opacity-85",
secondary: "bg-fill text-label hover:bg-fill/70",
};
export function Button({ variant = "primary", className, ...props }: ButtonProps) {
return (
<button
className={cn("rounded-full px-5 py-2.5 font-semibold", variants[variant], className)}
{...props}
/>
);
}How I migrate a real codebase
- Tokens first. Move the theme into CSS variables and expose them to Tailwind. In Tailwind v4 that's a
@themeblock in your CSS, with no config file. - Leaves before layouts. Convert buttons, inputs and cards first, then the pages that use them. Both systems can run side by side during the migration.
- State through data attributes. Instead of a
focusedprop changing CSS, setdata-focusedon the element and style it withdata-[focused=true]:variants. It works in Server Components and reads clearly in DevTools. - One `cn()` helper.
clsxplustailwind-mergelets a parent override a child's classes without specificity fights. - Delete the registry last. Once nothing imports styled-components, remove the provider and the dependency, and watch the client bundle shrink.
@import "tailwindcss";
@theme {
--color-accent: #1d1d1f;
--color-label: #1d1d1f;
--breakpoint-tablet: 640px;
--animate-rise: rise 0.9s cubic-bezier(0.32, 0.72, 0, 1) both;
}Gotchas that still catch people
- Cascade layers. Tailwind v4 puts utilities in a CSS layer, and unlayered third-party CSS beats any layered rule. If a slider library's stylesheet wins, that's why. Use the
!important modifier for those few overrides. - Logical properties. v4's
space-xandspace-yuse logical margins. Inside an element with a verticalwriting-mode, they point the other way. Usegapfor flex layouts and it stops mattering. - Class soup. Long class lists aren't a reason to reach for
@apply. They're a sign it's time to extract a component. - Dynamic class names. Tailwind finds classes by scanning your source. A class built at runtime from string pieces never gets generated, so map variants to complete class names.
If I started a new Next.js project today, it would be Tailwind from the first commit. But the habits styled-components taught me still hold: keep styles close to components, make variants explicit, and treat design tokens as code.