Generate Custom shadcn/ui Themes

The shadcn/UI library provides a set of pre-built Tailwind CSS components that you can easily style to match your brand or application. A key feature of shadcn/UI is its flexible theming system, which lets you customize the look and feel of components without rewriting styles.

Theming in shadcn/UI is achieved through CSS custom properties (variables) and Tailwind CSS classes. In fact, shadcn/UI supports two approaches for theming: using CSS variables (recommended) or using Tailwind utility classes

Example Theme

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 221.2 83.2% 53.3%;
    --radius: 1rem;
    --chart-1: 12 76% 61%;
    --chart-2: 173 58% 39%;
    --chart-3: 197 37% 24%;
    --chart-4: 43 74% 66%;
    --chart-5: 27 87% 67%;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    --popover: 222.2 84% 4.9%;
    --popover-foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    --primary-foreground: 222.2 47.4% 11.2%;
    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;
    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 224.3 76.3% 48%;
    --chart-1: 220 70% 50%;
    --chart-2: 160 60% 45%;
    --chart-3: 30 80% 55%;
    --chart-4: 280 65% 60%;
    --chart-5: 340 75% 55%;
  }
}

Step-by-Step Guide

Here’s how you can generate a custom shadcn UI theme using a single color and CSS variables:

1. Choose Your Base Color: Select a primary color that represents your brand, for example, a hex code like #FF0000 (red). This will be your starting point.

2. Convert to OKLCH for Uniformity: Convert your base color to the OKLCH color space for better perceptual uniformity. You can use online tools or Tailwind's color utilities to help with this conversion.

3. Define CSS Variables: In your app/globals.css, define CSS variables based on your base color. For instance:

   • Set --primary-color: oklch(0.6 0.2 30) (example OKLCH values).

   • Derive other colors like --background: oklch(0.95 0.05 30) for a lighter background, adjusting lightness and chroma for contrast.

4. Ensure Accessibility: Use tools like contrast checkers to ensure your color combinations meet WCAG guidelines, especially for text and background pairs.

5. Apply to Components: Update your components.json under tailwind.baseColor to reference your custom theme, and apply these variables across shadcn UI components.

Unexpected Detail

An interesting aspect is that shadcn UI's theming system, updated for Tailwind v4, uses the @theme directive and OKLCH colors, which might be new for developers used to traditional RGB or HSL. This shift enhances color accuracy but requires learning new color manipulation techniques.

Survey Note: Detailed Exploration of Custom shadcn UI Themes

Overview and Context

shadcn UI, launched in March 2023, is a customizable component library for building modern web applications, primarily using React and Tailwind CSS. It emphasizes open-source, accessible components that developers can copy and paste into their codebase, offering full control over customization. As of March 24, 2025, the latest updates include support for Tailwind CSS v4, which introduces enhanced theming capabilities using CSS variables and the OKLCH color space.

The task of generating custom themes using a single color and CSS variables aligns with shadcn UI's design philosophy of flexibility and accessibility. This approach allows developers to create dynamic, brand-consistent themes while ensuring compliance with accessibility standards like WCAG.

Understanding shadcn UI Theming

Theming in shadcn UI is tightly integrated with Tailwind CSS v4, which supports the @theme directive and inline theming options. The documentation, available at https://ui.shadcn.com/docs/tailwind-v4, highlights updates such as moving :root and .dark out of @layer base, wrapping color values in hsl(), and using @theme inline for better control.

Predefined themes like Stone, Zinc, Neutral, Gray, and Slate are provided, with base colors defined in app/globals.css. For example, the Stone theme includes:

These themes demonstrate how base colors are set, with options to configure in components.json under tailwind.baseColor, such as "neutral" or "slate". For further details on color formats, refer to the Tailwind CSS documentation at https://tailwindcss.com/docs/colors.

Generating Custom Themes with a Single Color

To generate a custom theme, start by selecting a single base color, such as #FF0000 (red). Convert this to OKLCH for uniformity, using online tools or Tailwind's utilities. For example, if your base color is --primary-color: oklch(0.6 0.2 30), you can derive other theme colors:

• Background: Use a lighter version, e.g., --background: oklch(0.95 0.05 30), by increasing lightness (L) for contrast.

• Foreground: Ensure readability, e.g., --foreground: oklch(0.15 0.01 30), by adjusting for dark text on light backgrounds.

• Dark Mode: Mirror the process, adjusting for accessibility, as seen in the update for March 12, 2025, projects at https://ui.shadcn.com/docs/theming#base-colors.

Ensure accessibility by checking contrast ratios with tools, aligning with WCAG guidelines. The documentation suggests using pnpm dlx shadcn@latest add --all --overwrite for updates, ensuring compatibility with new OKLCH colors.

Practical Implementation

Define your CSS variables in app/globals.css, for example:

• :root { --primary-color: oklch(0.6 0.2 30); --background: oklch(0.95 0.05 30); }

• For dark mode, .dark { --background: oklch(0.15 0.01 30); }

Update components.json to reference your custom theme, and apply these variables across shadcn UI components. The demo at https://v4.shadcn.com showcases practical applications.

Generating custom shadcn UI themes using a single color and CSS variables is a powerful way to personalize your application while maintaining accessibility.

By leveraging Tailwind CSS v4's features and OKLCH color space, you can create dynamic, brand-aligned themes with ease. For further exploration, refer to the documentation and demo links provided.

FAQ

Can I use any color as my base color for the theme?

Yes, but ensure it meets accessibility standards for contrast with other elements.

Do I need to update my project for Tailwind v4 to use custom themes?

It's recommended, as Tailwind v4 supports OKLCH and @theme for better theming.

Can I switch between light and dark modes easily with custom themes?

Yes, define separate variables for .dark in CSS for seamless mode switching.