Theme System Overview

Understanding the tweakcn Theme Picker theme structure and system

The tweakcn Theme Picker provides 43+ professionally designed themes for shadcn/ui applications, each supporting both light and dark modes.

Theme Structure

Each theme is defined using a consistent structure that includes:

• Name: A unique identifier (e.g., catppuccin, cyberpunk)
• Title: Display name shown in the UI
• Colors: OKLCH color values for light and dark modes
• Typography: Custom font configuration

Theme Configuration

Themes are defined in themes-config.ts with the following interface:

interface ThemeConfig {
  name: string;        // Theme identifier
  title: string;       // Display name
  primaryLight: string; // OKLCH color for light mode
  primaryDark: string;  // OKLCH color for dark mode
  fontSans: string;    // Font family
}

Naming Convention

All themes follow a consistent {name}-{mode} pattern:

• {theme-name}-light - Light mode variant
• {theme-name}-dark - Dark mode variant

Examples:

• default-dark
• catppuccin-light
• cyberpunk-dark
• vercel-light

How Themes Work

Themes use CSS variables and the OKLCH color space to provide consistent, perceptually uniform colors:

1. CSS Variables: Each theme sets CSS custom properties that shadcn/ui components reference
2. OKLCH Colors: Uses OKLCH (Lightness, Chroma, Hue) for better color manipulation
3. Mode Switching: Themes include both light and dark variants with appropriate contrast

CSS Variable System

When you apply a theme like catppuccin-dark, the system:

1. Sets data-theme="catppuccin-dark" on the HTML element
2. Loads the corresponding CSS file with variable definitions
3. Applies the theme’s primary colors and typography
4. Maintains semantic color tokens (background, foreground, muted, etc.)

Theme Categories

Themes are organized into five categories:

Minimal

Clean, understated themes focused on simplicity and readability

Colorful

Vibrant themes with rich color palettes and visual impact

Branded

Themes inspired by popular brands and services

Creative

Unique, artistic themes with distinctive aesthetics

Dark

Sophisticated dark-first themes optimized for low-light environments

Using Themes

Installation

Install the theme system first:

npx shadcn@latest add https://tweakcn-picker.vercel.app/r/nextjs/theme-system.json

Then add individual themes:

npx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-{name}.json

Programmatic Access

Access theme data in your application:

import { useTheme } from "next-themes";
import { themes } from "@/lib/themes-config";

export function MyComponent() {
  const { theme, setTheme } = useTheme();
  
  // Get current theme name and mode
  const currentName = theme?.replace(/-light$|-dark$/, "") || "default";
  const isDark = theme?.endsWith("-dark") ?? true;
  
  // Switch modes
  const toggleMode = () => {
    setTheme(`${currentName}-${isDark ? "light" : "dark"}`);
  };
  
  return (
    <button onClick={toggleMode}>
      {isDark ? "Light" : "Dark"} Mode
    </button>
  );
}

Next Steps

Browse Themes

Explore all available themes by category

Installation

Learn how to install and configure themes