# Tailwind CSS Theme Configuration

> Configure Tailwind CSS v4 and Shadcn UI themes in this repo.

*Canonical: https://makerkit.dev/docs/nextjs-prisma/branding/tailwind-css*

---

Configure your color palette and component styling using Tailwind CSS v4 and Shadcn UI themes - all through CSS variables without modifying components.

This repo uses Tailwind CSS v4 with Shadcn UI for styling. Theme customization happens through CSS variables defined in the `styles/` directory.

The Tailwind CSS theme in this kit is a set of CSS custom properties (variables) that control colors, radii, and spacing across all Shadcn UI components. Changing these variables updates the entire UI.

## CSS File Structure

| File | Purpose | Edit? |
|------|---------|-------|
| `globals.css` | Main entry point, imports other files | Rarely |
| `theme.css` | Tailwind v4 theme tokens | Rarely |
| `shadcn-ui.css` | Shadcn UI CSS variables | Rarely |
| `custom.css` | **Your customizations go here** | Yes |
| `makerkit.css` | Kit-specific styles | Rarely |
| `markdoc.css` | Documentation content styles | Rarely |

## Applying a Shadcn UI Theme

Copy CSS variables from the Shadcn UI themes page into your `custom.css`:

### Step 1: Choose a Theme

Go to the [Shadcn UI Themes page](https://ui.shadcn.com/themes), select a theme, and click "Copy".

### Step 2: Paste into custom.css

Edit `apps/web/styles/custom.css` and paste the copied CSS:

```css
/*
 * custom.css
 * Add your custom styles here
 */

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    --card: 0 0% 100%;
    --card-foreground: 240 10% 3.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 240 10% 3.9%;
    --primary: 240 5.9% 10%;
    --primary-foreground: 0 0% 98%;
    /* ... all other variables from the theme */
  }

  .dark {
    --background: 240 10% 3.9%;
    --foreground: 0 0% 98%;
    /* ... dark mode variables */
  }
}
```

### Step 3: Restart the Dev Server

Tailwind CSS v4 may require a restart to pick up CSS changes:

```bash
pnpm dev
```

After restart, verify your theme applied by checking any button or link - they should show your new primary color. If colors don't update, hard refresh with Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows).

## Defining Custom Colors

To use your own brand colors, define CSS variables in `custom.css`:

```css
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    /* Add all required variables */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    --primary-foreground: 222.2 47.4% 11.2%;
  }
}
```

Colors use HSL format without the `hsl()` wrapper: `hue saturation% lightness%`.

## Required CSS Variables

Shadcn UI expects these variables to be defined:

| Variable | Purpose |
|----------|---------|
| `--background` | Page background |
| `--foreground` | Default text color |
| `--primary` | Primary brand color |
| `--primary-foreground` | Text on primary color |
| `--secondary` | Secondary color |
| `--muted` | Muted backgrounds |
| `--accent` | Accent highlights |
| `--destructive` | Error/danger color |
| `--border` | Border color |
| `--ring` | Focus ring color |
| `--radius` | Border radius |

See the [Shadcn UI theming docs](https://ui.shadcn.com/docs/theming) for the complete list.

## Common Pitfalls

- **Editing `shadcn-ui.css` instead of `custom.css`**: Your changes may be overwritten. Always use `custom.css` for customizations.
- **Wrong HSL format**: Use `221.2 83.2% 53.3%` not `hsl(221.2, 83.2%, 53.3%)`. The `hsl()` wrapper is added by Tailwind.
- **Mismatched theme class**: The `shadcnUiStyle` variable must exactly match the theme file name (e.g., `style-nova` not `nova`).
- **Forgetting dark mode**: Always define both `:root` (light) and `.dark` (dark) variants for each variable.
- **Not restarting dev server**: Tailwind v4 CSS changes may require a restart to take effect.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "How do I preview theme changes without restarting?", "answer": "Most CSS variable changes apply immediately. If they don't, try a hard refresh (Cmd+Shift+R). For import changes, a restart is required."},
     {"question": "Can I mix multiple themes?", "answer": "Yes, but import order matters. Later imports override earlier ones. For mixing, define specific overrides in custom.css after the theme import."},
     {"question": "How do I add custom Tailwind utilities?", "answer": "Add them in custom.css using the @layer utilities directive. They'll be available throughout your application."},
     {"question": "Does the theme affect email templates?", "answer": "No. Email templates use inline styles. Update email styling separately in the email template components."}
   ]
/%}

## Related

- [Branding Overview](./overview) - Full branding customization guide
- [Logo Configuration](./logo) - Application logo and favicons
- [Font Configuration](./fonts) - Typography customization

---

**Next:** [Logo →](./logo)