Use when styling React components, choosing a CSS approach, implementing responsive design, or managing CSS architecture. Prevents the common mistake of global style leakage or choosing an incompatible CSS-in-JS library for Server Components. Covers CSS Modules, Tailwind CSS, CSS-in-JS, inline styles, clsx/cn, conditional classes, CSS custom properties. Keywords: CSS Modules, Tailwind, CSS-in-JS, clsx, className, scoped styles, CSS in React, Tailwind setup, CSS Modules, styled-components, scoped styles, dark mode CSS..
Use when styling React components, choosing a CSS approach, implementing responsive design, or managing CSS architecture. Prevents the common mistake of global style leakage or choosing an incompatible CSS-in-JS library for Server Components. Covers CSS Modules, Tailwind CSS, CSS-in-JS, inline styles, clsx/cn, conditional classes, CSS custom properties. Keywords: CSS Modules, Tailwind, CSS-in-JS, clsx, className, scoped styles, CSS in React, Tailwind setup, CSS Modules, styled-components, scoped styles, dark mode CSS..
license
MIT
compatibility
Designed for Claude Code. Requires React 18.x or 19.x with TypeScript.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
react-impl-styling
Quick Reference
Styling Approach Decision Tree
Need to style a React component?
├── Is it a dynamic value computed at runtime (e.g., position, color from props)?
│ └── YES → Use inline styles with React.CSSProperties
├── Is the project using Tailwind CSS?
│ └── YES → Use Tailwind utility classes with cn() helper
├── Do you need scoped, file-level styles?
│ └── YES → Use CSS Modules (.module.css)
├── Do you need a component library with runtime theming?
│ └── YES → Consider CSS-in-JS (styled-components / Emotion)
└── DEFAULT → Use CSS Modules (safest, zero-runtime, best performance)
Approach Comparison
Approach
Runtime Cost
Scoping
TypeScript Support
Recommendation
CSS Modules
None
Automatic
Via declarations
Primary
Tailwind CSS
None
Via utilities
Via cn() typing
Strong alternative
Inline styles
Minimal
Inline
Native
Dynamic values only
CSS-in-JS
Moderate
Automatic
Native
Only when needed
Global CSS
None
None (global)
None
Variables + resets only
Critical Warnings
NEVER use inline styles for pseudo-classes (:hover, :focus), media queries, or animations -- inline styles cannot express these. ALWAYS use CSS Modules or Tailwind for interactive/responsive styles.
NEVER use string interpolation to build className strings -- ALWAYS use clsx() or cn() for conditional class composition to avoid whitespace bugs and improve readability.
NEVER import .css files in component files without the .module.css suffix when you need scoping -- plain .css imports are global and WILL cause style collisions across components.
NEVER use CSS-in-JS (styled-components, Emotion) in React Server Components -- these libraries require a client-side runtime. ALWAYS use CSS Modules or Tailwind for RSC.
ALWAYS define a TypeScript module declaration for .module.css files to prevent import errors and enable autocomplete.
CSS Modules (Primary Recommendation)
CSS Modules provide automatic scoping with zero runtime cost. The bundler (Vite, webpack) transforms class names to unique hashes at build time.
Setup
Create a TypeScript declaration so imports are typed:
NEVER use inline styles for static values -- move them to CSS Modules or Tailwind classes instead. Inline styles bypass the cascade, cannot be overridden by consumers, and increase bundle size.
className Patterns with clsx
The clsx library builds className strings from conditional inputs. ALWAYS use it instead of manual string concatenation:
For non-Tailwind projects, use CSS custom properties with a data-theme attribute and prefers-color-scheme fallback. Define dark overrides in :root[data-theme="dark"] (see Global Styles section above for the pattern). Toggle with:
React 19 introduces built-in support for <link> stylesheet ordering. Use the precedence prop to control CSS load order without manual management:
// React 19 onlyfunctionProductPage() {
return (
<><linkrel="stylesheet"href="/base.css"precedence="default" /><linkrel="stylesheet"href="/product.css"precedence="high" /><divclassName="product-layout"><ProductDetails /></div></>
);
}
functionProductDetails() {
// This stylesheet is deduplicated -- React loads it only oncereturn (
<><linkrel="stylesheet"href="/product.css"precedence="high" /><divclassName="product-details">{/* ... */}</div></>
);
}
React 19 deduplicates stylesheet links and orders them by precedence. This eliminates the need for CSS-in-JS runtime ordering in many cases.
React 18: No precedence prop support. Use CSS Modules or manual <link> ordering in index.html.
CSS-in-JS Overview
CSS-in-JS libraries (styled-components, Emotion) co-locate styles with components and support dynamic theming. Use them ONLY when the project requires runtime theme switching or an existing codebase depends on them.
NEVER choose CSS-in-JS for new projects without a specific runtime theming requirement. CSS Modules and Tailwind cover the vast majority of use cases with zero runtime cost.
