⚡
SaaS Template

Color Theming

Learn how to configure existing themes and create custom color schemes for your SaaS. Includes light/dark mode support.

How Theming Works

RankThis includes a sophisticated theming system with 8 predefined color themes plus light/dark mode support:

  • • Code-based configuration - Set default theme in config
  • • User preference storage - Themes persist across sessions
  • • Light/dark mode toggle - Independent of color theme
  • • CSS custom properties - Easy customization

Available Themes

ocean

Deep blues and teals. Professional and calming.

cosmic

Deep purples and cosmic vibes. Modern and mysterious.

celestial

Soft purples and celestial tones. Elegant and ethereal.

cherry

Warm reds and cherry tones. Energetic and bold.

forest

Rich greens and earth tones. Natural and grounding.

neon

Bright cyans and electric blues. Vibrant and energetic.

retro

Warm oranges and vintage vibes. Nostalgic and friendly.

mono

Neutral grays and minimal colors. Clean and professional.

Configure Default Theme

Set Default Theme in Code

Change your default theme by modifying the configuration file:

src/lib/themeConfig.ts
1export const THEME_CONFIG = {
2  // Change this string to switch themes
3  defaultColorTheme: "ocean", // ← Change this
4  
5  persistTheme: true,
6  allowThemeSwitching: true,
7};

Available options: ocean, cosmic, celestial, cherry, forest, neon, retro, mono

Configuration Options

Theme Configuration
src/lib/themeConfig.ts
 1export const THEME_CONFIG = {
 2  // Default color theme when user visits first time
 3  defaultColorTheme: "ocean",
 4  
 5  // Whether to save user's theme choice
 6  persistTheme: true,
 7  
 8  // Whether to show theme switcher in UI
 9  allowThemeSwitching: true,
10  
11  // Default light/dark mode
12  defaultMode: "system", // "light" | "dark" | "system"
13};
persistTheme
Saves user preference in localStorage
allowThemeSwitching
Shows/hides theme picker components
defaultMode
Initial light/dark mode preference

Create Custom Themes

Add a New Theme

Create custom themes by adding them to the color themes configuration:

src/lib/colorThemes.ts
 1export const colorThemes = {
 2  // ... existing themes ...
 3  
 4  // Your custom theme
 5  sunset: {
 6    light: {
 7      primary: "25 47% 55%",           // Orange-ish
 8      "primary-foreground": "210 40% 98%",
 9      secondary: "35 100% 95%",        // Light peach
10      "secondary-foreground": "25 47% 15%",
11      accent: "45 100% 85%",           // Warm yellow
12      "accent-foreground": "25 47% 15%",
13      // ... other CSS custom properties
14    },
15    dark: {
16      primary: "25 85% 60%",           // Brighter orange
17      "primary-foreground": "25 47% 10%",
18      secondary: "25 47% 10%",         // Dark background
19      "secondary-foreground": "35 100% 95%",
20      accent: "25 47% 15%",            // Darker accent
21      "accent-foreground": "35 100% 95%",
22      // ... other CSS custom properties
23    },
24  },
25};
Theme Structure

Each theme needs both light and dark variants with these properties:

Core Colors

  • • primary - Main brand color
  • • secondary - Supporting color
  • • accent - Highlight color
  • • background - Page background
  • • foreground - Main text

UI Colors

  • • card - Card backgrounds
  • • muted - Subtle backgrounds
  • • border - Element borders
  • • input - Form inputs
  • • ring - Focus rings
Color Format

Colors use HSL format without the hsl() wrapper:

1// ✅ Correct format
2primary: "220 50% 50%",  // hue saturation lightness
3

4// ❌ Wrong format  
5primary: "hsl(220, 50%, 50%)",
6primary: "#3b82f6",
7primary: "rgb(59, 130, 246)",

💡 Use an HSL color picker to get the right values

Light/Dark Mode

Theme Toggle Component

Users can toggle between light/dark modes using the theme toggle:

1import { ThemeToggle } from "~/components/ThemeToggle";
2

3// Add to your header or navigation
4<ThemeToggle />

The toggle automatically saves user preference and applies it across the site.

💡 Testing Your Themes

Quick Testing

Change defaultColorTheme in config and refresh the page

Check Both Modes

Test your theme in both light and dark modes for consistency

Accessibility

Ensure sufficient contrast ratios for text readability

Component Development Guide

Learn how to create theme-aware components using the triple-color architecture.

🎨 Triple-Color Architecture

RankThis uses three color systems that work together for maximum flexibility:

Dynamic Semantic Colors

Primary System
  • • Auto light/dark switching
  • • Semantic naming
  • • CSS custom properties
  • • Use for: Layout, content

Static Brand Colors

Brand Identity
  • • Never change
  • • Consistent identity
  • • Tailwind config
  • • Use for: CTAs, logos

Dynamic Color Themes

User Choice
  • • 8 preset themes
  • • User-selectable
  • • CSS class-based
  • • Use for: Accents
🛠️ Component Development Patterns

✅ Recommended Patterns

 1// Theme-aware layout
 2<div className="bg-background text-foreground border-border">
 3  <h2 className="text-foreground">Adapts to themes</h2>
 4  <p className="text-muted-foreground">Subdued text</p>
 5</div>
 6

 7// Brand elements (CTAs)
 8<button className="bg-brand text-brand-foreground">
 9  Consistent brand button
10</button>
11

12// Theme-adaptive accents
13<div className="bg-primary text-primary-foreground">
14  Changes with color theme
15</div>

❌ Anti-Patterns

 1// ❌ Hardcoded colors
 2<div className="bg-white text-black">
 3  Breaks in dark mode
 4</div>
 5

 6// ❌ Mixed approaches
 7<div className="bg-background text-blue-500">
 8  Inconsistent theming
 9</div>
10

11// ❌ Inline styles
12<div style={{ backgroundColor: '#fff' }}>
13  Ignores theme system
14</div>
🌗 Semantic Colors Reference

Use these semantic colors for components that adapt to light/dark mode:

Core Colors

backgroundMain background
foregroundMain text
primaryTheme accent
secondaryAlt backgrounds

Utility Colors

mutedSubdued content
accentHighlights
destructiveErrors
borderBorders
🔧 Theme Hooks

useTheme Hook

 1import { useTheme } from "~/hooks/useTheme";
 2

 3export function Component() {
 4  const { isDark, toggle } = useTheme();
 5  
 6  return (
 7    <div>
 8      <p>Mode: {isDark ? 'Dark' : 'Light'}</p>
 9      <button onClick={toggle}>Toggle</button>
10    </div>
11  );
12}

useColorTheme Hook

 1import { useColorTheme } from "~/hooks/useColorTheme";
 2

 3export function Component() {
 4  const { colorTheme, setColorTheme } = useColorTheme();
 5  
 6  return (
 7    <div>
 8      <p>Theme: {colorTheme}</p>
 9      <button onClick={() => setColorTheme('ocean')}>
10        Switch to Ocean
11      </button>
12    </div>
13  );
14}
🧪 Testing Components

Always test your components across theme variations:

Testing Checklist

  • • ✅ Light mode appearance
  • • ✅ Dark mode appearance
  • • ✅ All 8 color themes
  • • ✅ Color contrast accessibility
  • • ✅ Hover/focus states
  • • ✅ Mobile responsiveness

Quick Test Wrapper

1// For component testing
2<div className="space-y-4">
3  <div className="light theme-ocean p-4 border">
4    <YourComponent />
5  </div>
6  <div className="dark theme-cosmic p-4 border">
7    <YourComponent />
8  </div>
9</div>