Skip to main content

Color Theme & Design System

Last updated: 25.09.2025

This guide explains how to use the custom color system in PathoSearch instead of default Tailwind colors for consistent branding and theming.

Overview​

PathoSearch uses a custom color palette built on top of Tailwind CSS v4 with semantic color tokens that automatically support light/dark mode theming. Always use these custom colors instead of default Tailwind colors to maintain design consistency.

Color Palette​

Primary Colors (Magenta)​

  • bg-primary-1 - Lightest magenta (#f3e9f5)
  • bg-primary-2 - Light magenta (#b679c1)
  • bg-primary-3 - Medium magenta (#9e4cad)
  • bg-primary - Base primary color (#861f98)

Secondary Colors (Purple)​

  • bg-secondary-1 through bg-secondary-12 - Purple gradient scale
  • bg-secondary - Base secondary color (#483569)

Tertiary Colors (Emerald)​

  • bg-tertiary-1 - Light emerald (#edf6f6)
  • bg-tertiary-2 - Medium emerald (#6cb5b5)
  • bg-tertiary-3 - Dark emerald (#6cb5b5)
  • bg-tertiary - Base tertiary color (#47a3a3)

Semantic Colors​

Success Colors

bg-success-1    /* Light success background */
bg-success-2    /* Medium success */
bg-success-3    /* Dark success */
bg-success      /* Base success (#6fcc52) */

Warning Colors

bg-warning-1    /* Light warning background */
bg-warning-2    /* Medium warning */  
bg-warning-3    /* Dark warning */
bg-warning      /* Base warning (#ffbc37) */

Error/Destructive Colors

bg-destructive-1    /* Light error background */
bg-destructive-2    /* Medium error */
bg-destructive-3    /* Dark error */
bg-destructive      /* Base error (#cb0000) */

Info Colors

bg-info-1       /* Light info background */
bg-info-2       /* Medium info */
bg-info-3       /* Dark info */  
bg-info         /* Base info (#1096e5) */

Grayscale Colors​

  • bg-grayscale-1 through bg-grayscale-10 - Complete grayscale range
  • text-grayscale-7 - Standard text color
  • text-grayscale-6 - Muted text color

Shadcn UI Semantic Tokens​

bg-background       /* Page background */
bg-card            /* Card backgrounds */
bg-muted           /* Muted backgrounds */
text-foreground    /* Primary text */
text-muted-foreground /* Secondary text */
border-border      /* Standard borders */

Usage Examples​

❌ Don't Use Default Tailwind Colors​

// Avoid these default Tailwind classes
<div className="bg-blue-500 text-white">
<button className="bg-red-600 hover:bg-red-700">
<span className="text-gray-500">

✅ Use Custom Semantic Colors​

// Use semantic color tokens instead
<div className="bg-primary text-primary-foreground">
<button className="bg-destructive hover:bg-destructive/90">
<span className="text-muted-foreground">

// For status indicators
<div className="bg-success-1 text-success border border-success">
  Success message
</div>

<div className="bg-warning-1 text-warning border border-warning">
  Warning message  
</div>

<div className="bg-destructive-1 text-destructive border border-destructive">
  Error message
</div>

Component Styling Examples​

Cards & Containers

<div className="bg-card text-card-foreground border border rounded-lg">
  <div className="p-4">
    <h3 className="text-foreground font-semibold">Title</h3>
    <p className="text-muted-foreground">Description</p>
  </div>
</div>

Buttons & Interactive Elements

import { Button } from '@kit/ui/button';

<Button variant="default">
  Primary Action
</Button>

<Button variant="secondary">
  Secondary Action  
</Button>

<Button variant="outline">
  Outline Action
</Button>

<Button variant="destructive">
  Delete Action
</Button>

<Button variant="ghost">
  Ghost Action
</Button>

<Button variant="link">
  Link Action
</Button>

Status Badges

import { Badge } from '@kit/ui/badge';

<Badge variant="default">
  Default
</Badge>

<Badge variant="secondary">
  Secondary
</Badge>

<Badge variant="success">
  Active
</Badge>

<Badge variant="warning">
  Pending
</Badge>

<Badge variant="destructive">
  Failed
</Badge>

<Badge variant="info">
  Information
</Badge>

<Badge variant="outline">
  Draft
</Badge>

Dark Mode Support​

All custom colors automatically adapt to dark mode. The color tokens remain the same, but the underlying values change:

// This automatically works in both light and dark mode
<div className="bg-card text-foreground border">
  Content that adapts to theme
</div>

Customizing Colors​

Colors are defined in apps/web/styles/shadcn-ui.css and apps/web/styles/theme.css:

  1. Update color values in shadcn-ui.css
  2. Add new semantic tokens in theme.css
  3. Use the new tokens throughout your components

Adding New Color Variants​

/* In shadcn-ui.css */
:root {
  --color-brand-1: #f0f9ff;
  --color-brand-2: #0ea5e9;  
  --color-brand-3: #0284c7;
  --color-brand-4: #0369a1;
}

/* In theme.css */
@theme {
  --color-brand: var(--color-brand-4);
  --color-brand-1: var(--color-brand-1);
  --color-brand-2: var(--color-brand-2);
  --color-brand-3: var(--color-brand-3);
}

Then use with bg-brand, text-brand-1, etc.

Design System Benefits​

✅ Consistent branding across all components
✅ Automatic dark mode support
✅ Semantic naming for better maintainability
✅ Design token approach for easy theme updates
✅ Accessibility compliance with proper contrast ratios

Best Practices​

  1. Always use semantic colors over hardcoded values
  2. Use scale modifiers 1, 2, 3 (e.g., bg-primary hover:bg-primary-1)
  3. Test in both light and dark mode during development
  4. Follow the existing component patterns in the codebase

References​

References:

Remember: Consistency is key. Always use the custom color system to maintain PathoSearch's visual identity and ensure a professional, cohesive user experience.