@agentscope-ai/design 1.0.22 → 1.0.23-beta.1767091755248

package/lib/antd/themes/generateTheme.d.ts

@@ -1,39 +1,61 @@
 /**
- * 主题生成器 - Theme Generator
+ * Theme Generator
 
- * 核心功能：
- * 1. 颜色空间转换（HEX/RGB/HSL）
- * 2. 颜色调整和生成
- * 3. 完整主题配置生成（支持浅色/暗色模式）
+ * Generates a complete theme configuration based on input primary color, background color, and text color.
+ * Supports both light and dark modes.
  *
- * 设计原则（参考 Radix Colors）：
- * - 浅色模式：背景 95-99% 亮度，边框 80-90% 亮度，文本 15-25% 亮度
- * - 暗色模式：背景 0-10% 亮度，边框使用透明度，文本 85-95% 亮度
- * - 状态色和装饰色在暗色模式下使用预设优化值
+ * ## Core Features
+ * 1. **Color Space Conversion**: HEX ↔ RGB ↔ HSL conversions
+ * 2. **Color Adjustment and Generation**: Adjust brightness and saturation based on HSL color space
+ * 3. **Complete Theme Configuration**: Generates a complete theme configuration object including
+ *    primary colors, text colors, background colors, border colors, fill colors, status colors,
+ *    decorative colors, shadows, etc.
  *
- * 生成规则：
- * - 主色 (Primary)：从输入的主色生成，暗色模式自动调整亮度
- * - 背景色系：基于 bgBase 生成，保持色相统一
- * - 文本色系：基于 textBase 生成，保持色相统一
- * - 边框色系：基于 bgBase 生成，饱和度提高以增强可见度
- * - 填充色系：暗色模式基于文本色+透明度，浅色模式基于背景色
- * - 状态色/装饰色/阴影：暗色模式使用预设优化值，浅色模式使用配置文件
+ * ## Design Principles
+ * ### Light Mode
+ * - Background: 95-99% lightness
+ * - Border: 80-90% lightness
+ * - Text: 15-25% lightness
+ *
+ * ### Dark Mode
+ * - Background: 0-10% lightness
+ * - Border: Uses transparency to enhance layering
+ * - Text: 85-95% lightness
+ * - Status colors and decorative colors: Use preset optimized values
+ *
+ * ## Generation Rules
+ * - **Primary Color**: Generated from input primary color, automatically adjusts brightness in dark mode for readability
+ * - **Background Color System**: Generated based on bgBase, maintains consistent hue
+ * - **Text Color System**: Generated based on textBase, uses transparency to achieve different levels
+ * - **Border Color System**: Generated based on bgBase, increases saturation to enhance visibility
+ * - **Fill Color System**: Dark mode uses text color + transparency, light mode uses background color
+ * - **Status Colors/Decorative Colors/Shadows**: Dark mode uses preset optimized values, light mode uses configuration file
  */
 /**
- * 生成完整主题
- * @param {string} primaryHex - 主色调
- * @param {string} bgBaseHex - 背景基础色
- * @param {string} textBaseHex - 文本基础色
- * @param {boolean} darkMode - 是否为暗色模式
- * @returns {Object} 完整的主题配置对象
+ * Generates complete theme configuration
+ *
+ * Generates a complete theme configuration object based on input primary color, background color,
+ * text color, and mode (light/dark). The theme configuration includes: primary colors, text colors,
+ * background colors, border colors, fill colors, status colors, decorative colors, shadows, etc.
+ *
+ * @param {Object} props - Theme generation parameters
+ * @param {string} props.primaryHex - Primary color HEX value (required)
+ * @param {string} [props.bgBaseHex] - Background base color HEX value, uses default if not provided (light: #ffffff, dark: #000000)
+ * @param {string} [props.textBaseHex] - Text base color HEX value, uses default if not provided (light: #1a1a1a, dark: #E7E7ED)
+ * @param {boolean} [props.darkMode=false] - Whether it is dark mode
+ * @returns {Object | null} Complete theme configuration object, returns null if parameters are invalid
  */
 interface GenerateThemeProps {
+    /** Primary color HEX value */
     primaryHex: string;
+    /** Background base color HEX value */
     bgBaseHex?: string;
+    /** Text base color HEX value */
     textBaseHex?: string;
+    /** Whether it is dark mode */
     darkMode: boolean;
 }
-declare const generateTheme: ({ primaryHex, bgBaseHex, textBaseHex, darkMode, }: GenerateThemeProps) => {
+declare const generateTheme: (config: GenerateThemeProps) => {
     borderRadiusXS: number;
     borderRadiusSM: number;
     borderRadius: number;
@@ -51,6 +73,7 @@ declare const generateTheme: ({ primaryHex, bgBaseHex, textBaseHex, darkMode, }:
     colorPrimaryText: any;
     colorPrimaryTextHover: any;
     colorPrimaryTextActive: any;
+    colorTextOnPrimary: string;
     colorTextBase: string;
     colorText: string;
     colorTextSecondary: string;
@@ -60,7 +83,7 @@ declare const generateTheme: ({ primaryHex, bgBaseHex, textBaseHex, darkMode, }:
     colorBgBase: string;
     colorBgContainer: any;
     colorBgElevated: any;
-    colorBgLayout: any;
+    colorBgLayout: string;
     colorBgSpotlight: string;
     colorBgMask: string;
     colorBorder: any;

package/lib/antd/themes/generateTheme.js

@@ -1,32 +1,46 @@
 /**
- * 主题生成器 - Theme Generator
+ * Theme Generator
 
- * 核心功能：
- * 1. 颜色空间转换（HEX/RGB/HSL）
- * 2. 颜色调整和生成
- * 3. 完整主题配置生成（支持浅色/暗色模式）
+ * Generates a complete theme configuration based on input primary color, background color, and text color.
+ * Supports both light and dark modes.
  *
- * 设计原则（参考 Radix Colors）：
- * - 浅色模式：背景 95-99% 亮度，边框 80-90% 亮度，文本 15-25% 亮度
- * - 暗色模式：背景 0-10% 亮度，边框使用透明度，文本 85-95% 亮度
- * - 状态色和装饰色在暗色模式下使用预设优化值
+ * ## Core Features
+ * 1. **Color Space Conversion**: HEX ↔ RGB ↔ HSL conversions
+ * 2. **Color Adjustment and Generation**: Adjust brightness and saturation based on HSL color space
+ * 3. **Complete Theme Configuration**: Generates a complete theme configuration object including
+ *    primary colors, text colors, background colors, border colors, fill colors, status colors,
+ *    decorative colors, shadows, etc.
  *
- * 生成规则：
- * - 主色 (Primary)：从输入的主色生成，暗色模式自动调整亮度
- * - 背景色系：基于 bgBase 生成，保持色相统一
- * - 文本色系：基于 textBase 生成，保持色相统一
- * - 边框色系：基于 bgBase 生成，饱和度提高以增强可见度
- * - 填充色系：暗色模式基于文本色+透明度，浅色模式基于背景色
- * - 状态色/装饰色/阴影：暗色模式使用预设优化值，浅色模式使用配置文件
+ * ## Design Principles
+ * ### Light Mode
+ * - Background: 95-99% lightness
+ * - Border: 80-90% lightness
+ * - Text: 15-25% lightness
+ *
+ * ### Dark Mode
+ * - Background: 0-10% lightness
+ * - Border: Uses transparency to enhance layering
+ * - Text: 85-95% lightness
+ * - Status colors and decorative colors: Use preset optimized values
+ *
+ * ## Generation Rules
+ * - **Primary Color**: Generated from input primary color, automatically adjusts brightness in dark mode for readability
+ * - **Background Color System**: Generated based on bgBase, maintains consistent hue
+ * - **Text Color System**: Generated based on textBase, uses transparency to achieve different levels
+ * - **Border Color System**: Generated based on bgBase, increases saturation to enhance visibility
+ * - **Fill Color System**: Dark mode uses text color + transparency, light mode uses background color
+ * - **Status Colors/Decorative Colors/Shadows**: Dark mode uses preset optimized values, light mode uses configuration file
  */
 
 import themeDataDark from "./bailianDarkTheme.json";
 import themeData from "./bailianTheme.json";
 
-// ==================== 颜色转换工具函数 ====================
+// ==================== Color Conversion Utility Functions ====================
 
 /**
- * HEX 转 RGB
+ * Converts HEX color value to RGB object
+ * @param {string} hex - HEX color value (e.g., '#FF0000' or 'FF0000')
+ * @returns {{r: number, g: number, b: number} | null} RGB object, returns null if conversion fails
  */
 var hexToRgb = function hexToRgb(hex) {
   var result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
@@ -38,21 +52,29 @@ var hexToRgb = function hexToRgb(hex) {
 };
 
 /**
- * RGB 转 HEX
+ * Converts RGB values to HEX color string
+ * @param {number} r - Red component (0-255)
+ * @param {number} g - Green component (0-255)
+ * @param {number} b - Blue component (0-255)
+ * @returns {string} HEX color string (e.g., '#FF0000')
  */
 var rgbToHex = function rgbToHex(r, g, b) {
   return '#' + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1).toUpperCase();
 };
 
 /**
- * RGB 转 HSL
+ * Converts RGB values to HSL object
+ * @param {number} r - Red component (0-255)
+ * @param {number} g - Green component (0-255)
+ * @param {number} b - Blue component (0-255)
+ * @returns {{h: number, s: number, l: number}} HSL object (h: 0-360, s: 0-100, l: 0-100)
  */
 var rgbToHsl = function rgbToHsl(r, g, b) {
-  r /= 255;
-  g /= 255;
-  b /= 255;
-  var max = Math.max(r, g, b),
-    min = Math.min(r, g, b);
+  var rr = r / 255;
+  var gg = g / 255;
+  var bb = b / 255;
+  var max = Math.max(rr, gg, bb),
+    min = Math.min(rr, gg, bb);
   var h,
     s,
     l = (max + min) / 2;
@@ -62,14 +84,14 @@ var rgbToHsl = function rgbToHsl(r, g, b) {
     var d = max - min;
     s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
     switch (max) {
-      case r:
-        h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+      case rr:
+        h = ((gg - bb) / d + (gg < bb ? 6 : 0)) / 6;
         break;
-      case g:
-        h = ((b - r) / d + 2) / 6;
+      case gg:
+        h = ((bb - rr) / d + 2) / 6;
         break;
-      case b:
-        h = ((r - g) / d + 4) / 6;
+      case bb:
+        h = ((rr - gg) / d + 4) / 6;
         break;
       default:
         h = 0;
@@ -83,29 +105,34 @@ var rgbToHsl = function rgbToHsl(r, g, b) {
 };
 
 /**
- * HSL 转 RGB
+ * Converts HSL values to RGB object
+ * @param {number} h - Hue (0-360)
+ * @param {number} s - Saturation (0-100)
+ * @param {number} l - Lightness (0-100)
+ * @returns {{r: number, g: number, b: number}} RGB object (r, g, b: 0-255)
  */
 var hslToRgb = function hslToRgb(h, s, l) {
-  h /= 360;
-  s /= 100;
-  l /= 100;
+  var hh = h / 360;
+  var ss = s / 100;
+  var ll = l / 100;
   var r, g, b;
-  if (s === 0) {
-    r = g = b = l;
+  if (ss === 0) {
+    r = g = b = ll;
   } else {
     var hue2rgb = function hue2rgb(p, q, t) {
-      if (t < 0) t += 1;
-      if (t > 1) t -= 1;
-      if (t < 1 / 6) return p + (q - p) * 6 * t;
-      if (t < 1 / 2) return q;
-      if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+      var tt = t;
+      if (tt < 0) tt += 1;
+      if (tt > 1) tt -= 1;
+      if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+      if (tt < 1 / 2) return q;
+      if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
       return p;
     };
-    var q = l < 0.5 ? l * (1 + s) : l + s - l * s;
-    var p = 2 * l - q;
-    r = hue2rgb(p, q, h + 1 / 3);
-    g = hue2rgb(p, q, h);
-    b = hue2rgb(p, q, h - 1 / 3);
+    var q = ll < 0.5 ? ll * (1 + ss) : ll + ss - ll * ss;
+    var p = 2 * ll - q;
+    r = hue2rgb(p, q, hh + 1 / 3);
+    g = hue2rgb(p, q, hh);
+    b = hue2rgb(p, q, hh - 1 / 3);
   }
   return {
     r: Math.round(r * 255),
@@ -114,10 +141,14 @@ var hslToRgb = function hslToRgb(h, s, l) {
   };
 };
 
-// ==================== 颜色调整函数 ====================
+// ==================== Color Adjustment Functions ====================
 
 /**
- * 调整颜色的亮度和饱和度（相对调整）
+ * Adjusts color brightness and saturation relatively
+ * @param {string} hex - Original HEX color value
+ * @param {number} lightness - Lightness adjustment value (positive for lighter, negative for darker)
+ * @param {number} [saturation=0] - Saturation adjustment value (positive to increase, negative to decrease)
+ * @returns {string} Adjusted HEX color value
  */
 var adjustColor = function adjustColor(hex, lightness) {
   var saturation = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0;
@@ -131,7 +162,11 @@ var adjustColor = function adjustColor(hex, lightness) {
 };
 
 /**
- * 生成指定亮度的颜色（绝对值）
+ * Generates a color with specified lightness (absolute value)
+ * @param {string} hex - Base HEX color value
+ * @param {number} targetLightness - Target lightness value (0-100)
+ * @param {number | null} [targetSaturation=null] - Target saturation value (0-100), keeps original saturation if null
+ * @returns {string} Generated HEX color value
  */
 var generateColorWithLightness = function generateColorWithLightness(hex, targetLightness) {
   var targetSaturation = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
@@ -147,7 +182,11 @@ var generateColorWithLightness = function generateColorWithLightness(hex, target
 };
 
 /**
- * 基于基础色生成色阶（保持色相，调整亮度和饱和度）
+ * Generates color scale based on base color (maintains hue, adjusts lightness and saturation)
+ * @param {string} baseHex - Base HEX color value
+ * @param {number} lightness - Target lightness value (0-100)
+ * @param {number} [saturationMultiplier=1] - Saturation multiplier (1 to keep original saturation)
+ * @returns {string} Generated HEX color value
  */
 var generateColorScale = function generateColorScale(baseHex, lightness) {
   var saturationMultiplier = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 1;
@@ -160,30 +199,34 @@ var generateColorScale = function generateColorScale(baseHex, lightness) {
   return rgbToHex(newRgb.r, newRgb.g, newRgb.b);
 };
 
-// ==================== 主题生成函数 ====================
+// ==================== Theme Generation Function ====================
 
 /**
- * 生成完整主题
- * @param {string} primaryHex - 主色调
- * @param {string} bgBaseHex - 背景基础色
- * @param {string} textBaseHex - 文本基础色
- * @param {boolean} darkMode - 是否为暗色模式
- * @returns {Object} 完整的主题配置对象
+ * Generates complete theme configuration
+ * 
+ * Generates a complete theme configuration object based on input primary color, background color,
+ * text color, and mode (light/dark). The theme configuration includes: primary colors, text colors,
+ * background colors, border colors, fill colors, status colors, decorative colors, shadows, etc.
+ * 
+ * @param {Object} props - Theme generation parameters
+ * @param {string} props.primaryHex - Primary color HEX value (required)
+ * @param {string} [props.bgBaseHex] - Background base color HEX value, uses default if not provided (light: #ffffff, dark: #000000)
+ * @param {string} [props.textBaseHex] - Text base color HEX value, uses default if not provided (light: #1a1a1a, dark: #E7E7ED)
+ * @param {boolean} [props.darkMode=false] - Whether it is dark mode
+ * @returns {Object | null} Complete theme configuration object, returns null if parameters are invalid
  */
 
-var generateTheme = function generateTheme(_ref) {
-  var primaryHex = _ref.primaryHex,
-    bgBaseHex = _ref.bgBaseHex,
-    textBaseHex = _ref.textBaseHex,
-    _ref$darkMode = _ref.darkMode,
-    darkMode = _ref$darkMode === void 0 ? false : _ref$darkMode;
-  bgBaseHex = bgBaseHex || (darkMode ? '#000000' : '#ffffff');
-  textBaseHex = textBaseHex || (darkMode ? '#E7E7ED' : '#1a1a1a');
+var generateTheme = function generateTheme(config) {
+  var primaryHex = config.primaryHex,
+    _config$darkMode = config.darkMode,
+    darkMode = _config$darkMode === void 0 ? false : _config$darkMode;
+  var bgBaseHex = config.bgBaseHex || (darkMode ? '#000000' : '#ffffff');
+  var textBaseHex = config.textBaseHex || (darkMode ? '#E7E7ED' : '#1a1a1a');
   var rgb = hexToRgb(primaryHex);
   if (!rgb) return null;
   var hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
 
-  // 获取背景色和文本色的 RGB 和 HSL
+  // Get RGB and HSL values for background and text colors
   var bgBaseRgb = hexToRgb(bgBaseHex);
   var textBaseRgb = hexToRgb(textBaseHex);
   var bgBaseHsl = bgBaseRgb ? rgbToHsl(bgBaseRgb.r, bgBaseRgb.g, bgBaseRgb.b) : {
@@ -192,22 +235,30 @@ var generateTheme = function generateTheme(_ref) {
     l: darkMode ? 5 : 99
   };
 
-  // 参考 Radix Colors 的色阶系统
-  // 浅色模式：
-  //   Scale 1-3: 背景色 (95-99% 亮度)
-  //   Scale 6-8: 边框色、填充色 (80-90% 亮度)
-  //   Scale 11-12: 文本色 (15-25% 亮度)
-  // 暗色模式：
-  //   Scale 1-3: 背景色 (0-10% 亮度)
-  //   Scale 6-8: 边框色、填充色 (带透明度)
-  //   Scale 11-12: 文本色 (85-95% 亮度)
+  // Light mode:
+  //   Scale 1-3: Background colors (95-99% lightness)
+  //   Scale 6-8: Border colors, fill colors (80-90% lightness)
+  //   Scale 11-12: Text colors (15-25% lightness)
+  // Dark mode:
+  //   Scale 1-3: Background colors (0-10% lightness)
+  //   Scale 6-8: Border colors, fill colors (with transparency)
+  //   Scale 11-12: Text colors (85-95% lightness)
 
-  var baseSaturation = Math.max(8, Math.min(hsl.s, 40)); // 主色背景（如 primaryBg）使用低饱和度
-  var borderSaturation = Math.max(12, Math.min(hsl.s * 0.6, 35)); // 主色边框（如 primaryBorder）使用的饱和度
+  // Calculate saturation values related to primary color
+  // Primary color background uses low saturation to ensure background is not too vibrant
+  var baseSaturation = Math.max(8, Math.min(hsl.s, 40));
+  // Primary color border uses medium saturation to enhance visibility
+  var borderSaturation = Math.max(12, Math.min(hsl.s * 0.6, 35));
 
-  // 生成主色相关的颜色
+  // Calculate actual generated primary color (considering dark mode adjustment)
+  var actualPrimaryHex = darkMode ? generateColorWithLightness(primaryHex, Math.max(hsl.l - 5, 42), hsl.s * 0.95) : primaryHex;
+  // Get actual primary color lightness to determine text on primary color
+  var actualPrimaryRgb = hexToRgb(actualPrimaryHex);
+  var actualPrimaryHsl = actualPrimaryRgb ? rgbToHsl(actualPrimaryRgb.r, actualPrimaryRgb.g, actualPrimaryRgb.b) : hsl;
+
+  // Generate complete theme configuration object
   var theme = {
-    // 保留边框圆角配置
+    // ========== Border Radius Configuration ==========
     borderRadiusXS: themeData.borderRadiusXS,
     borderRadiusSM: themeData.borderRadiusSM,
     borderRadius: themeData.borderRadius,
@@ -215,54 +266,64 @@ var generateTheme = function generateTheme(_ref) {
     borderRadiusXL: themeData.borderRadiusXL,
     borderRadiusFull: themeData.borderRadiusFull,
     wireframe: themeData.wireframe,
-    // 主色系 - 暗色模式下生成适配的主色
+    // ========== Primary Color System ==========
+    // Automatically adjusts primary color brightness in dark mode to ensure readability
     colorPrimary: darkMode ? generateColorWithLightness(primaryHex, Math.max(hsl.l - 5, 42), hsl.s * 0.95) : primaryHex,
     colorPrimaryHover: darkMode ? generateColorWithLightness(primaryHex, Math.min(hsl.l + 10, 55), hsl.s * 0.95) : adjustColor(primaryHex, hsl.l < 50 ? 10 : -10, 0),
     colorPrimaryActive: darkMode ? generateColorWithLightness(primaryHex, Math.max(hsl.l - 10, 35), hsl.s * 0.95) : adjustColor(primaryHex, hsl.l < 50 ? -10 : -20, 0),
-    colorPrimaryBg: darkMode ? generateColorWithLightness(primaryHex, 13, baseSaturation * 0.6) // 暗色模式：深色背景
+    colorPrimaryBg: darkMode ? generateColorWithLightness(primaryHex, 13, baseSaturation * 0.6) // Dark mode: dark background (13% lightness)
     : generateColorWithLightness(primaryHex, 96, baseSaturation * 0.8),
-    // 浅色模式：浅色背景
+    // Light mode: light background (96% lightness)
     colorPrimaryBgHover: darkMode ? generateColorWithLightness(primaryHex, 13, baseSaturation * 0.6) : generateColorWithLightness(primaryHex, 94, baseSaturation),
     colorPrimaryBorder: darkMode ? generateColorWithLightness(primaryHex, 17, borderSaturation * 0.8) : generateColorWithLightness(primaryHex, 88, borderSaturation * 0.8),
     colorPrimaryBorderHover: darkMode ? generateColorWithLightness(primaryHex, 22, borderSaturation) : generateColorWithLightness(primaryHex, 82, borderSaturation),
     colorPrimaryText: darkMode ? generateColorWithLightness(primaryHex, Math.max(hsl.l - 5, 42), hsl.s * 0.95) : primaryHex,
     colorPrimaryTextHover: darkMode ? generateColorWithLightness(primaryHex, Math.min(hsl.l + 10, 55), hsl.s * 0.95) : adjustColor(primaryHex, hsl.l < 50 ? 10 : -10, 0),
     colorPrimaryTextActive: darkMode ? generateColorWithLightness(primaryHex, Math.max(hsl.l - 10, 35), hsl.s * 0.95) : adjustColor(primaryHex, hsl.l < 50 ? -10 : -20, 0),
-    // 文本颜色 - 基于 textBase 的色相生成（Scale 11-12）
+    // Text color displayed on primary color background: automatically selects black or white based on actual primary color lightness
+    // Light theme colors (lightness > 50) use black text, dark theme colors (lightness <= 50) use white text
+    colorTextOnPrimary: actualPrimaryHsl.l > 50 ? '#000000' : '#ffffff',
+    // ========== Text Color System ==========
+    // Generated based on textBase hue, uses transparency to achieve different levels
     colorTextBase: textBaseHex,
     colorText: "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.88)"),
     colorTextSecondary: "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.65)"),
     colorTextTertiary: "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.45)"),
     colorTextQuaternary: "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.25)"),
     colorTextWhite: '#fff',
-    // 背景颜色 - 基于 bgBase 的色相生成 (Scale 1-3)
+    // ========== Background Color System ==========
+    // Generated based on bgBase hue, maintains consistent hue
     colorBgBase: bgBaseHex,
-    colorBgContainer: darkMode ? generateColorScale(bgBaseHex, Math.min(bgBaseHsl.l + 3, 8), 1.2) // 暗色：稍微亮一点 (5-8%)
-    : generateColorScale(bgBaseHex, Math.min(bgBaseHsl.l + 1, 99), 0.8),
-    // 浅色：稍微深一点
-    colorBgElevated: darkMode ? generateColorScale(bgBaseHex, Math.min(bgBaseHsl.l + 3, 8), 1.2) // 暗色：与 container 相同
+    colorBgContainer: darkMode ? generateColorScale(bgBaseHex, Math.min(bgBaseHsl.l + hsl.l * 0.08, 12), 1.2) // Dark mode: dynamically adjusts based on primary color lightness (brighter primary = brighter container, max 12% lightness)
+    : generateColorScale(bgBaseHex, Math.max(100 - hsl.l * 0.05, 96), 0.8),
+    // Light mode: darker primary = grayer container; lighter primary = closer to white (min 96% lightness)
+    colorBgElevated: darkMode ? generateColorScale(bgBaseHex, Math.min(bgBaseHsl.l + 3, 8), 1.2) // Dark mode: slightly brighter than container (max 8% lightness)
     : bgBaseHex,
-    // 浅色：使用 bgBase 本身
-    colorBgLayout: darkMode ? generateColorScale(bgBaseHex, Math.min(bgBaseHsl.l + 3, 8), 1.2) // 暗色：与 container 相同
-    : generateColorScale(bgBaseHex, Math.max(bgBaseHsl.l - 2, 96), 1.2),
-    // 浅色：稍微深一点
+    // Light mode: uses bgBase itself (usually white)
+    colorBgLayout: bgBaseHex,
+    // Keeps consistent with bgBase
     colorBgSpotlight: darkMode ? "rgba(".concat(hexToRgb(generateColorScale(bgBaseHex, 28, 1.2)).r, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 28, 1.2)).g, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 28, 1.2)).b, ", 0.85)") : "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.85)"),
     colorBgMask: darkMode ? "rgba(".concat(bgBaseRgb.r, ", ").concat(bgBaseRgb.g, ", ").concat(bgBaseRgb.b, ", 0.8)") : "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.45)"),
-    // 边框和填充 - 暗色模式使用透明度，浅色模式使用实色
-    colorBorder: darkMode ? "rgba(".concat(hexToRgb(generateColorScale(bgBaseHex, 28, 2)).r, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 28, 2)).g, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 28, 2)).b, ", 0.8)") // 暗色：中等亮度 + 透明度
+    // ========== Border and Fill Color System ==========
+    // Dark mode uses transparency to enhance layering, light mode uses solid colors
+    colorBorder: darkMode ? "rgba(".concat(hexToRgb(generateColorScale(bgBaseHex, 28, 2)).r, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 28, 2)).g, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 28, 2)).b, ", 0.8)") // Dark mode: medium lightness (28%) + 80% opacity
     : generateColorScale(bgBaseHex, 81, 2.5),
-    // 浅色：实色边框
+    // Light mode: solid border (81% lightness)
     colorBorderSecondary: darkMode ? "rgba(".concat(hexToRgb(generateColorScale(bgBaseHex, 22, 1.8)).r, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 22, 1.8)).g, ", ").concat(hexToRgb(generateColorScale(bgBaseHex, 22, 1.8)).b, ", 0.8)") : generateColorScale(bgBaseHex, 88, 2),
-    colorFill: darkMode ? "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.18)") // 暗色：基于文本色的透明填充
+    colorFill: darkMode ? "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.18)") // Dark mode: transparent fill based on text color
     : generateColorScale(bgBaseHex, 81, 2.5) + '5c',
     colorFillSecondary: darkMode ? "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.12)") : generateColorScale(bgBaseHex, 81, 2.5) + '33',
     colorFillTertiary: darkMode ? "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.08)") : generateColorScale(bgBaseHex, 81, 2.5) + '26',
     colorFillQuaternary: darkMode ? "rgba(".concat(textBaseRgb.r, ", ").concat(textBaseRgb.g, ", ").concat(textBaseRgb.b, ", 0.04)") : generateColorScale(bgBaseHex, 81, 2.5) + '1a',
-    colorFillDisable: darkMode ? generateColorScale(textBaseHex, 55, 0.8) // 暗色：中等亮度的灰色
+    colorFillDisable: darkMode ? generateColorScale(textBaseHex, 55, 0.8) // Dark mode: medium lightness gray (55% lightness)
     : generateColorScale(bgBaseHex, 86, 1.8),
-    // 链接色 - 暗色模式下生成适配的颜色
+    // Light mode: light gray (86% lightness)
+
+    // ========== Link Color ==========
+    // Automatically adjusts brightness in dark mode to ensure readability
     colorLink: darkMode ? generateColorWithLightness(primaryHex, Math.max(hsl.l - 5, 42), hsl.s * 0.95) : primaryHex,
-    // 状态色 - 暗色模式下使用预设值
+    // ========== Status Colors ==========
+    // Dark mode uses preset optimized values, light mode uses values from configuration file
     colorInfo: darkMode ? themeDataDark.colorInfo : themeData.colorInfo,
     colorInfoHover: darkMode ? themeDataDark.colorInfoHover : themeData.colorInfoHover,
     colorInfoText: darkMode ? themeDataDark.colorInfoText : themeData.colorInfoText,
@@ -288,7 +349,8 @@ var generateTheme = function generateTheme(_ref) {
     colorErrorBgHover: darkMode ? themeDataDark.colorErrorBgHover : themeData.colorErrorBgHover,
     colorErrorBorder: darkMode ? themeDataDark.colorErrorBorder : themeData.colorErrorBorder,
     colorErrorBorderHover: darkMode ? themeDataDark.colorErrorBorderHover : themeData.colorErrorBorderHover,
-    // 装饰色 - 暗色模式下使用预设值
+    // ========== Decorative Colors ==========
+    // Dark mode uses preset optimized values, light mode uses values from configuration file
     colorPurple: darkMode ? themeDataDark.colorPurple : themeData.colorPurple,
     colorPurpleHover: darkMode ? themeDataDark.colorPurpleHover : themeData.colorPurpleHover,
     colorPurpleBg: darkMode ? themeDataDark.colorPurpleBg : themeData.colorPurpleBg,
@@ -316,7 +378,8 @@ var generateTheme = function generateTheme(_ref) {
     colorLavender: darkMode ? themeDataDark.colorLavender : themeData.colorLavender || '#A77BFF',
     colorLavenderHover: darkMode ? themeDataDark.colorLavenderHover : themeData.colorLavenderHover || '#BB99FF',
     colorLavenderBg: darkMode ? themeDataDark.colorLavenderBg : themeData.colorLavenderBg || 'rgba(226, 212, 255, 0.8)',
-    // 阴影 - 暗色模式使用预设值
+    // ========== Shadows ==========
+    // Dark mode uses preset optimized values, light mode uses values from configuration file
     boxShadow: darkMode ? themeDataDark.boxShadow : themeData.boxShadow,
     boxShadowSecondary: darkMode ? themeDataDark.boxShadowSecondary : themeData.boxShadowSecondary,
     boxShadowTertiary: darkMode ? themeDataDark.boxShadowTertiary : themeData.boxShadowTertiary,