@dsai-io/tools 0.0.1 → 1.0.7

package/dist/tokens/index.d.ts

@@ -1,4 +1,5 @@
-import { R as ResolvedConfig, O as OutputFormat } from '../types-Idj08nad.js';
+import { R as ResolvedConfig, i as ResolvedThemesConfig, j as ResolvedThemeDefinition, O as OutputFormat, b as ThemeDefinition, d as FrameworkMappingConfig, e as FrameworkMappingPattern, F as FrameworkTarget } from '../types-DabOzcsj.js';
+import { z, ZodError } from 'zod';
 
 /**
  * Token-specific type definitions
@@ -48,7 +49,7 @@ interface TokenCollection {
 /**
  * Figma export format (from Tokens Studio)
  */
-interface FigmaExport {
+interface FigmaExport$1 {
     [collectionName: string]: FigmaCollection;
 }
 /**
@@ -90,7 +91,7 @@ interface ValidationIssue {
 /**
  * Result of token validation
  */
-interface ValidationResult {
+interface ValidationResult$1 {
     /** Whether validation passed (no errors) */
     valid: boolean;
     /** Validation errors (blocking issues) */
@@ -147,6 +148,14 @@ interface TransformOptions {
     dryRun?: boolean;
     /** Enable verbose output */
     verbose?: boolean;
+    /** Enable strict schema validation */
+    strict?: boolean;
+    /** Enable incremental build (only process changed files) */
+    incremental?: boolean;
+    /** Force full rebuild (ignore cache) */
+    force?: boolean;
+    /** Cache directory for incremental builds */
+    cacheDir?: string;
 }
 /**
  * Result of token transformation
@@ -192,6 +201,8 @@ interface BuildOptions {
     skipTransform?: boolean;
     /** Only build theme CSS */
     onlyTheme?: boolean;
+    /** Source directory for Figma exports */
+    sourceDir?: string;
     /** Enable watch mode */
     watch?: boolean;
     /** Dry run (don't write files) */
@@ -200,8 +211,18 @@ interface BuildOptions {
     verbose?: boolean;
     /** Suppress output */
     quiet?: boolean;
+    /** Enable strict schema validation */
+    strict?: boolean;
+    /** Enable incremental build (only process changed files) */
+    incremental?: boolean;
+    /** Force full rebuild (ignore cache) */
+    force?: boolean;
+    /** Cache directory for incremental builds */
+    cacheDir?: string;
     /** Output directory for all formats */
     outputDir?: string;
+    /** Output formats to generate (default: ['css', 'scss', 'json']) */
+    formats?: Array<'css' | 'scss' | 'js' | 'ts' | 'json' | 'android' | 'ios'>;
     /** Per-format output directories */
     outputDirs?: Partial<Record<string, string>>;
     /** Per-format output file names */
@@ -236,6 +257,45 @@ interface BuildOptions {
         /** Style Dictionary config file name */
         styleDictionaryConfig?: string;
     };
+    /**
+     * Themes configuration for multi-theme builds.
+     * When provided with enabled: true, the 'multi-theme' step will
+     * use config-driven theme definitions instead of hardcoded themes.
+     */
+    themesConfig?: {
+        /** Whether theme building is enabled */
+        enabled?: boolean;
+        /** Theme definitions by name */
+        definitions?: Record<string, {
+            isDefault?: boolean;
+            suffix?: string | null;
+            selector: string;
+            mediaQuery?: string;
+            dataAttribute?: string;
+            outputFiles?: Partial<Record<string, string>>;
+        }>;
+    };
+    /**
+     * Post-process configuration for CSS files
+     */
+    postprocessConfig?: {
+        /** Whether postprocessing is enabled */
+        enabled?: boolean;
+        /** CSS output directory */
+        cssDir?: string;
+        /** CSS files to process */
+        files?: string[];
+        /** Text replacements to apply */
+        replacements?: Array<{
+            description?: string;
+            from: string | RegExp;
+            to: string;
+        }>;
+    };
+    /**
+     * CSS output directory (from SCSS config)
+     */
+    cssOutputDir?: string;
 }
 /**
  * Result of token build
@@ -396,6 +456,213 @@ declare function toDTCGToken(token: LegacyToken): DTCGToken;
  */
 declare function parseTokenReference(ref: string): string[] | null;
 
+/**
+ * Mode Extractor Module
+ *
+ * Extracts specific modes from nested Figma token structures.
+ * Handles the conversion from Figma's nested mode structure to flat token files.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/mode-extractor
+ */
+/**
+ * Mode extraction options
+ */
+interface ModeExtractionOptions {
+    /** Mode name to extract (e.g., 'Light', 'Dark') */
+    modeName: string;
+    /** Path to the modes in the token structure (e.g., ['Foundation', 'modes']) */
+    modesPath?: string[];
+    /** Whether to preserve non-mode tokens */
+    preserveNonModeTokens?: boolean;
+}
+/**
+ * Mode extraction result
+ */
+interface ModeExtractionResult {
+    /** Extracted tokens for the specified mode */
+    tokens: Record<string, unknown>;
+    /** Mode name that was extracted */
+    modeName: string;
+    /** Whether any tokens were found */
+    hasTokens: boolean;
+}
+/**
+ * Extract a specific mode from token structure
+ *
+ * @param tokens - Source token object
+ * @param options - Extraction options
+ * @returns Extracted tokens for the specified mode
+ *
+ * @example
+ * ```typescript
+ * const tokens = {
+ *   Foundation: {
+ *     modes: {
+ *       Light: { colors: { primary: { $value: '#0000ff' } } },
+ *       Dark: { colors: { primary: { $value: '#ffffff' } } }
+ *     }
+ *   }
+ * };
+ *
+ * const result = extractMode(tokens, {
+ *   modeName: 'Light',
+ *   modesPath: ['Foundation', 'modes']
+ * });
+ * // result.tokens = { colors: { primary: { $value: '#0000ff' } } }
+ * ```
+ */
+declare function extractMode(tokens: Record<string, unknown>, options: ModeExtractionOptions): ModeExtractionResult;
+/**
+ * Extract multiple modes from token structure
+ *
+ * @param tokens - Source token object
+ * @param modeNames - Array of mode names to extract
+ * @param modesPath - Path to modes in structure
+ * @returns Map of mode name to extracted tokens
+ *
+ * @example
+ * ```typescript
+ * const results = extractModes(tokens, ['Light', 'Dark']);
+ * // results.get('Light') = light mode tokens
+ * // results.get('Dark') = dark mode tokens
+ * ```
+ */
+declare function extractModes(tokens: Record<string, unknown>, modeNames: string[], modesPath?: string[]): Map<string, ModeExtractionResult>;
+/**
+ * Auto-detect available modes in token structure
+ *
+ * @param tokens - Source token object
+ * @param modesPath - Path to modes in structure
+ * @returns Array of detected mode names
+ *
+ * @example
+ * ```typescript
+ * const modes = detectModes(tokens);
+ * // modes = ['Light', 'Dark']
+ * ```
+ */
+declare function detectModes$2(tokens: Record<string, unknown>, modesPath?: string[]): string[];
+/**
+ * Flatten mode structure by hoisting mode tokens to top level
+ *
+ * Useful when you want to completely flatten the structure instead of preserving nesting
+ *
+ * @param tokens - Source token object
+ * @param modeName - Mode to extract
+ * @param modesPath - Path to modes
+ * @returns Flattened token structure
+ *
+ * @example
+ * ```typescript
+ * const flattened = flattenModeStructure(tokens, 'Light');
+ * // { colors: { primary: { $value: '#0000ff' } } }
+ * ```
+ */
+declare function flattenModeStructure(tokens: Record<string, unknown>, modeName: string, modesPath?: string[]): Record<string, unknown>;
+
+/**
+ * Mode Preprocessor Module
+ *
+ * Preprocesses token files by extracting mode-specific tokens into separate files.
+ * This allows theme builders to work with mode-specific token sets.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/mode-preprocessor
+ */
+/**
+ * Preprocessor configuration
+ */
+interface PreprocessorConfig {
+    /** Source directory containing original token files */
+    sourceDir: string;
+    /** Output directory for preprocessed files */
+    outputDir: string;
+    /** Files to preprocess (glob patterns or file paths) */
+    files: string[];
+    /** Mode names to extract (auto-detected if not provided) */
+    modes?: string[];
+    /** Path to modes in token structure */
+    modesPath?: string[];
+    /** Whether to preserve original files */
+    preserveOriginals?: boolean;
+    /** Whether to clean output directory before processing */
+    clean?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Preprocessing result for a single file
+ */
+interface FilePreprocessingResult {
+    /** Original file path */
+    sourceFile: string;
+    /** Detected or configured modes */
+    modes: string[];
+    /** Generated output files by mode */
+    outputFiles: Map<string, string>;
+    /** Whether preprocessing succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Overall preprocessing result
+ */
+interface PreprocessingResult {
+    /** Results for each processed file */
+    files: FilePreprocessingResult[];
+    /** Total files processed */
+    totalFiles: number;
+    /** Number of successful preprocessings */
+    successCount: number;
+    /** Number of failed preprocessings */
+    failureCount: number;
+    /** Output directory used */
+    outputDir: string;
+    /** Cleanup function to remove preprocessed files */
+    cleanup: () => void;
+}
+/**
+ * Preprocess a single token file
+ *
+ * @param filePath - Path to the token file
+ * @param config - Preprocessor configuration
+ * @returns Preprocessing result
+ */
+declare function preprocessFile(filePath: string, config: PreprocessorConfig): FilePreprocessingResult;
+/**
+ * Preprocess all token files
+ *
+ * @param config - Preprocessor configuration
+ * @returns Overall preprocessing result
+ *
+ * @example
+ * ```typescript
+ * const result = preprocessTokenFiles({
+ *   sourceDir: './src/figma-exports',
+ *   outputDir: './src/.preprocessed',
+ *   files: ['foundation.json', 'semantic.json'],
+ *   modes: ['Light', 'Dark'],
+ *   clean: true,
+ * });
+ *
+ * // Build tokens using preprocessed files...
+ *
+ * // Cleanup when done
+ * result.cleanup();
+ * ```
+ */
+declare function preprocessTokenFiles(config: PreprocessorConfig): PreprocessingResult;
+/**
+ * Get list of preprocessed files for a specific mode
+ *
+ * @param result - Preprocessing result
+ * @param modeName - Mode to get files for
+ * @returns Array of file paths for the mode
+ */
+declare function getPreprocessedFilesForMode(result: PreprocessingResult, modeName: string): string[];
+
 /**
  * Token validation module
  *
@@ -423,7 +690,7 @@ declare function parseTokenReference(ref: string): string[] | null;
  * }
  * ```
  */
-declare function validateTokens(config: ResolvedConfig, options?: ValidateOptions): Promise<ValidationResult>;
+declare function validateTokens(config: ResolvedConfig, options?: ValidateOptions): Promise<ValidationResult$1>;
 /**
  * Validate tokens and exit with code (for CLI usage)
  *
@@ -432,6 +699,305 @@ declare function validateTokens(config: ResolvedConfig, options?: ValidateOption
  */
 declare function validateTokensCLI(config: ResolvedConfig, options?: ValidateOptions): Promise<void>;
 
+/**
+ * @fileoverview Zod schemas for DTCG (Design Tokens Community Group) token format
+ * @see https://design-tokens.github.io/community-group/format/
+ */
+
+/**
+ * Base DTCG token structure
+ */
+declare const dtcgTokenBaseSchema: z.ZodObject<{
+    $value: z.ZodUnknown;
+    $type: z.ZodOptional<z.ZodEnum<{
+        string: "string";
+        number: "number";
+        color: "color";
+        dimension: "dimension";
+        fontFamily: "fontFamily";
+        fontWeight: "fontWeight";
+        shadow: "shadow";
+        duration: "duration";
+        cubicBezier: "cubicBezier";
+        strokeStyle: "strokeStyle";
+        border: "border";
+        transition: "transition";
+        gradient: "gradient";
+        typography: "typography";
+    }>>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type DTCGTokenBase = z.infer<typeof dtcgTokenBaseSchema>;
+/**
+ * Generic DTCG token (allows any token or group)
+ */
+declare const dtcgTokenSchema: z.ZodType<DTCGTokenOrGroup>;
+type DTCGTokenOrGroup = DTCGTokenBase | {
+    [key: string]: DTCGTokenOrGroup;
+};
+/**
+ * DTCG token collection (root level)
+ */
+declare const dtcgTokenCollectionSchema: z.ZodRecord<z.ZodString, z.ZodType<DTCGTokenOrGroup, unknown, z.core.$ZodTypeInternals<DTCGTokenOrGroup, unknown>>>;
+type DTCGTokenCollection = z.infer<typeof dtcgTokenCollectionSchema>;
+/**
+ * DTCG file format with optional metadata
+ */
+declare const dtcgFileSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$catchall<z.ZodType<DTCGTokenOrGroup, unknown, z.core.$ZodTypeInternals<DTCGTokenOrGroup, unknown>>>>;
+type DTCGFile = z.infer<typeof dtcgFileSchema>;
+
+/**
+ * @fileoverview Zod schemas for Figma token export format
+ * Validates the structure of tokens exported from Figma Variables API
+ */
+
+/**
+ * Figma variables API response
+ */
+declare const figmaVariablesResponseSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        variables: z.ZodRecord<z.ZodString, z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            key: z.ZodOptional<z.ZodString>;
+            resolvedType: z.ZodEnum<{
+                BOOLEAN: "BOOLEAN";
+                FLOAT: "FLOAT";
+                STRING: "STRING";
+                COLOR: "COLOR";
+            }>;
+            valuesByMode: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+                r: z.ZodNumber;
+                g: z.ZodNumber;
+                b: z.ZodNumber;
+                a: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"VARIABLE_ALIAS">;
+                id: z.ZodString;
+            }, z.core.$strip>]>>;
+            variableCollectionId: z.ZodString;
+            remote: z.ZodBoolean;
+            description: z.ZodString;
+            hiddenFromPublishing: z.ZodBoolean;
+            scopes: z.ZodArray<z.ZodString>;
+            codeSyntax: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strip>>;
+        variableCollections: z.ZodRecord<z.ZodString, z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            modes: z.ZodArray<z.ZodObject<{
+                modeId: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strip>>;
+            defaultModeId: z.ZodString;
+            remote: z.ZodBoolean;
+            hiddenFromPublishing: z.ZodBoolean;
+            variableIds: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Figma export format (as produced by @dsai-io/figma-tokens)
+ * This is the format after exportTokens() processes the Figma API response
+ */
+declare const figmaExportSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+/**
+ * Figma export with metadata
+ */
+declare const figmaExportWithMetadataSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    $description: z.ZodOptional<z.ZodString>;
+    $version: z.ZodOptional<z.ZodString>;
+    $source: z.ZodOptional<z.ZodString>;
+    $figmaFileKey: z.ZodOptional<z.ZodString>;
+    $exportedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodUnion<readonly [z.ZodObject<{
+    modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
+type FigmaVariablesResponse = z.infer<typeof figmaVariablesResponseSchema>;
+type FigmaExport = z.infer<typeof figmaExportSchema>;
+type FigmaExportWithMetadata = z.infer<typeof figmaExportWithMetadataSchema>;
+
+/**
+ * @fileoverview Zod schemas for Style Dictionary token format
+ * @see https://amzn.github.io/style-dictionary/
+ */
+
+/**
+ * Style Dictionary token (legacy format - uses "value" not "$value")
+ */
+declare const styleDictionaryTokenSchema: z.ZodObject<{
+    value: z.ZodUnknown;
+    type: z.ZodOptional<z.ZodString>;
+    comment: z.ZodOptional<z.ZodString>;
+    themeable: z.ZodOptional<z.ZodBoolean>;
+    attributes: z.ZodOptional<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        item: z.ZodOptional<z.ZodString>;
+        subitem: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    name: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    original: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnknown;
+    }, z.core.$loose>>;
+    filePath: z.ZodOptional<z.ZodString>;
+    isSource: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type StyleDictionaryTokenOrGroup = z.infer<typeof styleDictionaryTokenSchema> | {
+    [key: string]: StyleDictionaryTokenOrGroup;
+};
+/**
+ * Style Dictionary tokens collection
+ */
+declare const styleDictionaryTokensSchema: z.ZodRecord<z.ZodString, z.ZodType<StyleDictionaryTokenOrGroup, unknown, z.core.$ZodTypeInternals<StyleDictionaryTokenOrGroup, unknown>>>;
+type StyleDictionaryTokens = z.infer<typeof styleDictionaryTokensSchema>;
+/**
+ * Style Dictionary input file format
+ */
+declare const styleDictionaryInputSchema: z.ZodRecord<z.ZodString, z.ZodType<StyleDictionaryTokenOrGroup, unknown, z.core.$ZodTypeInternals<StyleDictionaryTokenOrGroup, unknown>>>;
+type StyleDictionaryInput = z.infer<typeof styleDictionaryInputSchema>;
+
+/**
+ * @fileoverview Token schema validation
+ * Exports Zod schemas and validation functions for token formats
+ */
+
+/**
+ * Validation error details
+ */
+interface ValidationError {
+    /** Path to the invalid token (e.g., "colors.primary.$value") */
+    path: string;
+    /** Error message */
+    message: string;
+    /** The invalid value */
+    value?: unknown;
+    /** Error code from Zod */
+    code?: string;
+}
+/**
+ * Validation result
+ */
+interface ValidationResult<T = unknown> {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validated and typed data (only if valid) */
+    data?: T;
+    /** Validation errors (only if invalid) */
+    errors?: ValidationError[];
+    /** Original Zod error (for debugging) */
+    zodError?: ZodError;
+}
+/**
+ * Validation options
+ */
+interface ValidationOptions {
+    /** Strict mode - treat warnings as errors */
+    strict?: boolean;
+    /** Abort after first error */
+    abortEarly?: boolean;
+}
+/**
+ * Validate DTCG token collection
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ *
+ * @example
+ * ```ts
+ * const result = validateDTCGTokens({
+ *   colors: {
+ *     primary: {
+ *       $value: '#0066ff',
+ *       $type: 'color',
+ *     },
+ *   },
+ * });
+ *
+ * if (result.valid) {
+ *   console.log('Valid tokens:', result.data);
+ * } else {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateDTCGTokens(data: unknown, _options?: ValidationOptions): ValidationResult<DTCGTokenCollection>;
+/**
+ * Validate DTCG file format
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ */
+declare function validateDTCGFile(data: unknown, _options?: ValidationOptions): ValidationResult<DTCGFile>;
+/**
+ * Validate Figma export format
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ *
+ * @example
+ * ```ts
+ * const result = validateFigmaExport(exportedData);
+ * if (!result.valid) {
+ *   console.error('Invalid Figma export:', result.errors);
+ * }
+ * ```
+ */
+declare function validateFigmaExport(data: unknown, _options?: ValidationOptions): ValidationResult<FigmaExport>;
+/**
+ * Validate Figma export with metadata
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ */
+declare function validateFigmaExportWithMetadata(data: unknown, _options?: ValidationOptions): ValidationResult<FigmaExportWithMetadata>;
+/**
+ * Validate Figma Variables API response
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ */
+declare function validateFigmaVariablesResponse(data: unknown, _options?: ValidationOptions): ValidationResult<FigmaVariablesResponse>;
+/**
+ * Validate Style Dictionary input format
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ *
+ * @example
+ * ```ts
+ * const result = validateStyleDictionaryInput(tokens);
+ * if (!result.valid) {
+ *   throw new Error(`Invalid tokens: ${result.errors.map(e => e.message).join(', ')}`);
+ * }
+ * ```
+ */
+declare function validateStyleDictionaryInput(data: unknown, _options?: ValidationOptions): ValidationResult<StyleDictionaryInput>;
+/**
+ * Validate Style Dictionary tokens
+ *
+ * @param data - Data to validate
+ * @param options - Validation options
+ * @returns Validation result with typed data
+ */
+declare function validateStyleDictionaryTokens(data: unknown, _options?: ValidationOptions): ValidationResult<StyleDictionaryTokens>;
+
 /**
  * Figma Export Validation module
  *
@@ -476,9 +1042,9 @@ interface ValidateFigmaOptions {
 /**
  * Figma validation result
  */
-interface ValidateFigmaResult extends ValidationResult {
+interface ValidateFigmaResult extends ValidationResult$1 {
     /** Per-file validation results */
-    files: Map<string, ValidationResult>;
+    files: Map<string, ValidationResult$1>;
     /** Detected modes across all files */
     detectedModes: Set<string>;
     /** Missing expected files */
@@ -487,7 +1053,7 @@ interface ValidateFigmaResult extends ValidationResult {
 /**
  * Validate a single Figma export file
  */
-declare function validateFigmaFile(filePath: string, expectedCollection?: ExpectedCollection): ValidationResult & {
+declare function validateFigmaFile(filePath: string, expectedCollection?: ExpectedCollection): ValidationResult$1 & {
     detectedModes: Set<string>;
 };
 /**
@@ -497,7 +1063,7 @@ declare function validateFigmaExports(options?: ValidateFigmaOptions): ValidateF
 /**
  * Detect modes from Figma export data
  */
-declare function detectModes$1(data: FigmaExport, collectionName?: string): string[];
+declare function detectModes$1(data: FigmaExport$1, collectionName?: string): string[];
 /**
  * CLI entry point for Figma validation
  */
@@ -532,8 +1098,10 @@ interface TokenTransformOptions {
 declare function transformValue(value: unknown, type: string | undefined, options?: TokenTransformOptions): unknown;
 /**
  * Transform type from Figma to DTCG standard
+ * @param figmaType - The original Figma type
+ * @param scopes - Token scopes to determine type-specific handling
  */
-declare function transformType(figmaType: string | undefined): TokenType | undefined;
+declare function transformType(figmaType: string | undefined, scopes?: string[]): TokenType | undefined;
 /**
  * Transform a single token from Figma format to DTCG-compliant format
  */
@@ -545,7 +1113,7 @@ declare function transformTokenTree(obj: unknown, parentKey?: string, options?:
 /**
  * Detect modes from Figma export data
  */
-declare function detectModes(data: FigmaExport, collectionPath?: string): string[];
+declare function detectModes(data: FigmaExport$1, collectionPath?: string): string[];
 /**
  * Transform Figma tokens to Style Dictionary format
  */
@@ -594,8 +1162,13 @@ declare function getDefaultSyncPaths(tokensDir: string): {
 declare function syncTokens(options: SyncOptions): SyncResult;
 /**
  * CLI entry point for token sync
+ * @param tokensDir - The tokens package directory
+ * @param customPaths - Optional custom paths for source and target files
  */
-declare function syncTokensCLI(tokensDir: string): boolean;
+declare function syncTokensCLI(tokensDir: string, customPaths?: {
+    syncSource?: string;
+    syncTarget?: string;
+}): boolean;
 
 /**
  * @file Token Build Module
@@ -643,16 +1216,380 @@ declare function syncTokensCLI(tokensDir: string): boolean;
  * });
  * ```
  */
-declare function buildTokens(tokensDir: string, toolsDir: string, options?: BuildOptions): BuildResult;
+declare function buildTokens(tokensDir: string, toolsDir: string, options?: BuildOptions): Promise<BuildResult>;
 /**
  * CLI entry point for token build
  */
-declare function buildTokensCLI(tokensDir: string, toolsDir: string, args?: string[]): boolean;
+declare function buildTokensCLI(tokensDir: string, toolsDir: string, args?: string[]): Promise<boolean>;
 /**
  * Parse CLI arguments and run build
  * Used as the main entry point when called directly
  */
-declare function runBuildCLI(tokensDir: string, toolsDir: string): void;
+declare function runBuildCLI(tokensDir: string, toolsDir: string): Promise<void>;
+
+/**
+ * Theme Discovery Module
+ *
+ * Discovers and categorizes token files by theme based on file suffix patterns.
+ * Supports both auto-detection from file names and explicit theme definitions.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/theme-discovery
+ */
+
+/**
+ * Result of theme file discovery
+ */
+interface ThemeFilesResult {
+    /** Theme name */
+    theme: string;
+    /** Theme definition */
+    definition: ResolvedThemeDefinition;
+    /** Files belonging to this theme */
+    files: string[];
+}
+/**
+ * Discovery result with all themes
+ */
+interface DiscoveryResult {
+    /** Files organized by theme - Map of theme name to file paths */
+    themes: Map<string, string[]>;
+    /** Theme definitions organized by theme name */
+    definitions: Map<string, ResolvedThemeDefinition>;
+    /** Files that couldn't be matched to any theme (when autoDetect is false) */
+    orphanFiles: string[];
+    /** Themes with no files found */
+    emptyThemes: string[];
+    /** Total files discovered */
+    totalFiles: number;
+}
+/**
+ * Options for theme discovery
+ */
+interface DiscoveryOptions {
+    /** Base directory for file patterns */
+    sourceDir: string;
+    /** Glob pattern for finding token files */
+    pattern?: string;
+    /** Whether to include verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Discover token files organized by theme
+ *
+ * This function scans the source directory for JSON token files and
+ * categorizes them by theme based on their file suffix patterns.
+ *
+ * @param themesConfig - Resolved themes configuration
+ * @param options - Discovery options including source directory
+ * @returns Discovery result with files organized by theme
+ *
+ * @example
+ * ```typescript
+ * const result = discoverThemeFiles(themesConfig, {
+ *   sourceDir: 'src/collections',
+ *   pattern: '**\/*.json',
+ * });
+ *
+ * // result.themes = [
+ * //   { theme: 'light', files: ['foundation.json', 'semantic.json'] },
+ * //   { theme: 'dark', files: ['foundation-dark.json', 'semantic-dark.json'] },
+ * // ]
+ * ```
+ */
+declare function discoverThemeFiles(themesConfig: ResolvedThemesConfig, options: DiscoveryOptions): DiscoveryResult;
+/**
+ * Get files for a specific theme
+ *
+ * For the default theme, this returns all files EXCEPT those
+ * matching other theme suffixes.
+ *
+ * For non-default themes, this returns only files with the
+ * matching suffix.
+ *
+ * @param themeName - Name of the theme to get files for
+ * @param themesConfig - Resolved themes configuration
+ * @param options - Discovery options
+ * @returns Array of file paths for the theme
+ */
+declare function getThemeFiles(themeName: string, themesConfig: ResolvedThemesConfig, options: DiscoveryOptions): string[];
+/**
+ * Auto-detect themes from file suffixes
+ *
+ * Scans files in the source directory and extracts unique
+ * theme suffixes to build a dynamic theme list.
+ *
+ * @param sourceDir - Directory to scan
+ * @param pattern - Glob pattern for files
+ * @param selectorPattern - Pattern for generating selectors
+ * @returns Map of theme names to their suffixes
+ */
+declare function autoDetectThemes(sourceDir: string, pattern?: string, selectorPattern?: string): Map<string, {
+    suffix: string | null;
+    selector: string;
+}>;
+
+/**
+ * @file Theme Builder Module
+ * @description Builds token outputs for a single theme using Style Dictionary
+ *
+ * This module orchestrates the build process for individual themes, generating
+ * the appropriate Style Dictionary configuration based on the theme definition.
+ *
+ * Key responsibilities:
+ * - Generate Style Dictionary config for a theme
+ * - Use correct CSS format based on theme type (default vs non-default)
+ * - Support all output formats (CSS, SCSS, JS, TS, JSON)
+ * - Generate output file paths from theme definition
+ *
+ * @example
+ * ```typescript
+ * import { buildTheme, generateThemeBuildConfig } from '@dsai-io/tools';
+ *
+ * const result = await buildTheme({
+ *   themeName: 'dark',
+ *   themeDefinition: {
+ *     isDefault: false,
+ *     suffix: '-dark',
+ *     selector: '[data-dsai-theme="dark"]',
+ *     outputFiles: { css: 'tokens-dark.css' },
+ *   },
+ *   files: ['collections/color-dark.json', 'collections/semantic-dark.json'],
+ *   outputDir: 'dist',
+ *   config: resolvedConfig,
+ * });
+ * ```
+ *
+ * @module @dsai-io/tools/tokens/theme-builder
+ */
+
+/**
+ * Minimal configuration required for theme building
+ *
+ * This interface only includes the properties actually used by the theme builder,
+ * allowing callers to pass either a full ResolvedTokensConfig or a minimal object.
+ */
+interface ThemeBuildConfig {
+    /** Output formats to generate */
+    formats: OutputFormat[];
+    /** Theme definitions (used by buildAllThemes to lookup theme metadata) */
+    themes?: {
+        definitions?: Record<string, ThemeDefinition | ResolvedThemeDefinition>;
+    };
+}
+/**
+ * Options for building a single theme
+ */
+interface ThemeBuildOptions {
+    /** Name of the theme (e.g., 'light', 'dark', 'pro') */
+    themeName: string;
+    /** Resolved theme definition with all required fields */
+    themeDefinition: ResolvedThemeDefinition;
+    /** Array of token file paths for this theme */
+    files: string[];
+    /** Output directory for generated files */
+    outputDir: string;
+    /** Build configuration (formats and optionally theme definitions) */
+    config: ThemeBuildConfig;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Skip cache lookup (force rebuild) */
+    skipCache?: boolean;
+}
+/**
+ * Result of building a single theme
+ */
+interface ThemeBuildResult {
+    /** Whether the build succeeded */
+    success: boolean;
+    /** Theme name that was built */
+    themeName: string;
+    /** Generated output files by format */
+    outputs: Partial<Record<OutputFormat, string[]>>;
+    /** Error message if build failed */
+    error?: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Whether result was from cache */
+    fromCache: boolean;
+}
+/**
+ * Style Dictionary configuration for a theme
+ */
+interface ThemeStyleDictionaryConfig {
+    /** Source token files */
+    source: string[];
+    /** Platform configurations */
+    platforms: Record<string, StyleDictionaryPlatformConfig>;
+    /** Whether tokens use DTCG format ($value, $type, etc.) */
+    usesDtcg?: boolean;
+    /** Logging configuration */
+    log?: {
+        warnings?: 'warn' | 'error' | 'disabled';
+        verbosity?: 'default' | 'silent' | 'verbose';
+        errors?: {
+            brokenReferences?: 'throw' | 'console';
+        };
+    };
+}
+/**
+ * Style Dictionary platform configuration
+ */
+interface StyleDictionaryPlatformConfig {
+    /** Transform group to use */
+    transformGroup?: string;
+    /** Build path for outputs */
+    buildPath: string;
+    /** Output file configurations */
+    files: StyleDictionaryFileConfig[];
+    /** Custom options for formats */
+    options?: Record<string, unknown>;
+}
+/**
+ * Style Dictionary file configuration
+ */
+interface StyleDictionaryFileConfig {
+    /** Output file path (relative to buildPath) */
+    destination: string;
+    /** Format to use for output */
+    format: string;
+    /** Filter for tokens to include */
+    filter?: Record<string, unknown>;
+    /** Format-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Generate Style Dictionary configuration for a single theme
+ *
+ * @param options - Theme build options
+ * @returns Style Dictionary configuration object
+ *
+ * @example
+ * ```typescript
+ * const sdConfig = generateThemeBuildConfig({
+ *   themeName: 'dark',
+ *   themeDefinition: { isDefault: false, selector: '[data-dsai-theme="dark"]' },
+ *   files: ['collections/color-dark.json'],
+ *   outputDir: 'dist',
+ *   config: resolvedConfig,
+ * });
+ * // Returns Style Dictionary config with dark mode format
+ * ```
+ */
+declare function generateThemeBuildConfig(options: ThemeBuildOptions): ThemeStyleDictionaryConfig;
+/**
+ * Build token outputs for a single theme
+ *
+ * This function generates Style Dictionary configuration from the theme
+ * definition and runs the build process. For default themes, it uses
+ * `css/variables-with-comments` format with `:root` selector. For
+ * non-default themes, it uses `css/variables-dark-mode` with the
+ * theme-specific selector.
+ *
+ * @param options - Theme build options
+ * @returns Build result with success status and output files
+ *
+ * @example
+ * ```typescript
+ * const result = await buildTheme({
+ *   themeName: 'dark',
+ *   themeDefinition: resolvedThemeDef,
+ *   files: ['collections/color-dark.json'],
+ *   outputDir: 'dist',
+ *   config: resolvedConfig,
+ *   verbose: true,
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Built files:', result.outputs);
+ * }
+ * ```
+ */
+declare function buildTheme(options: ThemeBuildOptions): Promise<ThemeBuildResult>;
+/**
+ * Options for building multiple themes
+ */
+interface MultiThemeBuildOptions {
+    /** Build configuration with formats and theme definitions */
+    config: ThemeBuildConfig;
+    /** Map of theme name to file paths */
+    themeFiles: Map<string, string[]>;
+    /** Output directory for all themes */
+    outputDir: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Only build these specific themes (if not set, build all) */
+    themes?: string[];
+    /** Skip cache lookup */
+    skipCache?: boolean;
+}
+/**
+ * Result of building multiple themes
+ */
+interface MultiThemeBuildResult {
+    /** Overall success (true if all themes succeeded) */
+    success: boolean;
+    /** Individual theme results */
+    results: ThemeBuildResult[];
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Number of themes built successfully */
+    successCount: number;
+    /** Number of themes that failed */
+    failCount: number;
+}
+/**
+ * Build multiple themes in sequence
+ *
+ * This function iterates through all configured themes and builds each one
+ * using the appropriate Style Dictionary configuration. It collects results
+ * and returns a summary of the build process.
+ *
+ * @param options - Multi-theme build options
+ * @returns Aggregated build results
+ *
+ * @example
+ * ```typescript
+ * const result = await buildAllThemes({
+ *   config: resolvedConfig,
+ *   themeFiles: new Map([
+ *     ['light', ['collections/color.json']],
+ *     ['dark', ['collections/color-dark.json']],
+ *   ]),
+ *   outputDir: 'dist',
+ *   verbose: true,
+ * });
+ *
+ * console.log(`Built ${result.successCount}/${result.results.length} themes`);
+ * ```
+ */
+declare function buildAllThemes(options: MultiThemeBuildOptions): Promise<MultiThemeBuildResult>;
+/**
+ * Get the appropriate CSS format for a theme
+ *
+ * @param isDefault - Whether this is the default theme
+ * @returns Style Dictionary format name
+ */
+declare function getCssFormat(isDefault: boolean): string;
+/**
+ * Get the CSS selector for a theme
+ *
+ * @param themeDefinition - Resolved theme definition
+ * @returns CSS selector string
+ */
+declare function getThemeSelector(themeDefinition: ResolvedThemeDefinition): string;
+/**
+ * Validate theme definitions for conflicts
+ *
+ * Checks for:
+ * - Multiple default themes
+ * - Duplicate selectors
+ * - Duplicate suffixes
+ *
+ * @param definitions - Map of theme name to definition
+ * @returns Array of validation error messages
+ */
+declare function validateThemeDefinitions(definitions: Map<string, ResolvedThemeDefinition>): string[];
 
 /**
  * @file Token Clean Module
@@ -1486,6 +2423,17 @@ interface SDLogConfig {
     /** How to handle errors */
     errors?: 'error' | 'throw';
 }
+/**
+ * Expand configuration for composite tokens
+ */
+interface SDExpandConfig {
+    /** Optional type mapping for composite token properties */
+    typesMap?: Record<string, string | string[] | Record<string, string | string[]>>;
+    /** Include specific token types */
+    include?: string[] | ((token: SDToken, config: SDConfig) => boolean);
+    /** Exclude specific token types */
+    exclude?: string[] | ((token: SDToken, config: SDConfig) => boolean);
+}
 /**
  * Full Style Dictionary configuration
  */
@@ -1494,6 +2442,8 @@ interface SDConfig {
     log?: SDLogConfig;
     /** Preprocessors to run on source tokens */
     preprocessors?: string[];
+    /** Configures whether and how composite tokens will be expanded */
+    expand?: boolean | SDExpandConfig | ((token: SDToken, config: SDConfig) => boolean);
     /** Source token file patterns */
     source?: string[];
     /** Additional files to include */
@@ -1999,11 +2949,11 @@ declare const cssTransformGroup: TransformGroupDefinition;
  */
 
 /**
- * custom/js transform group
+ * js-custom transform group
  *
  * Transforms for generating JavaScript/TypeScript exports:
  * - attribute/cti: Add CTI attributes
- * - name/camel: camelCase names
+ * - name/js-identifier: PascalCase names with numeric segment handling
  * - fontWeight/unitless: Keep font weights unitless
  * - lineHeight/unitless: Keep line heights unitless
  * - dimension/rem: Convert dimensions to rem
@@ -2067,4 +3017,295 @@ declare const transformGroups: TransformGroupDefinition[];
  */
 declare function registerTransformGroups(sd: StyleDictionaryInstance, customGroups?: TransformGroupDefinition[]): void;
 
-export { type BuildOptions, type BuildResult, type BuildStep, type BundleConfig, type BundleResult, type CleanOptions, type CleanResult, type CleanedDirectory, type CreateSDConfigOptions, DEFAULT_CLEAN_DIRECTORIES, DEFAULT_FILE_NAMES, type DTCGToken, type FigmaCollection, type FigmaExport, type FormatDefinition, type LegacyToken, type MergeConfig, type MergeContent, type MergeOptions, type MergeResult, type OutputConfig, type PlaceholderValues, type PostprocessOptions, type PostprocessResult, type PreprocessorDefinition, type ReplacementRule, type SDConfig, type SDDictionary, type SDFile, type SDFormatArgs, type SDLogConfig, type SDPlatform, type SDPlatformType, type SDToken, type SDTransformOptions, type StyleDictionaryInstance, type StyleMergeResult, type StyleScannedFile, type StyleScannerOptions, type StyleScannerResult, type SyncOptions, type SyncResult, type Token, type TokenCollection, type TransformOptions as TokenTransformOptions, type TransformResult as TokenTransformResult, type TokenType, type ValidationResult as TokenValidationResult, type TransformDefinition, type TransformGroupDefinition, type TransformType, VALID_TOKEN_TYPES, type ValidateOptions, type ValidationIssue, type ValidationSeverity, addScssImportHeader, buildTokens, buildTokensCLI, builtInFormats, builtInPreprocessors, builtInTransforms, cleanTokenOutputs, cleanTokensCLI, createBundle, createBundleFromFiles, createBundles, createFixReferencesPreprocessor, createOutputConfig, createStyleDictionaryConfig, cssTransformGroup, cssVariablesWithComments, detectModes$1 as detectFigmaModes, detectModes as detectTransformModes, dimensionRem, ensureOutputDirs, filterFiles, fixReferences, fontWeightUnitless, getDefaultCssDir, getDefaultFiles, getDefaultIgnorePatterns, getDefaultSyncPaths, getDefaultTransformations, getSDTokenType, getSDTokenValue, getTokenDescription, getTokenType, getTokenValue, hasDTCGValue, isDTCGToken, isLegacyToken, isSDToken, isToken, isTokenReference, isValidTokenType, jsTransformGroup, lineHeightUnitless, loadContent, mergeCollections, mergeCollectionsCLI, mergeContent, nameKebab, parseTokenReference, postprocessCLI, postprocessCss, postprocessCssFiles, processScssImportHeader, registerAll, registerFormats, registerPreprocessors, registerTransformGroups, registerTransforms, replacePlaceholders, resolveAllOutputPaths, resolveOutputPath, runBuildCLI, scanDirectories, scssTransformGroup, setupStyleDictionary, sortFiles, syncTokens, syncTokensCLI, toDTCGToken, transformGroups, transformToken, transformTokenTree, transformTokens, transformTokensCLI, transformType, transformValue, typescriptDeclarations, validateFigmaCLI, validateFigmaExports, validateFigmaFile, validateOutputPaths, validateTokens, validateTokensCLI };
+/**
+ * Bootstrap Framework Mapper
+ *
+ * Maps Figma/DTCG token names to Bootstrap 5.x variable names.
+ * This is the complete mapping list extracted from the playground's
+ * _variables.scss compatibility layer.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Complete token name → Bootstrap variable name mappings
+ *
+ * These mappings handle cases where Figma/DTCG token naming conventions
+ * differ from Bootstrap 5.x variable naming conventions.
+ *
+ * The mappings are extracted from the playground's manual _variables.scss
+ * compatibility layer to ensure complete parity.
+ *
+ * CATEGORIES:
+ * - Typography: Font sizes, weights, headings, display, line heights, letter spacing
+ * - Colors: Pass through (no mapping needed - names match)
+ * - Spacing: Pass through (no mapping needed - names match)
+ * - Layout: Pass through (no mapping needed - names match)
+ * - Shadows: Custom mappings to Bootstrap shadow variable names
+ * - Border Radius: Custom mappings to Bootstrap radius variable names
+ */
+declare const BOOTSTRAP_MAPPINGS: Record<string, string>;
+/**
+ * Pattern-based mappings for Bootstrap
+ *
+ * Applied after explicit mappings for tokens that follow
+ * predictable naming patterns. These handle bulk transformations
+ * for categories with consistent naming.
+ */
+declare const BOOTSTRAP_PATTERNS: FrameworkMappingPattern[];
+/**
+ * Bootstrap framework mapping configuration
+ */
+declare const bootstrapMapper: FrameworkMappingConfig;
+/**
+ * Apply Bootstrap-specific name mapping to a token name
+ *
+ * @param tokenName - Original token name (e.g., 'typography-heading-h1')
+ * @returns Mapped name (e.g., 'h1-font-size')
+ *
+ * @example
+ * ```typescript
+ * mapToBootstrapName('typography-text-base')
+ * // Returns: 'font-size-base'
+ *
+ * mapToBootstrapName('typography-heading-h1')
+ * // Returns: 'h1-font-size'
+ *
+ * mapToBootstrapName('color-blue-500')
+ * // Returns: 'color-blue-500' (pass through)
+ * ```
+ */
+declare function mapToBootstrapName(tokenName: string): string;
+
+/**
+ * shadcn/ui Framework Mapper
+ *
+ * Maps Figma/DTCG token names to shadcn/ui CSS variable names.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Explicit token name → shadcn/ui variable name mappings
+ *
+ * shadcn/ui uses a simplified naming convention with CSS custom properties.
+ * @see https://ui.shadcn.com/docs/theming
+ */
+declare const SHADCN_MAPPINGS: Record<string, string>;
+/**
+ * shadcn/ui framework mapping configuration
+ */
+declare const shadcnMapper: FrameworkMappingConfig;
+/**
+ * Apply shadcn-specific name mapping to a token name
+ *
+ * @param tokenName - Original token name (e.g., 'semantic-primary')
+ * @returns Mapped name (e.g., 'primary')
+ */
+declare function mapToShadcnName(tokenName: string): string;
+
+/**
+ * Framework Mapper Utilities
+ *
+ * Core utilities for applying framework-specific name mappings to tokens.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Framework mapper function type
+ */
+type FrameworkMapper = (tokenName: string) => string;
+/**
+ * Framework mapper with configuration
+ */
+interface FrameworkMapperWithConfig {
+    /** The mapping function */
+    map: FrameworkMapper;
+    /** The framework configuration */
+    config: FrameworkMappingConfig;
+}
+/**
+ * Get the framework mapper for a specific target
+ *
+ * @param framework - Target framework
+ * @returns Framework mapper with config
+ */
+declare function getFrameworkMapper(framework: FrameworkTarget): FrameworkMapperWithConfig;
+/**
+ * Create a custom framework mapper with user-provided mappings
+ *
+ * @param baseFramework - Base framework to extend (or 'custom' for empty)
+ * @param customMappings - Additional name mappings
+ * @param customPatterns - Additional pattern mappings
+ * @returns Combined framework mapper
+ */
+declare function createFrameworkMapper(baseFramework: FrameworkTarget, customMappings?: Record<string, string>, customPatterns?: FrameworkMappingPattern[]): FrameworkMapperWithConfig;
+/**
+ * Apply name mapping to a token name using specified framework
+ *
+ * @param tokenName - Original token name
+ * @param framework - Target framework
+ * @param customMappings - Optional custom mappings to merge
+ * @returns Mapped token name
+ */
+declare function applyNameMapping(tokenName: string, framework?: FrameworkTarget, customMappings?: Record<string, string>): string;
+
+/**
+ * Token Diff Utility
+ *
+ * Compares token collections to detect changes for changelog generation.
+ * Identifies added, removed, modified, and type-changed tokens.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Types of changes that can occur to tokens
+ */
+type TokenChangeType = 'added' | 'removed' | 'modified' | 'type-changed' | 'deprecated';
+/**
+ * Details about a token value change
+ */
+interface TokenValueChange {
+    /** Previous value */
+    oldValue: unknown;
+    /** New value */
+    newValue: unknown;
+    /** Previous type */
+    oldType?: string;
+    /** New type */
+    newType?: string;
+}
+/**
+ * Information about a single token change
+ */
+interface TokenChange {
+    /** Full token path (e.g., 'color.brand.primary') */
+    path: string;
+    /** Type of change */
+    type: TokenChangeType;
+    /** Value change details (for modified/type-changed) */
+    valueChange?: TokenValueChange;
+    /** Token description */
+    description?: string;
+    /** Whether this is a breaking change */
+    breaking: boolean;
+}
+/**
+ * Result of comparing two token collections
+ */
+interface TokenDiff {
+    /** Tokens that were added */
+    added: TokenChange[];
+    /** Tokens that were removed */
+    removed: TokenChange[];
+    /** Tokens whose values changed */
+    modified: TokenChange[];
+    /** Tokens whose types changed (breaking) */
+    typeChanged: TokenChange[];
+    /** Tokens marked as deprecated */
+    deprecated: TokenChange[];
+    /** Total number of changes */
+    totalChanges: number;
+    /** Whether there are breaking changes */
+    hasBreaking: boolean;
+}
+/**
+ * Compare two token collections and return the differences
+ *
+ * @param oldTokens - Previous version of tokens
+ * @param newTokens - New version of tokens
+ * @returns Detailed diff of all changes
+ */
+declare function diffTokens(oldTokens: TokenCollection, newTokens: TokenCollection): TokenDiff;
+/**
+ * Get a summary of changes as a plain text description
+ */
+declare function summarizeDiff(diff: TokenDiff): string;
+/**
+ * Filter diff by change type
+ */
+declare function filterDiff(diff: TokenDiff, types: TokenChangeType[]): TokenChange[];
+/**
+ * Get only breaking changes
+ */
+declare function getBreakingChanges(diff: TokenDiff): TokenChange[];
+
+/**
+ * Token Changelog Generator
+ *
+ * Generates human-readable changelogs from token diffs in Markdown format.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for changelog generation
+ */
+interface ChangelogOptions {
+    /** Version number (e.g., '1.2.0') */
+    version?: string;
+    /** Release date (defaults to today) */
+    date?: Date;
+    /** Custom header for the changelog entry */
+    header?: string;
+    /** Whether to include descriptions */
+    includeDescriptions?: boolean;
+    /** Whether to include value changes (before/after) */
+    includeValues?: boolean;
+    /** Maximum value length to display (truncates longer values) */
+    maxValueLength?: number;
+    /** Whether to group by change type */
+    groupByType?: boolean;
+}
+/**
+ * Result of changelog generation
+ */
+interface ChangelogResult {
+    /** Generated Markdown content */
+    content: string;
+    /** Number of entries in the changelog */
+    entryCount: number;
+    /** Whether there are breaking changes */
+    hasBreaking: boolean;
+}
+/**
+ * Generate a changelog entry from a token diff
+ *
+ * @param diff - Token diff to generate changelog from
+ * @param options - Changelog options
+ * @returns Generated changelog content
+ */
+declare function generateChangelog(diff: TokenDiff, options?: ChangelogOptions): ChangelogResult;
+/**
+ * Write changelog to file (append mode)
+ *
+ * @param content - Changelog content to write
+ * @param filePath - Path to changelog file
+ * @returns Whether the write was successful
+ */
+declare function writeChangelog(content: string, filePath: string): Promise<boolean>;
+/**
+ * Generate and write changelog in one step
+ *
+ * @param diff - Token diff to generate changelog from
+ * @param filePath - Path to changelog file
+ * @param options - Changelog options
+ * @returns Result of changelog generation
+ */
+declare function generateAndWriteChangelog(diff: TokenDiff, filePath: string, options?: ChangelogOptions): Promise<ChangelogResult & {
+    written: boolean;
+}>;
+/**
+ * CLI entry point for generating changelog from two token files
+ *
+ * @param oldTokensPath - Path to old/previous tokens file
+ * @param newTokensPath - Path to new/current tokens file
+ * @param outputPath - Path to changelog file (default: 'TOKENS-CHANGELOG.md')
+ * @param version - Version number for the changelog entry
+ * @returns Whether the operation was successful
+ */
+declare function generateChangelogCLI(oldTokensPath: string, newTokensPath: string, outputPath?: string, version?: string): Promise<boolean>;
+
+export { BOOTSTRAP_MAPPINGS, BOOTSTRAP_PATTERNS, type BuildOptions, type BuildResult, type BuildStep, type BundleConfig, type BundleResult, type ChangelogOptions, type ChangelogResult, type CleanOptions, type CleanResult, type CleanedDirectory, type CreateSDConfigOptions, DEFAULT_CLEAN_DIRECTORIES, DEFAULT_FILE_NAMES, type DTCGFile, type DTCGToken, type DTCGTokenCollection, type DiscoveryOptions, type DiscoveryResult, type FigmaCollection, type FigmaExport$1 as FigmaExport, type FigmaExportWithMetadata, type FigmaVariablesResponse, type FilePreprocessingResult, type FormatDefinition, type FrameworkMapper, type FrameworkMapperWithConfig, FrameworkMappingConfig, FrameworkMappingPattern, FrameworkTarget, type LegacyToken, type MergeConfig, type MergeContent, type MergeOptions, type MergeResult, type ModeExtractionOptions, type ModeExtractionResult, type MultiThemeBuildOptions, type MultiThemeBuildResult, type OutputConfig, type PlaceholderValues, type PostprocessOptions, type PostprocessResult, type PreprocessingResult, type PreprocessorConfig, type PreprocessorDefinition, type ReplacementRule, type SDConfig, type SDDictionary, type SDFile, type SDFormatArgs, type SDLogConfig, type SDPlatform, type SDPlatformType, type SDToken, type SDTransformOptions, SHADCN_MAPPINGS, type ValidationError as SchemaValidationError, type ValidationOptions as SchemaValidationOptions, type ValidationResult as SchemaValidationResult, type StyleDictionaryFileConfig, type StyleDictionaryInstance, type StyleDictionaryPlatformConfig, type StyleMergeResult, type StyleScannedFile, type StyleScannerOptions, type StyleScannerResult, type SyncOptions, type SyncResult, type ThemeBuildConfig, type ThemeBuildOptions, type ThemeBuildResult, type ThemeFilesResult, type ThemeStyleDictionaryConfig, type Token, type TokenChange, type TokenChangeType, type TokenCollection, type TokenDiff, type TransformOptions as TokenTransformOptions, type TransformResult as TokenTransformResult, type TokenType, type ValidationResult$1 as TokenValidationResult, type TokenValueChange, type TransformDefinition, type TransformGroupDefinition, type TransformType, VALID_TOKEN_TYPES, type ValidateOptions, type ValidationIssue, type ValidationSeverity, addScssImportHeader, applyNameMapping, autoDetectThemes, bootstrapMapper, buildAllThemes, buildTheme, buildTokens, buildTokensCLI, builtInFormats, builtInPreprocessors, builtInTransforms, cleanTokenOutputs, cleanTokensCLI, createBundle, createBundleFromFiles, createBundles, createFixReferencesPreprocessor, createFrameworkMapper, createOutputConfig, createStyleDictionaryConfig, cssTransformGroup, cssVariablesWithComments, detectModes$1 as detectFigmaModes, detectModes$2 as detectModes, detectModes as detectTransformModes, diffTokens, dimensionRem, discoverThemeFiles, dtcgFileSchema, dtcgTokenCollectionSchema, dtcgTokenSchema, ensureOutputDirs, extractMode, extractModes, figmaExportSchema, figmaExportWithMetadataSchema, figmaVariablesResponseSchema, filterDiff, filterFiles, fixReferences, flattenModeStructure, fontWeightUnitless, generateAndWriteChangelog, generateChangelog, generateChangelogCLI, generateThemeBuildConfig, getBreakingChanges, getCssFormat, getDefaultCssDir, getDefaultFiles, getDefaultIgnorePatterns, getDefaultSyncPaths, getDefaultTransformations, getFrameworkMapper, getPreprocessedFilesForMode, getSDTokenType, getSDTokenValue, getThemeFiles, getThemeSelector, getTokenDescription, getTokenType, getTokenValue, hasDTCGValue, isDTCGToken, isLegacyToken, isSDToken, isToken, isTokenReference, isValidTokenType, jsTransformGroup, lineHeightUnitless, loadContent, mapToBootstrapName, mapToShadcnName, mergeCollections, mergeCollectionsCLI, mergeContent, nameKebab, parseTokenReference, postprocessCLI, postprocessCss, postprocessCssFiles, preprocessFile, preprocessTokenFiles, processScssImportHeader, registerAll, registerFormats, registerPreprocessors, registerTransformGroups, registerTransforms, replacePlaceholders, resolveAllOutputPaths, resolveOutputPath, runBuildCLI, scanDirectories, scssTransformGroup, setupStyleDictionary, shadcnMapper, sortFiles, styleDictionaryInputSchema, styleDictionaryTokenSchema, summarizeDiff, syncTokens, syncTokensCLI, toDTCGToken, transformGroups, transformToken, transformTokenTree, transformTokens, transformTokensCLI, transformType, transformValue, typescriptDeclarations, validateDTCGFile, validateDTCGTokens, validateFigmaCLI, validateFigmaExport, validateFigmaExportWithMetadata, validateFigmaExports, validateFigmaFile, validateFigmaVariablesResponse, validateOutputPaths, validateStyleDictionaryInput, validateStyleDictionaryTokens, validateThemeDefinitions, validateTokens, validateTokensCLI, writeChangelog };