Skip to content
Writing

· 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, size and disabled flow 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:

tsx
// 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 @theme block 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 focused prop changing CSS, set data-focused on the element and style it with data-[focused=true]: variants. It works in Server Components and reads clearly in DevTools.
  • One `cn()` helper. clsx plus tailwind-merge lets 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.
css
@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-x and space-y use logical margins. Inside an element with a vertical writing-mode, they point the other way. Use gap for 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.