@atomazing-org/design-system 1.0.62 → 1.0.64

package/README.md

@@ -0,0 +1,268 @@
+@atomazing-org/design-system
+
+Modern MUI + Emotion design system with a ready theme factory, extended typography, global styles, component overrides, animations, and handy utilities.
+
+Contents
+- Introduction
+- Installation
+- Quick Start
+- Provider Props
+- Dynamic Themes (array)
+- Theme Switching (UI)
+- Dark Mode Control
+- Extended Palette (4 variants)
+- Palette Overrides
+- Using Palette In SX
+- Typography Variants
+- Global Styles
+- Animations
+- Components
+- Utilities
+- SSR Notes
+- Peer Dependencies
+
+Introduction
+The package streamlines consistent theming across apps: dark/light mode, typography variants, global styles, and component defaults. Built on MUI v7 + Emotion.
+
+Installation
+```bash
+npm install @atomazing-org/design-system
+npm install @mui/material @mui/icons-material @emotion/react @emotion/styled @emotion/css
+```
+
+Quick Start
+```tsx
+import { ThemeProviderWrapper } from '@atomazing-org/design-system';
+
+export function App() {
+  return (
+    <ThemeProviderWrapper>
+      {/* your app */}
+    </ThemeProviderWrapper>
+  );
+}
+```
+
+If `themes` is not provided, the provider falls back to a single "Default" theme using the current palette brand color.
+
+Provider Props
+- `themes?: { name: string; primaryColor: string; secondaryColor?: string }[]`
+- `fontFamily?: string`
+- `colorPaletteOverride?: Partial<ColorPaletteType>`
+
+Dynamic Themes (array)
+Provide a fully dynamic list of themes to the provider. This takes priority over static defaults.
+
+```tsx
+<ThemeProviderWrapper
+  themes={[
+    { name: 'Blue', primaryColor: '#3B82F6' },
+    { name: 'Green', primaryColor: '#22C55E', secondaryColor: '#F6F9F6' },
+    { name: 'Gray', primaryColor: '#64748B' },
+  ]}
+>
+  {/* ... */}
+</ThemeProviderWrapper>
+```
+
+Theme Switching (UI)
+Use the theme context to read and change the active theme.
+
+```tsx
+import { useThemeSettings } from '@atomazing-org/design-system';
+import { ToggleButton, ToggleButtonGroup } from '@mui/material';
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useThemeSettings();
+  const options = ['Blue', 'Green', 'Gray'];
+
+  return (
+    <ToggleButtonGroup
+      size="small"
+      exclusive
+      color="brand"
+      value={theme}
+      onChange={(_, v) => v && setTheme(v)}
+    >
+      {options.map((o) => (
+        <ToggleButton key={o} value={o}>{o}</ToggleButton>
+      ))}
+    </ToggleButtonGroup>
+  );
+}
+```
+
+Dark Mode Control
+Use `useThemeSettings()` to read and set dark mode. Modes: `light | dark | system | auto`.
+
+```tsx
+import { useThemeSettings, darkModeOptions } from '@atomazing-org/design-system';
+import { RadioGroup, FormControlLabel, Radio } from '@mui/material';
+
+export function DarkModeSelector() {
+  const { darkMode, setDarkMode } = useThemeSettings();
+  const options = darkModeOptions; // label + icon
+
+  return (
+    <RadioGroup
+      row
+      value={darkMode}
+      onChange={(e) => setDarkMode(e.target.value as any)}
+    >
+      {options.map((o) => (
+        <FormControlLabel key={o.value} value={o.value} control={<Radio />} label={o.label} />
+      ))}
+    </RadioGroup>
+  );
+}
+```
+
+Extended Palette (4 variants)
+The design system adds four typed colors to the MUI palette, available on common components via the `color` prop:
+
+- brand: project brand color (uses the active theme `primary`).
+- neutral: neutral/gray scale color (from the design-system palette).
+- accent: supporting accent color (from palette `accent`).
+- muted: soft/desaturated color (based on neutral by default).
+
+Supported components: `Button`, `Chip`, `Badge`, `Alert`.
+
+```tsx
+import { Button, Chip, Alert } from '@mui/material';
+
+<Button color="brand" variant="contained">Brand</Button>
+<Button color="neutral" variant="outlined">Neutral</Button>
+<Chip color="accent" label="Accent" />
+<Alert color="muted" variant="filled">Muted Alert</Alert>
+```
+
+Palette Overrides
+Override base palette tokens for the whole app.
+
+```tsx
+<ThemeProviderWrapper
+  colorPaletteOverride={{
+    brand: '#4F46E5',
+    accent: '#F59E0B',
+    muted: '#94A3B8',
+    neutral: '#64748B',
+    success: '#16A34A',
+    warning: '#D97706',
+    error: '#DC2626',
+    info: '#0284C7',
+  }}
+>
+  {/* ... */}
+</ThemeProviderWrapper>
+```
+
+Using Palette In SX
+```tsx
+import { Box } from '@mui/material';
+
+<Box sx={{ bgcolor: (t) => t.palette.accent.main, color: (t) => t.palette.getContrastText(t.palette.accent.main) }}>
+  Accent surface
+</Box>
+```
+
+Typography Variants
+Extra variants are available (mapping to `<p>`/headers). Examples:
+
+```tsx
+import { Typography } from '@mui/material';
+
+<Typography variant="text_md_regular">Body text</Typography>
+<Typography variant="text_sm_bold">Strong caption</Typography>
+<Typography variant="header_lg_bold">Section Title</Typography>
+```
+
+Global Styles
+`ThemeProviderWrapper` injects global styles via Emotion. You can also set a custom font family:
+
+```tsx
+<ThemeProviderWrapper fontFamily="Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Arial, sans-serif">
+  {/* ... */}
+</ThemeProviderWrapper>
+```
+
+Animations
+Keyframes ready for use in Emotion/MUI `sx`:
+
+```tsx
+import { keyframes } from '@emotion/react';
+import { fadeIn, slideIn, scale, pulseAnimation, progressPulse } from '@atomazing-org/design-system';
+import styled from '@emotion/styled';
+
+const Card = styled.div`
+  animation: ${fadeIn} 300ms ease-in both;
+`;
+
+const Glowing = styled.div`
+  animation: ${progressPulse('#9FA9EA')} 2s ease-in-out infinite;
+`;
+```
+
+Components
+- ErrorBoundary
+```tsx
+import { ErrorBoundary } from '@atomazing-org/design-system';
+
+<ErrorBoundary>
+  <App />
+</ErrorBoundary>
+```
+
+- Loading
+```tsx
+import { Loading } from '@atomazing-org/design-system';
+
+<Loading />
+```
+
+- PathName / DialogBtn
+```tsx
+import { PathName, DialogBtn } from '@atomazing-org/design-system';
+
+<PathName>/settings/profile</PathName>
+<DialogBtn variant="contained" color="brand">OK</DialogBtn>
+```
+
+Utilities
+```tsx
+import {
+  getFontColor, isFontLight, isHexColor,
+  timeAgo, timeAgoFromStart,
+  useResponsiveDisplay, useSystemTheme,
+  displayGreeting, getDayIdentifier,
+  systemInfo,
+} from '@atomazing-org/design-system';
+
+// Colors
+getFontColor('#ffffff'); // '#101727' | '#f0f0f0'
+isFontLight('#222');
+isHexColor('#abc');
+
+// Time
+timeAgo(new Date(Date.now() - 3600_000));
+timeAgoFromStart(new Date(Date.now() + 90_000));
+
+// Device
+const isMobile = useResponsiveDisplay(768);
+const sysTheme = useSystemTheme(); // 'light' | 'dark' | 'unknown'
+
+// Misc
+displayGreeting(); // Good morning / afternoon / evening
+getDayIdentifier(new Date()); // 'YYYY-MM-DD'
+console.log(systemInfo.os, systemInfo.browser);
+```
+
+SSR Notes
+- The library guards `localStorage`/`navigator`. Use normally in SSR apps; hydration updates settings on client.
+- For Next.js, place the provider in a client boundary (e.g., `layout.tsx` with `"use client"`).
+
+Peer Dependencies
+- `@mui/material` ^7
+- `@mui/icons-material` ^7
+- `@emotion/react` ^11
+- `@emotion/styled` ^11
+- `@emotion/css` ^11 (optional)

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as _emotion_styled from '@emotion/styled';
 import * as _emotion_react from '@emotion/react';
 import * as React$1 from 'react';
-import React__default, { ErrorInfo, FC, PropsWithChildren } from 'react';
+import React__default, { ErrorInfo, ReactNode, FC, PropsWithChildren } from 'react';
 import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
 import * as _mui_material from '@mui/material';
 import { Theme, PaletteMode } from '@mui/material';
@@ -46,7 +46,7 @@ type DarkModeOptions = "system" | "auto" | "light" | "dark";
 interface OptionItem {
     label: string;
     value: DarkModeOptions;
-    icon: any;
+    icon: ReactNode;
 }
 /**
  * Represents user-specific theme preferences stored in the application.
@@ -198,33 +198,41 @@ declare module "@mui/material/Typography" {
     }
 }
 
-declare const useThemeSettings: () => ThemeContextProps;
+interface ColorPaletteType {
+    fontDark: string;
+    fontLight: string;
+    brand: string;
+    accent: string;
+    muted: string;
+    success: string;
+    info: string;
+    warning: string;
+    error: string;
+    neutral: string;
+}
 
-declare const ThemeProviderWrapper: FC<PropsWithChildren>;
+declare const darkModeOptions: OptionItem[];
 
-/**
- * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
- *
- * @param value - The string to check.
- * @returns `true` if the string is a valid hex color; otherwise, `false`.
- */
-declare const isHexColor: (value: string) => boolean;
-/**
- * Determines the ideal font color (white or black) for contrast against a given background color.
- *
- * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
- *
- * @param backgroundColor - A valid hex color (e.g., "#ffffff").
- * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
- */
-declare const getFontColor: (backgroundColor: string) => string;
-/**
- * Determines whether the ideal font color for a background is light (i.e., white).
- *
- * @param color - The background color in hex.
- * @returns `true` if white text is recommended; otherwise, `false`.
- */
-declare const isFontLight: (color: string) => boolean;
+declare const defaultColorPalette: ColorPaletteType;
+
+declare const useThemeSettings: () => ThemeContextProps;
+
+type ThemeProviderWrapperProps = PropsWithChildren<{
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+    /**
+     * Optional dynamic list of themes.
+     * Takes precedence over static defaults when provided.
+     */
+    themes?: {
+        name: string;
+        primaryColor: string;
+        secondaryColor?: string;
+    }[];
+    /** Optional color palette override (e.g., fontLight/fontDark/accent colors). */
+    colorPaletteOverride?: Partial<ColorPaletteType>;
+}>;
+declare const ThemeProviderWrapper: FC<ThemeProviderWrapperProps>;
 
 /**
  * Common component style overrides and default props shared across the design system.
@@ -232,25 +240,7 @@ declare const isFontLight: (color: string) => boolean;
  */
 declare const commonComponentProps: Theme["components"];
 
-declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode) => Theme;
-/**
- * A predefined list of named themes based on the `themeConfig` definition.
- */
-declare const themes: {
-    name: string;
-    MuiTheme: Theme;
-}[];
-/**
- * Determines whether dark mode should be enabled based on user settings and system conditions.
- *
- * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
- * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
- * @param backgroundColor - The background color to assess contrast in 'auto' mode.
- * @returns True if dark mode should be used.
- */
-declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
-
-declare const darkModeOptions: OptionItem[];
+declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode, secondaryColor?: string) => Theme;
 
 /**
  * Injects global styles into the document using Emotion.
@@ -259,7 +249,11 @@ declare const darkModeOptions: OptionItem[];
  *
  * Uses the MUI theme to dynamically adjust colors for light/dark mode.
  */
-declare const GlobalStyles: FC;
+interface GlobalStylesProps {
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+}
+declare const GlobalStyles: FC<GlobalStylesProps>;
 
 /**
  * Fade in from the left with slight movement on the X-axis.
@@ -352,18 +346,39 @@ declare const installAppAnimation: {
     toString: () => string;
 } & string;
 
-declare const ColorPalette: {
-    readonly fontDark: "#101727";
-    readonly fontLight: "#f0f0f0";
-    readonly purple: "#440850";
-    readonly lavender: "#9FA9EA";
-    readonly carrot: "#F3503A";
-    readonly pistachio: "#62ED97";
-};
-declare const themeConfig: Record<string, {
-    primaryColor: string;
-    secondaryColor?: string;
-}>;
+/** Returns the active color palette, allowing app-level overrides. */
+declare const getColorPalette: () => ColorPaletteType;
+/**
+ * Overrides the active color palette with app-provided values.
+ * Pass `undefined` or empty to reset to defaults.
+ */
+declare const setColorPaletteOverride: (override?: Partial<ColorPaletteType>) => void;
+/** Backward-compatible live view of the active palette. */
+declare const ColorPalette: Readonly<ColorPaletteType>;
+
+/**
+ * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string is a valid hex color; otherwise, `false`.
+ */
+declare const isHexColor: (value: string) => boolean;
+/**
+ * Determines the ideal font color (white or black) for contrast against a given background color.
+ *
+ * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
+ *
+ * @param backgroundColor - A valid hex color (e.g., "#ffffff").
+ * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
+ */
+declare const getFontColor: (backgroundColor: string) => string;
+/**
+ * Determines whether the ideal font color for a background is light (i.e., white).
+ *
+ * @param color - The background color in hex.
+ * @returns `true` if white text is recommended; otherwise, `false`.
+ */
+declare const isFontLight: (color: string) => boolean;
 
 /**
  * Returns a greeting based on the current time.
@@ -386,12 +401,23 @@ type OperatingSystem = "Windows" | "macOS" | "Linux" | "iOS" | "Android" | "Unkn
 type Browser = "Chrome" | "Firefox" | "Safari" | "Edge" | "Unknown";
 /**
  * Basic information about the user's system (OS and browser).
+ * Safe for SSR: resolves to Unknown values on server.
  */
 declare const systemInfo: {
     os: OperatingSystem;
     browser: Browser;
 };
 
+/**
+ * Determines whether dark mode should be enabled based on user settings and system conditions.
+ *
+ * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
+ * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
+ * @param backgroundColor - The background color to assess contrast in 'auto' mode.
+ * @returns True if dark mode should be used.
+ */
+declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
+
 /**
  * Converts a given date to a human-readable relative time string.
  *
@@ -416,4 +442,4 @@ declare const useResponsiveDisplay: (breakpoint?: number) => boolean;
  */
 declare const useSystemTheme: () => SystemTheme;
 
-export { type AppSettings, ColorPalette, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, displayGreeting, fadeIn, fadeInLeft, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };
+export { type AppSettings, ColorPalette, type ColorPaletteType, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, defaultColorPalette, displayGreeting, fadeIn, fadeInLeft, getColorPalette, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, setColorPaletteOverride, slideIn, slideInBottom, systemInfo, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _emotion_styled from '@emotion/styled';
 import * as _emotion_react from '@emotion/react';
 import * as React$1 from 'react';
-import React__default, { ErrorInfo, FC, PropsWithChildren } from 'react';
+import React__default, { ErrorInfo, ReactNode, FC, PropsWithChildren } from 'react';
 import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
 import * as _mui_material from '@mui/material';
 import { Theme, PaletteMode } from '@mui/material';
@@ -46,7 +46,7 @@ type DarkModeOptions = "system" | "auto" | "light" | "dark";
 interface OptionItem {
     label: string;
     value: DarkModeOptions;
-    icon: any;
+    icon: ReactNode;
 }
 /**
  * Represents user-specific theme preferences stored in the application.
@@ -198,33 +198,41 @@ declare module "@mui/material/Typography" {
     }
 }
 
-declare const useThemeSettings: () => ThemeContextProps;
+interface ColorPaletteType {
+    fontDark: string;
+    fontLight: string;
+    brand: string;
+    accent: string;
+    muted: string;
+    success: string;
+    info: string;
+    warning: string;
+    error: string;
+    neutral: string;
+}
 
-declare const ThemeProviderWrapper: FC<PropsWithChildren>;
+declare const darkModeOptions: OptionItem[];
 
-/**
- * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
- *
- * @param value - The string to check.
- * @returns `true` if the string is a valid hex color; otherwise, `false`.
- */
-declare const isHexColor: (value: string) => boolean;
-/**
- * Determines the ideal font color (white or black) for contrast against a given background color.
- *
- * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
- *
- * @param backgroundColor - A valid hex color (e.g., "#ffffff").
- * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
- */
-declare const getFontColor: (backgroundColor: string) => string;
-/**
- * Determines whether the ideal font color for a background is light (i.e., white).
- *
- * @param color - The background color in hex.
- * @returns `true` if white text is recommended; otherwise, `false`.
- */
-declare const isFontLight: (color: string) => boolean;
+declare const defaultColorPalette: ColorPaletteType;
+
+declare const useThemeSettings: () => ThemeContextProps;
+
+type ThemeProviderWrapperProps = PropsWithChildren<{
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+    /**
+     * Optional dynamic list of themes.
+     * Takes precedence over static defaults when provided.
+     */
+    themes?: {
+        name: string;
+        primaryColor: string;
+        secondaryColor?: string;
+    }[];
+    /** Optional color palette override (e.g., fontLight/fontDark/accent colors). */
+    colorPaletteOverride?: Partial<ColorPaletteType>;
+}>;
+declare const ThemeProviderWrapper: FC<ThemeProviderWrapperProps>;
 
 /**
  * Common component style overrides and default props shared across the design system.
@@ -232,25 +240,7 @@ declare const isFontLight: (color: string) => boolean;
  */
 declare const commonComponentProps: Theme["components"];
 
-declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode) => Theme;
-/**
- * A predefined list of named themes based on the `themeConfig` definition.
- */
-declare const themes: {
-    name: string;
-    MuiTheme: Theme;
-}[];
-/**
- * Determines whether dark mode should be enabled based on user settings and system conditions.
- *
- * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
- * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
- * @param backgroundColor - The background color to assess contrast in 'auto' mode.
- * @returns True if dark mode should be used.
- */
-declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
-
-declare const darkModeOptions: OptionItem[];
+declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode, secondaryColor?: string) => Theme;
 
 /**
  * Injects global styles into the document using Emotion.
@@ -259,7 +249,11 @@ declare const darkModeOptions: OptionItem[];
  *
  * Uses the MUI theme to dynamically adjust colors for light/dark mode.
  */
-declare const GlobalStyles: FC;
+interface GlobalStylesProps {
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+}
+declare const GlobalStyles: FC<GlobalStylesProps>;
 
 /**
  * Fade in from the left with slight movement on the X-axis.
@@ -352,18 +346,39 @@ declare const installAppAnimation: {
     toString: () => string;
 } & string;
 
-declare const ColorPalette: {
-    readonly fontDark: "#101727";
-    readonly fontLight: "#f0f0f0";
-    readonly purple: "#440850";
-    readonly lavender: "#9FA9EA";
-    readonly carrot: "#F3503A";
-    readonly pistachio: "#62ED97";
-};
-declare const themeConfig: Record<string, {
-    primaryColor: string;
-    secondaryColor?: string;
-}>;
+/** Returns the active color palette, allowing app-level overrides. */
+declare const getColorPalette: () => ColorPaletteType;
+/**
+ * Overrides the active color palette with app-provided values.
+ * Pass `undefined` or empty to reset to defaults.
+ */
+declare const setColorPaletteOverride: (override?: Partial<ColorPaletteType>) => void;
+/** Backward-compatible live view of the active palette. */
+declare const ColorPalette: Readonly<ColorPaletteType>;
+
+/**
+ * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string is a valid hex color; otherwise, `false`.
+ */
+declare const isHexColor: (value: string) => boolean;
+/**
+ * Determines the ideal font color (white or black) for contrast against a given background color.
+ *
+ * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
+ *
+ * @param backgroundColor - A valid hex color (e.g., "#ffffff").
+ * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
+ */
+declare const getFontColor: (backgroundColor: string) => string;
+/**
+ * Determines whether the ideal font color for a background is light (i.e., white).
+ *
+ * @param color - The background color in hex.
+ * @returns `true` if white text is recommended; otherwise, `false`.
+ */
+declare const isFontLight: (color: string) => boolean;
 
 /**
  * Returns a greeting based on the current time.
@@ -386,12 +401,23 @@ type OperatingSystem = "Windows" | "macOS" | "Linux" | "iOS" | "Android" | "Unkn
 type Browser = "Chrome" | "Firefox" | "Safari" | "Edge" | "Unknown";
 /**
  * Basic information about the user's system (OS and browser).
+ * Safe for SSR: resolves to Unknown values on server.
  */
 declare const systemInfo: {
     os: OperatingSystem;
     browser: Browser;
 };
 
+/**
+ * Determines whether dark mode should be enabled based on user settings and system conditions.
+ *
+ * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
+ * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
+ * @param backgroundColor - The background color to assess contrast in 'auto' mode.
+ * @returns True if dark mode should be used.
+ */
+declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
+
 /**
  * Converts a given date to a human-readable relative time string.
  *
@@ -416,4 +442,4 @@ declare const useResponsiveDisplay: (breakpoint?: number) => boolean;
  */
 declare const useSystemTheme: () => SystemTheme;
 
-export { type AppSettings, ColorPalette, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, displayGreeting, fadeIn, fadeInLeft, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };
+export { type AppSettings, ColorPalette, type ColorPaletteType, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, defaultColorPalette, displayGreeting, fadeIn, fadeInLeft, getColorPalette, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, setColorPaletteOverride, slideIn, slideInBottom, systemInfo, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };