@styleframe/theme 2.3.0 → 2.5.0

package/dist/theme.d.ts

@@ -3,95 +3,15 @@ import { ModifierFactory } from '@styleframe/core';
 import { Reference } from '@styleframe/core';
 import { Styleframe } from '@styleframe/core';
 import { TokenValue } from '@styleframe/core';
+import { UtilityAutogenerateFn } from '@styleframe/core';
 import { UtilityCallbackFn } from '@styleframe/core';
 import { UtilityCreatorFn } from '@styleframe/core';
 import { Variable } from '@styleframe/core';
 
-/**
- * Creates a generic composable function for a CSS utility.
- *
- * This factory function generates `use*Utility` composables (like `useMarginUtility`, `usePaddingUtility`, etc.)
- * from a utility name and factory function.
- *
- * @param utilityName - The utility name (e.g., 'margin', 'padding')
- * @param factory - Function that receives { value } and returns CSS declarations
- * @param options - Configuration options
- * @returns A composable function that creates utilities for the given property
- *
- * @example
- * ```typescript
- * // Create a useMarginUtility composable
- * export const useMarginUtility = createUseUtility(
- *     'm',
- *     ({ value }) => ({ margin: value })
- * );
- *
- * // Usage
- * const s = styleframe();
- * const createMargin = useMarginUtility(s, {
- *     sm: '0.5rem',
- *     md: '1rem',
- *     lg: '1.5rem',
- * });
- * ```
- */
-export declare function createUseUtility<UtilityName extends string, Defaults extends Record<string, TokenValue> = Record<string, TokenValue>>(utilityName: UtilityName, factory: UtilityCallbackFn, options?: CreateUseUtilityOptions<Defaults>): <T extends Record<string, TokenValue> = Defaults>(s: Styleframe, values?: T, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
-
-export declare interface CreateUseUtilityOptions<Defaults extends Record<string, TokenValue>> {
-    /** Default values for the utility */
-    defaults?: Defaults;
-    /** Whether to merge user values with defaults (true) or replace them (false) */
-    mergeDefaults?: boolean;
-}
-
-/**
- * Creates a generic composable function for a CSS property.
- *
- * This factory function generates `use*` composables (like `useFontFamily`, `useLineHeight`, etc.)
- * from a CSS property name string.
- *
- * @param propertyName - The CSS property name (e.g., 'font-family', 'line-height')
- * @returns A composable function that creates variables for the given property
- *
- * @example
- * ```typescript
- * import { styleframe } from "styleframe";
- * import { createUseVariable } from "styleframe/theme";
- *
- * // Create a useFontFamily composable
- * const useFontFamily = createUseVariable("font-family");
- *
- * const s = styleframe();
- * const { fontFamily, fontFamilyMono } = useFontFamily(s, {
- *   default: "Arial, sans-serif",
- *   mono: "Courier, monospace",
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Create a useLineHeight composable
- * const useLineHeight = createUseVariable("line-height");
- *
- * const s = styleframe();
- * const { lineHeight, lineHeightTight, lineHeightLoose } = useLineHeight(s, {
- *   default: "1.5",
- *   tight: "1.25",
- *   loose: "1.75",
- * });
- * ```
- */
-export declare function createUseVariable<PropertyName extends string, PropertyType = TokenValue, Delimiter extends string = ".", Defaults extends Record<string, PropertyType> = Record<string, PropertyType>, MergeDefaults extends boolean = false>(propertyName: PropertyName, { defaults, mergeDefaults, transform, delimiter, }?: {
-    defaults?: Defaults;
-    mergeDefaults?: MergeDefaults;
-    transform?: (value: PropertyType) => TokenValue;
-    delimiter?: Delimiter;
-}): <T extends Record<string, PropertyType> = Defaults>(s: Styleframe, tokens?: T) => ExportKeys<PropertyName, MergeDefaults extends true ? Defaults & T : T, Delimiter>;
-
 /**
  * Default align-content utility values matching Tailwind CSS.
  */
-export declare const defaultAlignContentValues: {
+export declare const alignContentValues: {
     normal: string;
     center: string;
     start: string;
@@ -106,7 +26,7 @@ export declare const defaultAlignContentValues: {
 /**
  * Default align-items utility values matching Tailwind CSS.
  */
-export declare const defaultAlignItemsValues: {
+export declare const alignItemsValues: {
     start: string;
     end: string;
     center: string;
@@ -117,7 +37,7 @@ export declare const defaultAlignItemsValues: {
 /**
  * Default align-self utility values matching Tailwind CSS.
  */
-export declare const defaultAlignSelfValues: {
+export declare const alignSelfValues: {
     auto: string;
     start: string;
     end: string;
@@ -126,10 +46,15 @@ export declare const defaultAlignSelfValues: {
     baseline: string;
 };
 
+/**
+ * Generates all variation keys for all colors in the record
+ */
+declare type AllColorVariations<TColors extends Record<string, string>> = UnionToIntersection<ColorVariationsForKey<keyof TColors>>;
+
 /**
  * Default animation utility values matching Tailwind CSS.
  */
-export declare const defaultAnimationValues: {
+export declare const animationValues: {
     none: string;
     spin: string;
     ping: string;
@@ -140,15 +65,15 @@ export declare const defaultAnimationValues: {
 /**
  * Default appearance utility values matching Tailwind CSS.
  */
-export declare const defaultAppearanceValues: {
+export declare const appearanceValues: {
     none: string;
     auto: string;
 };
 
 /**
- * Default aspect ratio utility values matching Tailwind CSS.
+ * Default aspect-ratio utility values matching Tailwind CSS.
  */
-export declare const defaultAspectRatioValues: {
+export declare const aspectRatioValues: {
     auto: string;
     square: string;
     video: string;
@@ -157,7 +82,7 @@ export declare const defaultAspectRatioValues: {
 /**
  * Default backface-visibility utility values matching Tailwind CSS.
  */
-export declare const defaultBackfaceVisibilityValues: {
+export declare const backfaceVisibilityValues: {
     visible: string;
     hidden: string;
 };
@@ -165,7 +90,7 @@ export declare const defaultBackfaceVisibilityValues: {
 /**
  * Default background-attachment utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundAttachmentValues: {
+export declare const backgroundAttachmentValues: {
     fixed: string;
     local: string;
     scroll: string;
@@ -174,7 +99,7 @@ export declare const defaultBackgroundAttachmentValues: {
 /**
  * Default background-blend-mode utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundBlendModeValues: {
+export declare const backgroundBlendModeValues: {
     normal: string;
     multiply: string;
     screen: string;
@@ -196,7 +121,7 @@ export declare const defaultBackgroundBlendModeValues: {
 /**
  * Default background-clip utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundClipValues: {
+export declare const backgroundClipValues: {
     border: string;
     padding: string;
     content: string;
@@ -206,7 +131,7 @@ export declare const defaultBackgroundClipValues: {
 /**
  * Default background-image utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundImageValues: {
+export declare const backgroundImageValues: {
     none: string;
     "gradient-to-t": string;
     "gradient-to-tr": string;
@@ -221,7 +146,7 @@ export declare const defaultBackgroundImageValues: {
 /**
  * Default background-origin utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundOriginValues: {
+export declare const backgroundOriginValues: {
     border: string;
     padding: string;
     content: string;
@@ -230,7 +155,7 @@ export declare const defaultBackgroundOriginValues: {
 /**
  * Default background-position utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundPositionValues: {
+export declare const backgroundPositionValues: {
     bottom: string;
     center: string;
     left: string;
@@ -245,7 +170,7 @@ export declare const defaultBackgroundPositionValues: {
 /**
  * Default background-repeat utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundRepeatValues: {
+export declare const backgroundRepeatValues: {
     repeat: string;
     "no-repeat": string;
     "repeat-x": string;
@@ -257,7 +182,7 @@ export declare const defaultBackgroundRepeatValues: {
 /**
  * Default background-size utility values matching Tailwind CSS.
  */
-export declare const defaultBackgroundSizeValues: {
+export declare const backgroundSizeValues: {
     auto: string;
     cover: string;
     contain: string;
@@ -266,24 +191,23 @@ export declare const defaultBackgroundSizeValues: {
 /**
  * Default border-collapse utility values matching Tailwind CSS.
  */
-export declare const defaultBorderCollapseValues: {
+export declare const borderCollapseValues: {
     collapse: string;
     separate: string;
 };
 
-/**
- * Default border-style utility values matching Tailwind CSS.
- */
-export declare const defaultBorderStyleUtilityValues: {
-    solid: string;
-    dashed: string;
-    dotted: string;
-    double: string;
-    hidden: string;
+export declare const borderRadiusValues: {
+    default: string;
     none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    full: string;
 };
 
-export declare const defaultBorderStyleValues: {
+export declare const borderStyleValues: {
     readonly default: "@solid";
     readonly none: "none";
     readonly solid: "solid";
@@ -295,7 +219,7 @@ export declare const defaultBorderStyleValues: {
     readonly outset: "outset";
 };
 
-export declare const defaultBorderWidthValues: {
+export declare const borderWidthValues: {
     default: string;
     none: number;
     thin: string;
@@ -306,12 +230,12 @@ export declare const defaultBorderWidthValues: {
 /**
  * Default box-decoration-break utility values matching Tailwind CSS.
  */
-export declare const defaultBoxDecorationBreakValues: {
+export declare const boxDecorationBreakValues: {
     clone: string;
     slice: string;
 };
 
-export declare const defaultBoxShadowValues: {
+export declare const boxShadowValues: {
     default: string;
     none: string;
     xs: string;
@@ -327,7 +251,7 @@ export declare const defaultBoxShadowValues: {
 /**
  * Default box-sizing utility values matching Tailwind CSS.
  */
-export declare const defaultBoxSizingValues: {
+export declare const boxSizingValues: {
     border: string;
     content: string;
 };
@@ -335,7 +259,7 @@ export declare const defaultBoxSizingValues: {
 /**
  * Default break-after utility values matching Tailwind CSS.
  */
-export declare const defaultBreakAfterValues: {
+export declare const breakAfterValues: {
     auto: string;
     avoid: string;
     all: string;
@@ -349,7 +273,7 @@ export declare const defaultBreakAfterValues: {
 /**
  * Default break-before utility values matching Tailwind CSS.
  */
-export declare const defaultBreakBeforeValues: {
+export declare const breakBeforeValues: {
     auto: string;
     avoid: string;
     all: string;
@@ -363,14 +287,14 @@ export declare const defaultBreakBeforeValues: {
 /**
  * Default break-inside utility values matching Tailwind CSS.
  */
-export declare const defaultBreakInsideValues: {
+export declare const breakInsideValues: {
     auto: string;
     avoid: string;
     "avoid-page": string;
     "avoid-column": string;
 };
 
-export declare const defaultBreakpointValues: {
+export declare const breakpointValues: {
     xs: number;
     sm: number;
     md: number;
@@ -381,7 +305,7 @@ export declare const defaultBreakpointValues: {
 /**
  * Default caption-side utility values matching Tailwind CSS.
  */
-export declare const defaultCaptionSideValues: {
+export declare const captionSideValues: {
     top: string;
     bottom: string;
 };
@@ -389,7 +313,7 @@ export declare const defaultCaptionSideValues: {
 /**
  * Default clear utility values matching Tailwind CSS.
  */
-export declare const defaultClearValues: {
+export declare const clearValues: {
     start: string;
     end: string;
     left: string;
@@ -398,7 +322,7 @@ export declare const defaultClearValues: {
     none: string;
 };
 
-export declare const defaultColorLightnessValues: {
+export declare const colorLightnessValues: {
     readonly 50: 5;
     readonly 100: 10;
     readonly 200: 20;
@@ -412,34 +336,234 @@ export declare const defaultColorLightnessValues: {
     readonly 950: 95;
 };
 
+/**
+ * Color result type that strongly types base colors and all variations.
+ */
+declare type ColorResult<TColors extends Record<string, string> | false, TMerge extends boolean = false> = TColors extends false ? undefined : TColors extends Record<string, string> ? TMerge extends true ? ExportKeys<"color", Omit<DefaultColors, keyof TColors> & TColors, "."> & AllColorVariations<Omit<DefaultColors, keyof TColors> & TColors> : ExportKeys<"color", TColors, "."> & AllColorVariations<TColors> : ExportKeys<"color", DefaultColors, "."> & AllColorVariations<DefaultColors>;
+
 /**
  * Default color-scheme utility values matching Tailwind CSS.
  */
-export declare const defaultColorSchemeValues: {
+export declare const colorSchemeValues: {
     normal: string;
     light: string;
     dark: string;
     "light-dark": string;
 };
 
-export declare const defaultColorShadeValues: {
+export declare const colorShadeValues: {
     readonly 50: 5;
     readonly 100: 10;
     readonly 150: 15;
     readonly 200: 20;
 };
 
-export declare const defaultColorTintValues: {
+/**
+ * Configuration for color generation behavior
+ */
+export declare interface ColorsMetaConfig {
+    generateLightness?: boolean;
+    generateShades?: boolean;
+    generateTints?: boolean;
+    lightnessLevels?: Record<string | number, number>;
+    shadeLevels?: Record<string | number, number>;
+    tintLevels?: Record<string | number, number>;
+}
+
+export declare const colorTintValues: {
     readonly 50: 5;
     readonly 100: 10;
     readonly 150: 15;
     readonly 200: 20;
 };
 
+export declare const colorValues: {
+    primary: string;
+    secondary: string;
+    success: string;
+    warning: string;
+    danger: string;
+    info: string;
+    light: string;
+    dark: string;
+};
+
+/**
+ * Generates all variation keys for a single color name (distributive over K)
+ */
+declare type ColorVariationsForKey<K> = K extends string ? ExportKeys<`color.${K}`, DefaultLightnessLevels, "-"> & ExportKeys<`color.${K}-shade`, DefaultShadeLevels, "-"> & ExportKeys<`color.${K}-tint`, DefaultTintLevels, "-"> : never;
+
+/**
+ * Creates an autogenerate function that handles @-prefixed numeric multiplier values.
+ *
+ * When a value like "@1.5" is detected (@ prefix + numeric), it generates:
+ * - key: the numeric value as string (e.g., "1.5")
+ * - value: calc(var(--baseVariable, fallback) * multiplier)
+ *
+ * Non-multiplier values fall back to the default transformUtilityKey behavior.
+ *
+ * @example
+ * ```typescript
+ * const autogenerate = createMultiplierAutogenerate({
+ *     s,
+ *     baseVariable: "spacing",
+ *     fallback: "1rem",
+ * });
+ *
+ * // Usage with utility:
+ * const createMargin = s.utility("margin", ({ value }) => ({ margin: value }), { autogenerate });
+ * createMargin(["@1.5", "@2", "@-1"]);
+ * // Generates:
+ * // ._margin:1.5 { margin: calc(var(--spacing, 1rem) * 1.5); }
+ * // ._margin:2 { margin: calc(var(--spacing, 1rem) * 2); }
+ * // ._margin:-1 { margin: calc(var(--spacing, 1rem) * -1); }
+ * ```
+ */
+export declare function createMultiplierAutogenerate(options: CreateMultiplierAutogenerateOptions): UtilityAutogenerateFn;
+
+export declare interface CreateMultiplierAutogenerateOptions {
+    /** The Styleframe instance (required for css template literal) */
+    s: Styleframe;
+    /** The base variable to multiply against (variable object or variable name string) */
+    baseVariable: Variable | string;
+    /** Fallback value if the base variable is not defined (e.g., "1rem") */
+    fallback?: string;
+    /** Optional key replacer function for non-multiplier values */
+    replacer?: (key: string) => string;
+}
+
+/**
+ * Creates a composable function for spacing-based CSS utilities with multiplier support.
+ *
+ * This is similar to createUseUtility but adds automatic multiplier generation:
+ * - @-prefixed numeric values like "@1.5" become: calc(var(--spacing) * 1.5)
+ * - Named values and references work as normal
+ *
+ * @example
+ * ```typescript
+ * export const useMarginUtility = createUseSpacingUtility(
+ *     'margin',
+ *     ({ value }) => ({ margin: value })
+ * );
+ *
+ * // Usage:
+ * const s = styleframe();
+ * const createMargin = useMarginUtility(s, { sm: ref(spacingSm) });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createMargin(["@1.5", "@2", "@-1"]);
+ * // Generates:
+ * // ._margin:1.5 { margin: calc(var(--spacing) * 1.5); }
+ * // ._margin:2 { margin: calc(var(--spacing) * 2); }
+ * // ._margin:-1 { margin: calc(var(--spacing) * -1); }
+ * ```
+ */
+export declare function createUseSpacingUtility<UtilityName extends string, Defaults extends Record<string, TokenValue> = Record<string, TokenValue>>(utilityName: UtilityName, factory: UtilityCallbackFn, options?: CreateUseSpacingUtilityOptions<Defaults>): <T extends Record<string, TokenValue> = Defaults>(s: Styleframe, values?: T, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
+
+export declare interface CreateUseSpacingUtilityOptions<Defaults extends Record<string, TokenValue>> {
+    /** Default values for the utility */
+    defaults?: Defaults;
+    /** Whether to merge user values with defaults (true) or replace them (false) */
+    mergeDefaults?: boolean;
+    /**
+     * The base spacing variable name or Variable object.
+     * Defaults to "spacing" which references var(--spacing).
+     */
+    baseVariable?: string | Variable;
+    /**
+     * Fallback value if the base variable is not defined.
+     * Only used when baseVariable is a string. Defaults to "1rem".
+     */
+    fallback?: string;
+}
+
+/**
+ * Creates a generic composable function for a CSS utility.
+ *
+ * This factory function generates `use*Utility` composables (like `useMarginUtility`, `usePaddingUtility`, etc.)
+ * from a utility name and factory function.
+ *
+ * @param utilityName - The utility name (e.g., 'margin', 'padding')
+ * @param factory - Function that receives { value } and returns CSS declarations
+ * @param options - Configuration options
+ * @returns A composable function that creates utilities for the given property
+ *
+ * @example
+ * ```typescript
+ * // Create a useMarginUtility composable
+ * export const useMarginUtility = createUseUtility(
+ *     'm',
+ *     ({ value }) => ({ margin: value })
+ * );
+ *
+ * // Usage
+ * const s = styleframe();
+ * const createMargin = useMarginUtility(s, {
+ *     sm: '0.5rem',
+ *     md: '1rem',
+ *     lg: '1.5rem',
+ * });
+ * ```
+ */
+export declare function createUseUtility<UtilityName extends string, Defaults extends Record<string, TokenValue> = Record<string, TokenValue>>(utilityName: UtilityName, factory: UtilityCallbackFn, options?: CreateUseUtilityOptions<Defaults>): <T extends Record<string, TokenValue> = Defaults>(s: Styleframe, values?: T, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
+
+export declare interface CreateUseUtilityOptions<Defaults extends Record<string, TokenValue>> {
+    /** Default values for the utility */
+    defaults?: Defaults;
+    /** Whether to merge user values with defaults (true) or replace them (false) */
+    mergeDefaults?: boolean;
+}
+
+/**
+ * Creates a generic composable function for a CSS property.
+ *
+ * This factory function generates `use*` composables (like `useFontFamily`, `useLineHeight`, etc.)
+ * from a CSS property name string.
+ *
+ * @param propertyName - The CSS property name (e.g., 'font-family', 'line-height')
+ * @returns A composable function that creates variables for the given property
+ *
+ * @example
+ * ```typescript
+ * import { styleframe } from "styleframe";
+ * import { createUseVariable } from "styleframe/theme";
+ *
+ * // Create a useFontFamily composable
+ * const useFontFamily = createUseVariable("font-family");
+ *
+ * const s = styleframe();
+ * const { fontFamily, fontFamilyMono } = useFontFamily(s, {
+ *   default: "Arial, sans-serif",
+ *   mono: "Courier, monospace",
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create a useLineHeight composable
+ * const useLineHeight = createUseVariable("line-height");
+ *
+ * const s = styleframe();
+ * const { lineHeight, lineHeightTight, lineHeightLoose } = useLineHeight(s, {
+ *   default: "1.5",
+ *   tight: "1.25",
+ *   loose: "1.75",
+ * });
+ * ```
+ */
+export declare function createUseVariable<PropertyName extends string, PropertyType = TokenValue, Delimiter extends string = ".", Defaults extends Record<string, PropertyType> = Record<string, PropertyType>, MergeDefaults extends boolean = false>(propertyName: PropertyName, { defaults, mergeDefaults, transform, delimiter, }?: {
+    defaults?: Defaults;
+    mergeDefaults?: MergeDefaults;
+    transform?: (value: PropertyType) => TokenValue;
+    delimiter?: Delimiter;
+}): <T extends Record<string, PropertyType> = Defaults>(s: Styleframe, tokens?: T, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<PropertyName, MergeDefaults extends true ? Defaults & T : T, Delimiter>;
+
 /**
  * Default cursor utility values matching Tailwind CSS.
  */
-export declare const defaultCursorValues: {
+export declare const cursorValues: {
     auto: string;
     default: string;
     pointer: string;
@@ -478,10 +602,130 @@ export declare const defaultCursorValues: {
     "zoom-out": string;
 };
 
+declare type DefaultBorderRadius = typeof borderRadiusValues;
+
+declare type DefaultBorderStyle = typeof borderStyleValues;
+
+/**
+ * Default border-style utility values matching Tailwind CSS.
+ */
+export declare const defaultBorderStyleUtilityValues: {
+    solid: string;
+    dashed: string;
+    dotted: string;
+    double: string;
+    hidden: string;
+    none: string;
+};
+
+declare type DefaultBorderWidth = typeof borderWidthValues;
+
+declare type DefaultBoxShadow = typeof boxShadowValues;
+
+declare type DefaultBreakpoint = typeof breakpointValues;
+
+declare type DefaultColors = typeof colorValues;
+
+/**
+ * Default colors meta configuration
+ */
+export declare const defaultColorsMetaConfig: Required<ColorsMetaConfig>;
+
+declare type DefaultEasing = typeof easingValues;
+
+declare type DefaultFontFamily = typeof fontFamilyValues;
+
+declare type DefaultFontSize = typeof fontSizeValues;
+
+declare type DefaultFontStyle = typeof fontStyleValues;
+
+declare type DefaultFontWeight = typeof fontWeightValues;
+
+/**
+ * Default font-weight utility values matching Tailwind CSS.
+ */
+export declare const defaultFontWeightUtilityValues: {
+    thin: string;
+    extralight: string;
+    light: string;
+    normal: string;
+    medium: string;
+    semibold: string;
+    bold: string;
+    extrabold: string;
+    black: string;
+};
+
+declare type DefaultLetterSpacing = typeof letterSpacingValues;
+
+declare type DefaultLightnessLevels = typeof colorLightnessValues;
+
+declare type DefaultLineHeight = typeof lineHeightValues;
+
+declare type DefaultScale = typeof scaleValues;
+
+declare type DefaultShadeLevels = typeof colorShadeValues;
+
+declare type DefaultSpacing = typeof spacingValues;
+
+declare type DefaultTintLevels = typeof colorTintValues;
+
+/**
+ * Configuration options for the default design tokens preset.
+ * Generic type parameters capture the shape of each domain's configuration.
+ *
+ * - Omit or set to `undefined` to use default values
+ * - Set to `false` to disable the domain entirely
+ * - Provide a custom record to use custom values
+ * - Set `meta.merge` to `true` to merge custom values with defaults
+ */
+export declare interface DesignTokensPresetConfig<TSpacing extends Record<string, TokenValue> | false = DefaultSpacing, TBorderWidth extends Record<string, TokenValue> | false = DefaultBorderWidth, TBorderRadius extends Record<string, TokenValue> | false = DefaultBorderRadius, TBorderStyle extends Record<string, TokenValue> | false = DefaultBorderStyle, TBoxShadow extends Record<string, TokenValue> | false = DefaultBoxShadow, TColors extends Record<string, string> | false = DefaultColors, TFontFamily extends Record<string, TokenValue> | false = DefaultFontFamily, TFontSize extends Record<string, TokenValue> | false = DefaultFontSize, TFontStyle extends Record<string, TokenValue> | false = DefaultFontStyle, TFontWeight extends Record<string, TokenValue> | false = DefaultFontWeight, TLineHeight extends Record<string, TokenValue> | false = DefaultLineHeight, TLetterSpacing extends Record<string, TokenValue> | false = DefaultLetterSpacing, TScale extends Record<string, TokenValue> | false = DefaultScale, TBreakpoint extends Record<string, number> | false = DefaultBreakpoint, TEasing extends Record<string, TokenValue> | false = DefaultEasing, TMerge extends boolean = false> {
+    spacing?: TSpacing;
+    borderWidth?: TBorderWidth;
+    borderRadius?: TBorderRadius;
+    borderStyle?: TBorderStyle;
+    boxShadow?: TBoxShadow;
+    colors?: TColors;
+    meta?: MetaConfigWithMerge<TMerge>;
+    fontFamily?: TFontFamily;
+    fontSize?: TFontSize;
+    fontStyle?: TFontStyle;
+    fontWeight?: TFontWeight;
+    lineHeight?: TLineHeight;
+    letterSpacing?: TLetterSpacing;
+    scale?: TScale;
+    scalePowers?: readonly number[];
+    breakpoint?: TBreakpoint;
+    easing?: TEasing;
+}
+
+/**
+ * Result structure for the default design tokens preset.
+ * The result type reflects the exact structure based on config generics.
+ */
+export declare interface DesignTokensPresetResult<TSpacing extends Record<string, TokenValue> | false = DefaultSpacing, TBorderWidth extends Record<string, TokenValue> | false = DefaultBorderWidth, TBorderRadius extends Record<string, TokenValue> | false = DefaultBorderRadius, TBorderStyle extends Record<string, TokenValue> | false = DefaultBorderStyle, TBoxShadow extends Record<string, TokenValue> | false = DefaultBoxShadow, TColors extends Record<string, string> | false = DefaultColors, TFontFamily extends Record<string, TokenValue> | false = DefaultFontFamily, TFontSize extends Record<string, TokenValue> | false = DefaultFontSize, TFontStyle extends Record<string, TokenValue> | false = DefaultFontStyle, TFontWeight extends Record<string, TokenValue> | false = DefaultFontWeight, TLineHeight extends Record<string, TokenValue> | false = DefaultLineHeight, TLetterSpacing extends Record<string, TokenValue> | false = DefaultLetterSpacing, TScale extends Record<string, TokenValue> | false = DefaultScale, TBreakpoint extends Record<string, number> | false = DefaultBreakpoint, TEasing extends Record<string, TokenValue> | false = DefaultEasing, TMerge extends boolean = false> {
+    spacing: TokenResult<TSpacing, "spacing", DefaultSpacing, TMerge>;
+    borderWidth: TokenResult<TBorderWidth, "border-width", DefaultBorderWidth, TMerge>;
+    borderRadius: TokenResult<TBorderRadius, "border-radius", DefaultBorderRadius, TMerge>;
+    borderStyle: TokenResult<TBorderStyle, "border-style", DefaultBorderStyle, TMerge>;
+    boxShadow: TokenResult<TBoxShadow, "box-shadow", DefaultBoxShadow, TMerge>;
+    colors: ColorResult<TColors, TMerge>;
+    fontFamily: TokenResult<TFontFamily, "font-family", DefaultFontFamily, TMerge>;
+    fontSize: TokenResult<TFontSize, "font-size", DefaultFontSize, TMerge>;
+    fontStyle: TokenResult<TFontStyle, "font-style", DefaultFontStyle, TMerge>;
+    fontWeight: TokenResult<TFontWeight, "font-weight", DefaultFontWeight, TMerge>;
+    lineHeight: TokenResult<TLineHeight, "line-height", DefaultLineHeight, TMerge>;
+    letterSpacing: TokenResult<TLetterSpacing, "letter-spacing", DefaultLetterSpacing, TMerge>;
+    scale: TokenResult<TScale, "scale", DefaultScale, TMerge>;
+    scalePowers: TScale extends false ? undefined : Record<number, TokenValue>;
+    breakpoint: TokenResult<TBreakpoint, "breakpoint", DefaultBreakpoint, TMerge>;
+    easing: TokenResult<TEasing, "easing", DefaultEasing, TMerge>;
+}
+
 /**
  * Default display utility values matching Tailwind CSS.
  */
-export declare const defaultDisplayValues: {
+export declare const displayValues: {
     block: string;
     "inline-block": string;
     inline: string;
@@ -508,7 +752,7 @@ export declare const defaultDisplayValues: {
 /**
  * Default divide-style utility values matching Tailwind CSS.
  */
-export declare const defaultDivideStyleValues: {
+export declare const divideStyleValues: {
     solid: string;
     dashed: string;
     dotted: string;
@@ -516,7 +760,7 @@ export declare const defaultDivideStyleValues: {
     none: string;
 };
 
-export declare const defaultEasingValues: {
+export declare const easingValues: {
     readonly linear: "linear";
     readonly ease: "ease";
     readonly "ease-in": "ease-in";
@@ -550,10 +794,28 @@ export declare const defaultEasingValues: {
     readonly bounce: "linear(0, 0.004, 0.016, 0.035, 0.063, 0.098, 0.141 13.6%, 0.25, 0.391, 0.563, 0.765, 1, 0.891 40.9%, 0.848, 0.813, 0.785, 0.766, 0.754, 0.75, 0.754, 0.766, 0.785, 0.813, 0.848, 0.891 68.2%, 1 72.7%, 0.973, 0.953, 0.941, 0.938, 0.941, 0.953, 0.973, 1, 0.988, 0.984, 0.988, 1)";
 };
 
+/**
+ * Generic type that transforms keys to their export names with a given prefix
+ *
+ * @example
+ * ExportKeys<"example-property", { "default": "...", "variant": "..." }> -> {
+ * 		"exampleProperty": Variable<'example-property'>,
+ * 		"examplePropertyVariant": Variable<'example-property.variant'>,
+ * }
+ */
+export declare type ExportKeys<Prefix extends string, T extends Record<string, unknown>, Separator extends string = "."> = {
+    [K in keyof T as CamelCase<ExportKeyVariableName<Prefix, K, Separator>>]: Variable<ExportKeyVariableName<Prefix, K, Separator>>;
+};
+
+/**
+ * Helper type to compute the variable name for a given prefix and key
+ */
+declare type ExportKeyVariableName<Prefix extends string, K, Separator extends string = "."> = K extends "default" ? Prefix : `${Prefix}${Separator}${K & (string | number)}`;
+
 /**
  * Default flex-direction utility values matching Tailwind CSS.
  */
-export declare const defaultFlexDirectionValues: {
+export declare const flexDirectionValues: {
     row: string;
     "row-reverse": string;
     col: string;
@@ -563,7 +825,7 @@ export declare const defaultFlexDirectionValues: {
 /**
  * Default flex utility values matching Tailwind CSS.
  */
-export declare const defaultFlexValues: {
+export declare const flexValues: {
     "1": string;
     auto: string;
     initial: string;
@@ -573,7 +835,7 @@ export declare const defaultFlexValues: {
 /**
  * Default flex-wrap utility values matching Tailwind CSS.
  */
-export declare const defaultFlexWrapValues: {
+export declare const flexWrapValues: {
     wrap: string;
     "wrap-reverse": string;
     nowrap: string;
@@ -582,7 +844,7 @@ export declare const defaultFlexWrapValues: {
 /**
  * Default float utility values matching Tailwind CSS.
  */
-export declare const defaultFloatValues: {
+export declare const floatValues: {
     start: string;
     end: string;
     right: string;
@@ -590,21 +852,29 @@ export declare const defaultFloatValues: {
     none: string;
 };
 
-export declare const defaultFontFamilyValues: {
+export declare const fontFamilyValues: {
     default: string;
     base: string;
     print: string;
     mono: string;
 };
 
-export declare const defaultFontSizeValues: {
+export declare const fontSizeValues: {
     default: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+    "4xl": string;
 };
 
 /**
  * Default font-smoothing utility values matching Tailwind CSS.
  */
-export declare const defaultFontSmoothingValues: {
+export declare const fontSmoothingValues: {
     antialiased: string;
     "subpixel-antialiased": string;
 };
@@ -612,7 +882,7 @@ export declare const defaultFontSmoothingValues: {
 /**
  * Default font-stretch utility values matching Tailwind CSS.
  */
-export declare const defaultFontStretchValues: {
+export declare const fontStretchValues: {
     "ultra-condensed": string;
     "extra-condensed": string;
     condensed: string;
@@ -624,18 +894,18 @@ export declare const defaultFontStretchValues: {
     "ultra-expanded": string;
 };
 
-/**
- * Default font-style utility values matching Tailwind CSS.
- */
-export declare const defaultFontStyleValues: {
+export declare const fontStyleValues: {
+    default: string;
     italic: string;
-    "not-italic": string;
+    oblique: string;
+    normal: string;
+    inherit: string;
 };
 
 /**
  * Default font-variant-numeric utility values matching Tailwind CSS.
  */
-export declare const defaultFontVariantNumericValues: {
+export declare const fontVariantNumericValues: {
     "normal-nums": string;
     ordinal: string;
     "slashed-zero": string;
@@ -644,25 +914,10 @@ export declare const defaultFontVariantNumericValues: {
     "proportional-nums": string;
     "tabular-nums": string;
     "diagonal-fractions": string;
-    "stacked-fractions": string;
-};
-
-/**
- * Default font-weight utility values matching Tailwind CSS.
- */
-export declare const defaultFontWeightUtilityValues: {
-    thin: string;
-    extralight: string;
-    light: string;
-    normal: string;
-    medium: string;
-    semibold: string;
-    bold: string;
-    extrabold: string;
-    black: string;
+    "stacked-fractions": string;
 };
 
-export declare const defaultFontWeightValues: {
+export declare const fontWeightValues: {
     default: string;
     extralight: number;
     light: number;
@@ -679,7 +934,7 @@ export declare const defaultFontWeightValues: {
 /**
  * Default forced-color-adjust utility values matching Tailwind CSS.
  */
-export declare const defaultForcedColorAdjustValues: {
+export declare const forcedColorAdjustValues: {
     auto: string;
     none: string;
 };
@@ -687,7 +942,7 @@ export declare const defaultForcedColorAdjustValues: {
 /**
  * Default grid-auto-flow utility values matching Tailwind CSS.
  */
-export declare const defaultGridAutoFlowValues: {
+export declare const gridAutoFlowValues: {
     row: string;
     col: string;
     dense: string;
@@ -698,16 +953,31 @@ export declare const defaultGridAutoFlowValues: {
 /**
  * Default hyphens utility values matching Tailwind CSS.
  */
-export declare const defaultHyphensValues: {
+export declare const hyphensValues: {
     none: string;
     manual: string;
     auto: string;
 };
 
+export declare function isKeyReferenceValue(value: unknown): value is `@${string}`;
+
+/**
+ * Check if a value is a numeric string or number (including negative numbers and decimals).
+ *
+ * @example
+ * isNumericValue(1) // true
+ * isNumericValue("1.5") // true
+ * isNumericValue("-0.5") // true
+ * isNumericValue(".5") // true
+ * isNumericValue("sm") // false
+ * isNumericValue("1rem") // false
+ */
+export declare function isNumericValue(value: unknown): value is string | number;
+
 /**
  * Default isolation utility values matching Tailwind CSS.
  */
-export declare const defaultIsolationValues: {
+export declare const isolationValues: {
     isolate: string;
     auto: string;
 };
@@ -715,7 +985,7 @@ export declare const defaultIsolationValues: {
 /**
  * Default justify-content utility values matching Tailwind CSS.
  */
-export declare const defaultJustifyContentValues: {
+export declare const justifyContentValues: {
     normal: string;
     start: string;
     end: string;
@@ -729,7 +999,7 @@ export declare const defaultJustifyContentValues: {
 /**
  * Default justify-items utility values matching Tailwind CSS.
  */
-export declare const defaultJustifyItemsValues: {
+export declare const justifyItemsValues: {
     start: string;
     end: string;
     center: string;
@@ -739,7 +1009,7 @@ export declare const defaultJustifyItemsValues: {
 /**
  * Default justify-self utility values matching Tailwind CSS.
  */
-export declare const defaultJustifySelfValues: {
+export declare const justifySelfValues: {
     auto: string;
     start: string;
     end: string;
@@ -747,7 +1017,7 @@ export declare const defaultJustifySelfValues: {
     stretch: string;
 };
 
-export declare const defaultLetterSpacingValues: {
+export declare const letterSpacingValues: {
     default: string;
     tighter: string;
     tight: string;
@@ -756,7 +1026,7 @@ export declare const defaultLetterSpacingValues: {
     wider: string;
 };
 
-export declare const defaultLineHeightValues: {
+export declare const lineHeightValues: {
     default: string;
     tight: number;
     snug: number;
@@ -768,7 +1038,7 @@ export declare const defaultLineHeightValues: {
 /**
  * Default list-style-position utility values matching Tailwind CSS.
  */
-export declare const defaultListStylePositionValues: {
+export declare const listStylePositionValues: {
     inside: string;
     outside: string;
 };
@@ -776,16 +1046,35 @@ export declare const defaultListStylePositionValues: {
 /**
  * Default list-style-type utility values matching Tailwind CSS.
  */
-export declare const defaultListStyleTypeValues: {
+export declare const listStyleTypeValues: {
     none: string;
     disc: string;
     decimal: string;
 };
 
+/**
+ * Meta configuration for advanced options
+ */
+export declare interface MetaConfig {
+    /**
+     * When true, custom values are merged with defaults instead of replacing them.
+     * Custom values override defaults with the same key.
+     */
+    merge?: boolean;
+    colors?: ColorsMetaConfig;
+}
+
+/**
+ * Meta configuration with merge option typed for inference
+ */
+export declare type MetaConfigWithMerge<TMerge extends boolean = false> = Omit<MetaConfig, "merge"> & {
+    merge?: TMerge;
+};
+
 /**
  * Default mix-blend-mode utility values matching Tailwind CSS.
  */
-export declare const defaultMixBlendModeValues: {
+export declare const mixBlendModeValues: {
     normal: string;
     multiply: string;
     screen: string;
@@ -809,7 +1098,7 @@ export declare const defaultMixBlendModeValues: {
 /**
  * Default object-fit utility values matching Tailwind CSS.
  */
-export declare const defaultObjectFitValues: {
+export declare const objectFitValues: {
     contain: string;
     cover: string;
     fill: string;
@@ -820,7 +1109,7 @@ export declare const defaultObjectFitValues: {
 /**
  * Default object-position utility values matching Tailwind CSS.
  */
-export declare const defaultObjectPositionValues: {
+export declare const objectPositionValues: {
     bottom: string;
     center: string;
     left: string;
@@ -835,7 +1124,7 @@ export declare const defaultObjectPositionValues: {
 /**
  * Default outline-style utility values matching Tailwind CSS.
  */
-export declare const defaultOutlineStyleValues: {
+export declare const outlineStyleValues: {
     none: string;
     solid: string;
     dashed: string;
@@ -846,7 +1135,7 @@ export declare const defaultOutlineStyleValues: {
 /**
  * Default overflow utility values matching Tailwind CSS.
  */
-export declare const defaultOverflowValues: {
+export declare const overflowValues: {
     auto: string;
     hidden: string;
     clip: string;
@@ -857,16 +1146,16 @@ export declare const defaultOverflowValues: {
 /**
  * Default overflow-wrap utility values matching Tailwind CSS.
  */
-export declare const defaultOverflowWrapValues: {
+export declare const overflowWrapValues: {
     normal: string;
     "break-word": string;
     anywhere: string;
 };
 
 /**
- * Default overscroll-behavior utility values matching Tailwind CSS.
+ * Default overscroll utility values matching Tailwind CSS.
  */
-export declare const defaultOverscrollValues: {
+export declare const overscrollValues: {
     auto: string;
     contain: string;
     none: string;
@@ -875,7 +1164,7 @@ export declare const defaultOverscrollValues: {
 /**
  * Default perspective-origin utility values matching Tailwind CSS.
  */
-export declare const defaultPerspectiveOriginValues: {
+export declare const perspectiveOriginValues: {
     center: string;
     top: string;
     "top-right": string;
@@ -890,7 +1179,7 @@ export declare const defaultPerspectiveOriginValues: {
 /**
  * Default place-content utility values matching Tailwind CSS.
  */
-export declare const defaultPlaceContentValues: {
+export declare const placeContentValues: {
     center: string;
     start: string;
     end: string;
@@ -904,7 +1193,7 @@ export declare const defaultPlaceContentValues: {
 /**
  * Default place-items utility values matching Tailwind CSS.
  */
-export declare const defaultPlaceItemsValues: {
+export declare const placeItemsValues: {
     start: string;
     end: string;
     center: string;
@@ -915,7 +1204,7 @@ export declare const defaultPlaceItemsValues: {
 /**
  * Default place-self utility values matching Tailwind CSS.
  */
-export declare const defaultPlaceSelfValues: {
+export declare const placeSelfValues: {
     auto: string;
     start: string;
     end: string;
@@ -926,7 +1215,7 @@ export declare const defaultPlaceSelfValues: {
 /**
  * Default pointer-events utility values matching Tailwind CSS.
  */
-export declare const defaultPointerEventsValues: {
+export declare const pointerEventsValues: {
     none: string;
     auto: string;
 };
@@ -934,7 +1223,7 @@ export declare const defaultPointerEventsValues: {
 /**
  * Default position utility values matching Tailwind CSS.
  */
-export declare const defaultPositionValues: {
+export declare const positionValues: {
     static: string;
     fixed: string;
     absolute: string;
@@ -945,16 +1234,25 @@ export declare const defaultPositionValues: {
 /**
  * Default resize utility values matching Tailwind CSS.
  */
-export declare const defaultResizeValues: {
+export declare const resizeValues: {
     none: string;
     y: string;
     x: string;
     both: string;
 };
 
-export declare const defaultScalePowerValues: readonly number[];
+/**
+ * Resolves which value record to use based on config:
+ * - false => never (will be undefined)
+ * - undefined => default values
+ * - custom record => that record (or merged with defaults if TMerge is true)
+ */
+declare type ResolveTokens<TConfig, TDefault extends Record<string, unknown>, TMerge extends boolean = false> = TConfig extends false ? never : TConfig extends undefined ? TDefault : TConfig extends Record<string, unknown> ? TMerge extends true ? Omit<TDefault, keyof TConfig> & TConfig : TConfig : TDefault;
 
-export declare const defaultScaleValues: {
+export declare const scalePowerValues: readonly number[];
+
+/** biome-ignore-all lint/suspicious/noApproximativeNumericConstant: Scale ratios are magic numbers */
+export declare const scaleValues: {
     readonly default: "@minor-third";
     readonly "minor-second": 1.067;
     readonly "major-second": 1.125;
@@ -969,7 +1267,7 @@ export declare const defaultScaleValues: {
 /**
  * Default scroll-behavior utility values matching Tailwind CSS.
  */
-export declare const defaultScrollBehaviorValues: {
+export declare const scrollBehaviorValues: {
     auto: string;
     smooth: string;
 };
@@ -977,7 +1275,7 @@ export declare const defaultScrollBehaviorValues: {
 /**
  * Default scroll-snap-align utility values matching Tailwind CSS.
  */
-export declare const defaultScrollSnapAlignValues: {
+export declare const scrollSnapAlignValues: {
     start: string;
     end: string;
     center: string;
@@ -987,7 +1285,7 @@ export declare const defaultScrollSnapAlignValues: {
 /**
  * Default scroll-snap-stop utility values matching Tailwind CSS.
  */
-export declare const defaultScrollSnapStopValues: {
+export declare const scrollSnapStopValues: {
     normal: string;
     always: string;
 };
@@ -995,7 +1293,7 @@ export declare const defaultScrollSnapStopValues: {
 /**
  * Default scroll-snap-type utility values matching Tailwind CSS.
  */
-export declare const defaultScrollSnapTypeValues: {
+export declare const scrollSnapTypeValues: {
     none: string;
     x: string;
     y: string;
@@ -1004,10 +1302,22 @@ export declare const defaultScrollSnapTypeValues: {
     proximity: string;
 };
 
+export declare const spacingValues: {
+    default: string;
+    "2xs": string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+};
+
 /**
  * Default table-layout utility values matching Tailwind CSS.
  */
-export declare const defaultTableLayoutValues: {
+export declare const tableLayoutValues: {
     auto: string;
     fixed: string;
 };
@@ -1015,7 +1325,7 @@ export declare const defaultTableLayoutValues: {
 /**
  * Default text-align utility values matching Tailwind CSS.
  */
-export declare const defaultTextAlignValues: {
+export declare const textAlignValues: {
     left: string;
     center: string;
     right: string;
@@ -1027,7 +1337,7 @@ export declare const defaultTextAlignValues: {
 /**
  * Default text-decoration-line utility values matching Tailwind CSS.
  */
-export declare const defaultTextDecorationLineValues: {
+export declare const textDecorationLineValues: {
     underline: string;
     overline: string;
     "line-through": string;
@@ -1037,7 +1347,7 @@ export declare const defaultTextDecorationLineValues: {
 /**
  * Default text-decoration-style utility values matching Tailwind CSS.
  */
-export declare const defaultTextDecorationStyleValues: {
+export declare const textDecorationStyleValues: {
     solid: string;
     double: string;
     dotted: string;
@@ -1048,7 +1358,7 @@ export declare const defaultTextDecorationStyleValues: {
 /**
  * Default text-overflow utility values matching Tailwind CSS.
  */
-export declare const defaultTextOverflowValues: {
+export declare const textOverflowValues: {
     truncate: string;
     "text-ellipsis": string;
     "text-clip": string;
@@ -1057,7 +1367,7 @@ export declare const defaultTextOverflowValues: {
 /**
  * Default text-transform utility values matching Tailwind CSS.
  */
-export declare const defaultTextTransformValues: {
+export declare const textTransformValues: {
     uppercase: string;
     lowercase: string;
     capitalize: string;
@@ -1067,17 +1377,22 @@ export declare const defaultTextTransformValues: {
 /**
  * Default text-wrap utility values matching Tailwind CSS.
  */
-export declare const defaultTextWrapValues: {
+export declare const textWrapValues: {
     wrap: string;
     nowrap: string;
     balance: string;
     pretty: string;
 };
 
+/**
+ * Generates ExportKeys or undefined based on config
+ */
+declare type TokenResult<TConfig, TPrefix extends string, TDefault extends Record<string, unknown>, TMerge extends boolean = false, TSeparator extends string = "."> = TConfig extends false ? undefined : ExportKeys<TPrefix, ResolveTokens<TConfig, TDefault, TMerge>, TSeparator>;
+
 /**
  * Default touch-action utility values matching Tailwind CSS.
  */
-export declare const defaultTouchActionValues: {
+export declare const touchActionValues: {
     auto: string;
     none: string;
     "pan-x": string;
@@ -1093,7 +1408,7 @@ export declare const defaultTouchActionValues: {
 /**
  * Default transform-origin utility values matching Tailwind CSS.
  */
-export declare const defaultTransformOriginValues: {
+export declare const transformOriginValues: {
     center: string;
     top: string;
     "top-right": string;
@@ -1108,7 +1423,7 @@ export declare const defaultTransformOriginValues: {
 /**
  * Default transform-style utility values matching Tailwind CSS.
  */
-export declare const defaultTransformStyleValues: {
+export declare const transformStyleValues: {
     flat: string;
     "3d": string;
 };
@@ -1116,7 +1431,7 @@ export declare const defaultTransformStyleValues: {
 /**
  * Default transition-behavior utility values matching Tailwind CSS.
  */
-export declare const defaultTransitionBehaviorValues: {
+export declare const transitionBehaviorValues: {
     normal: string;
     "allow-discrete": string;
 };
@@ -1124,7 +1439,7 @@ export declare const defaultTransitionBehaviorValues: {
 /**
  * Default transition-property utility values matching Tailwind CSS.
  */
-export declare const defaultTransitionPropertyValues: {
+export declare const transitionPropertyValues: {
     none: string;
     all: string;
     default: string;
@@ -1135,89 +1450,9 @@ export declare const defaultTransitionPropertyValues: {
 };
 
 /**
- * Default user-select utility values matching Tailwind CSS.
- */
-export declare const defaultUserSelectValues: {
-    none: string;
-    text: string;
-    all: string;
-    auto: string;
-};
-
-/**
- * Default vertical-align utility values matching Tailwind CSS.
- */
-export declare const defaultVerticalAlignValues: {
-    baseline: string;
-    top: string;
-    middle: string;
-    bottom: string;
-    "text-top": string;
-    "text-bottom": string;
-    sub: string;
-    super: string;
-};
-
-/**
- * Default visibility utility values matching Tailwind CSS.
- */
-export declare const defaultVisibilityValues: {
-    visible: string;
-    invisible: string;
-    collapse: string;
-};
-
-/**
- * Default white-space utility values matching Tailwind CSS.
- */
-export declare const defaultWhitespaceValues: {
-    normal: string;
-    nowrap: string;
-    pre: string;
-    "pre-line": string;
-    "pre-wrap": string;
-    "break-spaces": string;
-};
-
-/**
- * Default will-change utility values matching Tailwind CSS.
- */
-export declare const defaultWillChangeValues: {
-    auto: string;
-    scroll: string;
-    contents: string;
-    transform: string;
-};
-
-/**
- * Default word-break utility values matching Tailwind CSS.
- */
-export declare const defaultWordBreakValues: {
-    normal: string;
-    words: string;
-    all: string;
-    keep: string;
-};
-
-/**
- * Generic type that transforms keys to their export names with a given prefix
- *
- * @example
- * ExportKeys<"example-property", { "default": "...", "variant": "..." }> -> {
- * 		"exampleProperty": Variable<'example-property'>,
- * 		"examplePropertyVariant": Variable<'example-property.variant'>,
- * }
- */
-export declare type ExportKeys<Prefix extends string, T extends Record<string, unknown>, Separator extends string = "."> = {
-    [K in keyof T as CamelCase<ExportKeyVariableName<Prefix, K, Separator>>]: Variable<ExportKeyVariableName<Prefix, K, Separator>>;
-};
-
-/**
- * Helper type to compute the variable name for a given prefix and key
+ * Helper to convert a union to an intersection
  */
-declare type ExportKeyVariableName<Prefix extends string, K, Separator extends string = "."> = K extends "default" ? Prefix : `${Prefix}${Separator}${K & (string | number)}`;
-
-export declare function isKeyReferenceValue(value: unknown): value is `@${string}`;
+declare type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 
 /**
  * Create accent-color utility classes.
@@ -1474,6 +1709,21 @@ export declare const useBackgroundSizeUtility: <T extends Record<string, TokenVa
     contain: string;
 }>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
+/**
+ * Create background shorthand utility classes.
+ *
+ * @example
+ * ```typescript
+ * const s = styleframe();
+ * useBackgroundUtility(s, {
+ *     none: 'none',
+ *     cover: 'center / cover no-repeat',
+ *     contain: 'center / contain no-repeat',
+ * });
+ * ```
+ */
+export declare const useBackgroundUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
+
 /**
  * Create blur utility classes.
  *
@@ -1526,7 +1776,9 @@ export declare const useBorderCollapseUtility: <T extends Record<string, TokenVa
  * });
  * ```
  */
-export declare const useBorderColor: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"border-color", T, ".">;
+export declare const useBorderColor: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"border-color", T, ".">;
 
 /**
  * Create border-bottom-color utility classes.
@@ -1608,7 +1860,18 @@ export declare const useBorderColorYUtility: <T extends Record<string, TokenValu
  * });
  * ```
  */
-export declare const useBorderRadius: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"border-radius", T, ".">;
+export declare const useBorderRadius: <T extends Record<string, TokenValue> = {
+    default: string;
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    full: string;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"border-radius", T, ".">;
 
 /**
  * Create border-bottom-left-radius utility classes.
@@ -1755,7 +2018,9 @@ export declare const useBorderStyle: <T extends Record<string, TokenValue> = {
     readonly groove: "groove";
     readonly inset: "inset";
     readonly outset: "outset";
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"border-style", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"border-style", T, ".">;
 
 /**
  * Create border-style utility classes.
@@ -1800,7 +2065,9 @@ export declare const useBorderWidth: <T extends Record<string, TokenValue> = {
     thin: string;
     medium: string;
     thick: string;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"border-width", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"border-width", T, ".">;
 
 /**
  * Create border-bottom-width utility classes.
@@ -1909,7 +2176,9 @@ export declare const useBoxShadow: <T extends Record<string, TokenValue> = {
     "2xl": string;
     inner: string;
     ring: string;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"box-shadow", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"box-shadow", T, ".">;
 
 /**
  * Create box-shadow-color utility classes.
@@ -2013,7 +2282,9 @@ export declare const useBreakpoint: <T extends Record<string, TokenValue> = {
     md: number;
     lg: number;
     xl: number;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"breakpoint", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"breakpoint", T, ".">;
 
 /**
  * Create brightness utility classes.
@@ -2064,7 +2335,9 @@ export declare const useClearUtility: <T extends Record<string, TokenValue> = {
  * });
  * ```
  */
-export declare const useColor: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"color", T, ".">;
+export declare const useColor: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"color", T, ".">;
 
 /**
  * Create a set of lightness levels for a color variable.
@@ -2091,7 +2364,9 @@ export declare const useColor: <T extends Record<string, TokenValue> = Record<st
  * });
  * ```
  */
-export declare function useColorLightness<Name extends string, T extends Record<string | number, number>>(s: Styleframe, color: Variable<Name>, levels: T): ExportKeys<Name, T, "-">;
+export declare function useColorLightness<Name extends string, T extends Record<string | number, number>>(s: Styleframe, color: Variable<Name>, levels: T, { default: isDefault }?: {
+    default?: boolean;
+}): ExportKeys<Name, T, "-">;
 
 /**
  * Create color-scheme utility classes.
@@ -2124,7 +2399,9 @@ export declare const useColorSchemeUtility: <T extends Record<string, TokenValue
  * });
  * ```
  */
-export declare function useColorShade<Name extends string, T extends Record<string | number, number>>(s: Styleframe, color: Variable<Name>, levels: T): ExportKeys<`${Name}-shade`, T, "-">;
+export declare function useColorShade<Name extends string, T extends Record<string | number, number>>(s: Styleframe, color: Variable<Name>, levels: T, { default: isDefault }?: {
+    default?: boolean;
+}): ExportKeys<`${Name}-shade`, T, "-">;
 
 /**
  * Create a set of relative color tint (lighter) levels
@@ -2147,7 +2424,9 @@ export declare function useColorShade<Name extends string, T extends Record<stri
  * });
  * ```
  */
-export declare function useColorTint<Name extends string, T extends Record<string | number, number>>(s: Styleframe, color: Variable<Name>, levels: T): ExportKeys<`${Name}-tint`, T, "-">;
+export declare function useColorTint<Name extends string, T extends Record<string | number, number>>(s: Styleframe, color: Variable<Name>, levels: T, { default: isDefault }?: {
+    default?: boolean;
+}): ExportKeys<`${Name}-tint`, T, "-">;
 
 /**
  * Create color utility classes.
@@ -2246,6 +2525,57 @@ export declare const useCursorUtility: <T extends Record<string, TokenValue> = {
     "zoom-out": string;
 }>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
+/**
+ * Create a complete design token system with sensible defaults.
+ *
+ * @param s - The Styleframe instance
+ * @param config - Configuration options for customizing the preset
+ * @returns An object containing all generated design token variables
+ *
+ * @remarks
+ * **Scale Powers**: The `scalePowers` result is only generated when the `scale` config
+ * includes a key named `scale` (either via defaults or a custom config with `{ default: "@scale", scale: "1.2" }`).
+ * If you provide a custom scale config without a `scale` key (e.g., `{ ratio: "1.25" }`),
+ * `scalePowers` will be `undefined`.
+ *
+ * @example
+ * ```typescript
+ * import { styleframe } from "styleframe";
+ * import { useDesignTokensPreset } from "@styleframe/theme";
+ *
+ * const s = styleframe();
+ *
+ * // Use all defaults
+ * const tokens = useDesignTokensPreset(s);
+ *
+ * // Customize specific domains
+ * const tokens = useDesignTokensPreset(s, {
+ *     colors: { primary: "#ff6600", secondary: "#333" },
+ *     meta: {
+ *         colors: {
+ *             generateLightness: true,
+ *             generateShades: false,
+ *         },
+ *     },
+ *     spacing: {
+ *         default: "0.5rem",
+ *         sm: "0.25rem",
+ *         md: "0.5rem",
+ *         lg: "1rem",
+ *     },
+ *     easing: false, // Disable easing entirely
+ * });
+ *
+ * // Merge custom values with defaults
+ * const tokens = useDesignTokensPreset(s, {
+ *     meta: { merge: true },
+ *     spacing: { xl: "2rem", xxl: "4rem" }, // Added to default spacing values
+ *     colors: { brand: "#ff6600" }, // Added to default colors
+ * });
+ * ```
+ */
+export declare function useDesignTokensPreset<TSpacing extends Record<string, TokenValue> | false = DefaultSpacing, TBorderWidth extends Record<string, TokenValue> | false = DefaultBorderWidth, TBorderRadius extends Record<string, TokenValue> | false = DefaultBorderRadius, TBorderStyle extends Record<string, TokenValue> | false = DefaultBorderStyle, TBoxShadow extends Record<string, TokenValue> | false = DefaultBoxShadow, TColors extends Record<string, string> | false = DefaultColors, TFontFamily extends Record<string, TokenValue> | false = DefaultFontFamily, TFontSize extends Record<string, TokenValue> | false = DefaultFontSize, TFontStyle extends Record<string, TokenValue> | false = DefaultFontStyle, TFontWeight extends Record<string, TokenValue> | false = DefaultFontWeight, TLineHeight extends Record<string, TokenValue> | false = DefaultLineHeight, TLetterSpacing extends Record<string, TokenValue> | false = DefaultLetterSpacing, TScale extends Record<string, TokenValue> | false = DefaultScale, TBreakpoint extends Record<string, number> | false = DefaultBreakpoint, TEasing extends Record<string, TokenValue> | false = DefaultEasing, TMerge extends boolean = false>(s: Styleframe, config?: DesignTokensPresetConfig<TSpacing, TBorderWidth, TBorderRadius, TBorderStyle, TBoxShadow, TColors, TFontFamily, TFontSize, TFontStyle, TFontWeight, TLineHeight, TLetterSpacing, TScale, TBreakpoint, TEasing, TMerge>): DesignTokensPresetResult<TSpacing, TBorderWidth, TBorderRadius, TBorderStyle, TBoxShadow, TColors, TFontFamily, TFontSize, TFontStyle, TFontWeight, TLineHeight, TLetterSpacing, TScale, TBreakpoint, TEasing, TMerge>;
+
 /**
  * Create display utility classes.
  *
@@ -2383,7 +2713,9 @@ export declare const useEasing: <T extends Record<string, TokenValue> = {
     readonly "ease-in-out-back": "cubic-bezier(0.68, -0.55, 0.265, 1.55)";
     readonly spring: "linear(0, 0.0018, 0.0069 1.15%, 0.026 2.3%, 0.0637, 0.1135 5.18%, 0.2229 7.78%, 0.5977 15.84%, 0.7014, 0.7904, 0.8641, 0.9228, 0.9676 28.8%, 1.0032 31.68%, 1.0225, 1.0352 36.29%, 1.0431 38.88%, 1.046 42.05%, 1.0448 44.35%, 1.0407 47.23%, 1.0118 61.63%, 1.0025 69.41%, 0.9981 80.35%, 0.9992 99.94%)";
     readonly bounce: "linear(0, 0.004, 0.016, 0.035, 0.063, 0.098, 0.141 13.6%, 0.25, 0.391, 0.563, 0.765, 1, 0.891 40.9%, 0.848, 0.813, 0.785, 0.766, 0.754, 0.75, 0.754, 0.766, 0.785, 0.813, 0.848, 0.891 68.2%, 1 72.7%, 0.973, 0.953, 0.941, 0.938, 0.941, 0.953, 0.973, 1, 0.988, 0.984, 0.988, 1)";
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"easing", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"easing", T, ".">;
 
 /**
  * Create fill utility classes for SVG elements.
@@ -2488,7 +2820,9 @@ export declare const useFontFamily: <T extends Record<string, TokenValue> = {
     base: string;
     print: string;
     mono: string;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"font-family", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"font-family", T, ".">;
 
 /**
  * Create font-family utility classes.
@@ -2530,7 +2864,17 @@ export declare const useFontFamilyUtility: <T extends Record<string, TokenValue>
  */
 export declare const useFontSize: <T extends Record<string, TokenValue> = {
     default: string;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"font-size", T, ".">;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+    "4xl": string;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"font-size", T, ".">;
 
 /**
  * Create font-size utility classes.
@@ -2572,12 +2916,49 @@ export declare const useFontStretchUtility: <T extends Record<string, TokenValue
     "ultra-expanded": string;
 }>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
+/**
+ * Create a set of font-style variables for use in a Styleframe instance.
+ *
+ * @usage
+ * ```typescript
+ * import { styleframe } from "styleframe";
+ * import { useFontStyle } from "styleframe/theme";
+ *
+ * const s = styleframe();
+ *
+ * const {
+ *   fontStyleItalic,
+ *   fontStyleOblique,
+ *   fontStyleNormal,
+ *   fontStyle,
+ * } = useFontStyle(s, {
+ *   default: "normal",
+ *   italic: "italic",
+ *   oblique: "oblique",
+ *   normal: "normal",
+ *   inherit: "inherit",
+ * });
+ * ```
+ */
+export declare const useFontStyle: <T extends Record<string, TokenValue> = {
+    default: string;
+    italic: string;
+    oblique: string;
+    normal: string;
+    inherit: string;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"font-style", T, ".">;
+
 /**
  * Create font-style utility classes.
  */
 export declare const useFontStyleUtility: <T extends Record<string, TokenValue> = {
+    default: string;
     italic: string;
-    "not-italic": string;
+    oblique: string;
+    normal: string;
+    inherit: string;
 }>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
@@ -2643,7 +3024,9 @@ export declare const useFontWeight: <T extends Record<string, TokenValue> = {
     lighter: string;
     bolder: string;
     inherit: string;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"font-weight", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"font-weight", T, ".">;
 
 /**
  * Create font-weight utility classes.
@@ -2669,23 +3052,29 @@ export declare const useForcedColorAdjustUtility: <T extends Record<string, Toke
 }>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create gap utility classes.
+ * Create gap utility classes with multiplier support.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * useGapUtility(s, { '0': '0', '1': '0.25rem', '2': '0.5rem' });
+ * const createGap = useGapUtility(s, { '0': '0', '1': '0.25rem', '2': '0.5rem' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createGap(["@1.5", "@2"]);
+ * // Generates:
+ * // ._gap:1.5 { gap: calc(var(--spacing) * 1.5); }
+ * // ._gap:2 { gap: calc(var(--spacing) * 2); }
  * ```
  */
 export declare const useGapUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create column-gap utility classes.
+ * Create column-gap utility classes with multiplier support.
  */
 export declare const useGapXUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create row-gap utility classes.
+ * Create row-gap utility classes with multiplier support.
  */
 export declare const useGapYUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
@@ -2930,7 +3319,9 @@ export declare const useLetterSpacing: <T extends Record<string, TokenValue> = {
     normal: string;
     wide: string;
     wider: string;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"letter-spacing", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"letter-spacing", T, ".">;
 
 /**
  * Create letter-spacing utility classes.
@@ -2996,7 +3387,9 @@ export declare const useLineHeight: <T extends Record<string, TokenValue> = {
     normal: number;
     relaxed: number;
     loose: number;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"line-height", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"line-height", T, ".">;
 
 /**
  * Create line-height utility classes.
@@ -3079,13 +3472,19 @@ export declare const useMarginRightUtility: <T extends Record<string, TokenValue
 export declare const useMarginTopUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create margin utility classes.
+ * Create margin utility classes with multiplier support.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * useMarginUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem', auto: 'auto' });
- * // Generates: ._margin:sm, ._margin:md, ._margin:lg, ._margin:auto
+ * const createMargin = useMarginUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem', auto: 'auto' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createMargin(["@1.5", "@2", "@-1"]);
+ * // Generates:
+ * // ._margin:1.5 { margin: calc(var(--spacing) * 1.5); }
+ * // ._margin:2 { margin: calc(var(--spacing) * 2); }
+ * // ._margin:-1 { margin: calc(var(--spacing) * -1); }
  * ```
  */
 export declare const useMarginUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -3401,13 +3800,18 @@ export declare const usePaddingRightUtility: <T extends Record<string, TokenValu
 export declare const usePaddingTopUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create padding utility classes.
+ * Create padding utility classes with multiplier support.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * usePaddingUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem' });
- * // Generates: ._padding:sm, ._padding:md, ._padding:lg
+ * const createPadding = usePaddingUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createPadding(["@1.5", "@2"]);
+ * // Generates:
+ * // ._padding:1.5 { padding: calc(var(--spacing) * 1.5); }
+ * // ._padding:2 { padding: calc(var(--spacing) * 2); }
  * ```
  */
 export declare const usePaddingUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -3575,6 +3979,16 @@ export declare const useRotateXUtility: <T extends Record<string, TokenValue> =
  */
 export declare const useRotateYUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
+/**
+ * Default user-select utility values matching Tailwind CSS.
+ */
+export declare const userSelectValues: {
+    none: string;
+    text: string;
+    all: string;
+    auto: string;
+};
+
 /**
  * Create saturate utility classes.
  */
@@ -3623,7 +4037,9 @@ export declare const useScale: <T extends Record<string, TokenValue> = {
     readonly "augmented-fourth": 1.414;
     readonly "perfect-fifth": 1.5;
     readonly golden: 1.618;
-}>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"scale", T, ".">;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"scale", T, ".">;
 
 export declare function useScalePowers<T extends readonly number[]>(s: Styleframe, scale: Variable | Reference, powers?: T): Record<number, TokenValue>;
 
@@ -3656,7 +4072,7 @@ export declare const useScrollBehaviorUtility: <T extends Record<string, TokenVa
 export declare const useScrollMarginBottomUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create scroll-margin-end utility classes.
+ * Create scroll-margin-inline-end utility classes.
  */
 export declare const useScrollMarginEndUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
@@ -3671,7 +4087,7 @@ export declare const useScrollMarginLeftUtility: <T extends Record<string, Token
 export declare const useScrollMarginRightUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create scroll-margin-start utility classes.
+ * Create scroll-margin-inline-start utility classes.
  */
 export declare const useScrollMarginStartUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
@@ -3701,7 +4117,7 @@ export declare const useScrollMarginYUtility: <T extends Record<string, TokenVal
 export declare const useScrollPaddingBottomUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create scroll-padding-end utility classes.
+ * Create scroll-padding-inline-end utility classes.
  */
 export declare const useScrollPaddingEndUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
@@ -3716,7 +4132,7 @@ export declare const useScrollPaddingLeftUtility: <T extends Record<string, Toke
 export declare const useScrollPaddingRightUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create scroll-padding-start utility classes.
+ * Create scroll-padding-inline-start utility classes.
  */
 export declare const useScrollPaddingStartUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
@@ -3808,14 +4224,18 @@ export declare const useSkewYUtility: <T extends Record<string, TokenValue> = Re
 export declare const useSpaceXReverseUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create space-x utility classes (horizontal space between children).
+ * Create space-x utility classes with multiplier support (horizontal space between children).
  * Uses the "lobotomized owl" selector to add margin-left to all but the first child.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * useSpaceXUtility(s, { sm: '0.5rem', md: '1rem' });
- * // Generates: ._space-x:sm > * + *, ._space-x:md > * + *
+ * const createSpaceX = useSpaceXUtility(s, { sm: '0.5rem', md: '1rem' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createSpaceX(["@1.5", "@2"]);
+ * // Generates:
+ * // ._space-x:1.5 > * + * { margin-left: calc(var(--spacing) * 1.5); }
  * ```
  */
 export declare const useSpaceXUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -3827,7 +4247,7 @@ export declare const useSpaceXUtility: <T extends Record<string, TokenValue> = R
 export declare const useSpaceYReverseUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create space-y utility classes (vertical space between children).
+ * Create space-y utility classes with multiplier support (vertical space between children).
  * Uses the "lobotomized owl" selector to add margin-top to all but the first child.
  */
 export declare const useSpaceYUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -3855,7 +4275,19 @@ export declare const useSpaceYUtility: <T extends Record<string, TokenValue> = R
  * });
  * ```
  */
-export declare const useSpacing: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, tokens?: T | undefined) => ExportKeys<"spacing", T, ".">;
+export declare const useSpacing: <T extends Record<string, TokenValue> = {
+    default: string;
+    "2xs": string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+}>(s: Styleframe, tokens?: T | undefined, { default: isDefault }?: {
+    default?: boolean;
+}) => ExportKeys<"spacing", T, ".">;
 
 /**
  * Create screen-reader only utility class.
@@ -3980,10 +4412,10 @@ export declare const useTextShadowColorUtility: <T extends Record<string, TokenV
  * ```typescript
  * const s = styleframe();
  * useTextShadowUtility(s, {
- *     sm: '0 1px 2px var(--tw-text-shadow-color, rgb(0 0 0 / 0.05))',
- *     default: '0 1px 3px var(--tw-text-shadow-color, rgb(0 0 0 / 0.1))',
- *     md: '0 2px 4px var(--tw-text-shadow-color, rgb(0 0 0 / 0.1))',
- *     lg: '0 4px 8px var(--tw-text-shadow-color, rgb(0 0 0 / 0.1))',
+ *     sm: '0 1px 2px var(--text-shadow-color, rgb(0 0 0 / 0.05))',
+ *     default: '0 1px 3px var(--text-shadow-color, rgb(0 0 0 / 0.1))',
+ *     md: '0 2px 4px var(--text-shadow-color, rgb(0 0 0 / 0.1))',
+ *     lg: '0 4px 8px var(--text-shadow-color, rgb(0 0 0 / 0.1))',
  *     none: 'none',
  * });
  * ```
@@ -4142,40 +4574,39 @@ export declare const useUserSelectUtility: <T extends Record<string, TokenValue>
  * Register all utility factories with the Styleframe instance and return their creator functions.
  *
  * This function is useful when you want to register all utilities at once for use with recipes.
- * Each utility factory is registered without default values, allowing recipes to automatically
- * generate utility classes based on the values used in recipe declarations.
+ * Each utility factory is registered with configurable default values.
+ *
+ * @param s - The Styleframe instance to register utilities with
+ * @param config - Configuration options for customizing utility defaults
+ * @returns An object containing creator functions for all registered utilities
  *
  * @example
  * ```typescript
  * import { styleframe } from "styleframe";
- * import { useUtilities } from "@styleframe/theme";
+ * import { useUtilitiesPreset } from "@styleframe/theme";
  *
  * const s = styleframe();
- * const {
- *   createMarginUtility,
- *   createPaddingUtility,
- *   createDisplayUtility,
- *   // ... all other utilities
- * } = useUtilities(s);
- *
- * // Now you can use the creator functions to define utility values
- * createMarginUtility({ sm: '0.5rem', md: '1rem', lg: '1.5rem' });
- * createPaddingUtility({ sm: '0.5rem', md: '1rem', lg: '1.5rem' });
- *
- * // Or use them in recipes - utilities are already registered
- * s.recipe({
- *   name: 'button',
- *   base: { display: 'flex' },
- *   variants: {
- *     size: {
- *       sm: { padding: '0.5rem' },
- *       md: { padding: '1rem' },
- *     },
- *   },
+ *
+ * // Use all defaults
+ * const utilities = useUtilitiesPreset(s);
+ *
+ * // Customize specific utilities
+ * const utilities = useUtilitiesPreset(s, {
+ *     display: { flex: "flex", block: "block", hidden: "none" },
+ *     position: false, // Disable position utilities
  * });
+ *
+ * // Merge custom values with defaults
+ * const utilities = useUtilitiesPreset(s, {
+ *     meta: { merge: true },
+ *     cursor: { custom: "url('custom.cur'), auto" },
+ * });
+ *
+ * // Now you can use the creator functions to define additional utility values
+ * utilities.createMarginUtility({ sm: '0.5rem', md: '1rem', lg: '1.5rem' });
  * ```
  */
-export declare function useUtilities(s: Styleframe): {
+export declare function useUtilitiesPreset(s: Styleframe, config?: UtilitiesPresetConfig): {
     createForcedColorAdjustUtility: UtilityCreatorFn;
     createNotSrOnlyUtility: UtilityCreatorFn;
     createSrOnlyUtility: UtilityCreatorFn;
@@ -4187,6 +4618,7 @@ export declare function useUtilities(s: Styleframe): {
     createBackgroundPositionUtility: UtilityCreatorFn;
     createBackgroundRepeatUtility: UtilityCreatorFn;
     createBackgroundSizeUtility: UtilityCreatorFn;
+    createBackgroundUtility: UtilityCreatorFn;
     createGradientFromUtility: UtilityCreatorFn;
     createGradientToUtility: UtilityCreatorFn;
     createGradientViaUtility: UtilityCreatorFn;
@@ -4553,4 +4985,161 @@ export declare const useWordBreakUtility: <T extends Record<string, TokenValue>
  */
 export declare const useZIndexUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
+/**
+ * Meta configuration for utilities preset
+ */
+export declare interface UtilitiesMetaConfig {
+    /**
+     * When true, custom values are merged with defaults instead of replacing them.
+     * Custom values override defaults with the same key.
+     */
+    merge?: boolean;
+}
+
+/**
+ * Configuration options for the utilities preset.
+ *
+ * - Omit or set to `undefined` to use default values
+ * - Set to `false` to disable the utility category entirely
+ * - Provide a custom record to use custom values
+ * - Set `meta.merge` to `true` to merge custom values with defaults
+ */
+export declare interface UtilitiesPresetConfig {
+    meta?: UtilitiesMetaConfig;
+    forcedColorAdjust?: Record<string, string> | false;
+    backgroundAttachment?: Record<string, string> | false;
+    backgroundClip?: Record<string, string> | false;
+    backgroundImage?: Record<string, string> | false;
+    backgroundOrigin?: Record<string, string> | false;
+    backgroundPosition?: Record<string, string> | false;
+    backgroundRepeat?: Record<string, string> | false;
+    backgroundSize?: Record<string, string> | false;
+    backgroundBlendMode?: Record<string, string> | false;
+    mixBlendMode?: Record<string, string> | false;
+    divideStyle?: Record<string, string> | false;
+    outlineStyle?: Record<string, string> | false;
+    flex?: Record<string, string> | false;
+    flexDirection?: Record<string, string> | false;
+    flexWrap?: Record<string, string> | false;
+    justifyContent?: Record<string, string> | false;
+    justifyItems?: Record<string, string> | false;
+    justifySelf?: Record<string, string> | false;
+    alignContent?: Record<string, string> | false;
+    alignItems?: Record<string, string> | false;
+    alignSelf?: Record<string, string> | false;
+    placeContent?: Record<string, string> | false;
+    placeItems?: Record<string, string> | false;
+    placeSelf?: Record<string, string> | false;
+    gridAutoFlow?: Record<string, string> | false;
+    appearance?: Record<string, string> | false;
+    colorScheme?: Record<string, string> | false;
+    cursor?: Record<string, string> | false;
+    pointerEvents?: Record<string, string> | false;
+    resize?: Record<string, string> | false;
+    scrollBehavior?: Record<string, string> | false;
+    scrollSnapAlign?: Record<string, string> | false;
+    scrollSnapStop?: Record<string, string> | false;
+    scrollSnapType?: Record<string, string> | false;
+    touchAction?: Record<string, string> | false;
+    userSelect?: Record<string, string> | false;
+    willChange?: Record<string, string> | false;
+    aspectRatio?: Record<string, string> | false;
+    boxDecorationBreak?: Record<string, string> | false;
+    boxSizing?: Record<string, string> | false;
+    breakAfter?: Record<string, string> | false;
+    breakBefore?: Record<string, string> | false;
+    breakInside?: Record<string, string> | false;
+    clear?: Record<string, string> | false;
+    display?: Record<string, string> | false;
+    float?: Record<string, string> | false;
+    isolation?: Record<string, string> | false;
+    objectFit?: Record<string, string> | false;
+    objectPosition?: Record<string, string> | false;
+    overflow?: Record<string, string> | false;
+    overscroll?: Record<string, string> | false;
+    position?: Record<string, string> | false;
+    visibility?: Record<string, string> | false;
+    borderCollapse?: Record<string, string> | false;
+    captionSide?: Record<string, string> | false;
+    tableLayout?: Record<string, string> | false;
+    backfaceVisibility?: Record<string, string> | false;
+    perspectiveOrigin?: Record<string, string> | false;
+    transformOrigin?: Record<string, string> | false;
+    transformStyle?: Record<string, string> | false;
+    animation?: Record<string, string> | false;
+    transitionBehavior?: Record<string, string> | false;
+    transitionProperty?: Record<string, string> | false;
+    fontSmoothing?: Record<string, string> | false;
+    fontStretch?: Record<string, string> | false;
+    fontVariantNumeric?: Record<string, string> | false;
+    hyphens?: Record<string, string> | false;
+    listStylePosition?: Record<string, string> | false;
+    listStyleType?: Record<string, string> | false;
+    overflowWrap?: Record<string, string> | false;
+    textAlign?: Record<string, string> | false;
+    textDecorationLine?: Record<string, string> | false;
+    textDecorationStyle?: Record<string, string> | false;
+    textOverflow?: Record<string, string> | false;
+    textTransform?: Record<string, string> | false;
+    textWrap?: Record<string, string> | false;
+    verticalAlign?: Record<string, string> | false;
+    whitespace?: Record<string, string> | false;
+    wordBreak?: Record<string, string> | false;
+}
+
+/**
+ * Default vertical-align utility values matching Tailwind CSS.
+ */
+export declare const verticalAlignValues: {
+    baseline: string;
+    top: string;
+    middle: string;
+    bottom: string;
+    "text-top": string;
+    "text-bottom": string;
+    sub: string;
+    super: string;
+};
+
+/**
+ * Default visibility utility values matching Tailwind CSS.
+ */
+export declare const visibilityValues: {
+    visible: string;
+    invisible: string;
+    collapse: string;
+};
+
+/**
+ * Default whitespace utility values matching Tailwind CSS.
+ */
+export declare const whitespaceValues: {
+    normal: string;
+    nowrap: string;
+    pre: string;
+    "pre-line": string;
+    "pre-wrap": string;
+    "break-spaces": string;
+};
+
+/**
+ * Default will-change utility values matching Tailwind CSS.
+ */
+export declare const willChangeValues: {
+    auto: string;
+    scroll: string;
+    contents: string;
+    transform: string;
+};
+
+/**
+ * Default word-break utility values matching Tailwind CSS.
+ */
+export declare const wordBreakValues: {
+    normal: string;
+    words: string;
+    all: string;
+    keep: string;
+};
+
 export { }