diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index c126e7681..8b73fb0be 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -96,7 +96,7 @@ export default defineConfig({
         {
           find: /^.*VPSwitchAppearance\.vue$/,
           replacement: fileURLToPath(
-            new URL('./theme/Appearance.vue', import.meta.url)
+            new URL('./theme/components/ThemeDropdown.vue', import.meta.url)
           )
         }
       ]
diff --git a/docs/.vitepress/constants.ts b/docs/.vitepress/constants.ts
index 0d0091e00..01942c889 100644
--- a/docs/.vitepress/constants.ts
+++ b/docs/.vitepress/constants.ts
@@ -332,4 +332,4 @@ export const sidebar: DefaultTheme.Sidebar | DefaultTheme.NavItemWithLink[] = [
       }
     ]
   }
-]
+]
\ No newline at end of file
diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue
index 4f37b3b8c..17b8bbe56 100644
--- a/docs/.vitepress/theme/Layout.vue
+++ b/docs/.vitepress/theme/Layout.vue
@@ -1,9 +1,12 @@
 <script setup lang="ts">
+import { useData } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import Announcement from './components/Announcement.vue'
 import Sidebar from './components/SidebarCard.vue'
+import { useTheme } from './themes/themeHandler'
 
 const { isDark } = useData()
+const { setMode } = useTheme()
 
 const enableTransitions = () =>
   'startViewTransition' in document &&
@@ -12,6 +15,8 @@ const enableTransitions = () =>
 provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
   if (!enableTransitions()) {
     isDark.value = !isDark.value
+    // Sync with theme handler
+    setMode(isDark.value ? 'dark' : 'light')
     return
   }
 
@@ -26,6 +31,8 @@ provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
   // @ts-expect-error
   await document.startViewTransition(async () => {
     isDark.value = !isDark.value
+    // Sync with theme handler
+    setMode(isDark.value ? 'dark' : 'light')
     await nextTick()
   }).ready
 
diff --git a/docs/.vitepress/theme/components/ColorPicker.vue b/docs/.vitepress/theme/components/ColorPicker.vue
index c213c0f65..61814b1a0 100644
--- a/docs/.vitepress/theme/components/ColorPicker.vue
+++ b/docs/.vitepress/theme/components/ColorPicker.vue
@@ -1,141 +1,262 @@
 <script setup lang="ts">
 import { colors } from '@fmhy/colors'
-import { useStorage, useStyleTag } from '@vueuse/core'
-import { watch, onMounted } from 'vue'
+import { useStorage } from '@vueuse/core'
+import { watch, onMounted, nextTick } from 'vue'
+import { useTheme } from '../themes/themeHandler'
+import { themeRegistry } from '../themes/configs'
+import type { Theme } from '../themes/types'
 import Switch from './Switch.vue'
 
-const colorScales = [
-  '50',
-  '100',
-  '200',
-  '300',
-  '400',
-  '500',
-  '600',
-  '700',
-  '800',
-  '900',
-  '950'
-] as const
-
 type ColorNames = keyof typeof colors
 const selectedColor = useStorage<ColorNames>('preferred-color', 'swarm')
-const isAmoledMode = useStorage('amoled-mode', false)
+
+// Use the theme system
+const { amoledEnabled, setAmoledEnabled, setTheme, state, mode, themeName } = useTheme()
 
 const colorOptions = Object.keys(colors).filter(
   (key) => typeof colors[key as keyof typeof colors] === 'object'
 ) as Array<ColorNames>
 
-const { css } = useStyleTag('', { id: 'brand-color' })
+// Preset themes (exclude dynamically generated color- themes)
+const presetThemeNames = Object.keys(themeRegistry).filter((k) => !k.startsWith('color-'))
 
-const updateThemeColor = (colorName: ColorNames, amoledEnabled: boolean) => {
-  const colorSet = colors[colorName]
+const getThemePreviewStyle = (name: string) => {
+  const theme = themeRegistry[name]
+  if (!theme) return {}
+  const modeKey = (mode && (mode as any).value) ? (mode as any).value as keyof typeof theme.modes : 'light'
+  const modeColors = theme.modes[modeKey]
 
-  const cssVars = colorScales
-    .map((scale) => `--vp-c-brand-${scale}: ${colorSet[scale]};`)
-    .join('\n    ')
-
-  const htmlElement = document.documentElement
-  
-  if (amoledEnabled) {
-    htmlElement.classList.add('theme-amoled')
-  } else {
-    htmlElement.classList.remove('theme-amoled')
+  if (theme.preview) {
+    // If preview is a URL or gradient, use it directly
+    if (theme.preview.startsWith('http') || theme.preview.startsWith('data:')) {
+      return { backgroundImage: `url(${theme.preview})`, backgroundSize: 'cover' }
+    }
+    return { background: theme.preview }
   }
-  
-  const darkBg = amoledEnabled ? '#000000' : 'rgb(26, 26, 26)'
-  const darkBgAlt = amoledEnabled ? '#000000' : 'rgb(23, 23, 23)'
-  const darkBgElv = amoledEnabled ? 'rgba(0, 0, 0, 0.9)' : 'rgba(23, 23, 23, 0.8)'
-  const darkBgSoft = amoledEnabled ? '#000000' : 'rgb(23, 23, 23)'
-  
-  css.value = `
-    :root {
-      ${cssVars}
-      --vp-c-brand-1: ${colorSet[500]};
-      --vp-c-brand-2: ${colorSet[600]};
-      --vp-c-brand-3: ${colorSet[800]};
-      --vp-c-brand-soft: ${colorSet[400]};
-      --vp-c-bg: #ffffff !important;
-      --vp-c-bg-alt: #f9f9f9 !important;
-      --vp-c-bg-elv: rgba(255, 255, 255, 0.7) !important;
-      --vp-c-bg-soft: #f9f9f9 !important;
-    }
 
-    .dark {
-      ${cssVars}
-      --vp-c-brand-1: ${colorSet[400]};
-      --vp-c-brand-2: ${colorSet[500]};
-      --vp-c-brand-3: ${colorSet[700]};
-      --vp-c-brand-soft: ${colorSet[300]};
-      --vp-c-bg: ${darkBg} !important;
-      --vp-c-bg-alt: ${darkBgAlt} !important;
-      --vp-c-bg-elv: ${darkBgElv} !important;
-      --vp-c-bg-soft: ${darkBgSoft} !important;
+  if (modeColors?.brand && modeColors.brand[1] && modeColors.brand[2]) {
+    return {
+      background: `linear-gradient(135deg, ${modeColors.brand[1]} 0%, ${modeColors.brand[2]} 100%)`
     }
-    
-    html, body {
-      background-color: #ffffff !important;
-    }
-    
-    .VPApp, .Layout, .VPContent, .VPHome, .VPHero, #app, .vp-doc {
-      background-color: #ffffff !important;
-    }
-    
-    .dark html, .dark body {
-      background-color: ${darkBg} !important;
-    }
-    
-    .dark .VPApp, .dark .Layout, .dark .VPContent, .dark .VPHome, .dark .VPHero, .dark #app, .dark .vp-doc {
-      background-color: ${darkBg} !important;
-    }
-  `
+  }
+
+  // Fallback to CSS var brand if present
+  return { background: 'var(--vp-c-brand-1)' }
 }
 
-onMounted(() => {
-  if (isAmoledMode.value) {
-    document.documentElement.classList.add('theme-amoled')
-  }
+const generateThemeFromColor = (colorName: ColorNames): Theme => {
+  const colorSet = colors[colorName]
   
-  // Re-apply the theme to ensure everything is initialized
-  updateThemeColor(selectedColor.value, isAmoledMode.value)
-})
-
-watch([selectedColor, isAmoledMode], ([color, amoled]) => {
-  updateThemeColor(color, amoled)
-})
+  return {
+    name: `color-${colorName}`,
+    displayName: normalizeColorName(colorName),
+    modes: {
+      light: {
+        brand: {
+          1: colorSet[500],
+          2: colorSet[600],
+          3: colorSet[800],
+          soft: colorSet[400]
+        },
+        bg: '#f8fafc',
+        bgAlt: '#eef2f5',
+        bgElv: 'rgba(255, 255, 255, 0.8)',
+        bgMark: 'rgb(226, 232, 240)',
+        text: {
+          1: '#0f172a',
+          2: '#334155',
+          3: '#64748b'
+        },
+        button: {
+          brand: {
+            bg: colorSet[500],
+            border: colorSet[400],
+            text: 'rgba(255, 255, 255)',
+            hoverBorder: colorSet[400],
+            hoverText: 'rgba(255, 255, 255)',
+            hoverBg: colorSet[400],
+            activeBorder: colorSet[400],
+            activeText: 'rgba(255, 255, 255)',
+            activeBg: colorSet[500]
+          },
+          alt: {
+            bg: '#484848',
+            text: '#f0eeee',
+            hoverBg: '#484848',
+            hoverText: '#f0eeee'
+          }
+        },
+        customBlock: {
+          info: {
+            bg: `${colorSet[100]}`,
+            border: `${colorSet[800]}`,
+            text: `${colorSet[800]}`,
+            textDeep: `${colorSet[900]}`
+          },
+          tip: {
+            bg: '#D8F8E4',
+            border: '#447A61',
+            text: '#2D6A58',
+            textDeep: '#166534'
+          },
+          warning: {
+            bg: '#FCEFC3',
+            border: '#9A8034',
+            text: '#9C701B',
+            textDeep: '#92400e'
+          },
+          danger: {
+            bg: '#FBE1E2',
+            border: '#B3565E',
+            text: '#912239',
+            textDeep: '#991b1b'
+          }
+        },
+        selection: {
+          bg: colorSet[200]
+        },
+        home: {
+          heroNameColor: 'transparent',
+          heroNameBackground: `-webkit-linear-gradient(120deg, ${colorSet[400]} 30%, ${colorSet[500]})`,
+          heroImageBackground: `linear-gradient(-45deg, ${colorSet[400]} 50%, ${colorSet[500]} 50%)`,
+          heroImageFilter: 'blur(44px)'
+        }
+      },
+      dark: {
+        brand: {
+          1: colorSet[400],
+          2: colorSet[500],
+          3: colorSet[600],
+          soft: colorSet[300]
+        },
+        bg: '#1A1A1A',
+        bgAlt: '#171717',
+        bgElv: '#1a1a1acc',
+        button: {
+          brand: {
+            bg: colorSet[400],
+            border: colorSet[300],
+            text: 'rgba(15, 23, 42)',
+            hoverBorder: colorSet[300],
+            hoverText: 'rgba(15, 23, 42)',
+            hoverBg: colorSet[300],
+            activeBorder: colorSet[300],
+            activeText: 'rgba(15, 23, 42)',
+            activeBg: colorSet[400]
+          },
+          alt: {
+            bg: '#484848',
+            text: '#f0eeee',
+            hoverBg: '#484848',
+            hoverText: '#f0eeee'
+          }
+        },
+        customBlock: {
+          info: {
+            bg: `${colorSet[950]}`,
+            border: `${colorSet[700]}`,
+            text: `${colorSet[200]}`,
+            textDeep: `${colorSet[200]}`
+          },
+          tip: {
+            bg: '#0C2A20',
+            border: '#184633',
+            text: '#B0EBC9',
+            textDeep: '#166534'
+          },
+          warning: {
+            bg: '#403207',
+            border: '#7E6211',
+            text: '#F9DE88',
+            textDeep: '#92400e'
+          },
+          danger: {
+            bg: '#3F060A',
+            border: '#7C0F18',
+            text: '#F7C1BC',
+            textDeep: '#991b1b'
+          }
+        },
+        selection: {
+          bg: colorSet[800]
+        },
+        home: {
+          heroNameColor: 'transparent',
+          heroNameBackground: `-webkit-linear-gradient(120deg, ${colorSet[400]} 30%, ${colorSet[500]})`,
+          heroImageBackground: `linear-gradient(-45deg, ${colorSet[400]} 50%, ${colorSet[500]} 50%)`,
+          heroImageFilter: 'blur(44px)'
+        }
+      }
+    }
+  }
+}
 
 const normalizeColorName = (colorName: string) =>
   colorName.replaceAll(/-/g, ' ').charAt(0).toUpperCase() +
   colorName.slice(1).replaceAll(/-/g, ' ')
+
+onMounted(async () => {
+  // Don't auto-apply color theme - only apply when user explicitly selects
+  // Wait for next tick to ensure theme handler is fully initialized
+  await nextTick()
+})
+
+watch(selectedColor, async (color) => {
+  const theme = generateThemeFromColor(color)
+  themeRegistry[`color-${color}`] = theme
+  // Explicitly set the theme to override any previous selection
+  await nextTick()
+  console.log('Setting theme to:', `color-${color}`)
+  console.log('Current themeName:', themeName ? themeName.value : undefined, 'mode:', mode ? (mode as any).value : undefined)
+  setTheme(`color-${color}`)
+  console.log('After setTheme, themeName:', themeName ? themeName.value : undefined)
+})
+
+const toggleAmoled = () => {
+  setAmoledEnabled(!amoledEnabled.value)
+}
 </script>
 
 <template>
   <div>
     <div class="flex flex-wrap gap-2">
+      <!-- Color picker generated themes (render first) -->
       <div v-for="color in colorOptions" :key="color">
         <button
-          :class=" [
-            'inline-block w-6 h-6 rounded-full transition-all duration-200'
+          :class="[
+            'inline-block w-6 h-6 rounded-full transition-all duration-200 border-2',
+            selectedColor === color
+              ? 'border-slate-200 dark:border-slate-400 shadow-lg'
+              : 'border-transparent'
           ]"
           @click="selectedColor = color"
           :title="normalizeColorName(color)"
         >
           <span
-            class="inline-block w-6 h-6 rounded-full"
-            :style="{ backgroundColor: colors[color][500] }"
+            class="inline-block w-full h-full rounded-full"
+            :style="{ backgroundColor: colors[color][500], backgroundSize: 'cover', backgroundPosition: 'center', backgroundRepeat: 'no-repeat' }"
+          ></span>
+        </button>
+      </div>
+
+      <!-- Preset themes (render at the end) -->
+      <div v-for="t in presetThemeNames" :key="t">
+        <button
+          :class="[
+            'inline-block w-6 h-6 rounded-full transition-all duration-200 border-2',
+            (themeName && themeName.value === t)
+              ? 'border-slate-200 dark:border-slate-400 shadow-lg'
+              : 'border-transparent'
+          ]"
+          @click="setTheme(t)"
+          :title="themeRegistry[t].displayName"
+        >
+          <span
+            class="inline-block w-full h-full rounded-full"
+            :style="Object.assign({ backgroundSize: 'cover', backgroundPosition: 'center', backgroundRepeat: 'no-repeat' }, getThemePreviewStyle(t))"
           ></span>
         </button>
       </div>
     </div>
-
-    <div class="mt-2 text-sm text-$vp-c-text-2">
-      Selected: {{ normalizeColorName(selectedColor) }}
-    </div>
-    
-    <!-- AMOLED toggle -->
-    <div class="mt-4 flex items-center gap-2">
-      <span class="text-sm text-$vp-c-text-2">AMOLED</span>
-      <Switch v-model="isAmoledMode" @click="isAmoledMode = !isAmoledMode" />
-    </div>
   </div>
 </template>
diff --git a/docs/.vitepress/theme/components/Feedback.vue b/docs/.vitepress/theme/components/Feedback.vue
index 876c99794..014c757db 100644
--- a/docs/.vitepress/theme/components/Feedback.vue
+++ b/docs/.vitepress/theme/components/Feedback.vue
@@ -145,36 +145,28 @@ const toggleCard = () => (isCardShown.value = !isCardShown.value)
   </template>
   <template v-else>
     <div
-      class="mt-2 p-4 border-2 border-solid bg-brand-50 border-brand-300 dark:bg-brand-950 dark:border-brand-800 rounded-xl col-span-3 transition-colors duration-250"
+      class="mt-2 p-4 border-2 border-solid bg-$vp-c-bg-alt border-$vp-c-divider rounded-xl col-span-3 transition-colors duration-250"
     >
       <div class="flex items-start md:items-center gap-3">
         <div class="pt-1 md:pt-0">
-          <div
-            class="w-10 h-10 rounded-full flex items-center justify-center bg-brand-500 dark:bg-brand-400"
-          >
+          <div class="w-10 h-10 rounded-full flex items-center justify-center bg-$vp-c-brand-3">
             <span
               :class="
                 isCardShown === false
-                  ? `i-lucide:mail w-6 h-6 text-white dark:text-brand-950`
-                  : `i-lucide:mail-x w-6 h-6 text-white dark:text-brand-950`
+                  ? `i-lucide:mail w-6 h-6 text-$vp-c-text-1`
+                  : `i-lucide:mail-x w-6 h-6 text-$vp-c-text-1`
               "
             />
           </div>
         </div>
-        <div
-          class="flex-grow flex items-start md:items-center gap-3 flex-col md:flex-row"
-        >
+        <div class="flex-grow flex items-start md:items-center gap-3 flex-col md:flex-row">
           <div class="flex-grow">
-            <div class="font-semibold text-brand-950 dark:text-brand-50">
-              Got feedback?
-            </div>
-            <div class="text-sm text-brand-800 dark:text-brand-100">
-              We'd love to know what you think about this page.
-            </div>
+            <div class="font-semibold text-$vp-c-text-1">Got feedback?</div>
+            <div class="text-sm text-$vp-c-text-2">We'd love to know what you think about this page.</div>
           </div>
           <div>
             <button
-              class="inline-block text-center rounded-full px-4 py-2.5 text-sm font-medium border-2 border-solid text-brand-700 border-brand-300 dark:text-brand-100 dark:border-brand-800"
+              class="inline-block text-center rounded-full px-4 py-2.5 text-sm font-medium border-2 border-solid text-$vp-c-text-1 border-$vp-c-divider"
               @click="toggleCard()"
             >
               Share Feedback
@@ -199,7 +191,7 @@ const toggleCard = () => (isCardShown.value = !isCardShown.value)
             <button
               v-for="item in feedbackOptions"
               :key="item.value"
-              class="bg-bg border-$vp-c-default-soft hover:border-primary mt-2 select-none rounded border-2 border-solid font-bold transition-all duration-250 rounded-lg text-[14px] font-500 leading-normal m-0 px-3 py-1.5 text-center align-middle whitespace-nowrap"
+                class="bg-$vp-c-bg border-$vp-c-default-soft hover:border-primary mt-2 select-none rounded border-2 border-solid font-bold transition-all duration-250 rounded-lg text-[14px] font-500 leading-normal m-0 px-3 py-1.5 text-center align-middle whitespace-nowrap"
               @click="handleSubmit(item.value)"
             >
               <span>{{ item.label }}</span>
@@ -240,9 +232,10 @@ const toggleCard = () => (isCardShown.value = !isCardShown.value)
             </button>
             <button
               type="submit"
-              class="border border-div rounded-lg transition-colors duration-250 inline-block text-14px font-500 leading-1.5 px-3 py-3 text-center align-middle whitespace-nowrap disabled:opacity-50 text-text-2 bg-brand-100 dark:bg-brand-700 border-brand-800 dark:border-brand-700 disabled:bg-brand-100 dark:disabled:bg-brand-900 hover:border-brand-900 dark:hover:border-brand-800 hover:bg-brand-200 dark:hover:bg-brand-800"
+              class="btn btn-primary"
               :disabled="isDisabled"
               @click="handleSubmit()"
+              :style="isDisabled ? {} : { 'background-color': 'var(--vp-button-brand-bg)', 'border-color': 'var(--vp-button-brand-border)', color: 'var(--vp-button-brand-text)' }"
             >
               Send Feedback 📩
             </button>
@@ -284,14 +277,14 @@ const toggleCard = () => (isCardShown.value = !isCardShown.value)
 }
 
 .btn-primary {
-  color: #fff;
-  background-color: var(--vp-c-brand);
-  border-color: var(--vp-c-brand);
+  color: var(--vp-button-brand-text);
+  background-color: var(--vp-button-brand-bg);
+  border-color: var(--vp-button-brand-border);
 }
 
 .btn-primary:hover {
-  background-color: var(--vp-c-brand-darker);
-  border-color: var(--vp-c-brand-darker);
+  background-color: var(--vp-button-brand-hover-bg);
+  border-color: var(--vp-button-brand-hover-border);
 }
 
 .heading {
diff --git a/docs/.vitepress/theme/components/SidebarCard.vue b/docs/.vitepress/theme/components/SidebarCard.vue
index 48f0bb316..9d860772a 100644
--- a/docs/.vitepress/theme/components/SidebarCard.vue
+++ b/docs/.vitepress/theme/components/SidebarCard.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import Field from './CardField.vue'
 import ColorPicker from './ColorPicker.vue'
+import ThemeSelector from './ThemeSelector.vue'
 import InputField from './InputField.vue'
 import ToggleStarred from './ToggleStarred.vue'
 </script>
@@ -26,6 +27,12 @@ import ToggleStarred from './ToggleStarred.vue'
       </template>
     </InputField>
 
-    <ColorPicker />
+    <div class="mt-4">
+      <ColorPicker />
+    </div>
+
+    <div class="mt-6 pt-6 border-t border-$vp-c-divider">
+      <ThemeSelector />
+    </div>
   </div>
-</template>
+</template>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/components/ThemeDropdown.vue b/docs/.vitepress/theme/components/ThemeDropdown.vue
new file mode 100644
index 000000000..e7f2d6994
--- /dev/null
+++ b/docs/.vitepress/theme/components/ThemeDropdown.vue
@@ -0,0 +1,184 @@
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+import { useTheme } from '../themes/themeHandler'
+import type { DisplayMode } from '../themes/types'
+
+const { mode, setMode, state, amoledEnabled, setAmoledEnabled } = useTheme()
+
+const isOpen = ref(false)
+const dropdownRef = ref<HTMLElement | null>(null)
+
+interface ModeChoice {
+  mode: DisplayMode
+  label: string
+  icon: string
+  isAmoled?: boolean
+}
+
+const modeChoices: ModeChoice[] = [
+  { mode: 'light', label: 'Light', icon: 'i-ph-sun-duotone' },
+  { mode: 'dark', label: 'Dark', icon: 'i-ph-moon-duotone' },
+  { mode: 'dark', label: 'AMOLED', icon: 'i-ph-moon-stars-duotone', isAmoled: true }
+]
+
+const currentChoice = computed(() => {
+  const current = (mode && (mode as any).value) ? (mode as any).value : 'light'
+  if (current === 'dark' && amoledEnabled.value) {
+    return modeChoices[2] // AMOLED option
+  }
+  return modeChoices.find(choice => choice.mode === current && !choice.isAmoled) || modeChoices[0]
+})
+
+const toggleDropdown = () => {
+  isOpen.value = !isOpen.value
+}
+
+const selectMode = (choice: ModeChoice) => {
+  if (choice.isAmoled) {
+    setMode('dark')
+    setAmoledEnabled(true)
+  } else {
+    setMode(choice.mode)
+    setAmoledEnabled(false)
+  }
+  isOpen.value = false
+}
+
+const isActiveChoice = (choice: ModeChoice) => {
+  const current = (mode && (mode as any).value) ? (mode as any).value : 'light'
+  if (choice.isAmoled) {
+    return current === 'dark' && amoledEnabled.value
+  }
+  return choice.mode === current && !choice.isAmoled && !amoledEnabled.value
+}
+
+const handleClickOutside = (event: MouseEvent) => {
+  if (dropdownRef.value && !dropdownRef.value.contains(event.target as Node)) {
+    isOpen.value = false
+  }
+}
+
+onMounted(() => {
+  document.addEventListener('click', handleClickOutside)
+})
+
+onUnmounted(() => {
+  document.removeEventListener('click', handleClickOutside)
+})
+</script>
+
+<template>
+  <div ref="dropdownRef" class="theme-dropdown">
+    <button
+      type="button"
+      class="theme-dropdown-toggle"
+      :title="currentChoice.label"
+      @click="toggleDropdown"
+    >
+      <ClientOnly>
+        <div :class="[currentChoice.icon, 'text-xl']" />
+      </ClientOnly>
+    </button>
+
+    <Transition name="dropdown">
+      <div v-if="isOpen" class="theme-dropdown-menu">
+        <button
+          v-for="(choice, index) in modeChoices"
+          :key="index"
+          class="theme-dropdown-item"
+          :class="{ active: isActiveChoice(choice) }"
+          @click="selectMode(choice)"
+        >
+          <div :class="[choice.icon, 'text-lg']" />
+          <span>{{ choice.label }}</span>
+          <div v-if="isActiveChoice(choice)" class="i-ph-check text-lg ml-auto" />
+        </button>
+      </div>
+    </Transition>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.theme-dropdown {
+  position: relative;
+  display: inline-block;
+}
+
+.theme-dropdown-toggle {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  width: 36px;
+  height: 36px;
+  color: var(--vp-c-text-2);
+  transition: color 0.5s;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  border-radius: 8px;
+
+  &:hover {
+    color: var(--vp-c-text-1);
+    background: var(--vp-c-bg-elv);
+    transition: color 0.25s, background 0.25s;
+  }
+}
+
+.theme-dropdown-menu {
+  position: absolute;
+  top: calc(100% + 8px);
+  right: 0;
+  min-width: 180px;
+  background: var(--vp-c-bg-elv);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
+  padding: 6px;
+  z-index: 1000;
+  backdrop-filter: blur(12px);
+
+  .dark & {
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
+  }
+}
+
+.theme-dropdown-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  padding: 8px 12px;
+  background: transparent;
+  border: none;
+  border-radius: 6px;
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  transition: background 0.2s;
+  font-size: 14px;
+  text-align: left;
+
+  &:hover {
+    background: var(--vp-c-bg);
+  }
+
+  &.active {
+    color: var(--vp-c-brand-1);
+    font-weight: 500;
+  }
+
+  span {
+    flex: 1;
+  }
+}
+
+.dropdown-enter-active,
+.dropdown-leave-active {
+  transition: opacity 0.15s ease, transform 0.15s ease;
+}
+
+.dropdown-enter-from,
+.dropdown-leave-to {
+  opacity: 0;
+  transform: translateY(-8px);
+}
+</style>
diff --git a/docs/.vitepress/theme/components/ThemeSelector.vue b/docs/.vitepress/theme/components/ThemeSelector.vue
new file mode 100644
index 000000000..1653f3d27
--- /dev/null
+++ b/docs/.vitepress/theme/components/ThemeSelector.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useTheme } from '../themes/themeHandler'
+import { themeRegistry } from '../themes/configs'
+
+const { themeName, setTheme, getAvailableThemes, state, mode } = useTheme()
+
+const availableThemes = computed(() => getAvailableThemes())
+
+const getThemePreview = (name: string) => {
+  const theme = themeRegistry[name]
+  if (theme?.preview) {
+    return theme.preview
+  }
+  // Fallback: create gradient from theme's brand colors if they exist
+  const modeKey = (mode && (mode as any).value) ? (mode as any).value : 'light'
+  const colors = modeKey === 'dark' ? theme?.modes.dark : theme?.modes.light
+  
+  if (colors?.brand && colors.brand[1] && colors.brand[2] && colors.brand[3]) {
+    return `linear-gradient(135deg, ${colors.brand[1]} 0%, ${colors.brand[2]} 50%, ${colors.brand[3]} 100%)`
+  }
+  
+  return 'linear-gradient(135deg, var(--vp-c-brand-1) 0%, var(--vp-c-brand-2) 100%)'
+}
+
+const normalizeThemeName = (name: string) =>
+  name.replaceAll(/-/g, ' ').charAt(0).toUpperCase() +
+  name.slice(1).replaceAll(/-/g, ' ')
+
+const currentDisplayName = computed(() => {
+  const t = themeName && (themeName as any).value ? (themeName as any).value : ''
+  if (!t) return 'Default'
+  const cfg = themeRegistry[t]
+  if (cfg && cfg.displayName) return cfg.displayName
+  // fallback: humanize the key
+  return normalizeThemeName(t)
+})
+</script>
+
+<template>
+  <div>
+    <div class="mb-2 text-sm text-$vp-c-text-1">Theme</div>
+    <div class="text-sm text-$vp-c-text-2">
+      <span class="font-medium">Theme:</span>
+      <span class="ml-1">{{ currentDisplayName }}</span>
+    </div>
+  </div>
+</template>
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 04b2aa4b9..2c37e37ef 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -18,6 +18,7 @@ import type { Theme } from 'vitepress'
 import Components from '@fmhy/components'
 import DefaultTheme from 'vitepress/theme'
 import { loadProgress } from './composables/nprogress'
+import { useThemeHandler } from './themes/themeHandler'
 import Layout from './Layout.vue'
 import Post from './PostLayout.vue'
 
@@ -34,5 +35,7 @@ export default {
     app.component('Post', Post)
     app.component('Feedback', Feedback)
     loadProgress(router)
+    // Initialize theme handler
+    useThemeHandler()
   }
 } satisfies Theme
diff --git a/docs/.vitepress/theme/themes/README.md b/docs/.vitepress/theme/themes/README.md
new file mode 100644
index 000000000..9aa112d5d
--- /dev/null
+++ b/docs/.vitepress/theme/themes/README.md
@@ -0,0 +1,109 @@
+# Theme System
+
+This document explains the updated theme architecture, display modes, and integration components in the site.
+
+## Architecture
+
+- Display modes: `light` and `dark`.
+- AMOLED: an enhancement of `dark` mode (pure black backgrounds) toggled on top of dark — not a separate mode.
+- Themes: color schemes and optional design tokens that apply across modes.
+- Modes are independent from themes; themes define colors and tokens for light/dark.
+
+## File Structure
+
+```
+docs/.vitepress/theme/themes/
+├── types.ts             // Type definitions
+├── themeHandler.ts      // Theme handler logic & DOM/CSS application
+├── index.ts             // Exports
+└── configs/
+    ├── index.ts         // Theme registry (default + named themes)
+    └── catppuccin.ts    // Example theme (default)
+```
+
+## Core Types
+
+- `DisplayMode`: `'light' | 'dark'`.
+- `Theme`: `{ name, displayName, preview?, logo?, modes: { light, dark }, ... }`.
+- `ModeColors`:
+  - `brand?`: optional brand colors (`1`, `2`, `3`, `soft`). If omitted, the ColorPicker controls brand.
+  - `bg`, `bgAlt`, `bgElv`, `bgMark?`.
+  - `text?`: optional (`1`, `2`, `3`). If omitted, VitePress defaults are used.
+  - `button`: `brand` and `alt` sub-objects with `bg`, `border`, `text`, `hover*`, `active*`.
+  - `customBlock`: `info`, `tip`, `warning`, `danger` with `bg`, `border`, `text`, `textDeep`.
+  - `selection`: `{ bg }`.
+  - `home?`: optional hero styles.
+
+## Handler Behavior (`themeHandler.ts`)
+
+- Persists `theme` (`vitepress-theme-name`) and `mode` (`vitepress-display-mode`).
+- Applies HTML classes: always the current mode; adds `dark` for compatibility; adds `amoled` when dark + AMOLED enabled.
+- AMOLED handling: overrides dark backgrounds to pure black while retaining other dark tokens.
+- Brand colors:
+  - If theme provides brand colors, inline CSS variables are set.
+  - If theme omits brand colors, inline brand variables are removed so the ColorPicker stylesheet takes effect.
+- Text colors:
+  - Applied only if defined in the theme; otherwise defaults are used.
+- Custom logo:
+  - If theme provides `logo`, sets `--vp-theme-logo: url(...)` for downstream usage.
+
+## UI Components
+
+- `ThemeDropdown.vue`: replaces the appearance toggle.
+  - Options: Light, Dark, AMOLED (as dark variant).
+  - Stores/reads mode and AMOLED-enabled state.
+  - Aliased via `docs/.vitepress/config.mts` to override `VPSwitchAppearance.vue`.
+- `ColorPicker.vue`:
+  - Controls brand color CSS variables via a stylesheet tag (`#brand-color`).
+  - Reapplies colors on a custom event `theme-changed-apply-colors` when switching to themes without brand.
+- `ThemeSelector.vue`:
+  - Shows circular previews per theme (image via `preview` or gradient fallback).
+  - Calls `setTheme(name)`; independent from ColorPicker.
+
+## Theme Registry (`configs/index.ts`)
+
+- Example:
+```ts
+import { catppuccinTheme } from './catppuccin'
+
+export const themeRegistry = {
+  default: catppuccinTheme,
+  catppuccin: catppuccinTheme
+}
+```
+
+## Creating a Theme (`configs/<name>.ts`)
+
+- Export a `Theme` object with:
+  - `name`, `displayName`, optional `preview` (image URL/data) and `logo`.
+  - `modes.light` and `modes.dark` objects.
+  - Optional `fonts`, `spacing`, `borderRadius`, `customProperties`.
+- Register it in `configs/index.ts`.
+- If you omit `brand` in a mode, the ColorPicker-selected brand colors will be used.
+- If you omit `text` in a mode, VitePress default text colors will be used.
+
+## CSS Variables
+
+- Brand: `--vp-c-brand-1`, `--vp-c-brand-2`, `--vp-c-brand-3`, `--vp-c-brand-soft`.
+- Background: `--vp-c-bg`, `--vp-c-bg-alt`, `--vp-c-bg-elv`, `--vp-c-bg-mark`.
+- Text: `--vp-c-text-1`, `--vp-c-text-2`, `--vp-c-text-3`.
+- Buttons: `--vp-button-brand-*`, `--vp-button-alt-*`.
+- Custom blocks: `--vp-custom-block-{type}-*`.
+- Selection: `--vp-c-selection-bg`.
+- Home hero: `--vp-home-hero-*`.
+- Custom props: all keys in `customProperties`.
+- Optional: `--vp-theme-logo` (when theme defines `logo`).
+
+## Migration Notes
+
+- AMOLED is no longer a separate mode; it’s a dark enhancement (pure black backgrounds) toggled in the dropdown.
+- The legacy `Appearance.vue` toggle is replaced by `ThemeDropdown.vue` via alias in `config.mts`.
+- Themes can rely on the ColorPicker for brand colors by omitting `brand`.
+
+## Troubleshooting
+
+- Theme not applying: ensure it’s added to `themeRegistry` and named correctly.
+- Brand not changing: if a theme sets inline brand variables, ColorPicker won’t override; remove `brand` from the theme to defer to ColorPicker.
+- Colors not updating after theme switch: ColorPicker listens for `theme-changed-apply-colors`; make sure that event dispatch remains in `setTheme()`.
+- AMOLED not pure black: confirm dark mode is active and AMOLED toggle is enabled; handler overrides backgrounds when enabled.
+
diff --git a/docs/.vitepress/theme/themes/configs/catppuccin.ts b/docs/.vitepress/theme/themes/configs/catppuccin.ts
new file mode 100644
index 000000000..9125cb769
--- /dev/null
+++ b/docs/.vitepress/theme/themes/configs/catppuccin.ts
@@ -0,0 +1,161 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+import type { Theme } from '../types'
+
+export const catppuccinTheme: Theme = {
+  name: 'catppuccin',
+  displayName: 'Catppuccin',
+  preview: 'https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/logos/exports/1544x1544_circle.png',
+  modes: {
+    light: {
+      brand: {
+        1: '#8b5cf6',
+        2: '#7c3aed',
+        3: '#5b21b6',
+        soft: '#a78bfa'
+      },
+      bg: '#ffffff',
+      bgAlt: '#f9fafb',
+      bgElv: 'rgba(255, 255, 255, 0.7)',
+      bgMark: 'rgb(232, 232, 232)',
+      text: {
+        1: '#1f2937',
+        2: '#4b5563',
+        3: '#6b7280'
+      },
+      button: {
+        brand: {
+          bg: '#8b5cf6',
+          border: '#a78bfa',
+          text: 'rgba(42, 40, 47)',
+          hoverBorder: '#a78bfa',
+          hoverText: 'rgba(42, 40, 47)',
+          hoverBg: '#a78bfa',
+          activeBorder: '#a78bfa',
+          activeText: 'rgba(42, 40, 47)',
+          activeBg: '#8b5cf6'
+        },
+        alt: {
+          bg: '#484848',
+          text: '#f0eeee',
+          hoverBg: '#484848',
+          hoverText: '#f0eeee'
+        }
+      },
+      customBlock: {
+        info: {
+          bg: '#ede9fe',
+          border: '#5b21b6',
+          text: '#5b21b6',
+          textDeep: '#4c1d95'
+        },
+        tip: {
+          bg: '#d1fae5',
+          border: '#065f46',
+          text: '#065f46',
+          textDeep: '#064e3b'
+        },
+        warning: {
+          bg: '#fef3c7',
+          border: '#92400e',
+          text: '#92400e',
+          textDeep: '#78350f'
+        },
+        danger: {
+          bg: '#ffe4e6',
+          border: '#9f1239',
+          text: '#9f1239',
+          textDeep: '#881337'
+        }
+      },
+      selection: {
+        bg: '#5586a6'
+      },
+      home: {
+        heroNameColor: 'transparent',
+        heroNameBackground: '-webkit-linear-gradient(120deg, #c4b5fd 30%, #7bc5e4)',
+        heroImageBackground: 'linear-gradient(-45deg, #c4b5fd 50%, #47caff 50%)',
+        heroImageFilter: 'blur(44px)'
+      }
+    },
+    dark: {
+      brand: {
+        1: '#a78bfa',
+        2: '#8b5cf6',
+        3: '#6d28d9',
+        soft: '#c4b5fd'
+      },
+      bg: 'rgb(26, 26, 26)',
+      bgAlt: 'rgb(23, 23, 23)',
+      bgElv: 'rgba(23, 23, 23, 0.8)',
+      button: {
+        brand: {
+          bg: '#a78bfa',
+          border: '#c4b5fd',
+          text: 'rgba(42, 40, 47)',
+          hoverBorder: '#c4b5fd',
+          hoverText: 'rgba(42, 40, 47)',
+          hoverBg: '#c4b5fd',
+          activeBorder: '#c4b5fd',
+          activeText: 'rgba(42, 40, 47)',
+          activeBg: '#a78bfa'
+        },
+        alt: {
+          bg: '#484848',
+          text: '#f0eeee',
+          hoverBg: '#484848',
+          hoverText: '#f0eeee'
+        }
+      },
+      customBlock: {
+        info: {
+          bg: '#2e1065',
+          border: '#5b21b6',
+          text: '#ddd6fe',
+          textDeep: '#ddd6fe'
+        },
+        tip: {
+          bg: '#022c22',
+          border: '#065f46',
+          text: '#a7f3d0',
+          textDeep: '#a7f3d0'
+        },
+        warning: {
+          bg: '#451a03',
+          border: '#92400e',
+          text: '#fef08a',
+          textDeep: '#fef08a'
+        },
+        danger: {
+          bg: '#4c0519',
+          border: '#9f1239',
+          text: '#fecdd3',
+          textDeep: '#fecdd3'
+        }
+      },
+      selection: {
+        bg: '#0f2c47'
+      },
+      home: {
+        heroNameColor: 'transparent',
+        heroNameBackground: '-webkit-linear-gradient(120deg, #c4b5fd 30%, #7bc5e4)',
+        heroImageBackground: 'linear-gradient(-45deg, #c4b5fd 50%, #47caff 50%)',
+        heroImageFilter: 'blur(44px)'
+      }
+    }
+  }
+}
diff --git a/docs/.vitepress/theme/themes/configs/christmas.ts b/docs/.vitepress/theme/themes/configs/christmas.ts
new file mode 100644
index 000000000..d82f17d3a
--- /dev/null
+++ b/docs/.vitepress/theme/themes/configs/christmas.ts
@@ -0,0 +1,161 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+import type { Theme } from '../types'
+
+export const christmasTheme: Theme = {
+  name: 'Christmas',
+  displayName: 'Christmas',
+  preview: 'https://files.catbox.moe/inbi62.png',
+  modes: {
+    light: {
+      brand: {
+        1: '#BD2F2F',
+        2: '#22ff00ff',
+        3: '#155C2F',
+        soft: '#a200ffff'
+      },
+      bg: '#ffffffff',
+      bgAlt: '#f9fafb',
+      bgElv: 'rgba(255, 255, 255, 0.7)',
+      bgMark: 'rgb(232, 232, 232)',
+      text: {
+        1: '#1f2937',
+        2: '#4b5563',
+        3: '#353638ff'
+      },
+      button: {
+        brand: {
+          bg: '#155C2F',
+          border: '#0E3B1F',
+          text: 'rgba(255, 255, 255)',
+          hoverBorder: '#072a15ff',
+          hoverText: 'rgba(255, 255, 255)',
+          hoverBg: '#072a15ff',
+          activeBorder: '#072a15ff',
+          activeText: 'rgba(255, 255, 255)',
+          activeBg: '#072a15ff'
+        },
+        alt: {
+          bg: '#484848',
+          text: '#f0eeee',
+          hoverBg: '#484848',
+          hoverText: '#f0eeee'
+        }
+      },
+      customBlock: {
+        info: {
+          bg: '#dbeafe',
+          border: '#1e40af',
+          text: '#1e40af',
+          textDeep: '#1e3a8a'
+        },
+        tip: {
+          bg: '#D8F8E4',
+          border: '#447A61',
+          text: '#2D6A58',
+          textDeep: '#166534'
+          },
+          warning: {
+            bg: '#FCEFC3',
+            border: '#9A8034',
+            text: '#9C701B',
+            textDeep: '#92400e'
+          },
+          danger: {
+            bg: '#FBE1E2',
+            border: '#B3565E',
+            text: '#912239',
+            textDeep: '#991b1b'
+          }
+      },
+      selection: {
+        bg: '#bfdbfe'
+      },
+      home: {
+        heroNameColor: 'transparent',
+        heroNameBackground: '-webkit-linear-gradient(120deg, #BD2F2F 30%, #f9fafb)',
+        heroImageBackground: 'linear-gradient(-45deg, #BD2F2F 50%, #f9fafb 50%)',
+        heroImageFilter: 'blur(44px)'
+      }
+    },
+    dark: {
+      brand: {
+        1: '#2CA03C',
+        2: '#22ff00ff',
+        3: '#5C151A',
+        soft: '#a200ffff'
+      },
+      bg: 'rgb(26, 26, 26)',
+      bgAlt: 'rgb(23, 23, 23)',
+      bgElv: 'rgba(23, 23, 23, 0.8)',
+      button: {
+        brand: {
+          bg: '#155C2F',
+          border: '#0E3B1F',
+          text: 'rgba(255, 255, 255)',
+          hoverBorder: '#072a15ff',
+          hoverText: 'rgba(255, 255, 255)',
+          hoverBg: '#072a15ff',
+          activeBorder: '#072a15ff',
+          activeText: 'rgba(255, 255, 255)',
+          activeBg: '#072a15ff'
+        },
+        alt: {
+          bg: '#484848',
+          text: '#f0eeee',
+          hoverBg: '#484848',
+          hoverText: '#f0eeee'
+        }
+      },
+      customBlock: {
+        info: {
+          bg: '#0c4a6e',
+          border: '#0284c7',
+          text: '#bae6fd',
+          textDeep: '#bae6fd'
+        },
+          tip: {
+            bg: '#0C2A20',
+            border: '#184633',
+            text: '#B0EBC9',
+            textDeep: '#166534'
+          },
+          warning: {
+            bg: '#403207',
+            border: '#7E6211',
+            text: '#F9DE88',
+            textDeep: '#92400e'
+          },
+          danger: {
+            bg: '#3F060A',
+            border: '#7C0F18',
+            text: '#F7C1BC',
+            textDeep: '#991b1b'
+          }
+      },
+      selection: {
+        bg: '#1e3a8a'
+      },
+      home: {
+        heroNameColor: 'transparent',
+        heroNameBackground: '-webkit-linear-gradient(120deg, #f9fafb 30%, #BD2F2F)',
+        heroImageBackground: 'linear-gradient(-45deg, #f9fafb 50%,#BD2F2F 50%)',
+        heroImageFilter: 'blur(44px)'
+      }
+    }
+  }
+}
diff --git a/docs/.vitepress/theme/themes/configs/dark.ts b/docs/.vitepress/theme/themes/configs/dark.ts
new file mode 100644
index 000000000..bf0b9acf4
--- /dev/null
+++ b/docs/.vitepress/theme/themes/configs/dark.ts
@@ -0,0 +1,161 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+import type { Theme } from '../types'
+
+export const darkTheme: Theme = {
+  name: 'Christmas',
+  displayName: 'Christmas',
+  preview: 'https://files.catbox.moe/inbi62.png',
+  modes: {
+    light: {
+      brand: {
+        1: '#BD2F2F',
+        2: '#22ff00ff',
+        3: '#155C2F',
+        soft: '#a200ffff'
+      },
+      bg: '#ffffffff',
+      bgAlt: '#f9fafb',
+      bgElv: 'rgba(255, 255, 255, 0.7)',
+      bgMark: 'rgb(232, 232, 232)',
+      text: {
+        1: '#1f2937',
+        2: '#4b5563',
+        3: '#353638ff'
+      },
+      button: {
+        brand: {
+          bg: '#155C2F',
+          border: '#0E3B1F',
+          text: 'rgba(255, 255, 255)',
+          hoverBorder: '#072a15ff',
+          hoverText: 'rgba(255, 255, 255)',
+          hoverBg: '#072a15ff',
+          activeBorder: '#072a15ff',
+          activeText: 'rgba(255, 255, 255)',
+          activeBg: '#072a15ff'
+        },
+        alt: {
+          bg: '#484848',
+          text: '#f0eeee',
+          hoverBg: '#484848',
+          hoverText: '#f0eeee'
+        }
+      },
+      customBlock: {
+        info: {
+          bg: '#dbeafe',
+          border: '#1e40af',
+          text: '#1e40af',
+          textDeep: '#1e3a8a'
+        },
+        tip: {
+          bg: '#D8F8E4',
+          border: '#447A61',
+          text: '#2D6A58',
+          textDeep: '#166534'
+          },
+          warning: {
+            bg: '#FCEFC3',
+            border: '#9A8034',
+            text: '#9C701B',
+            textDeep: '#92400e'
+          },
+          danger: {
+            bg: '#FBE1E2',
+            border: '#B3565E',
+            text: '#912239',
+            textDeep: '#991b1b'
+          }
+      },
+      selection: {
+        bg: '#bfdbfe'
+      },
+      home: {
+        heroNameColor: 'transparent',
+        heroNameBackground: '-webkit-linear-gradient(120deg, #BD2F2F 30%, #f9fafb)',
+        heroImageBackground: 'linear-gradient(-45deg, #BD2F2F 50%, #f9fafb 50%)',
+        heroImageFilter: 'blur(44px)'
+      }
+    },
+    dark: {
+      brand: {
+        1: '#2CA03C',
+        2: '#22ff00ff',
+        3: '#5C151A',
+        soft: '#a200ffff'
+      },
+      bg: 'rgb(26, 26, 26)',
+      bgAlt: 'rgb(23, 23, 23)',
+      bgElv: 'rgba(23, 23, 23, 0.8)',
+      button: {
+        brand: {
+          bg: '#155C2F',
+          border: '#0E3B1F',
+          text: 'rgba(255, 255, 255)',
+          hoverBorder: '#072a15ff',
+          hoverText: 'rgba(255, 255, 255)',
+          hoverBg: '#072a15ff',
+          activeBorder: '#072a15ff',
+          activeText: 'rgba(255, 255, 255)',
+          activeBg: '#072a15ff'
+        },
+        alt: {
+          bg: '#484848',
+          text: '#f0eeee',
+          hoverBg: '#484848',
+          hoverText: '#f0eeee'
+        }
+      },
+      customBlock: {
+        info: {
+          bg: '#0c4a6e',
+          border: '#0284c7',
+          text: '#bae6fd',
+          textDeep: '#bae6fd'
+        },
+          tip: {
+            bg: '#0C2A20',
+            border: '#184633',
+            text: '#B0EBC9',
+            textDeep: '#166534'
+          },
+          warning: {
+            bg: '#403207',
+            border: '#7E6211',
+            text: '#F9DE88',
+            textDeep: '#92400e'
+          },
+          danger: {
+            bg: '#3F060A',
+            border: '#7C0F18',
+            text: '#F7C1BC',
+            textDeep: '#991b1b'
+          }
+      },
+      selection: {
+        bg: '#1e3a8a'
+      },
+      home: {
+        heroNameColor: 'transparent',
+        heroNameBackground: '-webkit-linear-gradient(120deg, #f9fafb 30%, #BD2F2F)',
+        heroImageBackground: 'linear-gradient(-45deg, #f9fafb 50%,#BD2F2F 50%)',
+        heroImageFilter: 'blur(44px)'
+      }
+    }
+  }
+}
diff --git a/docs/.vitepress/theme/themes/configs/index.ts b/docs/.vitepress/theme/themes/configs/index.ts
new file mode 100644
index 000000000..a6df1af17
--- /dev/null
+++ b/docs/.vitepress/theme/themes/configs/index.ts
@@ -0,0 +1,25 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+import { christmasTheme } from './christmas'
+import { catppuccinTheme } from './catppuccin'
+import type { ThemeRegistry } from '../types'
+
+export const themeRegistry: ThemeRegistry = {
+  catppuccin: catppuccinTheme,
+  christmas: christmasTheme,
+}
+
+export { christmasTheme, catppuccinTheme }
diff --git a/docs/.vitepress/theme/themes/index.ts b/docs/.vitepress/theme/themes/index.ts
new file mode 100644
index 000000000..3fa0d637f
--- /dev/null
+++ b/docs/.vitepress/theme/themes/index.ts
@@ -0,0 +1,19 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+export * from './types'
+export * from './themeHandler'
+export * from './configs'
diff --git a/docs/.vitepress/theme/themes/themeHandler.ts b/docs/.vitepress/theme/themes/themeHandler.ts
new file mode 100644
index 000000000..f86b42094
--- /dev/null
+++ b/docs/.vitepress/theme/themes/themeHandler.ts
@@ -0,0 +1,395 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+import { ref, onMounted, computed } from 'vue'
+import type { DisplayMode, ThemeState, Theme, ModeColors } from './types'
+import { themeRegistry } from './configs'
+
+const STORAGE_KEY_THEME = 'vitepress-theme-name'
+const STORAGE_KEY_MODE = 'vitepress-display-mode'
+const STORAGE_KEY_AMOLED = 'vitepress-amoled-enabled'
+
+export class ThemeHandler {
+  private state = ref<ThemeState>({
+    currentTheme: 'christmas',
+    currentMode: 'light' as DisplayMode,
+    theme: themeRegistry.christmas
+  })
+  private amoledEnabled = ref(false)
+
+  constructor() {
+    this.initializeTheme()
+  }
+
+  private initializeTheme() {
+    if (typeof window === 'undefined') return
+
+    // Load saved preferences
+    const savedTheme = localStorage.getItem(STORAGE_KEY_THEME) || 'christmas'
+    const savedMode = localStorage.getItem(STORAGE_KEY_MODE) as DisplayMode | null
+    const savedAmoled = localStorage.getItem(STORAGE_KEY_AMOLED) === 'true'
+
+    // Set theme
+    if (themeRegistry[savedTheme]) {
+      this.state.value.currentTheme = savedTheme
+      this.state.value.theme = themeRegistry[savedTheme]
+    }
+
+    // Set amoled preference
+    this.amoledEnabled.value = savedAmoled
+
+    // Set mode
+    if (savedMode) {
+      this.state.value.currentMode = savedMode
+    } else {
+      // Detect system preference for initial mode
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
+      this.state.value.currentMode = prefersDark ? 'dark' : 'light'
+    }
+
+    this.applyTheme()
+
+    // Listen for system theme changes (only if user hasn't set a preference)
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+      if (!localStorage.getItem(STORAGE_KEY_MODE)) {
+        this.state.value.currentMode = e.matches ? 'dark' : 'light'
+        this.applyTheme()
+      }
+    })
+  }
+
+  private applyTheme() {
+    if (typeof document === 'undefined') return
+
+    const { currentMode, theme } = this.state.value
+    const modeColors = theme.modes[currentMode]
+
+    this.applyDOMClasses(currentMode)
+    this.applyCSSVariables(modeColors, theme)
+  }
+
+  private applyDOMClasses(mode: DisplayMode) {
+    const root = document.documentElement
+    
+    // Remove all mode classes
+    root.classList.remove('dark', 'light', 'amoled')
+    
+    // Add current mode class
+    root.classList.add(mode)
+    
+    // Add amoled class if enabled in dark mode
+    if (mode === 'dark' && this.amoledEnabled.value) {
+      root.classList.add('amoled')
+    }
+    
+    // Add dark class for backward compatibility with VitePress
+    if (mode === 'dark') {
+      root.classList.add('dark')
+    }
+  }
+
+  private applyCSSVariables(colors: ModeColors, theme: Theme) {
+    if (typeof document === 'undefined') return
+
+    const root = document.documentElement
+
+    // Clear ALL inline styles related to theming to ensure clean slate
+    const allStyleProps = Array.from(root.style)
+    allStyleProps.forEach(prop => {
+      if (prop.startsWith('--vp-')) {
+        root.style.removeProperty(prop)
+      }
+    })
+    let bgColor = colors.bg
+    let bgAltColor = colors.bgAlt
+    let bgElvColor = colors.bgElv
+    
+    if (this.state.value.currentMode === 'dark' && this.amoledEnabled.value) {
+      bgColor = '#000000'
+      bgAltColor = '#000000'
+      bgElvColor = 'rgba(0, 0, 0, 0.9)'
+    }
+
+    // Apply brand colors only if theme specifies them
+    // Otherwise, remove inline styles to let ColorPicker CSS take effect
+    if (colors.brand && (colors.brand[1] || colors.brand[2] || colors.brand[3] || colors.brand.soft)) {
+      if (colors.brand[1]) root.style.setProperty('--vp-c-brand-1', colors.brand[1])
+      if (colors.brand[2]) root.style.setProperty('--vp-c-brand-2', colors.brand[2])
+      if (colors.brand[3]) root.style.setProperty('--vp-c-brand-3', colors.brand[3])
+      if (colors.brand.soft) root.style.setProperty('--vp-c-brand-soft', colors.brand.soft)
+    } else {
+      // Remove inline brand color styles so ColorPicker CSS can apply
+      root.style.removeProperty('--vp-c-brand-1')
+      root.style.removeProperty('--vp-c-brand-2')
+      root.style.removeProperty('--vp-c-brand-3')
+      root.style.removeProperty('--vp-c-brand-soft')
+    }
+
+    // Apply background colors
+    root.style.setProperty('--vp-c-bg', bgColor)
+    root.style.setProperty('--vp-c-bg-alt', bgAltColor)
+    root.style.setProperty('--vp-c-bg-elv', bgElvColor)
+    if (colors.bgMark) {
+      root.style.setProperty('--vp-c-bg-mark', colors.bgMark)
+    }
+
+    // Apply text colors - always set them to ensure proper theme switching
+    if (colors.text) {
+      if (colors.text[1]) root.style.setProperty('--vp-c-text-1', colors.text[1])
+      if (colors.text[2]) root.style.setProperty('--vp-c-text-2', colors.text[2])
+      if (colors.text[3]) root.style.setProperty('--vp-c-text-3', colors.text[3])
+    } else {
+      // Remove inline styles if theme doesn't specify text colors
+      // This allows CSS variables from style.scss to take effect
+      root.style.removeProperty('--vp-c-text-1')
+      root.style.removeProperty('--vp-c-text-2')
+      root.style.removeProperty('--vp-c-text-3')
+    }
+
+    // Debug: log applied text color variables so we can inspect in console
+    try {
+      // eslint-disable-next-line no-console
+      console.log('[ThemeHandler] applied text vars', {
+        theme: theme.name,
+        mode: this.state.value.currentMode,
+        vp_text_1: root.style.getPropertyValue('--vp-c-text-1'),
+        vp_text_2: root.style.getPropertyValue('--vp-c-text-2'),
+        vp_text_3: root.style.getPropertyValue('--vp-c-text-3')
+      })
+    } catch (e) {
+      // ignore
+    }
+
+    // Apply button colors
+    root.style.setProperty('--vp-button-brand-bg', colors.button.brand.bg)
+    root.style.setProperty('--vp-button-brand-border', colors.button.brand.border)
+    root.style.setProperty('--vp-button-brand-text', colors.button.brand.text)
+    root.style.setProperty('--vp-button-brand-hover-border', colors.button.brand.hoverBorder)
+    root.style.setProperty('--vp-button-brand-hover-text', colors.button.brand.hoverText)
+    root.style.setProperty('--vp-button-brand-hover-bg', colors.button.brand.hoverBg)
+    root.style.setProperty('--vp-button-brand-active-border', colors.button.brand.activeBorder)
+    root.style.setProperty('--vp-button-brand-active-text', colors.button.brand.activeText)
+    root.style.setProperty('--vp-button-brand-active-bg', colors.button.brand.activeBg)
+    root.style.setProperty('--vp-button-alt-bg', colors.button.alt.bg)
+    root.style.setProperty('--vp-button-alt-text', colors.button.alt.text)
+    root.style.setProperty('--vp-button-alt-hover-bg', colors.button.alt.hoverBg)
+    root.style.setProperty('--vp-button-alt-hover-text', colors.button.alt.hoverText)
+
+    // Apply custom block colors
+    const blocks = ['info', 'tip', 'warning', 'danger'] as const
+    blocks.forEach((block) => {
+      const blockColors = colors.customBlock[block]
+      root.style.setProperty(`--vp-custom-block-${block}-bg`, blockColors.bg)
+      root.style.setProperty(`--vp-custom-block-${block}-border`, blockColors.border)
+      root.style.setProperty(`--vp-custom-block-${block}-text`, blockColors.text)
+      root.style.setProperty(`--vp-custom-block-${block}-text-deep`, blockColors.textDeep)
+    })
+
+    // Apply selection color
+    root.style.setProperty('--vp-c-selection-bg', colors.selection.bg)
+
+    // Apply home hero colors (if defined)
+    if (colors.home) {
+      root.style.setProperty('--vp-home-hero-name-color', colors.home.heroNameColor)
+      root.style.setProperty('--vp-home-hero-name-background', colors.home.heroNameBackground)
+      root.style.setProperty('--vp-home-hero-image-background-image', colors.home.heroImageBackground)
+      root.style.setProperty('--vp-home-hero-image-filter', colors.home.heroImageFilter)
+    } else {
+      // Remove home hero color styles if theme doesn't specify them
+      root.style.removeProperty('--vp-home-hero-name-color')
+      root.style.removeProperty('--vp-home-hero-name-background')
+      root.style.removeProperty('--vp-home-hero-image-background-image')
+      root.style.removeProperty('--vp-home-hero-image-filter')
+    }
+
+    // Apply fonts (if defined)
+    if (theme.fonts?.body) {
+      root.style.setProperty('--vp-font-family-base', theme.fonts.body)
+    } else {
+      root.style.removeProperty('--vp-font-family-base')
+    }
+    if (theme.fonts?.heading) {
+      root.style.setProperty('--vp-font-family-heading', theme.fonts.heading)
+    } else {
+      root.style.removeProperty('--vp-font-family-heading')
+    }
+
+    // Apply border radius (if defined)
+    if (theme.borderRadius) {
+      root.style.setProperty('--vp-border-radius', theme.borderRadius)
+    } else {
+      root.style.removeProperty('--vp-border-radius')
+    }
+
+    // Apply spacing (if defined)
+    if (theme.spacing) {
+      if (theme.spacing.small) root.style.setProperty('--vp-spacing-small', theme.spacing.small)
+      else root.style.removeProperty('--vp-spacing-small')
+      if (theme.spacing.medium) root.style.setProperty('--vp-spacing-medium', theme.spacing.medium)
+      else root.style.removeProperty('--vp-spacing-medium')
+      if (theme.spacing.large) root.style.setProperty('--vp-spacing-large', theme.spacing.large)
+      else root.style.removeProperty('--vp-spacing-large')
+    } else {
+      root.style.removeProperty('--vp-spacing-small')
+      root.style.removeProperty('--vp-spacing-medium')
+      root.style.removeProperty('--vp-spacing-large')
+    }
+
+    // Apply custom properties (if defined)
+    if (theme.customProperties) {
+      Object.entries(theme.customProperties).forEach(([key, value]) => {
+        root.style.setProperty(key, value)
+      })
+    }
+
+    // Apply custom logo (if defined)
+    if (theme.logo) {
+      root.style.setProperty('--vp-theme-logo', `url(${theme.logo})`)
+    } else {
+      root.style.removeProperty('--vp-theme-logo')
+    }
+  }
+
+  public setTheme(themeName: string) {
+    if (!themeRegistry[themeName]) {
+      console.warn(`Theme "${themeName}" not found. Using christmas theme.`)
+      themeName = 'christmas'
+    }
+
+    this.state.value.currentTheme = themeName
+    this.state.value.theme = themeRegistry[themeName]
+    localStorage.setItem(STORAGE_KEY_THEME, themeName)
+    this.applyTheme()
+    
+    // Force re-apply ColorPicker colors if theme doesn't specify brand colors
+    this.ensureColorPickerColors()
+  }
+
+  public setMode(mode: DisplayMode) {
+    this.state.value.currentMode = mode
+    localStorage.setItem(STORAGE_KEY_MODE, mode)
+    this.applyTheme()
+  }
+
+  public toggleMode() {
+    const currentMode = this.state.value.currentMode
+    
+    // Toggle between light and dark
+    const newMode: DisplayMode = currentMode === 'light' ? 'dark' : 'light'
+    
+    this.setMode(newMode)
+  }
+
+  public setAmoledEnabled(enabled: boolean) {
+    this.amoledEnabled.value = enabled
+    localStorage.setItem(STORAGE_KEY_AMOLED, enabled.toString())
+    this.applyTheme()
+  }
+
+  public getAmoledEnabled() {
+    return this.amoledEnabled.value
+  }
+
+  public toggleAmoled() {
+    this.setAmoledEnabled(!this.amoledEnabled.value)
+  }
+
+  public getAmoledEnabledRef() {
+    return this.amoledEnabled
+  }
+
+  private ensureColorPickerColors() {
+    // If theme doesn't specify brand colors, force ColorPicker to reapply its selection
+    const currentMode = this.state.value.currentMode
+    const modeColors = this.state.value.theme.modes[currentMode]
+    
+    if (!modeColors.brand || !modeColors.brand[1]) {
+      // Trigger a custom event that ColorPicker can listen to
+      if (typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent('theme-changed-apply-colors'))
+      }
+    }
+  }
+
+  public getState() {
+    return this.state
+  }
+
+  public getMode() {
+    return this.state.value.currentMode
+  }
+
+  public getTheme() {
+    return this.state.value.currentTheme
+  }
+
+  public getCurrentTheme() {
+    return this.state.value.theme
+  }
+
+  public getAvailableThemes() {
+    return Object.keys(themeRegistry).map(key => ({
+      name: key,
+      displayName: themeRegistry[key].displayName
+    }))
+  }
+
+  public isDarkMode() {
+    const mode = this.state.value.currentMode
+    return mode === 'dark'
+  }
+
+  public isAmoledMode() {
+    return this.state.value.currentMode === 'dark' && this.amoledEnabled.value
+  }
+}
+
+// Global theme handler instance
+let themeHandlerInstance: ThemeHandler | null = null
+
+export function useThemeHandler() {
+  if (!themeHandlerInstance) {
+    themeHandlerInstance = new ThemeHandler()
+  }
+  return themeHandlerInstance
+}
+
+// Composable for use in Vue components
+export function useTheme() {
+  const handler = useThemeHandler()
+  const state = handler.getState()
+
+  onMounted(() => {
+    // Ensure theme is applied on mount
+    handler.setMode(handler.getMode())
+  })
+
+  return {
+    mode: computed(() => state.value.currentMode),
+    themeName: computed(() => state.value.currentTheme),
+    theme: computed(() => state.value.theme),
+    setMode: (mode: DisplayMode) => handler.setMode(mode),
+    setTheme: (themeName: string) => handler.setTheme(themeName),
+    toggleMode: () => handler.toggleMode(),
+    getAvailableThemes: () => handler.getAvailableThemes(),
+    isDarkMode: () => handler.isDarkMode(),
+    isAmoledMode: () => handler.isAmoledMode(),
+    amoledEnabled: handler.getAmoledEnabledRef(),
+    setAmoledEnabled: (enabled: boolean) => handler.setAmoledEnabled(enabled),
+    toggleAmoled: () => handler.toggleAmoled(),
+    state
+  }
+}
\ No newline at end of file
diff --git a/docs/.vitepress/theme/themes/types.ts b/docs/.vitepress/theme/themes/types.ts
new file mode 100644
index 000000000..cc997412c
--- /dev/null
+++ b/docs/.vitepress/theme/themes/types.ts
@@ -0,0 +1,134 @@
+/**
+ *  Copyright (c) 2025 taskylizard. Apache License 2.0.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+export type DisplayMode = 'light' | 'dark'
+
+export interface ModeColors {
+  // Brand colors (optional - if not specified, ColorPicker values are used)
+  brand?: {
+    1?: string
+    2?: string
+    3?: string
+    soft?: string
+  }
+
+  // Background colors
+  bg: string
+  bgAlt: string
+  bgElv: string
+  bgMark?: string
+
+  // Text colors (optional - if not specified, VitePress defaults are used)
+  text?: {
+    1?: string
+    2?: string
+    3?: string
+  }
+
+  // Button colors
+  button: {
+    brand: {
+      bg: string
+      border: string
+      text: string
+      hoverBorder: string
+      hoverText: string
+      hoverBg: string
+      activeBorder: string
+      activeText: string
+      activeBg: string
+    }
+    alt: {
+      bg: string
+      text: string
+      hoverBg: string
+      hoverText: string
+    }
+  }
+
+  // Custom blocks
+  customBlock: {
+    info: {
+      bg: string
+      border: string
+      text: string
+      textDeep: string
+    }
+    tip: {
+      bg: string
+      border: string
+      text: string
+      textDeep: string
+    }
+    warning: {
+      bg: string
+      border: string
+      text: string
+      textDeep: string
+    }
+    danger: {
+      bg: string
+      border: string
+      text: string
+      textDeep: string
+    }
+  }
+
+  // Selection color
+  selection: {
+    bg: string
+  }
+
+  // Home hero
+  home?: {
+    heroNameColor: string
+    heroNameBackground: string
+    heroImageBackground: string
+    heroImageFilter: string
+  }
+}
+
+export interface Theme {
+  name: string
+  displayName: string
+  preview?: string // URL or path to theme preview image
+  logo?: string // URL or path to custom logo
+  modes: {
+    light: ModeColors
+    dark: ModeColors
+  }
+  fonts?: {
+    body?: string
+    heading?: string
+  }
+  borderRadius?: string
+  spacing?: {
+    small?: string
+    medium?: string
+    large?: string
+  }
+  customProperties?: Record<string, string>
+}
+
+export interface ThemeRegistry {
+  [themeName: string]: Theme
+}
+
+export interface ThemeState {
+  currentTheme: string
+  currentMode: DisplayMode
+  theme: Theme
+}