Theme Configuration

This project is built on Tailwind CSS v4, providing a highly flexible theme customization system. From overall layout to detailed styling, you can personalize everything through CSS variables and Tailwind utility classes to create a unique user interface and experience.

Theme Configuration File

Theme configuration is located at: src/assets/styles/core/tailwind.css

CSS Theme Variables

Basic Color Variables

Using CSS Variables:

/* Text color */
color: var(--art-gray-100);
color: var(--art-gray-900);

/* Border */
border: 1px solid var(--default-border);
border: 1px solid var(--default-border-dashed);

/* Background color */
background-color: var(--default-bg-color); /* Page background */
background-color: var(--default-box-color); /* Card/container background */

/* Interactive states */
background-color: var(--art-hover-color); /* Hover state */
background-color: var(--art-active-color); /* Active state */

Using Tailwind Utility Classes:

<!-- Text color -->
<div class="text-g-900">Dark text</div>
<div class="text-g-500">Medium text</div>
<div class="text-g-100">Light text</div>

<!-- Background color -->
<div class="bg-box">Card background</div>
<div class="bg-hover-color">Hover background</div>

<!-- Border -->
<div class="border-full-d">Full border</div>
<div class="border-b-d">Bottom border</div>

<!-- Theme color -->
<div class="bg-primary text-white">Primary background</div>
<div class="text-primary">Primary text</div>

Theme Color System

The project uses OKLCH color space to define theme colors, providing more accurate color representation:

/* Theme colors */
color: var(--art-primary); /* Primary */
color: var(--art-secondary); /* Secondary */
color: var(--art-success); /* Success */
color: var(--art-warning); /* Warning */
color: var(--art-error); /* Error */
color: var(--art-info); /* Info */
color: var(--art-danger); /* Danger */

Element Plus Theme Color Variants:

The system automatically generates 9 different shades of theme color variants for various scenarios:

/* Lighter theme colors (higher number = lighter) */
background-color: var(--el-color-primary-light-1); /* Darkest */
background-color: var(--el-color-primary-light-5); /* Medium */
background-color: var(--el-color-primary-light-9); /* Lightest */

/* Darker theme colors (higher number = darker) */
background-color: var(--el-color-primary-dark-1);
background-color: var(--el-color-primary-dark-5);
background-color: var(--el-color-primary-dark-9);

Grayscale Color System

Provides 9 levels of grayscale colors that automatically adapt to Light/Dark mode:

/* CSS variable approach */
color: var(--art-gray-100); /* Lightest */
color: var(--art-gray-500); /* Medium */
color: var(--art-gray-900); /* Darkest */

/* Tailwind utility class approach */
<div class="text-g-100">Lightest text</div>
<div class="text-g-500">Medium text</div>
<div class="text-g-900">Darkest text</div>

<div class="bg-g-100">Lightest background</div>
<div class="bg-g-200">Light background</div>

Theme Variables Explained

Light Mode Variables

:root {
  /* Base colors */
  --art-color: #ffffff;
  --theme-color: var(--main-color);

  /* Theme colors - OKLCH format */
  --art-primary: oklch(0.7 0.23 260);
  --art-secondary: oklch(0.72 0.19 231.6);
  --art-error: oklch(0.73 0.15 25.3);
  --art-info: oklch(0.58 0.03 254.1);
  --art-success: oklch(0.78 0.17 166.1);
  --art-warning: oklch(0.78 0.14 75.5);
  --art-danger: oklch(0.68 0.22 25.3);

  /* Grayscale colors */
  --art-gray-100: #f9fafb;
  --art-gray-200: #f2f4f5;
  --art-gray-300: #e6eaeb;
  --art-gray-400: #dbdfe1;
  --art-gray-500: #949eb7;
  --art-gray-600: #7987a1;
  --art-gray-700: #4d5875;
  --art-gray-800: #383853;
  --art-gray-900: #323251;

  /* Border colors */
  --art-card-border: rgba(0, 0, 0, 0.07);
  --default-border: #e2e8ee;
  --default-border-dashed: #dbdfe9;

  /* Background colors */
  --default-bg-color: #fafbfc; /* Page background */
  --default-box-color: #ffffff; /* Card/container background */

  /* Interactive state colors */
  --art-hover-color: #f2f4f5; /* Hover state */
  --art-active-color: #f2f4f5; /* Active state */
  --art-el-active-color: #f2f4f5; /* Element component active state */
}

Dark Mode Variables

.dark {
  /* Base colors */
  --art-color: #000000;

  /* Grayscale colors (inverted in dark mode) */
  --art-gray-100: #110f0f;
  --art-gray-200: #17171c;
  --art-gray-300: #393946;
  --art-gray-400: #505062;
  --art-gray-500: #73738c;
  --art-gray-600: #8f8fa3;
  --art-gray-700: #ababba;
  --art-gray-800: #c7c7d1;
  --art-gray-900: #e3e3e8;

  /* Border colors */
  --art-card-border: rgba(255, 255, 255, 0.07);
  --default-border: rgba(255, 255, 255, 0.1);
  --default-border-dashed: #363843;

  /* Background colors */
  --default-bg-color: #070707; /* Page background */
  --default-box-color: #161618; /* Card/container background */

  /* Interactive state colors */
  --art-hover-color: #252530; /* Hover state */
  --art-active-color: #202226; /* Active state */
  --art-el-active-color: #2e2e38; /* Element component active state */
}

Tailwind Utility Class Extensions

The project extends Tailwind CSS with additional practical utility classes:

Layout Utility Classes

<!-- Flexbox shorthand classes -->
<div class="flex-c">
  <!-- flex + items-center -->
  <div class="flex-b">
    <!-- flex + justify-between -->
    <div class="flex-cc">
      <!-- flex + items-center + justify-center -->
      <div class="flex-cb"><!-- flex + items-center + justify-between --></div>
    </div>
  </div>
</div>

Transition Animations

<div class="tad-200">
  <!-- transition-all duration-200 -->
  <div class="tad-300"><!-- transition-all duration-300 --></div>
</div>

Border Utility Classes

<div class="border-full-d">
  <!-- Full border -->
  <div class="border-b-d">
    <!-- Bottom border -->
    <div class="border-t-d">
      <!-- Top border -->
      <div class="border-l-d">
        <!-- Left border -->
        <div class="border-r-d"><!-- Right border --></div>
      </div>
    </div>
  </div>
</div>

Other Utility Classes

<div class="c-p"><!-- cursor-pointer --></div>

Custom Border Radius

<div class="rounded-custom-xs">
  <!-- Small radius -->
  <div class="rounded-custom-sm"><!-- Medium radius --></div>
</div>

Theme Switching

Using the useTheme Hook

import { useTheme } from "@/hooks/core/useTheme";
import { SystemThemeEnum } from "@/enums/appEnum";

const { switchThemeStyles } = useTheme();

// Switch to dark theme
switchThemeStyles(SystemThemeEnum.DARK);

// Switch to light theme
switchThemeStyles(SystemThemeEnum.LIGHT);

// Switch to auto mode (follow system)
switchThemeStyles(SystemThemeEnum.AUTO);

Custom Theme Colors

Modifying Preset Theme Colors

Modify the preset theme color list in src/config/index.ts:

systemMainColor: [
  "#5D87FF", // Default blue
  "#B48DF3", // Purple
  "#1D84FF", // Sky blue
  "#60C041", // Green
  "#38C0FC", // Cyan
  "#F9901F", // Orange
  "#FF80C8", // Pink
];

Dynamically Setting Theme Colors

import { setElementThemeColor } from "@/utils/ui/colors";

// Set custom theme color
setElementThemeColor("#5D87FF");

Theme Color Utility Functions

The project provides complete color processing utilities (src/utils/ui/colors.ts):

import {
  hexToRgba, // Hex to RGBA
  hexToRgb, // Hex to RGB
  rgbToHex, // RGB to Hex
  getLightColor, // Generate lighter color
  getDarkColor, // Generate darker color
  colourBlend, // Color blending
} from "@/utils/ui/colors";

// Generate lighter color
const lightColor = getLightColor("#5D87FF", 0.3);

// Generate darker color
const darkColor = getDarkColor("#5D87FF", 0.3);

// Color blending
const blendedColor = colourBlend("#5D87FF", "#FFFFFF", 0.5);

Responsive Design

Using Tailwind's responsive prefixes:

<!-- Mobile-first approach -->
<div class="text-sm md:text-base lg:text-lg">Responsive text size</div>

<!-- Layout for different screens -->
<div class="flex-col md:flex-row">Responsive layout</div>

Best Practices

1. Prioritize Tailwind Utility Classes

<!-- ✅ Recommended -->
<div class="flex items-center gap-4 p-4 bg-box rounded-lg">
  <!-- ❌ Not recommended -->
  <div style="display: flex; align-items: center; gap: 1rem;"></div>
</div>

2. Use CSS Variables for Consistency

/* ✅ Recommended - Automatically adapts to theme */
.my-component {
  color: var(--art-gray-900);
  background: var(--default-box-color);
}

/* ❌ Not recommended - Hard-coded colors */
.my-component {
  color: #323251;
  background: #ffffff;
}

3. Use Semantic Color Variables

/* ✅ Recommended */
border-color: var(--default-border);
background: var(--art-hover-color);

/* ❌ Not recommended */
border-color: #e2e8ee;
background: #f2f4f5;

4. Leverage Utility Class Combinations

<!-- ✅ Recommended - Use predefined combination classes -->
<div class="flex-cb tad-300">
  <!-- ❌ Not recommended - Repeatedly write full classes -->
  <div
    class="flex items-center justify-between transition-all duration-300"
  ></div>
</div>

Theme Configuration Summary

By properly using CSS variables, Tailwind utility classes, and theme switching features, you can easily create beautiful, consistent, and maintainable user interfaces.