@aurora-ds/theme 1.5.0 → 1.6.0

package/dist/index.d.cts

@@ -262,6 +262,94 @@ type DeepPartial<T> = {
  * Type for theme overrides
  */
 type ThemeOverride<T extends Theme = Theme> = DeepPartial<T>;
+/**
+ * Base structure for custom themes with user-defined color tokens
+ * Use this when you want to completely replace the default color tokens
+ * with your own semantic tokens
+ */
+type CustomThemeBase<TColors extends Record<string, string>> = {
+    colors: TColors;
+    spacing: BaseSpacing;
+    radius: BaseRadius;
+    shadows: BaseShadows;
+    fontSize: BaseFontSize;
+    fontWeight: BaseFontWeight;
+    lineHeight: BaseLineHeight;
+    zIndex: BaseZIndex;
+    transition: BaseTransition;
+    opacity: BaseOpacity;
+    breakpoints: BaseBreakpoints;
+};
+/**
+ * Fully customizable theme where ALL token categories can be replaced
+ *
+ * @example
+ * ```ts
+ * // Define your own color tokens
+ * type MyColors = {
+ *     brand: string
+ *     brandHover: string
+ *     surface: string
+ *     textPrimary: string
+ *     textSecondary: string
+ * }
+ *
+ * // Create your theme type
+ * type MyTheme = CustomTheme<MyColors>
+ *
+ * // Use with createCustomTheme()
+ * const myTheme = createCustomTheme<MyColors>({
+ *     colors: {
+ *         brand: '#007bff',
+ *         brandHover: '#0056b3',
+ *         surface: '#ffffff',
+ *         textPrimary: '#212529',
+ *         textSecondary: '#6c757d',
+ *     },
+ *     // ... other tokens use defaults or custom
+ * })
+ * ```
+ */
+type CustomTheme<TColors extends Record<string, string> = Record<string, string>, TSpacing extends Record<string, string> = BaseSpacing, TRadius extends Record<string, string> = BaseRadius, TShadows extends Record<string, string> = BaseShadows, TFontSize extends Record<string, string> = BaseFontSize, TFontWeight extends Record<string, number> = BaseFontWeight, TLineHeight extends Record<string, number> = BaseLineHeight, TZIndex extends Record<string, number> = BaseZIndex, TTransition extends Record<string, string> = BaseTransition, TOpacity extends Record<string, number> = BaseOpacity, TBreakpoints extends Record<string, string> = BaseBreakpoints> = {
+    colors: TColors;
+    spacing: TSpacing;
+    radius: TRadius;
+    shadows: TShadows;
+    fontSize: TFontSize;
+    fontWeight: TFontWeight;
+    lineHeight: TLineHeight;
+    zIndex: TZIndex;
+    transition: TTransition;
+    opacity: TOpacity;
+    breakpoints: TBreakpoints;
+};
+/**
+ * Options for theme creation
+ */
+type CreateThemeOptions = {
+    /**
+     * How to handle the merge of overrides with the base theme
+     * - 'merge': Deep merge overrides into base (default, preserves base tokens)
+     * - 'replace': Replace entire categories when specified in overrides
+     */
+    mode?: 'merge' | 'replace';
+};
+/**
+ * Options for custom theme creation
+ */
+type CreateCustomThemeOptions<T> = {
+    /**
+     * Use defaults from the standard theme for non-color tokens
+     * If false, you must provide all tokens
+     * @default true
+     */
+    useDefaults?: boolean;
+    /**
+     * Partial overrides for non-color tokens
+     * Only used when useDefaults is true
+     */
+    overrides?: Partial<Omit<T, 'colors'>>;
+};
 
 /**
  * Color scale type - 12 shades from 25 to 950
@@ -335,56 +423,6 @@ declare const ThemeProvider: <T extends Theme>({ theme, children }: ThemeProvide
  */
 declare const useTheme: <T extends Theme = Theme>() => T;
 
-/**
- * Create a theme by merging a base theme with overrides
- *
- * @example
- * ```ts
- * const myTheme = createTheme(defaultTheme, {
- *     colors: {
- *         primary: '#ff0000',
- *         // Only override what you need
- *     },
- *     spacing: {
- *         md: '1.5rem',
- *     },
- * })
- * ```
- */
-declare const createTheme: <T extends Theme>(baseTheme: T, overrides: DeepPartial<T>) => T;
-/**
- * Merge multiple theme overrides into one
- * Later overrides take precedence
- *
- * @example
- * ```ts
- * const theme = mergeThemes(
- *     baseTheme,
- *     brandOverrides,
- *     darkModeOverrides,
- *     userPreferences
- * )
- * ```
- */
-declare const mergeThemes: <T extends Theme>(baseTheme: T, ...overrides: DeepPartial<T>[]) => T;
-/**
- * Create a theme extension factory
- * Useful for creating theme variants (dark mode, high contrast, etc.)
- *
- * @example
- * ```ts
- * const createDarkVariant = createThemeVariant({
- *     colors: {
- *         background: '#1a1a1a',
- *         text: '#ffffff',
- *     },
- * })
- *
- * const darkTheme = createDarkVariant(lightTheme)
- * ```
- */
-declare const createThemeVariant: <T extends Theme>(variantOverrides: DeepPartial<T>) => (baseTheme: T) => T;
-
 /**
  * Default spacing scale
  */
@@ -442,6 +480,125 @@ declare const defaultTheme: Theme;
  */
 declare const defaultDarkTheme: Theme;
 
+/**
+ * Create a theme by merging a base theme with overrides
+ *
+ * @param baseTheme - The base theme to extend
+ * @param overrides - Partial overrides to apply
+ * @param options - Optional configuration
+ * @param options.mode - 'merge' (default) deep merges, 'replace' replaces entire categories
+ *
+ * @example
+ * ```ts
+ * // Default behavior: deep merge (extends existing tokens)
+ * const myTheme = createTheme(defaultTheme, {
+ *     colors: {
+ *         primary: '#ff0000',
+ *         // Other color tokens from defaultTheme are preserved
+ *     },
+ * })
+ *
+ * // Replace mode: completely replace categories
+ * const myTheme = createTheme(defaultTheme, {
+ *     colors: {
+ *         // This becomes the ENTIRE colors object
+ *         brand: '#ff0000',
+ *         surface: '#ffffff',
+ *         text: '#000000',
+ *     },
+ * }, { mode: 'replace' })
+ * ```
+ */
+declare const createTheme: <T extends Theme>(baseTheme: T, overrides: DeepPartial<T>, options?: CreateThemeOptions) => T;
+/**
+ * Merge multiple theme overrides into one
+ * Later overrides take precedence
+ *
+ * @example
+ * ```ts
+ * const theme = mergeThemes(
+ *     baseTheme,
+ *     brandOverrides,
+ *     darkModeOverrides,
+ *     userPreferences
+ * )
+ * ```
+ */
+declare const mergeThemes: <T extends Theme>(baseTheme: T, ...overrides: DeepPartial<T>[]) => T;
+/**
+ * Create a theme extension factory
+ * Useful for creating theme variants (dark mode, high contrast, etc.)
+ *
+ * @example
+ * ```ts
+ * const createDarkVariant = createThemeVariant({
+ *     colors: {
+ *         background: '#1a1a1a',
+ *         text: '#ffffff',
+ *     },
+ * })
+ *
+ * const darkTheme = createDarkVariant(lightTheme)
+ * ```
+ */
+declare const createThemeVariant: <T extends Theme>(variantOverrides: DeepPartial<T>) => (baseTheme: T) => T;
+/**
+ * Create a fully custom theme with your own color tokens
+ * This allows you to define a completely different color token structure
+ * without being constrained by BaseColors
+ *
+ * @param config - Full theme configuration with custom colors
+ *
+ * @example
+ * ```ts
+ * // Define your custom color tokens
+ * type MyBrandColors = {
+ *     brand: string
+ *     brandHover: string
+ *     brandActive: string
+ *     surface: string
+ *     surfaceElevated: string
+ *     textPrimary: string
+ *     textSecondary: string
+ *     border: string
+ * }
+ *
+ * // Create a theme with ONLY your color tokens
+ * const myTheme = createCustomTheme<MyBrandColors>({
+ *     colors: {
+ *         brand: '#007bff',
+ *         brandHover: '#0056b3',
+ *         brandActive: '#004085',
+ *         surface: '#ffffff',
+ *         surfaceElevated: '#f8f9fa',
+ *         textPrimary: '#212529',
+ *         textSecondary: '#6c757d',
+ *         border: '#dee2e6',
+ *     },
+ *     // Uses defaults for other tokens, or provide your own:
+ *     // spacing: { ... },
+ *     // radius: { ... },
+ * })
+ *
+ * // TypeScript knows your theme has only YOUR color tokens:
+ * myTheme.colors.brand      // ✅ OK
+ * myTheme.colors.primary    // ❌ Error - doesn't exist
+ * ```
+ */
+declare const createCustomTheme: <TColors extends Record<string, string>, TSpacing extends Record<string, string> = typeof defaultSpacing, TRadius extends Record<string, string> = typeof defaultRadius, TShadows extends Record<string, string> = typeof defaultShadows, TFontSize extends Record<string, string> = typeof defaultFontSize, TFontWeight extends Record<string, number> = typeof defaultFontWeight, TLineHeight extends Record<string, number> = typeof defaultLineHeight, TZIndex extends Record<string, number> = typeof defaultZIndex, TTransition extends Record<string, string> = typeof defaultTransition, TOpacity extends Record<string, number> = typeof defaultOpacity, TBreakpoints extends Record<string, string> = typeof defaultBreakpoints>(config: {
+    colors: TColors;
+    spacing?: TSpacing;
+    radius?: TRadius;
+    shadows?: TShadows;
+    fontSize?: TFontSize;
+    fontWeight?: TFontWeight;
+    lineHeight?: TLineHeight;
+    zIndex?: TZIndex;
+    transition?: TTransition;
+    opacity?: TOpacity;
+    breakpoints?: TBreakpoints;
+}) => CustomTheme<TColors, TSpacing, TRadius, TShadows, TFontSize, TFontWeight, TLineHeight, TZIndex, TTransition, TOpacity, TBreakpoints>;
+
 declare const gray: ColorScale;
 
 declare const slate: ColorScale;
@@ -741,6 +898,32 @@ type FontFaceOptions = {
  * ```
  */
 declare const createStyles: <TTheme extends Theme = Theme, T extends Record<string, StyleWithPseudos | StyleFunction> = Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: TTheme) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
+/**
+ * Create a typed createStyles function pre-configured with your custom theme type.
+ * This eliminates the need to specify the theme type on every createStyles call.
+ *
+ * @example
+ * ```ts
+ * // 1. Define your custom theme
+ * type MyTheme = CustomTheme<{
+ *     brand: string
+ *     brandHover: string
+ *     surface: string
+ * }>
+ *
+ * // 2. Create a pre-typed createStyles function (do this once)
+ * export const createStyles = createTypedStyles<MyTheme>()
+ *
+ * // 3. Use it everywhere without specifying the type!
+ * const STYLES = createStyles((theme) => ({
+ *     button: {
+ *         backgroundColor: theme.colors.brand,    // ✅ TypeScript knows!
+ *         // backgroundColor: theme.colors.primary, // ❌ Error - doesn't exist
+ *     },
+ * }))
+ * ```
+ */
+declare const createTypedStyles: <TTheme extends Record<string, unknown>>() => <T extends Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: TTheme) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
 
 /**
  * Create and inject keyframes
@@ -1011,4 +1194,4 @@ declare const checkThemeContrast: (theme: {
  */
 declare const suggestContrastColor: (foreground: string, background: string, targetRatio?: number) => string | null;
 
-export { type BaseBreakpoints, type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseOpacity, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type ContrastResult, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeContrastIssue, type ThemeOverride, ThemeProvider, type ThemeProviderProps, type WCAGLevel, amber, amberDark, amberLight, black, blue, blueDark, blueLight, checkContrast, checkThemeContrast, clearSSRRules, colors, createStyles, createTheme, createThemeVariant, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultBreakpoints, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultOpacity, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getContrastRatio, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, meetsWCAG, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, suggestContrastColor, teal, tealDark, tealLight, transparent, useTheme, violet, violetDark, violetLight, white, yellow };
+export { type BaseBreakpoints, type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseOpacity, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type ContrastResult, type CreateCustomThemeOptions, type CreateThemeOptions, type CustomTheme, type CustomThemeBase, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeContrastIssue, type ThemeOverride, ThemeProvider, type ThemeProviderProps, type WCAGLevel, amber, amberDark, amberLight, black, blue, blueDark, blueLight, checkContrast, checkThemeContrast, clearSSRRules, colors, createCustomTheme, createStyles, createTheme, createThemeVariant, createTypedStyles, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultBreakpoints, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultOpacity, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getContrastRatio, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, meetsWCAG, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, suggestContrastColor, teal, tealDark, tealLight, transparent, useTheme, violet, violetDark, violetLight, white, yellow };

package/dist/index.d.ts

@@ -262,6 +262,94 @@ type DeepPartial<T> = {
  * Type for theme overrides
  */
 type ThemeOverride<T extends Theme = Theme> = DeepPartial<T>;
+/**
+ * Base structure for custom themes with user-defined color tokens
+ * Use this when you want to completely replace the default color tokens
+ * with your own semantic tokens
+ */
+type CustomThemeBase<TColors extends Record<string, string>> = {
+    colors: TColors;
+    spacing: BaseSpacing;
+    radius: BaseRadius;
+    shadows: BaseShadows;
+    fontSize: BaseFontSize;
+    fontWeight: BaseFontWeight;
+    lineHeight: BaseLineHeight;
+    zIndex: BaseZIndex;
+    transition: BaseTransition;
+    opacity: BaseOpacity;
+    breakpoints: BaseBreakpoints;
+};
+/**
+ * Fully customizable theme where ALL token categories can be replaced
+ *
+ * @example
+ * ```ts
+ * // Define your own color tokens
+ * type MyColors = {
+ *     brand: string
+ *     brandHover: string
+ *     surface: string
+ *     textPrimary: string
+ *     textSecondary: string
+ * }
+ *
+ * // Create your theme type
+ * type MyTheme = CustomTheme<MyColors>
+ *
+ * // Use with createCustomTheme()
+ * const myTheme = createCustomTheme<MyColors>({
+ *     colors: {
+ *         brand: '#007bff',
+ *         brandHover: '#0056b3',
+ *         surface: '#ffffff',
+ *         textPrimary: '#212529',
+ *         textSecondary: '#6c757d',
+ *     },
+ *     // ... other tokens use defaults or custom
+ * })
+ * ```
+ */
+type CustomTheme<TColors extends Record<string, string> = Record<string, string>, TSpacing extends Record<string, string> = BaseSpacing, TRadius extends Record<string, string> = BaseRadius, TShadows extends Record<string, string> = BaseShadows, TFontSize extends Record<string, string> = BaseFontSize, TFontWeight extends Record<string, number> = BaseFontWeight, TLineHeight extends Record<string, number> = BaseLineHeight, TZIndex extends Record<string, number> = BaseZIndex, TTransition extends Record<string, string> = BaseTransition, TOpacity extends Record<string, number> = BaseOpacity, TBreakpoints extends Record<string, string> = BaseBreakpoints> = {
+    colors: TColors;
+    spacing: TSpacing;
+    radius: TRadius;
+    shadows: TShadows;
+    fontSize: TFontSize;
+    fontWeight: TFontWeight;
+    lineHeight: TLineHeight;
+    zIndex: TZIndex;
+    transition: TTransition;
+    opacity: TOpacity;
+    breakpoints: TBreakpoints;
+};
+/**
+ * Options for theme creation
+ */
+type CreateThemeOptions = {
+    /**
+     * How to handle the merge of overrides with the base theme
+     * - 'merge': Deep merge overrides into base (default, preserves base tokens)
+     * - 'replace': Replace entire categories when specified in overrides
+     */
+    mode?: 'merge' | 'replace';
+};
+/**
+ * Options for custom theme creation
+ */
+type CreateCustomThemeOptions<T> = {
+    /**
+     * Use defaults from the standard theme for non-color tokens
+     * If false, you must provide all tokens
+     * @default true
+     */
+    useDefaults?: boolean;
+    /**
+     * Partial overrides for non-color tokens
+     * Only used when useDefaults is true
+     */
+    overrides?: Partial<Omit<T, 'colors'>>;
+};
 
 /**
  * Color scale type - 12 shades from 25 to 950
@@ -335,56 +423,6 @@ declare const ThemeProvider: <T extends Theme>({ theme, children }: ThemeProvide
  */
 declare const useTheme: <T extends Theme = Theme>() => T;
 
-/**
- * Create a theme by merging a base theme with overrides
- *
- * @example
- * ```ts
- * const myTheme = createTheme(defaultTheme, {
- *     colors: {
- *         primary: '#ff0000',
- *         // Only override what you need
- *     },
- *     spacing: {
- *         md: '1.5rem',
- *     },
- * })
- * ```
- */
-declare const createTheme: <T extends Theme>(baseTheme: T, overrides: DeepPartial<T>) => T;
-/**
- * Merge multiple theme overrides into one
- * Later overrides take precedence
- *
- * @example
- * ```ts
- * const theme = mergeThemes(
- *     baseTheme,
- *     brandOverrides,
- *     darkModeOverrides,
- *     userPreferences
- * )
- * ```
- */
-declare const mergeThemes: <T extends Theme>(baseTheme: T, ...overrides: DeepPartial<T>[]) => T;
-/**
- * Create a theme extension factory
- * Useful for creating theme variants (dark mode, high contrast, etc.)
- *
- * @example
- * ```ts
- * const createDarkVariant = createThemeVariant({
- *     colors: {
- *         background: '#1a1a1a',
- *         text: '#ffffff',
- *     },
- * })
- *
- * const darkTheme = createDarkVariant(lightTheme)
- * ```
- */
-declare const createThemeVariant: <T extends Theme>(variantOverrides: DeepPartial<T>) => (baseTheme: T) => T;
-
 /**
  * Default spacing scale
  */
@@ -442,6 +480,125 @@ declare const defaultTheme: Theme;
  */
 declare const defaultDarkTheme: Theme;
 
+/**
+ * Create a theme by merging a base theme with overrides
+ *
+ * @param baseTheme - The base theme to extend
+ * @param overrides - Partial overrides to apply
+ * @param options - Optional configuration
+ * @param options.mode - 'merge' (default) deep merges, 'replace' replaces entire categories
+ *
+ * @example
+ * ```ts
+ * // Default behavior: deep merge (extends existing tokens)
+ * const myTheme = createTheme(defaultTheme, {
+ *     colors: {
+ *         primary: '#ff0000',
+ *         // Other color tokens from defaultTheme are preserved
+ *     },
+ * })
+ *
+ * // Replace mode: completely replace categories
+ * const myTheme = createTheme(defaultTheme, {
+ *     colors: {
+ *         // This becomes the ENTIRE colors object
+ *         brand: '#ff0000',
+ *         surface: '#ffffff',
+ *         text: '#000000',
+ *     },
+ * }, { mode: 'replace' })
+ * ```
+ */
+declare const createTheme: <T extends Theme>(baseTheme: T, overrides: DeepPartial<T>, options?: CreateThemeOptions) => T;
+/**
+ * Merge multiple theme overrides into one
+ * Later overrides take precedence
+ *
+ * @example
+ * ```ts
+ * const theme = mergeThemes(
+ *     baseTheme,
+ *     brandOverrides,
+ *     darkModeOverrides,
+ *     userPreferences
+ * )
+ * ```
+ */
+declare const mergeThemes: <T extends Theme>(baseTheme: T, ...overrides: DeepPartial<T>[]) => T;
+/**
+ * Create a theme extension factory
+ * Useful for creating theme variants (dark mode, high contrast, etc.)
+ *
+ * @example
+ * ```ts
+ * const createDarkVariant = createThemeVariant({
+ *     colors: {
+ *         background: '#1a1a1a',
+ *         text: '#ffffff',
+ *     },
+ * })
+ *
+ * const darkTheme = createDarkVariant(lightTheme)
+ * ```
+ */
+declare const createThemeVariant: <T extends Theme>(variantOverrides: DeepPartial<T>) => (baseTheme: T) => T;
+/**
+ * Create a fully custom theme with your own color tokens
+ * This allows you to define a completely different color token structure
+ * without being constrained by BaseColors
+ *
+ * @param config - Full theme configuration with custom colors
+ *
+ * @example
+ * ```ts
+ * // Define your custom color tokens
+ * type MyBrandColors = {
+ *     brand: string
+ *     brandHover: string
+ *     brandActive: string
+ *     surface: string
+ *     surfaceElevated: string
+ *     textPrimary: string
+ *     textSecondary: string
+ *     border: string
+ * }
+ *
+ * // Create a theme with ONLY your color tokens
+ * const myTheme = createCustomTheme<MyBrandColors>({
+ *     colors: {
+ *         brand: '#007bff',
+ *         brandHover: '#0056b3',
+ *         brandActive: '#004085',
+ *         surface: '#ffffff',
+ *         surfaceElevated: '#f8f9fa',
+ *         textPrimary: '#212529',
+ *         textSecondary: '#6c757d',
+ *         border: '#dee2e6',
+ *     },
+ *     // Uses defaults for other tokens, or provide your own:
+ *     // spacing: { ... },
+ *     // radius: { ... },
+ * })
+ *
+ * // TypeScript knows your theme has only YOUR color tokens:
+ * myTheme.colors.brand      // ✅ OK
+ * myTheme.colors.primary    // ❌ Error - doesn't exist
+ * ```
+ */
+declare const createCustomTheme: <TColors extends Record<string, string>, TSpacing extends Record<string, string> = typeof defaultSpacing, TRadius extends Record<string, string> = typeof defaultRadius, TShadows extends Record<string, string> = typeof defaultShadows, TFontSize extends Record<string, string> = typeof defaultFontSize, TFontWeight extends Record<string, number> = typeof defaultFontWeight, TLineHeight extends Record<string, number> = typeof defaultLineHeight, TZIndex extends Record<string, number> = typeof defaultZIndex, TTransition extends Record<string, string> = typeof defaultTransition, TOpacity extends Record<string, number> = typeof defaultOpacity, TBreakpoints extends Record<string, string> = typeof defaultBreakpoints>(config: {
+    colors: TColors;
+    spacing?: TSpacing;
+    radius?: TRadius;
+    shadows?: TShadows;
+    fontSize?: TFontSize;
+    fontWeight?: TFontWeight;
+    lineHeight?: TLineHeight;
+    zIndex?: TZIndex;
+    transition?: TTransition;
+    opacity?: TOpacity;
+    breakpoints?: TBreakpoints;
+}) => CustomTheme<TColors, TSpacing, TRadius, TShadows, TFontSize, TFontWeight, TLineHeight, TZIndex, TTransition, TOpacity, TBreakpoints>;
+
 declare const gray: ColorScale;
 
 declare const slate: ColorScale;
@@ -741,6 +898,32 @@ type FontFaceOptions = {
  * ```
  */
 declare const createStyles: <TTheme extends Theme = Theme, T extends Record<string, StyleWithPseudos | StyleFunction> = Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: TTheme) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
+/**
+ * Create a typed createStyles function pre-configured with your custom theme type.
+ * This eliminates the need to specify the theme type on every createStyles call.
+ *
+ * @example
+ * ```ts
+ * // 1. Define your custom theme
+ * type MyTheme = CustomTheme<{
+ *     brand: string
+ *     brandHover: string
+ *     surface: string
+ * }>
+ *
+ * // 2. Create a pre-typed createStyles function (do this once)
+ * export const createStyles = createTypedStyles<MyTheme>()
+ *
+ * // 3. Use it everywhere without specifying the type!
+ * const STYLES = createStyles((theme) => ({
+ *     button: {
+ *         backgroundColor: theme.colors.brand,    // ✅ TypeScript knows!
+ *         // backgroundColor: theme.colors.primary, // ❌ Error - doesn't exist
+ *     },
+ * }))
+ * ```
+ */
+declare const createTypedStyles: <TTheme extends Record<string, unknown>>() => <T extends Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: TTheme) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
 
 /**
  * Create and inject keyframes
@@ -1011,4 +1194,4 @@ declare const checkThemeContrast: (theme: {
  */
 declare const suggestContrastColor: (foreground: string, background: string, targetRatio?: number) => string | null;
 
-export { type BaseBreakpoints, type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseOpacity, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type ContrastResult, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeContrastIssue, type ThemeOverride, ThemeProvider, type ThemeProviderProps, type WCAGLevel, amber, amberDark, amberLight, black, blue, blueDark, blueLight, checkContrast, checkThemeContrast, clearSSRRules, colors, createStyles, createTheme, createThemeVariant, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultBreakpoints, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultOpacity, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getContrastRatio, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, meetsWCAG, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, suggestContrastColor, teal, tealDark, tealLight, transparent, useTheme, violet, violetDark, violetLight, white, yellow };
+export { type BaseBreakpoints, type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseOpacity, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type ContrastResult, type CreateCustomThemeOptions, type CreateThemeOptions, type CustomTheme, type CustomThemeBase, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeContrastIssue, type ThemeOverride, ThemeProvider, type ThemeProviderProps, type WCAGLevel, amber, amberDark, amberLight, black, blue, blueDark, blueLight, checkContrast, checkThemeContrast, clearSSRRules, colors, createCustomTheme, createStyles, createTheme, createThemeVariant, createTypedStyles, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultBreakpoints, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultOpacity, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getContrastRatio, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, meetsWCAG, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, suggestContrastColor, teal, tealDark, tealLight, transparent, useTheme, violet, violetDark, violetLight, white, yellow };