> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BankkRoll/tweakcn-theme-picker/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```ts theme={null}
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:

<CardGroup cols={2}>
  <Card title="Minimal" icon="minus" href="/themes/minimal">
    Clean, understated themes focused on simplicity and readability
  </Card>

  <Card title="Colorful" icon="palette" href="/themes/colorful">
    Vibrant themes with rich color palettes and visual impact
  </Card>

  <Card title="Branded" icon="trademark" href="/themes/branded">
    Themes inspired by popular brands and services
  </Card>

  <Card title="Creative" icon="sparkles" href="/themes/creative">
    Unique, artistic themes with distinctive aesthetics
  </Card>

  <Card title="Dark" icon="moon" href="/themes/dark">
    Sophisticated dark-first themes optimized for low-light environments
  </Card>
</CardGroup>

## Using Themes

### Installation

Install the theme system first:

```bash theme={null}
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/nextjs/theme-system.json
```

Then add individual themes:

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

### Programmatic Access

Access theme data in your application:

```tsx theme={null}
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

<CardGroup cols={2}>
  <Card title="Browse Themes" icon="grid" href="/themes/minimal">
    Explore all available themes by category
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Learn how to install and configure themes
  </Card>
</CardGroup>