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

package/dist/index.d.ts

@@ -1,29 +1,60 @@
 import { z } from 'zod';
 
+/**
+ * Supported color formats for CSS output
+ */
 type ColorFormat = "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "oklch" | "p3";
-type ColorConfig = {
-    format?: ColorFormat;
-};
+/**
+ * Configuration for fluid (responsive) values
+ */
 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[]>;
 };
+/**
+ * Multiple named collections of tokens.
+ * Each key is a collection name (e.g., "base", "ui", "marketing").
+ */
 type TokenCollections = Record<string, TokenCollection>;
+/**
+ * Global options for token processing and output
+ */
 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;
 };
+/**
+ * Configuration for output directories
+ */
 type DirectoriesConfig = {
+    /** Directory containing token source files */
     tokens: string;
+    /** Optional directory for component files */
     components?: string;
+    /** Directory where CSS files will be written */
     css: string;
 };
+/**
+ * Configuration for CSS output generation
+ */
 type CSSOutputConfig = {
     /**
      * Controls how CSS variables are organized in output files:
@@ -34,412 +65,532 @@ type CSSOutputConfig = {
      * @default false
      */
     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
+ */
 type OutputConfig = {
+    /** Directory configuration for all output files */
     directories: DirectoriesConfig;
+    /** CSS-specific output configuration */
     css: CSSOutputConfig;
 };
+/**
+ * The main configuration type for Sugarcube.
+ * Defines all settings for token processing and output generation.
+ */
 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 */
     output: OutputConfig;
 }
 
 /**
- * Represents a single CSS file output with its name and content
- */
-type CSSFile = {
-    path: string;
-    css: string;
-};
-/**
- * Represents the output from generateCSS which always returns exactly one file
- */
-type SingleFileOutput = [CSSFile];
-/**
- * Represents multiple CSS file outputs from generateSeparateFiles or generateSingleFile
- */
-type CSSFileOutput = CSSFile[];
-/**
- * Result of the CSS generation process
- * For generateCSS: Contains exactly one file
- * For generate: Contains one or more files
+ * Base error type that all other error types extend from.
+ * Used as the foundation for all error types in the system.
+ * Provides a consistent structure for error messages across the codebase.
  */
-type CSSGenerationResult = {
-    output: SingleFileOutput | CSSFileOutput;
+type BaseError = {
+    /** A human-readable error message describing what went wrong */
+    message: string;
 };
 
 /**
- * A token value that can either be a raw value or a reference
+ * A token value that can either be a raw value or a reference.
+ * This is the base type for all token values in the W3C Design Token Format.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
  */
 type TokenValue<T extends TokenType> = RawTokenValue<T> | Reference<T>;
 /**
- * The actual value of a token without references
+ * The actual value of a token without references.
+ * This represents the concrete value that will be used in the final output.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
  */
 type RawTokenValue<T extends TokenType> = T extends SimpleTokenType ? SimpleTokenValue<T> : T extends CompositeTokenType ? CompositeTokenValue<T> : never;
 /**
- * A reference to another token, with optional type checking
+ * A reference to another token, with optional type checking.
+ * References are strings that point to other tokens in the token tree.
+ * The phantom type parameter ensures type safety when resolving references.
+ * @template T - The type of token being referenced
  */
 type Reference<T extends TokenType = TokenType> = string & {
+    /** Phantom type for type safety during reference resolution */
     __tokenType?: T;
 };
 /**
- * Metadata that can be attached to any node in the token tree
+ * Metadata that can be attached to any node in the token tree.
+ * This includes descriptions and custom extensions as defined in the W3C spec.
  */
 type NodeMetadata = {
+    /** Optional description of the token or group */
     $description?: string;
+    /** Optional custom extensions as defined in the W3C spec */
     $extensions?: {
         [key: string]: unknown;
     };
 };
 /**
- * A single token with its value and metadata
+ * A single token with its value and metadata.
+ * This is the basic building block of the token system.
  */
 type Token = NodeMetadata & {
+    /** The value of the token, which can be a raw value or a reference */
     $value: TokenValue<TokenType>;
+    /** Optional type specification, can be inherited from parent groups */
     $type?: TokenType;
 };
 /**
- * A group of tokens that can be nested. The type allows for:
+ * A group of tokens that can be nested.
+ * The type allows for:
  * - Regular token properties (non-$ prefixed) which must be Token | TokenGroup
  * - Metadata properties from NodeMetadata (like $description, $extensions)
  * - $type property for type inheritance as specified in the W3C spec
  * - undefined to support optional metadata properties
  */
 type TokenGroup = NodeMetadata & {
+    /** Optional type specification for the group, can be inherited by child tokens */
     $type?: TokenType;
+    /** Dynamic properties that can be either tokens, token groups, or undefined */
     [key: string]: Token | TokenGroup | TokenType | undefined;
 };
 /**
- * All possible token types, either simple or composite
+ * All possible token types, either simple or composite.
+ * This is the union of all supported token types in the system.
  */
 type TokenType = SimpleTokenType | CompositeTokenType;
 /**
- * Token types that contain a single value
+ * Token types that contain a single value.
+ * These are the basic building blocks of the token system.
  */
 type SimpleTokenType = "color" | "dimension" | "fluidDimension" | "duration" | "cubicBezier" | "fontFamily" | "fontWeight" | "number";
 /**
- * Values for simple token types
+ * Values for simple token types.
+ * Maps each simple token type to its corresponding value type.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
  */
 type SimpleTokenValue<T extends SimpleTokenType = SimpleTokenType> = T extends "color" ? Color : T extends "dimension" ? Dimension : T extends "fluidDimension" ? FluidDimension : T extends "duration" ? Duration : T extends "cubicBezier" ? CubicBezier : T extends "fontFamily" ? FontFamily : T extends "fontWeight" ? FontWeight : T extends "number" ? number : never;
 /**
- * Token types that contain multiple values or are structurally complex
+ * Token types that contain multiple values or are structurally complex.
+ * These types combine multiple simple types to create more complex tokens.
  */
 type CompositeTokenType = AlwaysDecomposedType | "border" | "shadow" | "gradient" | "transition" | StructuralCompositeType;
 /**
- * Token types that must always be broken down into their constituent parts
+ * Token types that must always be broken down into their constituent parts.
+ * These types are never used directly in CSS output.
  */
 type AlwaysDecomposedType = "typography";
 /**
- * Token types that define structural patterns
+ * Token types that define structural patterns.
+ * These types are used to define reusable patterns in the token system.
  */
 type StructuralCompositeType = "strokeStyle";
 /**
- * Values for composite token types
+ * Values for composite token types.
+ * Maps each composite token type to its corresponding value type.
+ * @template T - The type of token (e.g., "typography", "border", etc.)
  */
 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
+ * A color value in any valid CSS color format.
+ * This can be any string that is valid in CSS color contexts.
  */
 type Color = string;
 /**
- * A dimensional value with a numeric value and unit
+ * A dimensional value with a numeric value and unit.
+ * Used for measurements like width, height, spacing, etc.
  */
 type Dimension = {
+    /** The numeric value of the dimension */
     value: number;
+    /** The unit of measurement (px or rem) */
     unit: "px" | "rem";
 };
 /**
- * A fluid dimension that scales between min and max values
+ * A fluid dimension that scales between min and max values.
+ * Used for responsive design tokens that need to scale with viewport size.
  */
 type FluidDimension = {
+    /** The minimum value at the smallest viewport size */
     min: Dimension;
+    /** The maximum value at the largest viewport size */
     max: Dimension;
 };
 /**
- * A duration value with a numeric value and time unit
+ * A duration value with a numeric value and time unit.
+ * Used for animations, transitions, and other time-based values.
  */
 type Duration = {
+    /** The numeric value of the duration */
     value: number;
+    /** The unit of time (milliseconds or seconds) */
     unit: "ms" | "s";
 };
 /**
- * A cubic bezier curve defined by four control points
+ * A cubic bezier curve defined by four control points.
+ * Used for defining custom easing functions in animations and transitions.
+ * The four numbers represent the x,y coordinates of the two control points.
  */
 type CubicBezier = [number, number, number, number];
 /**
- * A font family name or list of fallback fonts
+ * A font family name or list of fallback fonts.
+ * Can be a single font name or an array of fonts in order of preference.
  */
 type FontFamily = string | string[];
 /**
- * A font weight value as either a number or semantic string
+ * A font weight value as either a number or semantic string.
+ * Numbers range from 100-900, strings are semantic names for common weights.
  */
 type FontWeight = number | FontWeightString;
 /**
- * Semantic font weight names
+ * Semantic font weight names.
+ * These are standardized names for common font weights.
  */
 type FontWeightString = "thin" | "hairline" | "extra-light" | "ultra-light" | "light" | "normal" | "regular" | "book" | "medium" | "semi-bold" | "demi-bold" | "bold" | "extra-bold" | "ultra-bold" | "black" | "heavy" | "extra-black" | "ultra-black";
 /**
- * Line cap style for strokes
+ * Line cap style for strokes.
+ * Defines how the end of a stroke should be rendered.
  */
 type LineCap = "round" | "butt" | "square";
 /**
- * Typography token combining font properties
+ * Typography token combining font properties.
+ * This is a composite type that combines multiple font-related properties.
  */
 type Typography = {
+    /** The font family to use */
     fontFamily: TokenValue<"fontFamily">;
+    /** The size of the font */
     fontSize: TokenValue<"dimension">;
+    /** Optional font weight */
     fontWeight?: TokenValue<"fontWeight">;
+    /** Optional letter spacing */
     letterSpacing?: TokenValue<"dimension">;
+    /** Optional line height as a multiplier */
     lineHeight?: TokenValue<"number">;
 };
 /**
- * Transition token defining animation properties
+ * Transition token defining animation properties.
+ * Used to define how properties should animate between states.
  */
 type Transition = {
+    /** How long the transition should take */
     duration: TokenValue<"duration">;
+    /** Optional delay before the transition starts */
     delay?: TokenValue<"duration">;
+    /** The easing function to use for the transition */
     timingFunction: TokenValue<"cubicBezier">;
 };
 /**
- * Predefined stroke style keywords
+ * Predefined stroke style keywords.
+ * These are the standard stroke styles available in CSS.
  */
 type StrokeStyleKeyword = "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "outset" | "inset";
 /**
- * Custom stroke style definition
+ * Custom stroke style definition.
+ * Used when the predefined stroke styles are not sufficient.
  */
 type StrokeStyleCustom = {
+    /** Array of dimensions defining the dash pattern */
     dashArray: Array<TokenValue<"dimension">>;
+    /** How the ends of the stroke should be rendered */
     lineCap: LineCap;
 };
 /**
- * A stroke style that can be either a keyword or custom definition
+ * A stroke style can be either a predefined keyword or a custom definition.
+ * This allows for both simple and complex stroke styles.
  */
 type StrokeStyle = StrokeStyleKeyword | StrokeStyleCustom;
 /**
- * Border token combining color, width, and style
+ * Border token combining color, width, and style.
+ * This is a composite type that defines a complete border.
  */
 type Border = {
+    /** The color of the border */
     color: TokenValue<"color">;
+    /** The width of the border */
     width: TokenValue<"dimension">;
+    /** The style of the border, either a stroke style or a reference to one */
     style: StrokeStyle | Reference<"strokeStyle">;
 };
 /**
- * Individual shadow definition
+ * A single shadow definition.
+ * This is the basic building block for shadow tokens.
  */
 type ShadowObject = {
+    /** The color of the shadow */
     color: TokenValue<"color">;
+    /** Horizontal offset of the shadow */
     offsetX: TokenValue<"dimension">;
+    /** Vertical offset of the shadow */
     offsetY: TokenValue<"dimension">;
+    /** How much the shadow should blur */
     blur: TokenValue<"dimension">;
+    /** How much the shadow should spread */
     spread: TokenValue<"dimension">;
+    /** Whether the shadow should be inset */
     inset?: boolean;
 };
 /**
- * Shadow token that can be single or multiple shadows
+ * A shadow can be either a single shadow or multiple shadows.
+ * Multiple shadows are rendered in order, with later shadows appearing on top.
  */
 type Shadow = ShadowObject | ShadowObject[];
 /**
- * Color stop in a gradient
+ * A single stop in a gradient.
+ * Defines the color and position of a point in the gradient.
  */
 type GradientStop = {
+    /** The color at this point in the gradient */
     color: TokenValue<"color">;
+    /** The position of this point in the gradient (0-1) */
     position: number | Reference<"number">;
 };
 /**
- * Gradient defined as a list of color stops
+ * A gradient is defined by a series of stops.
+ * The stops define how the gradient transitions between colors.
  */
 type Gradient = GradientStop[];
 
 /**
- * Source information for a token, tracking its collection and theme
+ * Source information for a token, tracking its collection and theme.
+ * This metadata helps with error reporting and token organization.
  */
 type TokenSource = {
+    /** The collection this token belongs to (e.g., "base", "ui", "marketing") */
     collection: string;
+    /** Optional theme name (e.g., "dark", "light", "high-contrast") */
     theme?: string;
+    /** The path to the source file containing this token */
     sourcePath: string;
 };
 /**
- * A complete token tree with collection and theme information
+ * A complete token tree with collection and theme information.
+ * This represents a single token file's contents with its metadata.
  */
 type TokenTree = {
+    /** The collection this token tree belongs to (e.g., "base", "ui", "marketing") */
     collection: string;
+    /** Optional theme name (e.g., "dark", "light", "high-contrast") */
     theme?: string;
+    /** The actual token data following the W3C design tokens format */
     tokens: TokenGroup;
+    /** The path to the source file containing these tokens */
     sourcePath: string;
 };
 
 /**
- * Base error type that all other error types extend from.
- * Used as the foundation for all error types in the system.
- */
-type BaseError = {
-    message: string;
-};
-
-/**
- * A flattened token with its source information and path
+ * 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.
+ * @template T - The type of token (e.g., "color", "dimension", etc.)
  */
 type FlattenedToken<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 */
     $path: string;
+    /** Information about where this token was loaded from */
     $source: TokenSource;
+    /** The original path before flattening */
     $originalPath: string;
 };
 /**
- * A map of flattened tokens and metadata by their lookup path, with an index for quick reference lookups
+ * 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.
  */
 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>;
 };
 /**
- * An error that occurred during token flattening
+ * 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;
 };
 
 /**
- * An error that occurred during token validation
+ * Represents a single CSS file output with its path and content
  */
-type ValidationError = BaseError & {
+type CSSFile = {
+    /** The path where the CSS file will be written */
     path: string;
-    source: TokenSource;
+    /** The CSS content to write to the file */
+    css: string;
+};
+/**
+ * Represents multiple CSS file outputs from generateSeparateFiles or generateSingleFile
+ */
+type CSSFileOutput = CSSFile[];
+
+/**
+ * Data structure for loading tokens from memory.
+ * Maps file paths to their token content and metadata.
+ * Used for programmatic token loading.
+ */
+type TokenMemoryData = Record<string, {
+    /** The collection name this token belongs to */
+    collection: string;
+    /** Optional theme name for themed tokens */
+    theme?: string;
+    /** The raw token content as a string */
+    content: string;
+}>;
+/**
+ * An error that occurred during token loading.
+ * Extends the base error type with file-specific information.
+ */
+type LoadError = BaseError & {
+    /** The file path where the error occurred */
+    file: string;
 };
 
 /**
- * A resolved token with its final value
+ * 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
+ * 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
+ * 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
+ * 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 warning that occurred during token normalization
- */
-type NormalizationWarning = {
-    type: "warning";
-    message: string;
-    file: string;
-    collection: string;
-    theme?: string;
-};
-/**
- * An error that occurred during token normalization
- */
-type NormalizationError = ValidationError & {
-    collection: string;
-    theme: string;
-};
-/**
- * A set of tokens for a theme, including metadata nodes
- */
-type ThemeTokenSet = {
-    default: ResolvedTokens;
-    [theme: string]: ResolvedTokens;
-};
-/**
- * Normalized tokens organized by collection and theme
- */
-type NormalizedTokens = {
-    [collection: string]: ThemeTokenSet;
-};
-/**
- * Result of the normalization process
+ * An error that occurred during token validation.
+ * Extends the base error type with token-specific information.
  */
-type NormalizeResult = {
-    tokens: NormalizedTokens;
-    errors: NormalizationError[];
-    warnings: NormalizationWarning[];
+type ValidationError = BaseError & {
+    /** The path to the token that failed validation */
+    path: string;
+    /** Source information about where the token was loaded from */
+    source: TokenSource;
 };
 
 /**
- * Result of loading token trees from files or memory
- */
-type LoadResult = {
-    trees: TokenTree[];
-    errors: LoadError[];
-};
-/**
- * Data structure for loading tokens from memory
+ * A warning that occurred during token normalization.
+ * Provides information about non-critical issues during the normalization process.
  */
-type TokenMemoryData = Record<string, {
+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;
-    content: string;
-}>;
-/**
- * An error that occurred during token loading
- */
-type LoadError = BaseError & {
-    file: string;
 };
 
 /**
- * Result of running the tokens-to-CSS pipeline
+ * Result of running the tokens-to-CSS pipeline.
+ * Contains the generated CSS files, token trees, and any errors or warnings.
  */
 type TokensToCSSPipelineResult = {
+    /** The generated 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
+ * Common error types that can occur during pipeline execution.
+ * Organizes errors by the pipeline stage where they occurred.
  */
 type PipelineErrors = {
+    /** Errors that occurred during token loading */
     load: LoadError[];
+    /** Errors that occurred during token flattening */
     flatten: FlattenError[];
+    /** Errors that occurred during token validation */
     validation: ValidationError[];
+    /** Errors that occurred during token resolution */
     resolution: ResolutionError[];
 };
 /**
- * Common warning types that can occur during pipeline execution
+ * Common warning types that can occur during pipeline execution.
+ * Organizes warnings by the pipeline stage where they occurred.
  */
 type PipelineWarnings = {
+    /** Warnings that occurred during token normalization */
     normalization: NormalizationWarning[];
 };
 /**
- * Result of running the validation pipeline
+ * 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;
 };
 /**
- * Options for loading tokens in the validation pipeline
+ * Options for loading tokens in the validation pipeline.
+ * Specifies whether to load tokens from files or memory.
  */
 type TokenLoader = {
     type: "files";
@@ -449,210 +600,244 @@ type TokenLoader = {
     data: TokenMemoryData;
 };
 /**
- * Options for configuring the validation pipeline
+ * 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
+ * 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.
+ *
+ * This pipeline orchestrates the entire token processing flow:
+ * 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
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * const result = await tokensToCSSPipeline(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 validationPipeline(config: SugarcubeConfig, options: ValidationPipelineOptions): Promise<ValidationPipelineResult>;
-
-declare function generationPipeline(trees: TokenTree[], resolved: ResolvedTokens, configState: SugarcubeConfig): Promise<GenerationPipelineResult>;
-
-declare function loadTreesFromConfig(config: SugarcubeConfig): Promise<LoadResult>;
-declare function loadTreesFromMemory(data: TokenMemoryData): Promise<LoadResult>;
-
-declare function validate(tokens: FlattenedTokens): ValidationError[];
-
-declare function flatten(trees: TokenTree[]): {
-    tokens: FlattenedTokens;
-    errors: FlattenError[];
-};
-
-declare function resolve(tokens: FlattenedTokens): {
-    resolved: ResolvedTokens;
-    errors: ResolutionError[];
-};
-
 /**
- * A processed token tree that has been filtered to only include tokens
- * from its specific collection and theme, with resolved values
+ * 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
+ *
+ * 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 config - The sugarcube configuration
+ * @param options - Pipeline options including the token loader configuration
+ * @returns The validation result containing trees, tokens, and any errors
+ *
+ * @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!");
+ * }
  */
-type ProcessedTree = {
-    collection: string;
-    theme?: string;
-    tokens: ResolvedTokens;
-};
+declare function validationPipeline(config: SugarcubeConfig, options: ValidationPipelineOptions): Promise<ValidationPipelineResult>;
 
 /**
- * Process token trees by filtering resolved tokens based on collection and theme.
- * Uses a two-level index (collection -> theme) for O(1) lookups.
+ * 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
+ *
+ * This pipeline exists to support workflows where you want to:
+ * - Validate tokens, then generate CSS
+ *
+ * @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
+ *
+ * @example
+ * // First validate tokens once
+ * const validationResult = await validationPipeline(config, options);
+ * if (validationResult.errors.validation.length > 0) {
+ *   throw new Error("Tokens failed validation");
+ * }
+ *
+ * // Generate CSS with different configs
+ * const lightThemeConfig = { ...config, options: { color: "hex" } };
+ * const darkThemeConfig = { ...config, options: { color: "rgb" } };
+ *
+ * const lightResult = await generationPipeline(
+ *   validationResult.trees,
+ *   validationResult.resolved,
+ *   lightThemeConfig
+ * );
+ *
+ * const darkResult = await generationPipeline(
+ *   validationResult.trees,
+ *   validationResult.resolved,
+ *   darkThemeConfig
+ * );
  */
-declare function processTrees(trees: TokenTree[], resolved: ResolvedTokens): ProcessedTree[];
+declare function generationPipeline(trees: TokenTree[], resolved: ResolvedTokens, configState: SugarcubeConfig): Promise<GenerationPipelineResult>;
 
 /**
- * A token that has been converted to CSS properties
- */
-type ConvertedToken<T extends TokenType = TokenType> = ResolvedToken<T> & {
-    $cssProperties: CSSProperties<T>;
-};
-/**
- * A collection of converted tokens
- */
-type ConvertedTokens = {
-    [lookupKey: string]: ConvertedToken | NodeMetadata;
-};
-/**
- * A collection of converted tokens organized by theme
- */
-type ConvertedThemeTokenSet = {
-    default: ConvertedTokens;
-    [theme: string]: ConvertedTokens;
-};
-/**
- * A collection of converted tokens organized by collection and theme
- */
-type NormalizedConvertedTokens = {
-    [collection: string]: ConvertedThemeTokenSet;
-};
-/**
- * CSS property types for different token types
- */
-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
- */
-type SimpleCSSProperties = {
-    value: string | number;
-    featureValues?: Array<{
-        query: string;
-        value: string;
-    }>;
-};
-/**
- * CSS properties that are always broken down into multiple properties
- */
-type AlwaysDecomposedProperties = CSSTypographyProperties;
-/**
- * CSS properties specific to typography tokens
- */
-type CSSTypographyProperties = {
-    "font-family": string;
-    "font-size": string;
-    "font-weight"?: number | string;
-    "letter-spacing"?: string;
-    "line-height"?: number | string;
-};
-/**
- * CSS properties for specific token types
+ * 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
+ *
+ * @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();
+ *
+ * // Load custom config file
+ * const config = await loadConfig("./config/sugarcube.json");
  */
-type CSSBorderProperties = {
-    value: string;
-};
-type CSSShadowProperties = {
-    value: string;
-};
-type CSSGradientProperties = {
-    value: string;
-};
-type CSSTransitionProperties = {
-    value: string;
-};
-
-declare function convert(tokens: NormalizedTokens, config: SugarcubeConfig): NormalizedConvertedTokens;
+declare function loadConfig(configPath?: string): Promise<SugarcubeConfig>;
 
 /**
- * Normalizes processed token trees into a collection-theme-token structure.
+ * Validates a sugarcube configuration object against the schema.
  *
- * This stage:
- * 1. Organizes tokens by collection and theme
- * 2. Removes collection prefixes from token keys (e.g., "default.color.primary" -> "color.primary")
- * 3. Preserves metadata nodes
- * 4. Maintains theme isolation (tokens only appear in their specified theme)
+ * This function:
+ * 1. Validates the configuration structure using the schema
+ * 2. Checks for duplicate filenames across collections
+ * 3. Returns the validated configuration if successful
  *
- * The output structure is:
- * {
- *   [collection]: {
- *     [theme]: {
- *       [tokenKey]: Token
- *     }
- *   }
- * }
+ * @param config - The configuration object to validate
+ * @returns The validated configuration
+ * @throws Error if the configuration is invalid or contains duplicate filenames
  *
- * For example:
- * {
- *   default: {
- *     default: { "color.primary": { $value: "#FF0000" } },
- *     dark: { "color.primary": { $value: "#000000" } }
- *   },
- *   components: {
- *     default: { "button.primary": { $value: "#00FF00" } }
+ * @example
+ * const config = {
+ *   tokens: {
+ *     source: ["tokens.json"],
+ *     type: "custom"
  *   }
- * }
+ * };
+ * const validatedConfig = validateConfig(config);
  */
-declare function normalizeTokens(trees: ProcessedTree[]): NormalizeResult;
-
+declare function validateConfig(config: Partial<SugarcubeConfig>): SugarcubeConfig;
 /**
- * Generates CSS variable files from normalized and converted design tokens.
- * Output organization is controlled by config.output.css.separate:
+ * Parses and validates a JSON configuration string.
  *
- * When separate=false (default):
- * - Generates one file per collection
- * - Each collection's tokens are combined into a single file named 'tokens.variables.css'
- * - Example for collections 'base' and 'ui':
- *   - base/tokens.variables.css
- *   - ui/tokens.variables.css
+ * This function:
+ * 1. Parses the JSON string into a configuration object
+ * 2. Validates the configuration using validateConfig
+ * 3. Returns the validated configuration if successful
  *
- * When separate=true:
- * - Generates multiple files per collection, based on source filenames
- * - Files are organized in directories by collection name
- * - Example for collection 'base' with source 'base.json' and collection 'ui' with source 'ui.json':
- *   - base/base.variables.css
- *   - ui/ui.variables.css
+ * @param configString - The JSON configuration string to parse and validate
+ * @returns The validated configuration
+ * @throws Error if the JSON is invalid or the configuration is invalid
  *
- * Note: Each collection gets its own directory regardless of the 'separate' setting.
- * This maintains a clear separation between different token collections.
+ * @example
+ * const configString = `{
+ *   "tokens": {
+ *     "source": ["tokens.json"],
+ *     "type": "custom"
+ *   }
+ * }`;
+ * const config = parseAndValidateConfig(configString);
  */
-declare function generate(tokens: NormalizedConvertedTokens, config: SugarcubeConfig): Promise<CSSGenerationResult>;
+declare function parseAndValidateConfig(configString: string): SugarcubeConfig;
 
 /**
- * Adds a warning banner to generated CSS content
- */
-declare function addWarningBanner(cssContent: string): string;
-/**
- * Gets the token file paths from config for use in warning banners
+ * 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 with directory creation
+ * Writes CSS files to disk, creating directories as needed.
+ *
+ * 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
+ *
+ * @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
+ *
+ * @example
+ * await writeCSSFilesToDisk([
+ *   { path: "styles/tokens.css", css: "body { color: red; }" }
+ * ]);
  */
 declare function writeCSSFilesToDisk(output: CSSFileOutput, addBanner?: boolean, tokenPaths?: string[]): Promise<CSSFileOutput>;
 
-/**
- * Validates the configuration object against the schema
- */
-declare function validateConfig(config: Partial<SugarcubeConfig>): SugarcubeConfig;
-/**
- * Parses and validates a JSON configuration string
- */
-declare function parseAndValidateConfig(configString: string): SugarcubeConfig;
-
-/**
- * Loads and validates the config file from disk
- */
-declare function loadConfig(configPath?: string): Promise<SugarcubeConfig>;
-
 /**
  * Manages the CSS index file that imports all CSS files.
  * @param options.cssOutputDirectory - Directory where the index.css will be created/updated
@@ -673,24 +858,24 @@ declare const configSchema: z.ZodObject<{
         type: z.ZodEnum<["starter-kit", "custom"]>;
         themes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
     }, "strip", z.ZodTypeAny, {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     }, {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     }>, 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, {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     }, {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     }>>]>;
     options: z.ZodOptional<z.ZodObject<{
@@ -773,12 +958,12 @@ declare const configSchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     tokens: {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     } | Record<string, {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     }>;
     output: {
@@ -803,12 +988,12 @@ declare const configSchema: z.ZodObject<{
     } | undefined;
 }, {
     tokens: {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     } | Record<string, {
-        source: string[];
         type: "starter-kit" | "custom";
+        source: string[];
         themes?: Record<string, string[]> | undefined;
     }>;
     output: {
@@ -833,4 +1018,4 @@ declare const configSchema: z.ZodObject<{
     } | undefined;
 }>;
 
-export { type CSSFileOutput, type CSSGenerationResult, type CSSOutputConfig, type ColorConfig, type ColorFormat, type DirectoriesConfig, type FluidConfig, type LoadError, type LoadResult, type OptionsConfig, type OutputConfig, type ResolutionError, type ResolvedToken, type ResolvedTokens, type SugarcubeConfig, type TokenCollection, type TokenCollections, type TokenLoader, type TokenMemoryData, type TokenSource, type TokenTree, type ValidationError, addWarningBanner, configSchema, convert, flatten, generate, generationPipeline, getTokenPathsFromConfig, loadConfig, loadTreesFromConfig, loadTreesFromMemory, manageCSSIndex, normalizeTokens, parseAndValidateConfig, processTrees, resolve, tokensToCSSPipeline, validate, validateConfig, validationPipeline, writeCSSFilesToDisk };
+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 };