Customize Theme Colors | Client Guides

The SaaS starter kit uses a CSS variable-based color system that makes it easy to customize the entire app's color palette. Simply update the values in one file, and the changes will apply everywhere.

ℹ️

Prerequisites

Basic understanding of CSS color values (hex codes)
Text editor to modify src/app/globals.css
Dev server running to preview changes in real-time

Understanding the Color System

The app uses four main color palettes, each with 11 shades (50-950). By default, the primary palette is a natural sage green for a calming, professional look:

Primary: Main brand color - Sage green by default (buttons, links, accents)
Success: Positive actions and states (confirmations, success messages)
Warning: Caution states (important notices, warnings)
Danger: Destructive actions and errors (delete buttons, error messages)

How to Customize Colors

Generate Your Color Palette

Use the free uicolors.app tool to generate a complete color palette from your brand color.

Go to https://uicolors.app/create
Enter your brand color (e.g., #3B82F6 for blue)
Adjust the palette using the sliders if needed
Click "Export" → "CSS Variables"
Copy the generated CSS variables

Update globals.css

Open src/app/globals.css and find the "COLOR PALETTE - CUSTOMIZE HERE" section. Replace the primary color values with your generated palette.

src/app/globals.css

1:root {
2  /* Primary Color Palette - CUSTOMIZE HERE */
3  /* Current: Sage Green - Natural & Calming */
4  --primary-50: #f4f7f4;   /* Lightest shade */
5  --primary-100: #e3ebe3;
6  --primary-200: #c5d8c5;
7  --primary-300: #9cb99c;
8  --primary-400: #769776;
9  --primary-500: #567a56;  /* Base color */
10  --primary-600: #426042;  /* Most commonly used */
11  --primary-700: #354d35;
12  --primary-800: #2c3e2c;
13  --primary-900: #243324;
14  --primary-950: #121b12;  /* Darkest shade */
15}

💡

Pro Tip

The 600 shade is used most frequently for interactive elements like buttons and links. The 500 shade is typically the "true" brand color.

Customize Other Palettes (Optional)

You can also customize success, warning, and danger colors to match your brand. Follow the same process using uicolors.app.

src/app/globals.css

1:root {
2  /* Success Color - Green by default */
3  --success-500: #22c55e;
4  --success-600: #16a34a;
5  /* ... other shades */
6 
7  /* Warning Color - Amber by default */
8  --warning-500: #f59e0b;
9  --warning-600: #d97706;
10  /* ... other shades */
11 
12  /* Danger Color - Red by default */
13  --danger-500: #ef4444;
14  --danger-600: #dc2626;
15  /* ... other shades */
16}

Preview Your Changes

Save the file and your dev server will automatically reload with the new colors. Check these areas to see the changes:

Navigation and header elements
Buttons (primary, secondary, danger variants)
Links and interactive elements
Badges and status indicators
Dark mode appearance

Advanced Customization

Border Radius

Control how rounded corners appear throughout the app by adjusting the radius variables:

src/app/globals.css

1:root {
2  --radius-sm: 0.25rem;   /* 4px - subtle rounding */
3  --radius-md: 0.375rem;  /* 6px - buttons */
4  --radius-lg: 0.5rem;    /* 8px - cards (default) */
5  --radius-xl: 0.75rem;   /* 12px - modals */
6  --radius-2xl: 1rem;     /* 16px - large cards */
7  --radius-full: 9999px;  /* pill shape */
8}

Surface Colors

These control background and surface colors. They automatically adapt to light/dark mode:

src/app/globals.css

1:root {
2  --background: #ffffff;              /* Page background */
3  --foreground: var(--primary-950);   /* Text color */
4  --surface: #ffffff;                 /* Card backgrounds */
5  --surface-elevated: var(--primary-50); /* Hover states */
6  --border: var(--primary-200);       /* Border colors */
7}
8 
9.dark {
10  --background: var(--primary-950);
11  --foreground: var(--primary-100);
12  --surface: var(--primary-950);
13  --surface-elevated: var(--primary-900);
14  --border: var(--primary-800);
15}

Using Colors in Your Code

Once you've customized the colors, you can use them in your components using Tailwind classes:

src/components/YourComponent.tsx

1export function YourComponent() {
2  return (
3    <div className="bg-surface border border-border rounded-lg p-6">
4      <h2 className="text-foreground text-xl font-bold">
5        Your Title
6      </h2>
7      <button className="bg-primary-600 hover:bg-primary-700 text-white">
8        Primary Button
9      </button>
10      <button className="bg-danger-600 hover:bg-danger-700 text-white">
11        Delete Button
12      </button>
13    </div>
14  );
15}

Troubleshooting

Changes not appearing

If your color changes don't show up:

Make sure you saved src/app/globals.css
Refresh your browser (Cmd+R / Ctrl+R)
Clear your browser cache (Cmd+Shift+R / Ctrl+Shift+R)
Restart the dev server: npm run dev

Dark mode looks broken

Make sure you updated both :root and .dark sections in globals.css. Dark mode uses inverted shade values (lighter shades for dark backgrounds).

Some elements still show old colors

A few components may use hardcoded color classes. Search for the old color name (e.g., "indigo-600") in your codebase and replace it with the appropriate primary shade.

Colors look washed out or too vibrant

Go back to uicolors.app and adjust the saturation and lightness sliders until you find the right balance.

Related Guides

Logo & Branding

Add your company logo and update branding elements

Customize UI Components

Fine-tune button styles, cards, and other UI components

Animations

Customize animation timing and motion effects

Next Steps

Now that you've customized your colors, you might want to:

Customize Logo & Branding - Add your company logo and update branding elements
Customize UI Components - Fine-tune individual component styles
Production Deployment - Deploy your customized app to production

ℹ️

Prerequisites

Basic understanding of CSS color values (hex codes)
Text editor to modify src/app/globals.css
Dev server running to preview changes in real-time

Understanding the Color System

The app uses four main color palettes, each with 11 shades (50-950). By default, the primary palette is a natural sage green for a calming, professional look:

Primary: Main brand color - Sage green by default (buttons, links, accents)
Success: Positive actions and states (confirmations, success messages)
Warning: Caution states (important notices, warnings)
Danger: Destructive actions and errors (delete buttons, error messages)

How to Customize Colors

Generate Your Color Palette

Use the free uicolors.app tool to generate a complete color palette from your brand color.

Go to https://uicolors.app/create
Enter your brand color (e.g., #3B82F6 for blue)
Adjust the palette using the sliders if needed
Click "Export" → "CSS Variables"
Copy the generated CSS variables

Update globals.css

Open src/app/globals.css and find the "COLOR PALETTE - CUSTOMIZE HERE" section. Replace the primary color values with your generated palette.

src/app/globals.css

1:root {
2  /* Primary Color Palette - CUSTOMIZE HERE */
3  /* Current: Sage Green - Natural & Calming */
4  --primary-50: #f4f7f4;   /* Lightest shade */
5  --primary-100: #e3ebe3;
6  --primary-200: #c5d8c5;
7  --primary-300: #9cb99c;
8  --primary-400: #769776;
9  --primary-500: #567a56;  /* Base color */
10  --primary-600: #426042;  /* Most commonly used */
11  --primary-700: #354d35;
12  --primary-800: #2c3e2c;
13  --primary-900: #243324;
14  --primary-950: #121b12;  /* Darkest shade */
15}

💡

Pro Tip

The 600 shade is used most frequently for interactive elements like buttons and links. The 500 shade is typically the "true" brand color.

Customize Other Palettes (Optional)

You can also customize success, warning, and danger colors to match your brand. Follow the same process using uicolors.app.

src/app/globals.css

1:root {
2  /* Success Color - Green by default */
3  --success-500: #22c55e;
4  --success-600: #16a34a;
5  /* ... other shades */
6 
7  /* Warning Color - Amber by default */
8  --warning-500: #f59e0b;
9  --warning-600: #d97706;
10  /* ... other shades */
11 
12  /* Danger Color - Red by default */
13  --danger-500: #ef4444;
14  --danger-600: #dc2626;
15  /* ... other shades */
16}

Preview Your Changes

Save the file and your dev server will automatically reload with the new colors. Check these areas to see the changes:

Navigation and header elements
Buttons (primary, secondary, danger variants)
Links and interactive elements
Badges and status indicators
Dark mode appearance

Advanced Customization

Border Radius

Control how rounded corners appear throughout the app by adjusting the radius variables:

src/app/globals.css

1:root {
2  --radius-sm: 0.25rem;   /* 4px - subtle rounding */
3  --radius-md: 0.375rem;  /* 6px - buttons */
4  --radius-lg: 0.5rem;    /* 8px - cards (default) */
5  --radius-xl: 0.75rem;   /* 12px - modals */
6  --radius-2xl: 1rem;     /* 16px - large cards */
7  --radius-full: 9999px;  /* pill shape */
8}

Surface Colors

These control background and surface colors. They automatically adapt to light/dark mode:

src/app/globals.css

1:root {
2  --background: #ffffff;              /* Page background */
3  --foreground: var(--primary-950);   /* Text color */
4  --surface: #ffffff;                 /* Card backgrounds */
5  --surface-elevated: var(--primary-50); /* Hover states */
6  --border: var(--primary-200);       /* Border colors */
7}
8 
9.dark {
10  --background: var(--primary-950);
11  --foreground: var(--primary-100);
12  --surface: var(--primary-950);
13  --surface-elevated: var(--primary-900);
14  --border: var(--primary-800);
15}

Using Colors in Your Code

Once you've customized the colors, you can use them in your components using Tailwind classes:

src/components/YourComponent.tsx

1export function YourComponent() {
2  return (
3    <div className="bg-surface border border-border rounded-lg p-6">
4      <h2 className="text-foreground text-xl font-bold">
5        Your Title
6      </h2>
7      <button className="bg-primary-600 hover:bg-primary-700 text-white">
8        Primary Button
9      </button>
10      <button className="bg-danger-600 hover:bg-danger-700 text-white">
11        Delete Button
12      </button>
13    </div>
14  );
15}

Troubleshooting

Changes not appearing

If your color changes don't show up:

Make sure you saved src/app/globals.css
Refresh your browser (Cmd+R / Ctrl+R)
Clear your browser cache (Cmd+Shift+R / Ctrl+Shift+R)
Restart the dev server: npm run dev

Dark mode looks broken

Make sure you updated both :root and .dark sections in globals.css. Dark mode uses inverted shade values (lighter shades for dark backgrounds).

Some elements still show old colors

A few components may use hardcoded color classes. Search for the old color name (e.g., "indigo-600") in your codebase and replace it with the appropriate primary shade.

Colors look washed out or too vibrant

Go back to uicolors.app and adjust the saturation and lightness sliders until you find the right balance.

Next Steps

Now that you've customized your colors, you might want to:

Customize Logo & Branding - Add your company logo and update branding elements
Customize UI Components - Fine-tune individual component styles
Production Deployment - Deploy your customized app to production