Styling with Tailwind CSS v4
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup Admin project utilizes Tailwind CSS v4 as its primary styling engine. This version transitions from a JavaScript-heavy configuration to a CSS-first approach using @theme blocks within CSS files to define design tokens. It provides a highly responsive, utility-first framework that handles both light and dark modes through CSS variables and native media queries.
The styling architecture is deeply integrated with Next.js 16 and React 19, leveraging modern CSS features like container queries and CSS variables for dynamic theme switching. Design tokens are centralized in the global CSS file and exposed to React components through standard utility classes and specialized UI components.
Sources: package.json:34, README.md:10, README.md:46
Core Styling Architecture
The project's styling system is built on a "CSS-first" configuration model. Instead of relying solely on tailwind.config.ts for theme definitions, Tailwind v4 imports directly into the global stylesheet and uses the @theme directive to map CSS variables to Tailwind utility classes.
Theme Configuration Flow
The following diagram illustrates how CSS variables flow from the root definition into the Tailwind theme engine and finally to React components.
The diagram shows the cascading nature of styles where the Global CSS layer provides the raw tokens that the Tailwind engine transforms into usable utilities.
Sources: app/globals.css:1-55, app/layout.tsx:43-55
Design Tokens and CSS Variables
The project defines its visual identity using a set of semantic CSS variables. These variables are updated based on the user's system preference using a prefers-color-scheme: dark media query.
Primary Color Palette
The following tokens are defined in app/globals.css and mapped to Tailwind's theme:
| Variable | Light Mode | Dark Mode | Description |
|---|---|---|---|
--background | #ffffff | #0a0a0a | Primary page background |
--foreground | #0a0a0a | #fafafa | Primary text color |
--primary | #171717 | #fafafa | Main brand/action color |
--muted | #f5f5f5 | #262626 | De-emphasized backgrounds |
--border | #e5e5e5 | #262626 | Component and layout borders |
--ring | #0a0a0a | #d4d4d4 | Focus state indicators |
Theme Mapping
In Tailwind v4, these variables are mapped to utility namespaces within an @theme inline block:
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-primary: var(--primary);
--color-border: var(--border);
/* ... */
}
Sources: app/globals.css:3-55
Typography and Fonts
Typography is handled via Next.js Google Fonts integration, specifically using Geist Sans and Geist Mono. These fonts are injected as CSS variables into the HTML body to maintain consistency across the application.
- Geist Sans: Defined as
--font-geist-sans, used for general UI text. - Geist Mono: Defined as
--font-geist-mono, used for tabular data, IDs, and code snippets. - Antialiasing: The
antialiasedutility is applied globally to the body tag.
Sources: app/layout.tsx:6-18, app/layout.tsx:43-45, app/globals.css:41
Component-Level Styling
Shared UI components utilize the cn (class-name) utility, which combines clsx and tailwind-merge to allow for dynamic class manipulation and predictable style overrides.
Implementation Patterns
UI Tables
Tables use a combination of border utilities and specific child selectors ([&_tr]) to manage layout and borders.
const TableHeader = React.forwardRef<...>(({ className, ...props }, ref) => (
<thead ref={ref} className={cn("[&_tr]:border-b", className)} {...props} />
));
Sources: components/ui/table.tsx:21-25, package.json:17, package.json:23
Cards and Containers
Cards leverage Tailwind's @container for container queries and standard spacing utilities.
function Card({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card"
className={cn(
"flex flex-col gap-6 rounded-xl border bg-card py-6 text-card-foreground shadow-sm",
className
)}
{...props}
/>
)
}
Sources: components/ui/card.tsx:5-17
Data Visualization Styling
The AdminLineChart and ChartContainer components demonstrate how Tailwind v4 tokens are integrated into third-party libraries like Recharts.
Dynamic Chart Theming
A unique ChartStyle component generates per-chart CSS overrides that map Tailwind theme colors to CSS variables used by Recharts SVG elements. This ensures that charts automatically respect light/dark mode transitions.
| Feature | Implementation | Source |
|---|---|---|
| Grid Lines | [&_.recharts-cartesian-grid_line]:stroke-border/50 | components/ui/chart.tsx:59 |
| Axis Text | [&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground | components/ui/chart.tsx:59 |
| Tooltips | bg-background border-border/50 shadow-xl | components/ui/chart.tsx:165-168 |
Summary
Styling in the Recoup Admin platform is managed through a modernized Tailwind CSS v4 pipeline. By moving configuration into CSS variables and using @theme blocks, the project achieves a seamless transition between light and dark modes while maintaining a strict design system. The integration of tailwind-merge and container queries allows for robust, component-based development that remains performant and easy to maintain.