Appearance

Theme ​

Custom Themes allow you to personalize your application's appearance by overriding the default colors, spacing, and visual elements. You can create a branded experience that matches your organization's visual identity.

What are Custom Themes? ​

Custom Themes let you:

  • Brand your application with your organization's colors
  • Customize the visual appearance of all interface elements
  • Support both light and dark modes with different color schemes
  • Override any design element using standard CSS variables
  • Maintain consistency across your entire application

How Custom Themes Work ​

The platform uses a comprehensive set of design tokens (CSS custom properties) that control every aspect of the visual appearance. By providing your own CSS values, you can override these defaults to create a completely custom look and feel.

Theme Structure ​

Your custom theme consists of CSS rules that define color values, spacing, and other visual properties for both light and dark modes. You can use any CSS color format:

css
:root {
  /* Light mode colors and properties - using different formats */
  --primary: #3b82f6; /* Hex */
  --accent: hsl(38, 92%, 50%); /* HSL */
  --background: white; /* Named color */
  --destructive: rgb(239, 68, 68); /* RGB */
  /* ... more properties */
}

.dark {
  /* Dark mode colors and properties */
  --primary: #60a5fa; /* Lighter hex for dark mode */
  --accent: hsl(38, 92%, 60%); /* Lighter HSL */
  --background: #0f172a; /* Dark hex */
  --destructive: rgb(248, 113, 113); /* Lighter RGB */
  /* ... more properties */
}

Setting Up Your Custom Theme ​

Step 1: Create the Theme Setting ​

  1. Navigate to your Settings in the admin interface
  2. Create a new setting with the name: simple.branding.theme
  3. In the value field, paste your custom CSS

Step 2: Define Your CSS ​

Your CSS should include both :root (light mode) and .dark (dark mode) selectors with your custom values.

Available Theme Properties ​

The platform uses the OKLCH color format for all theme variables. Below are all the available properties you can customize:

Light Mode Properties (:root) ​

css
:root {
  /* Layout */
  --radius: 0.625rem; /* Border radius for rounded corners */

  /* Background colors */
  --background: oklch(1 0 0); /* Main background */
  --foreground: oklch(0.145 0 0); /* Main text color */

  /* Card and panel colors */
  --card: oklch(1 0 0); /* Card backgrounds */
  --card-foreground: oklch(0.145 0 0); /* Card text */

  /* Popover and dropdown colors */
  --popover: oklch(1 0 0); /* Popover backgrounds */
  --popover-foreground: oklch(0.145 0 0); /* Popover text */

  /* Brand colors */
  --primary: oklch(0.205 0 0); /* Primary buttons, links */
  --primary-foreground: oklch(0.985 0 0); /* Text on primary elements */

  /* Supporting colors */
  --secondary: oklch(0.97 0 0); /* Secondary buttons */
  --secondary-foreground: oklch(0.205 0 0); /* Text on secondary elements */

  /* Subtle colors */
  --muted: oklch(0.97 0 0); /* Subtle backgrounds */
  --muted-foreground: oklch(0.556 0 0); /* Subtle text */

  /* Accent colors */
  --accent: oklch(0.97 0 0); /* Highlights, badges */
  --accent-foreground: oklch(0.205 0 0); /* Text on accent elements */

  /* Status colors */
  --destructive: oklch(0.577 0.245 27.325); /* Error buttons, alerts */

  /* Form elements */
  --border: oklch(0.922 0 0); /* Border colors */
  --input: oklch(0.922 0 0); /* Input field backgrounds */
  --ring: oklch(0.708 0 0); /* Focus ring color */

  /* Chart colors */
  --chart-1: oklch(0.646 0.222 41.116); /* First chart color */
  --chart-2: oklch(0.6 0.118 184.704); /* Second chart color */
  --chart-3: oklch(0.398 0.07 227.392); /* Third chart color */
  --chart-4: oklch(0.828 0.189 84.429); /* Fourth chart color */
  --chart-5: oklch(0.769 0.188 70.08); /* Fifth chart color */

  /* Sidebar colors */
  --sidebar: oklch(0.985 0 0); /* Sidebar background */
  --sidebar-foreground: oklch(0.145 0 0); /* Sidebar text */
  --sidebar-primary: oklch(0.205 0 0); /* Sidebar primary elements */
  --sidebar-primary-foreground: oklch(0.985 0 0); /* Text on sidebar primary */
  --sidebar-accent: oklch(0.97 0 0); /* Sidebar accent elements */
  --sidebar-accent-foreground: oklch(0.205 0 0); /* Text on sidebar accent */
  --sidebar-border: oklch(0.922 0 0); /* Sidebar borders */
  --sidebar-ring: oklch(0.708 0 0); /* Sidebar focus rings */
}

Dark Mode Properties (.dark) ​

css
.dark {
  /* Background colors */
  --background: oklch(0.145 0 0); /* Main background */
  --foreground: oklch(0.985 0 0); /* Main text color */

  /* Card and panel colors */
  --card: oklch(0.205 0 0); /* Card backgrounds */
  --card-foreground: oklch(0.985 0 0); /* Card text */

  /* Popover and dropdown colors */
  --popover: oklch(0.269 0 0); /* Popover backgrounds */
  --popover-foreground: oklch(0.985 0 0); /* Popover text */

  /* Brand colors */
  --primary: oklch(0.922 0 0); /* Primary buttons, links */
  --primary-foreground: oklch(0.205 0 0); /* Text on primary elements */

  /* Supporting colors */
  --secondary: oklch(0.269 0 0); /* Secondary buttons */
  --secondary-foreground: oklch(0.985 0 0); /* Text on secondary elements */

  /* Subtle colors */
  --muted: oklch(0.269 0 0); /* Subtle backgrounds */
  --muted-foreground: oklch(0.708 0 0); /* Subtle text */

  /* Accent colors */
  --accent: oklch(0.371 0 0); /* Highlights, badges */
  --accent-foreground: oklch(0.985 0 0); /* Text on accent elements */

  /* Status colors */
  --destructive: oklch(0.704 0.191 22.216); /* Error buttons, alerts */

  /* Form elements */
  --border: oklch(1 0 0 / 10%); /* Border colors with transparency */
  --input: oklch(1 0 0 / 15%); /* Input field backgrounds with transparency */
  --ring: oklch(0.556 0 0); /* Focus ring color */

  /* Chart colors */
  --chart-1: oklch(0.488 0.243 264.376); /* First chart color */
  --chart-2: oklch(0.696 0.17 162.48); /* Second chart color */
  --chart-3: oklch(0.769 0.188 70.08); /* Third chart color */
  --chart-4: oklch(0.627 0.265 303.9); /* Fourth chart color */
  --chart-5: oklch(0.645 0.246 16.439); /* Fifth chart color */

  /* Sidebar colors */
  --sidebar: oklch(0.205 0 0); /* Sidebar background */
  --sidebar-foreground: oklch(0.985 0 0); /* Sidebar text */
  --sidebar-primary: oklch(0.488 0.243 264.376); /* Sidebar primary elements */
  --sidebar-primary-foreground: oklch(0.985 0 0); /* Text on sidebar primary */
  --sidebar-accent: oklch(0.269 0 0); /* Sidebar accent elements */
  --sidebar-accent-foreground: oklch(0.985 0 0); /* Text on sidebar accent */
  --sidebar-border: oklch(1 0 0 / 10%); /* Sidebar borders with transparency */
  --sidebar-ring: oklch(0.439 0 0); /* Sidebar focus rings */
}

Color Format ​

The platform supports any valid CSS color format. You can use whichever format you're most comfortable with:

Supported Color Formats ​

OKLCH (Modern, recommended)

  • --primary: oklch(0.646 0.222 41.116);
  • --border: oklch(1 0 0 / 10%); (with transparency)

Hex Colors

  • --primary: #3b82f6;
  • --accent: #f59e0b;

RGB/RGBA

  • --primary: rgb(59, 130, 246);
  • --accent: rgba(245, 158, 11, 0.9);

HSL/HSLA

  • --primary: hsl(217, 91%, 60%);
  • --accent: hsla(38, 92%, 50%, 0.9);

Named Colors

  • --primary: blue;
  • --background: white;

Color Format Recommendations ​

For Brand Consistency: Use hex colors if you have existing brand guidelines

css
:root {
  --primary: #3b82f6; /* Your brand blue */
  --accent: #f59e0b; /* Your brand orange */
}

For Advanced Control: Use OKLCH for better color manipulation and wider gamut

css
:root {
  --primary: oklch(0.646 0.222 217); /* Perceptually uniform */
  --accent: oklch(0.7 0.15 38); /* Better color mixing */
}

For Familiarity: Use HSL if you're comfortable with hue/saturation/lightness

css
:root {
  --primary: hsl(217, 91%, 60%); /* Easy to adjust */
  --accent: hsl(38, 92%, 50%); /* Intuitive values */
}

Complete Theme Examples ​

Corporate Blue Theme (Using Hex Colors) ​

A professional theme with blue primary colors and orange accents:

css
:root {
  --primary: #2563eb; /* Corporate blue */
  --primary-foreground: white; /* White text */
  --accent: #f59e0b; /* Orange accent */
  --accent-foreground: #1f2937; /* Dark text */
  --sidebar-primary: #2563eb; /* Match primary */
  --chart-1: #2563eb; /* Blue charts */
  --chart-2: #f59e0b; /* Orange charts */
  --radius: 0.75rem; /* More rounded corners */
}

.dark {
  --primary: #3b82f6; /* Lighter blue for dark mode */
  --primary-foreground: #1f2937; /* Dark text */
  --accent: #fbbf24; /* Lighter orange */
  --accent-foreground: #1f2937; /* Dark text */
  --sidebar-primary: #3b82f6; /* Match primary */
  --chart-1: #3b82f6; /* Lighter blue charts */
  --chart-2: #fbbf24; /* Lighter orange charts */
}

Minimal Green Theme (Using HSL Colors) ​

A clean theme with green accents and minimal styling:

css
:root {
  --primary: hsl(142, 76%, 36%); /* Forest green */
  --primary-foreground: white; /* White text */
  --accent: hsl(142, 69%, 58%); /* Light green accent */
  --sidebar-primary: hsl(142, 76%, 36%); /* Match primary */
  --chart-1: hsl(142, 76%, 36%); /* Green charts */
  --chart-2: hsl(142, 69%, 58%); /* Light green charts */
  --radius: 0.25rem; /* Minimal rounded corners */
}

.dark {
  --primary: hsl(142, 69%, 58%); /* Lighter green for dark mode */
  --primary-foreground: #1f2937; /* Dark text */
  --accent: hsl(142, 69%, 68%); /* Lighter green accent */
  --sidebar-primary: hsl(142, 69%, 58%); /* Match primary */
  --chart-1: hsl(142, 69%, 58%); /* Lighter green charts */
  --chart-2: hsl(142, 69%, 68%); /* Lighter green charts */
}

Mixed Format Theme ​

You can even mix different color formats in the same theme:

css
:root {
  --primary: #3b82f6; /* Hex for brand colors */
  --accent: hsl(38, 92%, 50%); /* HSL for easy adjustment */
  --background: white; /* Named colors for simplicity */
  --destructive: rgb(239, 68, 68); /* RGB if you prefer */
  --border: rgba(0, 0, 0, 0.1); /* RGBA for transparency */
}

Customization Tips ​

Start Simple ​

Begin with just your brand colors and expand from there:

css
:root {
  --primary: #YOUR_BRAND_COLOR; /* Use your existing brand hex */
  --accent: #YOUR_ACCENT_COLOR; /* Your accent color */
}

.dark {
  --primary: #LIGHTER_BRAND_COLOR; /* Lighter version for dark mode */
  --accent: #LIGHTER_ACCENT_COLOR; /* Lighter accent */
}

Test Both Modes ​

Always define colors for both light (:root) and dark (.dark) modes. Dark mode colors typically need to be lighter than their light mode counterparts for proper contrast.

Use Consistent Color Families ​

For a cohesive look, use colors from the same family with different shades:

css
/* All blues using hex */
--primary: #2563eb; /* Vibrant blue */
--secondary: #eff6ff; /* Very light blue */
--sidebar-primary: #2563eb; /* Same vibrant blue */

/* Or using HSL for easier variation */
--primary: hsl(217, 91%, 60%); /* Base blue */
--secondary: hsl(217, 91%, 95%); /* Same hue, very light */
--accent: hsl(217, 91%, 70%); /* Same hue, lighter */

Consider Accessibility ​

Ensure sufficient contrast between foreground and background colors:

  • Light backgrounds need dark text
  • Dark backgrounds need light text
  • Interactive elements should be easily distinguishable

Advanced Customization ​

Adding Custom Properties ​

You can add your own CSS custom properties for additional customization:

css
:root {
  /* Standard properties */
  --primary: #3b82f6;

  /* Your custom properties */
  --company-logo-filter: brightness(0) saturate(100%) invert(27%);
  --header-height: 4rem;
  --custom-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

Partial Themes ​

You don't need to define every property. Only include the ones you want to change:

css
:root {
  --primary: #3b82f6;
  --accent: #f59e0b;
  --radius: 1rem;
}

.dark {
  --primary: #60a5fa;
  --accent: #fbbf24;
}

Troubleshooting ​

Theme Not Applying ​

  1. Check the setting name: Must be exactly simple.branding.theme
  2. Verify CSS syntax: Ensure proper CSS structure with selectors and properties
  3. Clear browser cache: Hard refresh your browser (Ctrl+F5 or Cmd+Shift+R)

Colors Look Wrong ​

  1. Check color format: Ensure you're using valid CSS color values (#3b82f6, rgb(59, 130, 246), hsl(217, 91%, 60%), etc.)
  2. Verify both modes: Define colors for both :root and .dark
  3. Test contrast: Ensure foreground colors work with background colors
  4. Check dark mode colors: Dark mode typically needs lighter colors than light mode

Some Elements Not Themed ​

  1. Check property names: Use exact property names like --primary not --primary-color
  2. Include all variants: Some elements use -foreground variants
  3. Test thoroughly: Check different pages and interface states

Best Practices ​

Design Consistency ​

  • Use a limited color palette - 2-3 main colors work better than many
  • Maintain visual hierarchy - Primary actions should stand out
  • Test in context - View your theme across different pages and features

Performance ​

  • Keep CSS minimal - Only override what you need to change
  • Use efficient selectors - Stick to :root and .dark
  • Avoid complex calculations - Use simple color values

Maintenance ​

  • Document your choices - Keep notes about your color decisions
  • Test updates - Verify your theme works after platform updates
  • Version control - Keep backups of your theme CSS

Common Questions ​

Can I use hex colors instead of OKLCH? ​

Yes! The platform supports any valid CSS color format including hex (#3b82f6), RGB (rgb(59, 130, 246)), HSL (hsl(217, 91%, 60%)), OKLCH (oklch(0.6 0.25 217)), and named colors (blue).

How do I use my existing brand colors? ​

Simply use your existing brand colors in whatever format you have them:

  • From brand guidelines: --primary: #3b82f6;
  • From design tools: --accent: rgb(245, 158, 11);
  • From CSS: --background: hsl(0, 0%, 100%);

No conversion needed!

Will my theme work on mobile devices? ​

Yes, custom themes automatically work across all devices and screen sizes. The platform's responsive design system applies your colors consistently.

Can I theme individual pages differently? ​

No, custom themes apply globally across your entire application. This ensures a consistent user experience.

What happens if I make a mistake in my CSS? ​

Invalid CSS will be ignored, and the default theme will be used instead. Check your browser's developer console for CSS errors.

How do I reset to the default theme? ​

Simply delete the simple.branding.theme setting or clear its value field. The platform will immediately return to the default appearance.

Can I preview my theme before applying it? ​

Currently, themes are applied immediately when saved. We recommend testing changes in a development environment first.