Back to Documentation

Theme System

Customize the look and feel of your app with our flexible theming system.

Theme System Overview

Our platform uses a simple yet powerful theme system that provides a consistent, beautiful design for all apps. Each app has a single theme that defines its colors, typography, and visual style.

How It Works

Your app's theme is defined using CSS custom properties (variables). These variables control colors, border radius, spacing, and fonts throughout your app. When you customize your theme, these variables are updated to reflect your choices.

Theme Variables: Defined in the :root section of your CSS

Theme Customization

You can fully customize the theme to match your brand identity or design preferences. Our theme system uses HSL color values, which make it easy to create consistent color palettes and maintain visual harmony across your application.

HSL Color Format

All theme variables use HSL (Hue, Saturation, Lightness) color format, expressed as space-separated values:

--primary: 221 83% 53%;
Hue (221)

The color shade (0-360)

Saturation (83%)

Color intensity (0-100%)

Lightness (53%)

Brightness (0-100%)

Importing Themes

You can import custom themes by providing CSS variables in the proper format. This makes it easy to apply themes from external sources or to reuse themes across different projects.

CSS Import Format

When importing themes, provide CSS with a :root section containing your HSL color variables:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222.2 84% 4.9%;
  --muted: 210 40% 96%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96%;
  --accent-foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 221.2 83% 53.3%;
  --radius: 0.5rem;
  /* Additional variables as needed */
}

All color values must be in HSL format, expressed as space-separated values (hue, saturation, lightness) without the "hsl()" wrapper.

Theme Editor Tool

To make theme creation easier, you can use our recommended theme editor tool. This tool provides a visual interface for selecting colors and automatically generates the proper CSS format.

How to use the theme editor:

  1. Visit the theme editor and customize your colors
  2. Click the Code button in the editor
  3. Select tailwind v3 from the format options
  4. Choose hsl as the color format
  5. Copy the generated CSS code from the :root section
  6. Paste it into your theme importer
Open Theme Editor Tool

Available Theme Variables

Here are all the CSS custom properties available in our theme system. Each variable serves a specific purpose in creating a cohesive design.

Core Colors

VariablePurposeUsage
--backgroundMain page background colorBody, main containers
--foregroundPrimary text colorHeadings, body text
--cardCard background colorCards, panels, modals
--card-foregroundText color on cardsText within cards
--popoverPopover background colorPopovers, tooltips, dropdowns
--popover-foregroundText color on popoversText within popovers

Semantic Colors

VariablePurposeUsage
--primaryPrimary brand colorPrimary buttons, links, highlights
--primary-foregroundText color on primary elementsText on primary buttons
--secondarySecondary accent colorSecondary buttons, subtle highlights
--secondary-foregroundText color on secondary elementsText on secondary buttons
--mutedMuted background colorDisabled states, subtle backgrounds
--muted-foregroundMuted text colorSecondary text, descriptions
--accentAccent color for highlightsHover states, active elements
--accent-foregroundText color on accent elementsText on accent backgrounds
--destructiveDestructive action colorDelete buttons, error states, warnings
--destructive-foregroundText color on destructive elementsText on destructive buttons

Border & Input

VariablePurposeUsage
--borderBorder colorDividers, card borders
--inputInput field border colorForm inputs, text areas
--ringFocus ring colorFocus indicators, accessibility
--radiusBorder radius valueRounded corners (e.g., "0.5rem")
--spacingBase spacing unitConsistent spacing (e.g., "0.25rem")

Chart Colors

VariablePurposeUsage
--chart-1First chart colorData visualization, graphs
--chart-2Second chart colorData visualization, graphs
--chart-3Third chart colorData visualization, graphs
--chart-4Fourth chart colorData visualization, graphs
--chart-5Fifth chart colorData visualization, graphs

Sidebar Colors

Sidebar-specific colors for apps with navigation sidebars.

VariablePurposeUsage
--sidebar-backgroundSidebar background colorSidebar containers
--sidebar-foregroundSidebar text colorSidebar text, icons
--sidebar-primarySidebar primary colorActive sidebar items
--sidebar-primary-foregroundText color on sidebar primaryText on active sidebar items
--sidebar-accentSidebar accent colorHover states in sidebar
--sidebar-accent-foregroundText color on sidebar accentText on hover states
--sidebar-borderSidebar border colorSidebar dividers, edges
--sidebar-ringSidebar focus ring colorFocus indicators in sidebar

Typography

VariablePurposeUsage
--font-sansSans-serif font familyBody text, UI elements
--font-serifSerif font familyHeadings, decorative text
--font-monoMonospace font familyCode blocks, technical text

Theme Conventions

Our theme system follows consistent naming conventions that make it intuitive to work with. Understanding these patterns will help you create harmonious themes.

Background/Foreground Pairs

Each UI element typically has a background color and a matching foreground (text) color that ensures proper contrast. For example, primary and primary-foreground are used together.

Primary Background
with Primary Foreground text
Secondary Background
with Secondary Foreground text
Muted Background
with Muted Foreground text
Accent Background
with Accent Foreground text

Semantic Color Variables

Our theme system uses semantic color variables that describe their purpose rather than their appearance. This approach ensures consistent design and makes theme switching seamless.

VariablePurpose
background / foregroundMain page background and text colors
card / card-foregroundCard elements and their text
primary / primary-foregroundPrimary actions, buttons, highlights
muted / muted-foregroundSubdued elements, secondary text