{"schemaVersion":1,"id":"https://lucioduran.com/decisions/styled-components-over-tailwind","url":"https://lucioduran.com/decisions/styled-components-over-tailwind","title":"styled-components over Tailwind CSS","description":"The portfolio requires a theming system that supports runtime switching between dark and light modes without page reload. The design language demands precise co","language":"en","datePublished":"2024-05-03","dateModified":null,"contentFormat":"text/markdown","content":"ADR-003acceptedMay 3, 2024\n\n# styled-components over Tailwind CSS\n\n## Context\n\nThe portfolio requires a theming system that supports runtime switching between dark and light modes without page reload. The design language demands precise control over micro-interactions, transitions, and conditional styling based on component state. The site's visual identity is achromatic with a single accent color, a system that requires theme tokens to be deeply integrated into every styled element. Tailwind CSS offers utility-first rapid development but generates static class strings at build time. Runtime theme switching with Tailwind requires CSS custom properties or a PostCSS plugin chain, both of which add indirection. styled-components provides a ThemeProvider that injects theme tokens directly into component scope, enabling conditional styling as native JavaScript expressions.\n\n## Decision\n\nAdopt styled-components with a ThemeProvider pattern as the sole styling solution. Theme objects define all design tokens (colors, borders, shadows) and are swapped at the provider level for dark/light mode. Each styled component accesses theme values via the theme prop, enabling expressions like \\`${({ theme }) =\\> theme.colors.borderDefault}\\`. Co-located styles keep visual logic adjacent to component logic, eliminating the cognitive overhead of mapping utility classes to design intent. No global CSS framework is used; GlobalStyle handles only resets and base typography.\n\n## Consequences\n\nPositive: Runtime theming works seamlessly, toggling dark/light mode triggers a re-render with the new theme object, and every component updates atomically. Co-located styles eliminate class name management and make component boundaries self-documenting. Conditional styling based on props (e.g., \\`$active\\` state in navigation) is expressed as native JavaScript, not className string concatenation. Negative: Runtime CSS-in-JS adds ~12KB to the JavaScript bundle (styled-components runtime). Server-side rendering requires additional configuration (ServerStyleSheet) to avoid FOUC. Build-time extraction is not the default, so critical CSS is not automatically inlined. The DX benefit of co-located, prop-driven styles justifies the bundle cost for a portfolio-scale application where the total JS payload is well under performance budgets.\n\n## Calibrated Uncertainty\n\n## Predictions at Decision Time\n\nExpected runtime theming to be the critical differentiator, specifically, instant dark/light mode switching without flicker or reload. Predicted the ~12KB bundle cost would be negligible relative to the total JS payload. Assumed that co-located styles would improve long-term maintainability by keeping styling decisions adjacent to component logic. Predicted no significant performance impact from runtime CSS generation at portfolio scale.\n\n## Measured Outcomes\n\nRuntime theming works exactly as designed, dark/light toggle is instantaneous with no FOUC (ServerStyleSheet configuration was the key). The 12KB bundle cost is indeed negligible (~8% of total JS). Maintainability prediction was accurate: when revisiting components after months, the co-located styles are immediately comprehensible. However, the styled-components ecosystem has shifted significantly since the decision, Tailwind has won the broader ecosystem war, styled-components v6 introduced breaking changes, and the React team's recommendation has moved toward zero-runtime solutions (CSS Modules, Panda CSS). The library is not abandoned but is clearly in maintenance mode.\n\n## Unknowns at Decision Time\n\nDid not anticipate the industry-wide shift away from runtime CSS-in-JS. At decision time, styled-components was the dominant CSS-in-JS library with strong community momentum. The React team's stance on runtime CSS-in-JS (specifically, Seb Markbage's posts about the performance ceiling of runtime approaches in React Server Components) was not publicly known. Also unknown: whether Tailwind v4 would solve the runtime theming gap with native CSS custom property support, it largely did.\n\n## Reversibility Classification\n\nTwo-Way Door\n\nMigration from styled-components to Tailwind or CSS Modules is a component-by-component refactor that can happen incrementally. Both systems can coexist in the same Next.js project during migration. Each component's styles are self-contained, so converting one component doesn't affect others. Estimated effort for full migration: 20-30 hours across 120+ components. No data model or API changes required.\n\n## Strongest Counter-Argument\n\nTailwind CSS with CSS custom properties for theming would have provided: zero runtime JavaScript cost, better tree-shaking, faster build times, and alignment with the industry's direction. Tailwind's utility-first approach also constrains design decisions in ways that enforce consistency, a benefit for a solo developer who is also the designer. The DX trade-off (utility classes vs template literals) is largely a matter of familiarity, not objective superiority. The counter-counter: at the time of the decision, Tailwind's theming story required significant custom configuration, and the portfolio's design system was already expressed as JavaScript theme objects.\n\n## Technical Context\n\nStack\n\n- styled-components 5.3\n- React 18\n- ThemeProvider\n- ServerStyleSheet\n\nBundle Cost\n\n~12KB gzipped\n\nTheme Tokens\n\n24\n\nStyled Components\n\n120+\n\nConstraints\n\n- Runtime theme switching required\n- No page reload on theme change\n- SSR FOUC prevention needed\n\n## Related Decisions\n\n- [ADR-004accepted\n\n  Single Accent Color System over Category-Based Palette](<https://lucioduran.com/decisions/single-accent-color-system>)\n- [ADR-007accepted\n\n  CSS Grid over Flexbox for Layout System](<https://lucioduran.com/decisions/css-grid-over-flexbox>)\n- [ADR-015accepted\n\n  Critical Rendering Path Optimization Strategy](<https://lucioduran.com/decisions/critical-rendering-path-optimization>)\n- [ADR-018accepted\n\n  Monolithic Page Components over Micro-Component Architecture](<https://lucioduran.com/decisions/monolithic-page-components>)\n\n[Back to Decisions](<https://lucioduran.com/decisions>)","headings":[{"level":1,"text":"styled-components over Tailwind CSS","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#title"},{"level":2,"text":"Context","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-context"},{"level":2,"text":"Decision","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-decision"},{"level":2,"text":"Consequences","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-consequences"},{"level":2,"text":"Calibrated Uncertainty","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-uncertainty"},{"level":2,"text":"Predictions at Decision Time","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-predictions"},{"level":2,"text":"Measured Outcomes","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-outcomes"},{"level":2,"text":"Unknowns at Decision Time","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-unknowns"},{"level":2,"text":"Reversibility Classification","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-reversibility"},{"level":2,"text":"Strongest Counter-Argument","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-counterArgument"},{"level":2,"text":"Technical Context","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-techContext"},{"level":2,"text":"Related Decisions","url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-relatedDecisions"}],"sections":[{"heading":"styled-components over Tailwind CSS","level":1,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind","content":"ADR-003acceptedMay 3, 2024"},{"heading":"styled-components over Tailwind CSS","level":1,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#title","content":""},{"heading":"Context","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-context","content":"The portfolio requires a theming system that supports runtime switching between dark and light modes without page reload. The design language demands precise control over micro-interactions, transitions, and conditional styling based on component state. The site's visual identity is achromatic with a single accent color, a system that requires theme tokens to be deeply integrated into every styled element. Tailwind CSS offers utility-first rapid development but generates static class strings at build time. Runtime theme switching with Tailwind requires CSS custom properties or a PostCSS plugin chain, both of which add indirection. styled-components provides a ThemeProvider that injects theme tokens directly into component scope, enabling conditional styling as native JavaScript expressions."},{"heading":"Decision","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-decision","content":"Adopt styled-components with a ThemeProvider pattern as the sole styling solution. Theme objects define all design tokens (colors, borders, shadows) and are swapped at the provider level for dark/light mode. Each styled component accesses theme values via the theme prop, enabling expressions like \\`${({ theme }) =\\> theme.colors.borderDefault}\\`. Co-located styles keep visual logic adjacent to component logic, eliminating the cognitive overhead of mapping utility classes to design intent. No global CSS framework is used; GlobalStyle handles only resets and base typography."},{"heading":"Consequences","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-consequences","content":"Positive: Runtime theming works seamlessly, toggling dark/light mode triggers a re-render with the new theme object, and every component updates atomically. Co-located styles eliminate class name management and make component boundaries self-documenting. Conditional styling based on props (e.g., \\`$active\\` state in navigation) is expressed as native JavaScript, not className string concatenation. Negative: Runtime CSS-in-JS adds ~12KB to the JavaScript bundle (styled-components runtime). Server-side rendering requires additional configuration (ServerStyleSheet) to avoid FOUC. Build-time extraction is not the default, so critical CSS is not automatically inlined. The DX benefit of co-located, prop-driven styles justifies the bundle cost for a portfolio-scale application where the total JS payload is well under performance budgets."},{"heading":"Calibrated Uncertainty","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-uncertainty","content":""},{"heading":"Predictions at Decision Time","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-predictions","content":"Expected runtime theming to be the critical differentiator, specifically, instant dark/light mode switching without flicker or reload. Predicted the ~12KB bundle cost would be negligible relative to the total JS payload. Assumed that co-located styles would improve long-term maintainability by keeping styling decisions adjacent to component logic. Predicted no significant performance impact from runtime CSS generation at portfolio scale."},{"heading":"Measured Outcomes","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-outcomes","content":"Runtime theming works exactly as designed, dark/light toggle is instantaneous with no FOUC (ServerStyleSheet configuration was the key). The 12KB bundle cost is indeed negligible (~8% of total JS). Maintainability prediction was accurate: when revisiting components after months, the co-located styles are immediately comprehensible. However, the styled-components ecosystem has shifted significantly since the decision, Tailwind has won the broader ecosystem war, styled-components v6 introduced breaking changes, and the React team's recommendation has moved toward zero-runtime solutions (CSS Modules, Panda CSS). The library is not abandoned but is clearly in maintenance mode."},{"heading":"Unknowns at Decision Time","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-unknowns","content":"Did not anticipate the industry-wide shift away from runtime CSS-in-JS. At decision time, styled-components was the dominant CSS-in-JS library with strong community momentum. The React team's stance on runtime CSS-in-JS (specifically, Seb Markbage's posts about the performance ceiling of runtime approaches in React Server Components) was not publicly known. Also unknown: whether Tailwind v4 would solve the runtime theming gap with native CSS custom property support, it largely did."},{"heading":"Reversibility Classification","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-reversibility","content":"Two-Way Door\n\nMigration from styled-components to Tailwind or CSS Modules is a component-by-component refactor that can happen incrementally. Both systems can coexist in the same Next.js project during migration. Each component's styles are self-contained, so converting one component doesn't affect others. Estimated effort for full migration: 20-30 hours across 120+ components. No data model or API changes required."},{"heading":"Strongest Counter-Argument","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-counterArgument","content":"Tailwind CSS with CSS custom properties for theming would have provided: zero runtime JavaScript cost, better tree-shaking, faster build times, and alignment with the industry's direction. Tailwind's utility-first approach also constrains design decisions in ways that enforce consistency, a benefit for a solo developer who is also the designer. The DX trade-off (utility classes vs template literals) is largely a matter of familiarity, not objective superiority. The counter-counter: at the time of the decision, Tailwind's theming story required significant custom configuration, and the portfolio's design system was already expressed as JavaScript theme objects."},{"heading":"Technical Context","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-techContext","content":"Stack\n\n- styled-components 5.3\n- React 18\n- ThemeProvider\n- ServerStyleSheet\n\nBundle Cost\n\n~12KB gzipped\n\nTheme Tokens\n\n24\n\nStyled Components\n\n120+\n\nConstraints\n\n- Runtime theme switching required\n- No page reload on theme change\n- SSR FOUC prevention needed"},{"heading":"Related Decisions","level":2,"url":"https://lucioduran.com/decisions/styled-components-over-tailwind#decisionDetail-relatedDecisions","content":"- [ADR-004accepted\n\n  Single Accent Color System over Category-Based Palette](<https://lucioduran.com/decisions/single-accent-color-system>)\n- [ADR-007accepted\n\n  CSS Grid over Flexbox for Layout System](<https://lucioduran.com/decisions/css-grid-over-flexbox>)\n- [ADR-015accepted\n\n  Critical Rendering Path Optimization Strategy](<https://lucioduran.com/decisions/critical-rendering-path-optimization>)\n- [ADR-018accepted\n\n  Monolithic Page Components over Micro-Component Architecture](<https://lucioduran.com/decisions/monolithic-page-components>)\n\n[Back to Decisions](<https://lucioduran.com/decisions>)"}],"links":[{"text":"ADR-004acceptedSingle Accent Color System over Category-Based Palette","url":"https://lucioduran.com/decisions/single-accent-color-system"},{"text":"ADR-007acceptedCSS Grid over Flexbox for Layout System","url":"https://lucioduran.com/decisions/css-grid-over-flexbox"},{"text":"ADR-015acceptedCritical Rendering Path Optimization Strategy","url":"https://lucioduran.com/decisions/critical-rendering-path-optimization"},{"text":"ADR-018acceptedMonolithic Page Components over Micro-Component Architecture","url":"https://lucioduran.com/decisions/monolithic-page-components"},{"text":"Back to Decisions","url":"https://lucioduran.com/decisions"}],"structuredData":[{"@context":"https://schema.org","@graph":[{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com/"},{"@type":"WebSite","@id":"https://lucioduran.com/#website","url":"https://lucioduran.com/","name":"Lucio Durán","inLanguage":["en","es"],"publisher":{"@id":"https://lucioduran.com/#person"}},{"@type":"WebPage","@id":"https://lucioduran.com/decisions/styled-components-over-tailwind#page","url":"https://lucioduran.com/decisions/styled-components-over-tailwind","name":"ADR-003: styled-components over Tailwind CSS | Lucio Durán","description":"The portfolio requires a theming system that supports runtime switching between dark and light modes without page reload. The design language demands precise co","inLanguage":"en","author":{"@id":"https://lucioduran.com/#person"},"publisher":{"@id":"https://lucioduran.com/#person"},"isPartOf":{"@id":"https://lucioduran.com/#website"},"isAccessibleForFree":true,"datePublished":"2024-05-03","mainEntity":{"@id":"https://lucioduran.com/decisions/styled-components-over-tailwind#article"},"breadcrumb":{"@id":"https://lucioduran.com/decisions/styled-components-over-tailwind#breadcrumb"}},{"@type":"TechArticle","url":"https://lucioduran.com/decisions/styled-components-over-tailwind","name":"ADR-003: styled-components over Tailwind CSS","headline":"styled-components over Tailwind CSS","datePublished":"2024-05-03","author":{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com/"},"isPartOf":{"@id":"https://lucioduran.com/#website"},"inLanguage":"en","about":"Software Architecture Decision Record","proficiencyLevel":"Expert","dependencies":"styled-components 5.3, React 18, ThemeProvider, ServerStyleSheet","@id":"https://lucioduran.com/decisions/styled-components-over-tailwind#article","publisher":{"@id":"https://lucioduran.com/#person"},"mainEntityOfPage":{"@id":"https://lucioduran.com/decisions/styled-components-over-tailwind#page"},"isAccessibleForFree":true},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://lucioduran.com/"},{"@type":"ListItem","position":2,"name":"Architecture Decisions","item":"https://lucioduran.com/decisions"},{"@type":"ListItem","position":3,"name":"styled-components over Tailwind CSS","item":"https://lucioduran.com/decisions/styled-components-over-tailwind"}],"@id":"https://lucioduran.com/decisions/styled-components-over-tailwind#breadcrumb"}]}],"contentHash":"f49f6f8e5bca49179fbab48d05432919b1c6a07c5938e53fdf89bf2df72bf30b","provenance":{"method":"Deterministic serialization of the server-rendered main element","source":"https://lucioduran.com/decisions/styled-components-over-tailwind","hashAlgorithm":"sha256","hashScope":"JSON document fields before contentHash and provenance","sourceHTMLBytes":44685,"contentBytes":6129}}
