```
ALWAYS pair light and dark variants together on the same element for maintainability.
---
## Inline Styles (Dynamic Values Only)
ALWAYS type inline styles with `React.CSSProperties`. Use inline styles ONLY for values computed at runtime from props or state:
```tsx
interface ProgressBarProps {
value: number; // 0-100
color?: string;
}
export function ProgressBar({ value, color = "#3b82f6" }: ProgressBarProps) {
const barStyle: React.CSSProperties = {
width: `${Math.min(100, Math.max(0, value))}%`,
backgroundColor: color,
height: "0.5rem",
borderRadius: "0.25rem",
transition: "width 0.3s ease",
};
return (
);
}
```
**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:
```tsx
import { clsx } from "clsx";
interface AlertProps {
severity: "info" | "warning" | "error";
dismissible?: boolean;
children: React.ReactNode;
}
export function Alert({ severity, dismissible = false, children }: AlertProps) {
return (
{children}
);
}
```
---
## Global Styles and CSS Custom Properties
### Global CSS Setup
ALWAYS define global design tokens as CSS custom properties in `:root`. This is the ONLY appropriate use for global CSS files:
```css
/* src/index.css */
:root {
--color-primary: #3b82f6;
--color-primary-hover: #2563eb;
--color-secondary: #64748b;
--color-background: #ffffff;
--color-surface: #f8fafc;
--color-text: #0f172a;
--color-text-muted: #64748b;
--color-border: #e2e8f0;
--radius-sm: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
}
/* Dark mode override */
@media (prefers-color-scheme: dark) {
:root {
--color-background: #0f172a;
--color-surface: #1e293b;
--color-text: #f1f5f9;
--color-text-muted: #94a3b8;
--color-border: #334155;
}
}
/* Reset */
*,
*::before,
*::after {
box-sizing: border-box;
margin: 0;
}
```
### Using Custom Properties in CSS Modules
```css
/* Card.module.css */
.card {
background-color: var(--color-surface);
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
padding: 1.5rem;
box-shadow: var(--shadow-sm);
color: var(--color-text);
}
```
---
## Responsive Design with CSS Modules
Use standard media queries inside CSS Modules. ALWAYS use mobile-first (`min-width`) breakpoints:
```css
/* Layout.module.css */
.grid {
display: grid;
grid-template-columns: 1fr;
gap: 1rem;
}
@media (min-width: 640px) { .grid { grid-template-columns: repeat(2, 1fr); } }
@media (min-width: 1024px) { .grid { grid-template-columns: repeat(3, 1fr); } }
```
---
## Dark Mode with CSS Custom Properties
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:
```tsx
import { useEffect, useState } from "react";
type Theme = "light" | "dark" | "system";
export function useTheme() {
const [theme, setTheme] = useState(
() => (localStorage.getItem("theme") as Theme) ?? "system"
);
useEffect(() => {
const root = document.documentElement;
if (theme === "system") root.removeAttribute("data-theme");
else root.setAttribute("data-theme", theme);
localStorage.setItem("theme", theme);
}, [theme]);
return { theme, setTheme };
}
```
---
## React 19: Stylesheet Precedence
React 19 introduces built-in support for `` stylesheet ordering. Use the `precedence` prop to control CSS load order without manual management:
```tsx
// React 19 only
function ProductPage() {
return (
<>
);
}
function ProductDetails() {
// This stylesheet is deduplicated -- React loads it only once
return (
<>
{/* ... */}
);
}
```
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 `` 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.
```tsx
// styled-components pattern (brief reference)
import styled from "styled-components";
const StyledButton = styled.button<{ $variant: "primary" | "secondary" }>`
padding: 0.5rem 1rem;
border-radius: 0.375rem;
font-weight: 600;
background-color: ${(props) =>
props.$variant === "primary" ? "var(--color-primary)" : "transparent"};
color: ${(props) =>
props.$variant === "primary" ? "white" : "var(--color-primary)"};
`;
```
**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.
---
## Reference Links
- [references/examples.md](references/examples.md) -- Complete styling approach examples with TypeScript
- [references/anti-patterns.md](references/anti-patterns.md) -- Common styling mistakes and how to avoid them
### Official Sources
- https://react.dev/learn#adding-styles
- https://react.dev/reference/react-dom/components/link (React 19 precedence)
- https://tailwindcss.com/docs
- https://github.com/lukeed/clsx
- https://github.com/dcastil/tailwind-merge