@sugarcube-org/core 0.0.1-alpha.5 → 0.0.1-alpha.7

package/dist/index.d.ts

@@ -1,28 +1,29 @@
 import { z } from 'zod';
 
 /**
- * Supported color formats for CSS output
+ * Directional variants for utility properties
  */
-type ColorFormat = "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "oklch" | "p3";
+type DirectionalVariant = "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all";
 /**
- * Configuration for fluid (responsive) values
+ * Properties-first utility configuration
+ * This is the approach where users configure utilities by CSS property
+ * Made it separate in case we want other types of configs later
  */
+type PropertyUtilityConfig = {
+    source: string;
+    directions?: DirectionalVariant | DirectionalVariant[];
+    prefix?: string;
+    stripDuplicates?: boolean;
+    collection?: string;
+};
+
+type ColorFallbackStrategy = "native" | "polyfill";
 type FluidConfig = {
-    /** Minimum viewport width in pixels */
     min: number;
-    /** Maximum viewport width in pixels */
     max: number;
 };
-/**
- * A collection of token files with shared namespace.
- * Represents either a starter kit or custom token collection.
- */
 type TokenCollection = {
-    /** Array of source file paths for this collection */
     source: string[];
-    /** Whether this is a starter kit or custom collection */
-    type: "starter-kit" | "custom";
-    /** Optional theme-specific source files */
     themes?: Record<string, string[]>;
 };
 /**
@@ -30,66 +31,53 @@ type TokenCollection = {
  * Each key is a collection name (e.g., "base", "ui", "marketing").
  */
 type TokenCollections = Record<string, TokenCollection>;
+type UserTransformsConfig = {
+    fluid?: FluidConfig;
+    colorFallbackStrategy?: ColorFallbackStrategy;
+};
 /**
- * Global options for token processing and output
+ * Configuration for transforms applied to tokens during processing (internal config)
  */
-type OptionsConfig = {
-    /** Configuration for fluid (responsive) values */
-    fluid?: FluidConfig;
-    /** Prefix to add to all CSS variable names */
-    prefix?: string;
-    /** Default color format for all color tokens */
-    color?: ColorFormat;
+type TransformsConfig = {
+    fluid: FluidConfig;
+    colorFallbackStrategy: ColorFallbackStrategy;
 };
 /**
- * Configuration for output directories
+ * Configuration for output directories (user config - optional fields)
  */
-type DirectoriesConfig = {
-    /** Directory containing token source files */
-    tokens: string;
-    /** Optional directory for component files */
+type UserOutputConfig = {
+    css?: string;
     components?: string;
-    /** Directory where CSS files will be written */
-    css: string;
+    separate?: boolean;
 };
 /**
- * Configuration for CSS output generation
+ * Configuration for output directories (internal config - required fields)
  */
-type CSSOutputConfig = {
-    /**
-     * Controls how CSS variables are organized in output files:
-     * - When false: Generates one file per collection, combining all tokens within each collection
-     *   (e.g., base/tokens.variables.css, ui/tokens.variables.css)
-     * - When true: Generates separate files by token type within each collection
-     *   (e.g., base/colors.variables.css, base/space.variables.css)
-     * @default false
-     */
+type OutputConfig = {
+    css: string;
+    components?: string;
     separate: boolean;
-    /** Whether to generate and manage an index.css file */
-    manageIndex?: boolean;
-    /** The format of the output CSS files */
-    format?: "css" | "scss" | "less";
 };
 /**
- * Configuration for all output generation
+ * Utilities configuration
+ * This is the approach where users configure utilities by CSS property
+ * Can be a single configuration or an array of configurations
  */
-type OutputConfig = {
-    /** Directory configuration for all output files */
-    directories: DirectoriesConfig;
-    /** CSS-specific output configuration */
-    css: CSSOutputConfig;
-};
+type UtilitiesConfig = Record<string, PropertyUtilityConfig | PropertyUtilityConfig[]>;
+interface UserConfig {
+    tokens?: TokenCollection | TokenCollections;
+    transforms?: UserTransformsConfig;
+    output?: UserOutputConfig;
+    utilities?: UtilitiesConfig;
+}
 /**
- * The main configuration type for Sugarcube.
- * Defines all settings for token processing and output generation.
+ * Internal configuration type - what code uses (complete, required fields)
  */
-interface SugarcubeConfig {
-    /** Token source configuration, either a single collection or multiple named collections */
-    tokens: TokenCollection | TokenCollections;
-    /** Optional global processing options */
-    options?: OptionsConfig;
-    /** Output configuration for generated files */
+interface InternalConfig {
+    tokens?: TokenCollection | TokenCollections;
+    transforms: TransformsConfig;
     output: OutputConfig;
+    utilities?: UtilitiesConfig;
 }
 
 /**
@@ -199,9 +187,20 @@ type StructuralCompositeType = "strokeStyle";
 type CompositeTokenValue<T extends CompositeTokenType = CompositeTokenType> = T extends "typography" ? Typography : T extends "border" ? Border : T extends "shadow" ? Shadow : T extends "gradient" ? Gradient : T extends "transition" ? Transition : T extends "strokeStyle" ? StrokeStyle : never;
 /**
  * A color value in any valid CSS color format.
- * This can be any string that is valid in CSS color contexts.
- */
-type Color = string;
+ * This can be either:
+ * - A string that is valid in CSS color contexts (legacy format)
+ * - A W3C color object with colorSpace, components, and optional alpha/hex
+ */
+type Color = string | {
+    /** The color space - supports "oklch" and "display-p3" */
+    colorSpace: "oklch" | "display-p3";
+    /** Array of 3 numbers representing the color components */
+    components: [number, number, number];
+    /** Optional alpha value between 0 and 1 (defaults to 1 if omitted) */
+    alpha?: number;
+    /** Optional hex fallback value for compatibility */
+    hex?: string;
+};
 /**
  * A dimensional value with a numeric value and unit.
  * Used for measurements like width, height, spacing, etc.
@@ -385,47 +384,159 @@ type TokenTree = {
 };
 
 /**
- * A flattened token with its source information and path.
- * Represents a token after it has been flattened from a nested structure into a flat key-value map.
+ * A resolved token with its final value.
+ * Contains both the original token data and its resolved value after reference resolution.
  * @template T - The type of token (e.g., "color", "dimension", etc.)
  */
-type FlattenedToken<T extends TokenType = TokenType> = NodeMetadata & {
+type ResolvedToken<T extends TokenType = TokenType> = NodeMetadata & {
     /** The type of the token */
     $type: T;
-    /** The value of the token */
-    $value: TokenValue<T>;
-    /** The path to this token in the flattened structure */
+    /** The original value of the token, which may contain references */
+    $value: RawTokenValue<T>;
+    /** The path to this token in the token tree */
     $path: string;
     /** Information about where this token was loaded from */
     $source: TokenSource;
-    /** The original path before flattening */
+    /** The original path before any resolution */
     $originalPath: string;
+    /** The final resolved value after all references are resolved */
+    $resolvedValue: RawTokenValue<T>;
 };
 /**
- * A map of flattened tokens and metadata by their lookup path, with an index for quick reference lookups.
- * Used to store the flattened state of all tokens in a collection.
- * Contains both the token map and a path index for efficient lookups.
+ * A map of resolved tokens by their lookup path.
+ * Used to store the final resolved state of all tokens in a collection.
+ * Keys are token paths, values are either resolved tokens or node metadata.
  */
-type FlattenedTokens = {
-    /** Map of token paths to their flattened tokens or metadata */
-    tokens: {
-        /** Token path as key, flattened token or metadata as value */
-        [lookupKey: string]: FlattenedToken | NodeMetadata;
-    };
-    /** Index mapping original paths to their namespaced keys for quick lookups */
-    pathIndex: Map<string, string>;
+type ResolvedTokens = {
+    /** Token path as key, resolved token or metadata as value */
+    [lookupKey: string]: ResolvedToken | NodeMetadata;
 };
 /**
- * An error that occurred during token flattening.
- * Extends the base error type with flattening-specific information.
+ * Type of resolution error that occurred.
+ * - "circular": A circular reference was detected
+ * - "missing": A referenced token could not be found
+ * - "type-mismatch": A referenced token's type doesn't match the expected type
  */
-type FlattenError = BaseError & {
-    /** The path to the token that failed flattening */
+type ResolutionErrorType = "circular" | "missing" | "type-mismatch";
+/**
+ * An error that occurred during token resolution.
+ * Extends the base error type with resolution-specific information.
+ */
+type ResolutionError = BaseError & {
+    /** The type of resolution error that occurred */
+    type: ResolutionErrorType;
+    /** The path to the token that failed resolution */
     path: string;
     /** Source information about where the token was loaded from */
     source: TokenSource;
 };
 
+/**
+ * A token that has been converted to CSS properties.
+ * Extends ResolvedToken with CSS-specific properties.
+ * @template T The type of token
+ */
+type ConvertedToken<T extends TokenType = TokenType> = ResolvedToken<T> & {
+    /** The CSS properties generated from the token */
+    $cssProperties: CSSProperties<T>;
+};
+/**
+ * A collection of converted tokens.
+ * Maps token paths to their converted values or metadata nodes.
+ */
+type ConvertedTokens = {
+    [lookupKey: string]: ConvertedToken | NodeMetadata;
+};
+/**
+ * A collection of converted tokens organized by theme.
+ * Each theme contains its own set of converted tokens.
+ */
+type ConvertedThemeTokenSet = {
+    /** The default theme's tokens */
+    default: ConvertedTokens;
+    /** Additional theme-specific tokens */
+    [theme: string]: ConvertedTokens;
+};
+/**
+ * A collection of converted tokens organized by collection and theme.
+ * The top-level structure for all converted tokens.
+ */
+type NormalizedConvertedTokens = {
+    [collection: string]: ConvertedThemeTokenSet;
+};
+/**
+ * CSS property types for different token types.
+ * Maps token types to their corresponding CSS property structures.
+ * @template T The type of token
+ */
+type CSSProperties<T extends TokenType> = T extends SimpleTokenType ? SimpleCSSProperties : T extends AlwaysDecomposedType ? AlwaysDecomposedProperties : T extends "border" ? CSSBorderProperties : T extends "shadow" ? CSSShadowProperties : T extends "gradient" ? CSSGradientProperties : T extends "transition" ? CSSTransitionProperties : T extends StructuralCompositeType ? SimpleCSSProperties : never;
+/**
+ * Simple CSS properties with a single value.
+ * Used for tokens that map to a single CSS property.
+ */
+type SimpleCSSProperties = {
+    /** The CSS value */
+    value: string | number;
+    /** Optional feature queries for responsive values */
+    featureValues?: Array<{
+        query: string;
+        value: string;
+    }>;
+};
+/**
+ * CSS properties that are always broken down into multiple properties.
+ * Currently only used for typography tokens.
+ */
+type AlwaysDecomposedProperties = CSSTypographyProperties;
+/**
+ * CSS properties specific to typography tokens.
+ * Maps typography tokens to their corresponding CSS properties.
+ */
+type CSSTypographyProperties = {
+    /** The font family to use */
+    "font-family": string;
+    /** The font size */
+    "font-size": string;
+    /** The font weight */
+    "font-weight"?: number | string;
+    /** The letter spacing */
+    "letter-spacing"?: string;
+    /** The line height */
+    "line-height"?: number | string;
+};
+/**
+ * CSS properties for specific token types.
+ * These types represent tokens that map to single CSS properties.
+ */
+/**
+ * CSS properties for border tokens.
+ */
+type CSSBorderProperties = {
+    /** The border value */
+    value: string;
+};
+/**
+ * CSS properties for shadow tokens.
+ */
+type CSSShadowProperties = {
+    /** The shadow value */
+    value: string;
+};
+/**
+ * CSS properties for gradient tokens.
+ */
+type CSSGradientProperties = {
+    /** The gradient value */
+    value: string;
+};
+/**
+ * CSS properties for transition tokens.
+ */
+type CSSTransitionProperties = {
+    /** The transition value */
+    value: string;
+};
+
 /**
  * Represents a single CSS file output with its path and content
  */
@@ -434,12 +545,36 @@ type CSSFile = {
     path: string;
     /** The CSS content to write to the file */
     css: string;
+    /** The collection name (e.g., "default", "base", "ui", "marketing") */
+    collection: string;
 };
 /**
  * Represents multiple CSS file outputs from generateSeparateFiles or generateSingleFile
  */
 type CSSFileOutput = CSSFile[];
 
+declare function generateCSSVariables(convertedTokens: NormalizedConvertedTokens, config: InternalConfig): Promise<CSSFileOutput>;
+
+/**
+ * An error that occurred during token flattening.
+ * Extends the base error type with flattening-specific information.
+ */
+type FlattenError = BaseError & {
+    /** The path to the token that failed flattening */
+    path: string;
+    /** Source information about where the token was loaded from */
+    source: TokenSource;
+};
+
+/**
+ * Result of loading a Sugarcube configuration file
+ */
+type LoadedConfig = {
+    /** The validated configuration */
+    config: InternalConfig;
+    /** The path to the config file that was loaded */
+    configPath: string;
+};
 /**
  * Data structure for loading tokens from memory.
  * Maps file paths to their token content and metadata.
@@ -462,54 +597,6 @@ type LoadError = BaseError & {
     file: string;
 };
 
-/**
- * A resolved token with its final value.
- * Contains both the original token data and its resolved value after reference resolution.
- * @template T - The type of token (e.g., "color", "dimension", etc.)
- */
-type ResolvedToken<T extends TokenType = TokenType> = NodeMetadata & {
-    /** The type of the token */
-    $type: T;
-    /** The original value of the token, which may contain references */
-    $value: RawTokenValue<T>;
-    /** The path to this token in the token tree */
-    $path: string;
-    /** Information about where this token was loaded from */
-    $source: TokenSource;
-    /** The original path before any resolution */
-    $originalPath: string;
-    /** The final resolved value after all references are resolved */
-    $resolvedValue: RawTokenValue<T>;
-};
-/**
- * A map of resolved tokens by their lookup path.
- * Used to store the final resolved state of all tokens in a collection.
- * Keys are token paths, values are either resolved tokens or node metadata.
- */
-type ResolvedTokens = {
-    /** Token path as key, resolved token or metadata as value */
-    [lookupKey: string]: ResolvedToken | NodeMetadata;
-};
-/**
- * Type of resolution error that occurred.
- * - "circular": A circular reference was detected
- * - "missing": A referenced token could not be found
- * - "type-mismatch": A referenced token's type doesn't match the expected type
- */
-type ResolutionErrorType = "circular" | "missing" | "type-mismatch";
-/**
- * An error that occurred during token resolution.
- * Extends the base error type with resolution-specific information.
- */
-type ResolutionError = BaseError & {
-    /** The type of resolution error that occurred */
-    type: ResolutionErrorType;
-    /** The path to the token that failed resolution */
-    path: string;
-    /** Source information about where the token was loaded from */
-    source: TokenSource;
-};
-
 /**
  * An error that occurred during token validation.
  * Extends the base error type with token-specific information.
@@ -522,35 +609,16 @@ type ValidationError = BaseError & {
 };
 
 /**
- * A warning that occurred during token normalization.
- * Provides information about non-critical issues during the normalization process.
- */
-type NormalizationWarning = {
-    /** The type of the warning */
-    type: "warning";
-    /** A human-readable message describing the warning */
-    message: string;
-    /** The file where the warning occurred */
-    file: string;
-    /** The collection where the warning occurred */
-    collection: string;
-    /** The theme where the warning occurred, if applicable */
-    theme?: string;
-};
-
-/**
- * Result of running the tokens-to-CSS pipeline.
- * Contains the generated CSS files, token trees, and any errors or warnings.
+ * Result of running any pipeline.
+ * Contains the generated output, token trees, and any errors.
  */
-type TokensToCSSPipelineResult = {
-    /** The generated CSS files */
+type PipelineResult = {
+    /** The generated output (e.g. CSS files) */
     output: CSSFileOutput;
     /** The loaded token trees */
     trees: TokenTree[];
     /** Any errors that occurred during pipeline execution */
     errors: PipelineErrors;
-    /** Any warnings that occurred during pipeline execution */
-    warnings: PipelineWarnings;
 };
 /**
  * Common error types that can occur during pipeline execution.
@@ -567,455 +635,731 @@ type PipelineErrors = {
     resolution: ResolutionError[];
 };
 /**
- * Common warning types that can occur during pipeline execution.
- * Organizes warnings by the pipeline stage where they occurred.
+ * Defines how tokens should be loaded and processed.
+ * Either from files using a config, or from memory with token data.
  */
-type PipelineWarnings = {
-    /** Warnings that occurred during token normalization */
-    normalization: NormalizationWarning[];
-};
-/**
- * Result of running the validation pipeline.
- * Contains the validated token trees, flattened tokens, and resolved tokens.
- */
-type ValidationPipelineResult = {
-    /** The loaded token trees */
-    trees: TokenTree[];
-    /** The flattened tokens */
-    flattenedTokens: FlattenedTokens;
-    /** The resolved tokens */
-    resolved: ResolvedTokens;
-    /** Any errors that occurred during pipeline execution */
-    errors: PipelineErrors;
+type TokenPipelineSource = {
+    type: "files";
+    config: InternalConfig;
+} | {
+    type: "memory";
+    data: Record<string, {
+        collection: string;
+        content: string;
+    }>;
+    config: InternalConfig;
 };
 /**
- * Options for loading tokens in the validation pipeline.
+ * Options for loading tokens in the pipeline.
  * Specifies whether to load tokens from files or memory.
  */
 type TokenLoader = {
     type: "files";
-    paths: SugarcubeConfig;
+    paths: InternalConfig;
 } | {
     type: "memory";
     data: TokenMemoryData;
 };
-/**
- * Options for configuring the validation pipeline.
- * Controls how tokens are loaded and processed.
- */
-type ValidationPipelineOptions = {
-    /** The token loader configuration */
-    loader: TokenLoader;
-};
-/**
- * Result of running the generation pipeline.
- * Contains the generated CSS files and any warnings.
- */
-type GenerationPipelineResult = {
-    /** The generated CSS files */
-    output: CSSFileOutput;
-    /** Any warnings that occurred during pipeline execution */
-    warnings: PipelineWarnings;
-};
 
 /**
- * The main pipeline that transforms design tokens into CSS output.
+ * Core token processing pipeline that handles loading, validation, and resolution of tokens.
+ * This is the foundation for all other token processing operations.
  *
- * This pipeline orchestrates the entire token processing flow:
+ * This pipeline:
  * 1. Loads token trees from config or memory
- * 2. Flattens trees into a single structure with source information
+ * 2. Flattens trees into a single structure
  * 3. Validates tokens for correctness
  * 4. Resolves all token references
- * 5. Processes trees into collections and themes
- * 6. Normalizes tokens into a standard format
- * 7. Converts tokens into CSS-ready format
- * 8. Generates final CSS output
  *
- * Each stage can produce errors or warnings, which are collected and returned
- * in the result. The pipeline stops at validation if any errors are found.
+ * Each stage can produce errors which are collected and returned in the result.
  *
- * @param config - The sugarcube configuration
- * @param options - Optional pipeline configuration including a custom token loader
- * @returns The pipeline result containing CSS output, trees, and any errors/warnings
+ * @param source - The source of tokens to process, either from memory or config
+ * @returns An object containing the processed trees, resolved tokens, and any errors
  *
  * @example
- * const result = await tokensToCSSPipeline(config);
+ * const result = await loadAndResolveTokens({ type: "config", config });
  * if (result.errors.validation.length > 0) {
  *   console.error("Validation failed:", result.errors.validation);
- * } else {
- *   // Use the generated CSS
- *   console.log(result.output);
  * }
  */
-declare function tokensToCSSPipeline(config: SugarcubeConfig, options?: {
-    loader?: TokenLoader;
-}): Promise<TokensToCSSPipelineResult>;
+declare function loadAndResolveTokens(source: TokenPipelineSource): Promise<{
+    trees: TokenTree[];
+    resolved: ResolvedTokens;
+    errors: PipelineResult["errors"];
+}>;
+
+type NamedUtilityValue = {
+    kind: "named";
+    value: string;
+    fraction: string | null;
+};
+type ArbitraryUtilityValue = {
+    kind: "arbitrary";
+    value: string;
+};
+type UtilityValue = NamedUtilityValue | ArbitraryUtilityValue;
+type StaticVariant = {
+    kind: "static";
+    root: string;
+};
+type FunctionalVariant = {
+    kind: "functional";
+    root: string;
+    value: UtilityValue;
+};
+type Variant = StaticVariant | FunctionalVariant;
+type StaticCandidate = {
+    kind: "static";
+    root: string;
+    variants: Variant[];
+    raw: string;
+};
+type FunctionalCandidate = {
+    kind: "functional";
+    root: string;
+    value: UtilityValue | null;
+    variants: Variant[];
+    raw: string;
+};
+type Candidate = StaticCandidate | FunctionalCandidate;
+interface StaticUtilityPattern {
+    properties: string[];
+    validator: (candidate: Candidate) => boolean;
+    generator: (candidate: Candidate) => string;
+}
 
 /**
- * A pipeline that validates design tokens without generating CSS output.
- *
- * This pipeline performs the initial stages of token processing:
- * 1. Loads token trees from config or memory
- * 2. Flattens trees into a single structure with source information
- * 3. Validates tokens for correctness
- * 4. Resolves all token references
+ * Processes and converts token trees into CSS-ready format.
+ * This pipeline:
+ * 1. Processes trees with resolved tokens to create a unified structure
+ * 2. Normalizes tokens into a collection-theme organization
+ * 3. Converts tokens to their CSS representations with properties
  *
- * Unlike the main pipeline, this one doesn't generate CSS output.
- * It's useful for:
- * - Validating tokens before full processing
- * - Checking token references
- * - Debugging token structure issues
  *
+ * @param trees - The token trees to process
+ * @param resolved - The resolved tokens for processing
  * @param config - The sugarcube configuration
- * @param options - Pipeline options including the token loader configuration
- * @returns The validation result containing trees, tokens, and any errors
+ * @param validationErrors - Optional array of validation errors. Tokens with validation errors will be filtered out before conversion.
+ * @returns The processed and converted tokens ready for CSS generation
  *
  * @example
- * const result = await validationPipeline(config, {
- *   loader: { type: "config" }
- * });
- *
- * if (result.errors.validation.length > 0) {
- *   console.error("Token validation failed:", result.errors.validation);
- * } else {
- *   console.log("All tokens are valid!");
- * }
+ * const convertedTokens = await processAndConvertTokens(trees, resolved, config);
+ * // convertedTokens = { collection: { theme: { "token.path": { $cssProperties: {...} } } } }
  */
-declare function validationPipeline(config: SugarcubeConfig, options: ValidationPipelineOptions): Promise<ValidationPipelineResult>;
+declare function processAndConvertTokens(trees: TokenTree[], resolved: ResolvedTokens, config: InternalConfig, validationErrors?: ValidationError[]): Promise<NormalizedConvertedTokens>;
+
+declare function generateIndex(stylesDir: string, config: InternalConfig): Promise<string>;
+declare function shouldRegenerateIndex(stylesDir: string, config: InternalConfig): Promise<boolean>;
 
 /**
- * A pipeline that generates CSS from pre-validated tokens.
- *
- * This pipeline handles the final stages of token processing:
- * 1. Processes trees into collections and themes
- * 2. Normalizes tokens into a standard format
- * 3. Converts tokens into CSS-ready format
- * 4. Generates final CSS output
+ * Writes CSS files to disk, creating directories as needed.
  *
- * This pipeline exists to support workflows where you want to:
- * - Validate tokens, then generate CSS
+ * This function:
+ * 1. Creates any missing directories in the file path
+ * 2. Adds a warning banner to prevent direct edits
+ * 3. Only writes files if the content has changed
+ * 4. Handles both single and multiple CSS file outputs
  *
- * @param trees - The token trees to process
- * @param resolved - The resolved tokens to convert
- * @param configState - The sugarcube configuration
- * @returns The generation result containing CSS output and any warnings
+ * @param output - Array of CSS file outputs to write
+ * @returns The original output array
+ * @throws Error if file writing fails
  *
  * @example
- * // First validate tokens once
- * const validationResult = await validationPipeline(config, options);
- * if (validationResult.errors.validation.length > 0) {
- *   throw new Error("Tokens failed validation");
- * }
+ * await writeCSSFilesToDisk([
+ *   { path: "styles/tokens.css", css: "body { color: red; }" }
+ * ]);
+ */
+declare function writeCSSVariablesToDisk(output: CSSFileOutput): Promise<CSSFileOutput>;
+/**
+ * Writes utility CSS files to disk, creating directories as needed.
  *
- * // Generate CSS with different configs
- * const lightThemeConfig = { ...config, options: { color: "hex" } };
- * const darkThemeConfig = { ...config, options: { color: "rgb" } };
+ * This function:
+ * 1. Creates any missing directories in the file path
+ * 2. Adds a warning banner specific to utility classes
+ * 3. Only writes files if the content has changed
  *
- * const lightResult = await generationPipeline(
- *   validationResult.trees,
- *   validationResult.resolved,
- *   lightThemeConfig
- * );
+ * @param output - The CSS file output to write
+ * @param config - The sugarcube configuration
+ * @returns The CSS file output that was written
+ * @throws Error if file writing fails
  *
- * const darkResult = await generationPipeline(
- *   validationResult.trees,
- *   validationResult.resolved,
- *   darkThemeConfig
+ * @example
+ * await writeCSSUtilitiesToDisk(
+ *   [{ path: "src/styles/utilities/utilities.css", css: ".p-4 { padding: var(--spacing-4); }" }],
+ *   config
  * );
  */
-declare function generationPipeline(trees: TokenTree[], resolved: ResolvedTokens, configState: SugarcubeConfig): Promise<GenerationPipelineResult>;
+declare function writeCSSUtilitiesToDisk(output: CSSFileOutput): Promise<CSSFileOutput>;
+
+declare function findConfigFile(basePath?: string): string | null;
+declare function configFileExists(basePath?: string): boolean;
+declare function loadTSConfig(configPath: string): Promise<unknown>;
+declare function loadUserConfig(configPath?: string): Promise<{
+    config: UserConfig;
+    configPath: string;
+}>;
+declare function loadInternalConfig(configPath?: string): Promise<LoadedConfig>;
 
 /**
- * Loads and validates the sugarcube configuration file from disk.
- *
- * This function:
- * 1. Reads the config file from the specified path
- * 2. Parses and validates the configuration
- * 3. Returns the validated configuration object
+ * Validates a user configuration object against the user schema.
  *
- * @param configPath - Path to the config file (default: "sugarcube.config.json")
- * @returns A promise that resolves to the validated configuration
- * @throws Error if the config file is not found or invalid
- *
- * @example
- * // Load default config file
- * const config = await loadConfig();
+ * @param config - The user configuration object to validate
+ * @returns The validated user configuration
+ * @throws Error if the configuration is invalid
+ */
+declare function validateUserConfig(config: Partial<UserConfig>): UserConfig;
+/**
+ * Validates an internal configuration object against the internal schema and checks for duplicate filenames.
  *
- * // Load custom config file
- * const config = await loadConfig("./config/sugarcube.json");
+ * @param config - The internal configuration object to validate
+ * @returns The validated internal configuration
+ * @throws Error if the configuration is invalid or contains duplicate filenames
  */
-declare function loadConfig(configPath?: string): Promise<SugarcubeConfig>;
-
+declare function validateInternalConfig(config: InternalConfig): InternalConfig;
 /**
- * Validates a sugarcube configuration object against the schema.
+ * Validates a user configuration object against the schema and fills in defaults.
  *
  * This function:
- * 1. Validates the configuration structure using the schema
- * 2. Checks for duplicate filenames across collections
- * 3. Returns the validated configuration if successful
+ * 1. Validates the configuration structure using the user schema
+ * 2. Fills in default values
+ * 3. Validates the complete configuration using the internal schema
+ * 4. Checks for duplicate filenames across collections
+ * 5. Returns the validated configuration with defaults filled in
  *
- * @param config - The configuration object to validate
- * @returns The validated configuration
+ * @param config - The user configuration object to validate
+ * @returns The validated configuration with defaults filled in
  * @throws Error if the configuration is invalid or contains duplicate filenames
  *
  * @example
  * const config = {
  *   tokens: {
- *     source: ["tokens.json"],
- *     type: "custom"
+ *     source: ["tokens.json"]
  *   }
  * };
  * const validatedConfig = validateConfig(config);
+ * // validatedConfig.output.css === "src/styles" (default filled in)
  */
-declare function validateConfig(config: Partial<SugarcubeConfig>): SugarcubeConfig;
+declare function validateConfig(config: Partial<UserConfig>): InternalConfig;
 /**
  * Parses and validates a JSON configuration string.
  *
  * This function:
  * 1. Parses the JSON string into a configuration object
- * 2. Validates the configuration using validateConfig
- * 3. Returns the validated configuration if successful
+ * 2. Validates and normalizes the configuration using validateConfig
+ * 3. Returns the validated and normalized configuration
  *
  * @param configString - The JSON configuration string to parse and validate
- * @returns The validated configuration
+ * @returns The validated and normalized configuration
  * @throws Error if the JSON is invalid or the configuration is invalid
  *
  * @example
  * const configString = `{
  *   "tokens": {
- *     "source": ["tokens.json"],
- *     "type": "custom"
+ *     "source": ["tokens.json"]
  *   }
  * }`;
  * const config = parseAndValidateConfig(configString);
+ * // config.output.css === "src/styles" (default filled in)
  */
-declare function parseAndValidateConfig(configString: string): SugarcubeConfig;
+declare function parseAndValidateConfig(configString: string): InternalConfig;
 
 /**
- * Gets all token source file paths from the configuration.
- *
- * This function handles both single and multiple collection configurations:
- * - Single collection: Returns the source array directly
- * - Multiple collections: Flattens and returns all source paths from all collections
- *
- * @param config - The sugarcube configuration
- * @returns An array of all token source file paths
- *
- * @example
- * // Single collection
- * getTokenPathsFromConfig({ tokens: { source: ["tokens.json"] } })
- * // Returns: ["tokens.json"]
- *
- * // Multiple collections
- * getTokenPathsFromConfig({
- *   tokens: {
- *     base: { source: ["base.json"] },
- *     ui: { source: ["ui.json"] }
- *   }
- * })
- * // Returns: ["base.json", "ui.json"]
- */
-declare function getTokenPathsFromConfig(config: SugarcubeConfig): string[];
-/**
- * Writes CSS files to disk, creating directories as needed.
+ * Fills in default values for any omitted fields in a user configuration.
  *
- * This function:
- * 1. Creates any missing directories in the file path
- * 2. Optionally adds a warning banner to prevent direct edits
- * 3. Only writes files if the content has changed
- * 4. Handles both single and multiple CSS file outputs
+ * This function takes a user config (with optional fields) and
+ * returns a complete internal config (with all required fields filled in).
  *
- * @param output - Array of CSS file outputs to write
- * @param addBanner - Whether to add the warning banner (default: true)
- * @param tokenPaths - Optional array of token source paths for the warning banner
- * @returns The original output array
- * @throws Error if file writing fails
+ * @param userConfig - The user configuration with optional fields
+ * @returns A complete configuration with all defaults filled in
  *
  * @example
- * await writeCSSFilesToDisk([
- *   { path: "styles/tokens.css", css: "body { color: red; }" }
- * ]);
+ * const userConfig = {
+ *   tokens: { source: ["tokens/*.json"] }
+ * };
+ * const completeConfig = fillDefaults(userConfig);
+ * // completeConfig.output.css === "src/styles"
+ * // completeConfig.output.components === "src/ui/components"
+ * // completeConfig.output.separate === false
  */
-declare function writeCSSFilesToDisk(output: CSSFileOutput, addBanner?: boolean, tokenPaths?: string[]): Promise<CSSFileOutput>;
+declare function fillDefaults(userConfig: UserConfig): InternalConfig;
 
-/**
- * Manages the CSS index file that imports all CSS files.
- * @param options.cssOutputDirectory - Directory where the index.css will be created/updated
- * @param options.files - CSS files to include in the index
- * @returns Path to the generated index file
- */
-declare function manageCSSIndex({ cssOutputDirectory, files, }: {
-    cssOutputDirectory: string;
-    files: string[];
-}): Promise<string>;
+interface CSSImport {
+    path: string;
+    layer: string;
+    relativePath: string;
+}
+declare function discoverAllFiles(stylesDir: string, config: InternalConfig): Promise<CSSImport[]>;
 
-/**
- * Schema for configuration
- */
-declare const configSchema: z.ZodObject<{
-    tokens: z.ZodUnion<[z.ZodObject<{
+declare function generateIndexContent(files: CSSImport[]): string;
+
+declare class Instrumentation implements Disposable {
+    #private;
+    private defaultFlush;
+    constructor(defaultFlush?: (message: string) => undefined);
+    hit(label: string): void;
+    start(label: string): void;
+    end(label: string): void;
+    report(flush?: (message: string) => undefined): void;
+    [Symbol.dispose](): void;
+}
+
+type CSSObject = Record<string, string | number | undefined>;
+declare function convertConfigToUnoRules(utilitiesConfig: UtilitiesConfig, tokens: NormalizedConvertedTokens): Array<[RegExp, (m: RegExpMatchArray) => CSSObject]>;
+
+declare const SUGARCUBE_FILE = "_sugarcube.css";
+declare const GLOBAL_DIR = "global";
+declare const UTILITIES_DIR = "utilities";
+declare const VARIABLES_FILE_SUFFIX = ".variables.gen.css";
+declare const DEFAULT_VARIABLES_FILENAME = "tokens";
+declare const DEFAULT_UTILITIES_FILENAME = "utilities.gen.css";
+declare const DEFAULT_STYLES_PATH = "src/styles";
+declare const DEFAULT_DESIGN_TOKENS_PATH = "src/design-tokens";
+declare const SUGARCUBE_CONFIG_FILE = "sugarcube.config.ts";
+
+declare const DEFAULT_CONFIG: {
+    readonly output: {
+        readonly css: "src/styles";
+        readonly components: "src/components/ui";
+        readonly separate: false;
+    };
+    readonly transforms: {
+        readonly fluid: {
+            readonly min: 320;
+            readonly max: 1200;
+        };
+        readonly colorFallbackStrategy: "native";
+    };
+};
+
+declare const DEFAULT_COLLECTION = "default";
+declare const DEFAULT_THEME = "default";
+
+declare const ErrorMessages: {
+    readonly LOAD: {
+        readonly NO_FILES_FOUND: (pattern: string) => string;
+        readonly INVALID_JSON: (path: string, message: string) => string;
+        readonly GLOB_ERROR: (pattern: string, error: string) => string;
+    };
+    readonly FLATTEN: {
+        readonly INVALID_TOKEN_NAME: (name: string) => string;
+        readonly MISSING_DOLLAR_PREFIX: (path: string) => string;
+        readonly INVALID_TOKEN_NESTING: (path: string) => string;
+        readonly COMPOSITE_TOKEN_MISSING_TYPE: (path: string) => string;
+        readonly CONFLICT_TOKEN_VS_GROUP: (path: string) => string;
+        readonly CONFLICT_INCOMPATIBLE_TYPES: (expected: string, received: string, path: string) => string;
+    };
+    readonly METADATA: {
+        readonly COLLECTION_ERROR: (message: string) => string;
+        readonly INVALID_EXTENSIONS: (path: string) => string;
+        readonly INVALID_DESCRIPTION: (path: string) => string;
+    };
+    readonly VALIDATE: {
+        readonly MISSING_TYPE: (path: string) => string;
+        readonly UNKNOWN_TOKEN_TYPE: (type: string, path: string) => string;
+        readonly INVALID_COLOR: (value: unknown, path: string) => string;
+        readonly INVALID_DIMENSION: (value: unknown, path: string) => string;
+        readonly INVALID_DIMENSION_UNIT: (unit: unknown, path: string) => string;
+        readonly INVALID_FONT_FAMILY: (value: unknown, path: string) => string;
+        readonly INVALID_FONT_WEIGHT: (value: unknown, path: string) => string;
+        readonly INVALID_DURATION: (value: unknown, path: string) => string;
+        readonly INVALID_DURATION_UNIT: (unit: unknown, path: string) => string;
+        readonly INVALID_CUBIC_BEZIER: (value: unknown, path: string) => string;
+        readonly INVALID_STROKE_STYLE: (value: unknown, path: string) => string;
+        readonly INVALID_STROKE_LINE_CAP: (value: unknown, path: string) => string;
+        readonly INVALID_BORDER: (value: unknown, path: string) => string;
+        readonly INVALID_SHADOW: (value: unknown, path: string) => string;
+        readonly INVALID_SHADOW_INSET: (value: unknown, path: string) => string;
+        readonly INVALID_TRANSITION: (value: unknown, path: string) => string;
+        readonly INVALID_GRADIENT: (value: unknown, path: string) => string;
+        readonly INVALID_GRADIENT_STOP_POSITION: (value: unknown, path: string) => string;
+        readonly INVALID_TYPOGRAPHY: (value: unknown, path: string) => string;
+        readonly MISSING_REQUIRED_PROPERTY: (prop: string, path: string) => string;
+        readonly INVALID_NUMBER: (value: unknown, path: string) => string;
+        readonly INVALID_ARRAY: (value: unknown, path: string) => string;
+        readonly MISSING_FLUID_CONFIG: (path: string) => string;
+        readonly INVALID_FLUID_DIMENSION: (value: unknown, path: string) => string;
+        readonly INVALID_VIEWPORT_CONFIG: (value: unknown, path: string) => string;
+        readonly MISMATCHED_UNITS: (unit1: unknown, unit2: unknown, path: string) => string;
+        readonly INVALID_FLUID_VALUE_RANGE: (path: string) => string;
+        readonly INVALID_TOKEN_TYPE: (expected: string, received: string, path: string) => string;
+        readonly INVALID_TYPE: (expected: string, value: unknown, path: string) => string;
+        readonly INVALID_ENUM_VALUE: (enumValues: unknown[], value: unknown, path: string) => string;
+    };
+    readonly RESOLVE: {
+        readonly CIRCULAR_REFERENCE: (path: string, ref: string) => string;
+        readonly REFERENCE_NOT_FOUND: (ref: string, path: string) => string;
+        readonly TYPE_MISMATCH: (path: string) => string;
+    };
+    readonly GENERATE: {
+        readonly INVALID_CSS_VALUE: (key: string, value: unknown) => string;
+        readonly INVALID_VARIABLE_NAME: (path: string, name: string) => string;
+    };
+    readonly CONFIG: {
+        readonly INVALID_JSON: (error: string) => string;
+        readonly INVALID_CONFIG: (path: string, message: string) => string;
+        readonly DUPLICATE_FILENAMES: (collection: string, filename: string, paths: string[]) => string;
+        readonly FILE_NOT_FOUND: (path: string) => string;
+    };
+    readonly UTILITIES: {
+        readonly RESERVED_PREFIX: (prefix: string, tokenType: string) => string;
+        readonly DUPLICATE_CLASS_NAME: (className: string, paths: string[]) => string;
+        readonly INVALID_PROPERTY_MAPPING: (tokenType: string) => string;
+        readonly DUPLICATE_PREFIX: (prefix: string, tokenType: string) => string;
+        readonly INVALID_COLLECTION: (property: string, collection: string, availableCollections: string[]) => string;
+        readonly TOKEN_PATH_CONFLICT: (tokenPath: string, collections: string) => string;
+        readonly MISSING_SOURCE: (property: string) => string;
+        readonly INVALID_SOURCE_PATTERN: (property: string, source: string) => string;
+        readonly INVALID_DIRECTIONS: (property: string) => string;
+        readonly INVALID_CONFIG_OBJECT: "utilitiesConfig must be an object";
+        readonly INVALID_TOKENS_OBJECT: "tokens must be an object";
+    };
+};
+
+declare const userConfigSchema: z.ZodObject<{
+    tokens: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodObject<{
         source: z.ZodArray<z.ZodString, "many">;
-        type: z.ZodEnum<["starter-kit", "custom"]>;
         themes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
     }, "strip", z.ZodTypeAny, {
-        type: "starter-kit" | "custom";
         source: string[];
         themes?: Record<string, string[]> | undefined;
     }, {
-        type: "starter-kit" | "custom";
         source: string[];
         themes?: Record<string, string[]> | undefined;
-    }>, z.ZodRecord<z.ZodString, z.ZodObject<{
+    }>>, z.ZodObject<{
         source: z.ZodArray<z.ZodString, "many">;
-        type: z.ZodEnum<["starter-kit", "custom"]>;
         themes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
     }, "strip", z.ZodTypeAny, {
-        type: "starter-kit" | "custom";
         source: string[];
         themes?: Record<string, string[]> | undefined;
     }, {
-        type: "starter-kit" | "custom";
         source: string[];
         themes?: Record<string, string[]> | undefined;
-    }>>]>;
-    options: z.ZodOptional<z.ZodObject<{
+    }>]>>;
+    transforms: z.ZodOptional<z.ZodObject<{
         fluid: z.ZodOptional<z.ZodObject<{
             min: z.ZodNumber;
             max: z.ZodNumber;
-        }, "strict", z.ZodTypeAny, {
+        }, "strip", z.ZodTypeAny, {
             min: number;
             max: number;
         }, {
             min: number;
             max: number;
         }>>;
-        prefix: z.ZodOptional<z.ZodString>;
-        color: z.ZodOptional<z.ZodEnum<["hex", "rgb", "rgba", "hsl", "hsla", "oklch", "p3"]>>;
+        colorFallbackStrategy: z.ZodOptional<z.ZodEnum<["native", "polyfill"]>>;
     }, "strip", z.ZodTypeAny, {
-        color?: "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "oklch" | "p3" | undefined;
         fluid?: {
             min: number;
             max: number;
         } | undefined;
-        prefix?: string | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
     }, {
-        color?: "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "oklch" | "p3" | undefined;
         fluid?: {
             min: number;
             max: number;
         } | undefined;
-        prefix?: string | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
     }>>;
-    output: z.ZodObject<{
-        directories: z.ZodObject<{
-            tokens: z.ZodString;
-            components: z.ZodOptional<z.ZodString>;
-            css: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            css: string;
-            tokens: string;
-            components?: string | undefined;
-        }, {
-            css: string;
-            tokens: string;
-            components?: string | undefined;
-        }>;
-        css: z.ZodObject<{
-            separate: z.ZodBoolean;
-            manageIndex: z.ZodOptional<z.ZodBoolean>;
-            format: z.ZodOptional<z.ZodEnum<["css", "scss", "less"]>>;
-        }, "strip", z.ZodTypeAny, {
-            separate: boolean;
-            manageIndex?: boolean | undefined;
-            format?: "css" | "scss" | "less" | undefined;
-        }, {
-            separate: boolean;
-            manageIndex?: boolean | undefined;
-            format?: "css" | "scss" | "less" | undefined;
-        }>;
+    output: z.ZodOptional<z.ZodObject<{
+        css: z.ZodOptional<z.ZodString>;
+        components: z.ZodOptional<z.ZodString>;
+        separate: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        css: {
-            separate: boolean;
-            manageIndex?: boolean | undefined;
-            format?: "css" | "scss" | "less" | undefined;
-        };
-        directories: {
-            css: string;
-            tokens: string;
-            components?: string | undefined;
-        };
+        css?: string | undefined;
+        components?: string | undefined;
+        separate?: boolean | undefined;
     }, {
-        css: {
-            separate: boolean;
-            manageIndex?: boolean | undefined;
-            format?: "css" | "scss" | "less" | undefined;
-        };
-        directories: {
-            css: string;
-            tokens: string;
-            components?: string | undefined;
-        };
-    }>;
+        css?: string | undefined;
+        components?: string | undefined;
+        separate?: boolean | undefined;
+    }>>;
+    utilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+        collection: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }>, z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+        collection: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }>, "many">]>>>;
 }, "strip", z.ZodTypeAny, {
-    tokens: {
-        type: "starter-kit" | "custom";
+    tokens?: {
         source: string[];
         themes?: Record<string, string[]> | undefined;
     } | Record<string, {
-        type: "starter-kit" | "custom";
         source: string[];
         themes?: Record<string, string[]> | undefined;
-    }>;
-    output: {
-        css: {
-            separate: boolean;
-            manageIndex?: boolean | undefined;
-            format?: "css" | "scss" | "less" | undefined;
-        };
-        directories: {
-            css: string;
-            tokens: string;
-            components?: string | undefined;
-        };
-    };
-    options?: {
-        color?: "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "oklch" | "p3" | undefined;
+    }> | undefined;
+    transforms?: {
         fluid?: {
             min: number;
             max: number;
         } | undefined;
-        prefix?: string | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
     } | undefined;
+    output?: {
+        css?: string | undefined;
+        components?: string | undefined;
+        separate?: boolean | undefined;
+    } | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }[]> | undefined;
 }, {
-    tokens: {
-        type: "starter-kit" | "custom";
+    tokens?: {
         source: string[];
         themes?: Record<string, string[]> | undefined;
     } | Record<string, {
-        type: "starter-kit" | "custom";
         source: string[];
         themes?: Record<string, string[]> | undefined;
+    }> | undefined;
+    transforms?: {
+        fluid?: {
+            min: number;
+            max: number;
+        } | undefined;
+        colorFallbackStrategy?: "native" | "polyfill" | undefined;
+    } | undefined;
+    output?: {
+        css?: string | undefined;
+        components?: string | undefined;
+        separate?: boolean | undefined;
+    } | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }[]> | undefined;
+}>;
+declare const internalConfigSchema: z.ZodObject<{
+    tokens: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodObject<{
+        source: z.ZodArray<z.ZodString, "many">;
+        themes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    }, {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    }>>, z.ZodObject<{
+        source: z.ZodArray<z.ZodString, "many">;
+        themes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    }, {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    }>]>>;
+    transforms: z.ZodObject<{
+        fluid: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            min: number;
+            max: number;
+        }, {
+            min: number;
+            max: number;
+        }>;
+        colorFallbackStrategy: z.ZodEnum<["native", "polyfill"]>;
+    }, "strip", z.ZodTypeAny, {
+        fluid: {
+            min: number;
+            max: number;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
+    }, {
+        fluid: {
+            min: number;
+            max: number;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
     }>;
+    output: z.ZodObject<{
+        css: z.ZodString;
+        components: z.ZodString;
+        separate: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        components: string;
+        css: string;
+        separate: boolean;
+    }, {
+        components: string;
+        css: string;
+        separate: boolean;
+    }>;
+    utilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+        collection: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }>, z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        directions: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, z.ZodArray<z.ZodEnum<["top", "right", "bottom", "left", "x", "y", "full", "all"]>, "many">]>>;
+        prefix: z.ZodOptional<z.ZodString>;
+        stripDuplicates: z.ZodOptional<z.ZodBoolean>;
+        collection: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }>, "many">]>>>;
+}, "strip", z.ZodTypeAny, {
     output: {
-        css: {
-            separate: boolean;
-            manageIndex?: boolean | undefined;
-            format?: "css" | "scss" | "less" | undefined;
-        };
-        directories: {
-            css: string;
-            tokens: string;
-            components?: string | undefined;
+        components: string;
+        css: string;
+        separate: boolean;
+    };
+    transforms: {
+        fluid: {
+            min: number;
+            max: number;
         };
+        colorFallbackStrategy: "native" | "polyfill";
     };
-    options?: {
-        color?: "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "oklch" | "p3" | undefined;
-        fluid?: {
+    tokens?: {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    } | Record<string, {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    }> | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }[]> | undefined;
+}, {
+    output: {
+        components: string;
+        css: string;
+        separate: boolean;
+    };
+    transforms: {
+        fluid: {
             min: number;
             max: number;
-        } | undefined;
+        };
+        colorFallbackStrategy: "native" | "polyfill";
+    };
+    tokens?: {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    } | Record<string, {
+        source: string[];
+        themes?: Record<string, string[]> | undefined;
+    }> | undefined;
+    utilities?: Record<string, {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
         prefix?: string | undefined;
-    } | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    } | {
+        source: string;
+        directions?: "top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all" | ("top" | "right" | "bottom" | "left" | "x" | "y" | "full" | "all")[] | undefined;
+        prefix?: string | undefined;
+        stripDuplicates?: boolean | undefined;
+        collection?: string | undefined;
+    }[]> | undefined;
 }>;
 
-export { type ResolvedToken, type ResolvedTokens, type SugarcubeConfig, type TokenCollection, type TokenLoader, type TokenTree, type ValidationPipelineResult, configSchema, generationPipeline, getTokenPathsFromConfig, loadConfig, manageCSSIndex, parseAndValidateConfig, tokensToCSSPipeline, validateConfig, validationPipeline, writeCSSFilesToDisk };
+/**
+ * Type guards for configuration objects.
+ * Functions to check the structure and type of configuration data.
+ */
+/**
+ * Type guard to check if tokens is a single collection.
+ *
+ * @param tokens - The tokens configuration to check
+ * @returns True if tokens is a single collection, false if it's multiple collections
+ *
+ * @example
+ * if (isSingleCollection(config.tokens)) {
+ *   // config.tokens is TokenCollection
+ * } else {
+ *   // config.tokens is TokenCollections
+ * }
+ */
+declare function isSingleCollection(tokens: TokenCollection | TokenCollections): tokens is TokenCollection;
+
+declare function isResolvedToken(token: unknown): token is ResolvedToken;
+declare function isResolvedTokenOfType<T extends TokenType>(token: unknown, type: T): token is ResolvedToken<T>;
+
+export { type ArbitraryUtilityValue, type CSSFileOutput, type Candidate, DEFAULT_COLLECTION, DEFAULT_CONFIG, DEFAULT_DESIGN_TOKENS_PATH, DEFAULT_STYLES_PATH, DEFAULT_THEME, DEFAULT_UTILITIES_FILENAME, DEFAULT_VARIABLES_FILENAME, ErrorMessages, type FunctionalCandidate, type FunctionalVariant, GLOBAL_DIR, Instrumentation, type InternalConfig, type LoadedConfig, type NamedUtilityValue, type NormalizedConvertedTokens, type OutputConfig, type PipelineResult, type ResolvedToken, type ResolvedTokens, SUGARCUBE_CONFIG_FILE, SUGARCUBE_FILE, type StaticCandidate, type StaticUtilityPattern, type StaticVariant, type TokenCollection, type TokenCollections, type TokenLoader, type TokenPipelineSource, type TokenTree, UTILITIES_DIR, type UserConfig, type UserOutputConfig, type UtilitiesConfig, type UtilityValue, VARIABLES_FILE_SUFFIX, type Variant, configFileExists, convertConfigToUnoRules, discoverAllFiles, fillDefaults, findConfigFile, generateCSSVariables, generateIndex, generateIndexContent, internalConfigSchema, isResolvedToken, isResolvedTokenOfType, isSingleCollection, loadAndResolveTokens, loadInternalConfig, loadTSConfig, loadUserConfig, parseAndValidateConfig, processAndConvertTokens, shouldRegenerateIndex, userConfigSchema, validateConfig, validateInternalConfig, validateUserConfig, writeCSSUtilitiesToDisk, writeCSSVariablesToDisk };