| name | theme-styling |
| description | Apply consistent theming with Tailwind CSS 4, including dark mode support and design tokens. Use when styling components, fixing dark mode issues, or adjusting visual design. |
Theme Styling
Apply consistent styling using Tailwind CSS 4 and the project's theme system.
Tailwind CSS 4
This project uses Tailwind CSS 4, which has significant changes from v3:
- Uses
@theme directive instead of theme() function
- PostCSS config uses
@tailwindcss/postcss
- CSS variables defined in
:root and .dark
Theme System
Colors are defined using CSS custom properties in site/src/index.css:
:root {
--background: oklch(0.97 0.01 85);
--foreground: oklch(0.20 0.02 250);
}
.dark {
--background: oklch(0.14 0.02 260);
--foreground: oklch(0.93 0.01 260);
}
See references/color-tokens.md for the complete token list.
Using Theme Colors
Always use semantic color names, not raw values:
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="border-border">
<button className="bg-primary text-primary-foreground">
// Bad - hardcoded colors
<div className="bg-white text-gray-900">
<div className="bg-[#1a1a2e]">
Dark Mode
Dark mode is implemented via the .dark class on the <html> element.
Adding Dark Mode Styles
Use the dark: variant for dark mode overrides:
<div className="bg-background text-foreground">
<div className="bg-white dark:bg-gray-900">
Testing Dark Mode
- Toggle with the theme switcher in the nav
- Or use browser DevTools to add/remove
.dark class on <html>
Spacing & Layout
Use consistent spacing from the Tailwind scale:
| Class | Size |
|---|
p-2 | 0.5rem (8px) |
p-4 | 1rem (16px) |
p-6 | 1.5rem (24px) |
p-8 | 2rem (32px) |
Mobile-First Responsive
Always start with mobile styles, then add larger breakpoints:
<div className="p-4 md:p-6 lg:p-8">
<div className="grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
// Bad - desktop first
<div className="p-8 sm:p-6 xs:p-4">
Typography
Use the system font stack (already configured):
<h1 className="text-3xl font-bold">
<h2 className="text-2xl font-semibold"> // 24px semibold
<h3 className="text-xl font-medium"> // 20px medium
<p className="text-base"> // 16px regular
<span className="text-sm text-muted-foreground"> // 14px muted
Interactive States
Use consistent state styles:
<button className="
bg-primary text-primary-foreground
hover:bg-primary/90
focus-visible:ring-2 focus-visible:ring-ring
disabled:opacity-50 disabled:pointer-events-none
">
Animations
Use tw-animate-css for animations (already imported):
<div className="animate-fade-in">
<div className="animate-slide-up">
For custom transitions:
<div className="transition-colors duration-200">
<div className="transition-transform duration-300 hover:scale-105">
The cn() Helper
Always use cn() from @/lib/utils for conditional classes:
import { cn } from '@/lib/utils'
<div className={cn(
'base-styles',
isActive && 'active-styles',
className
)}>
Common Patterns
Card
<div className="bg-card text-card-foreground rounded-lg border border-border p-6">
Section
<section className="py-12 md:py-16 lg:py-20">
Button (Primary)
<button className="
px-4 py-2 rounded-md
bg-primary text-primary-foreground
hover:bg-primary/90
focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring
">
Checklist
Before considering styling complete:
