@dsai-io/tools 0.0.1

package/dist/tokens/index.d.ts

@@ -0,0 +1,2070 @@
+import { R as ResolvedConfig, O as OutputFormat } from '../types-Idj08nad.js';
+
+/**
+ * Token-specific type definitions
+ *
+ * Defines types for DTCG-compliant tokens, validation, transformation,
+ * and build processes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * DTCG-compliant token value
+ * @see https://www.designtokens.org/
+ */
+interface DTCGToken {
+    /** The resolved value of the token */
+    $value: unknown;
+    /** Token type (color, dimension, etc.) */
+    $type?: TokenType;
+    /** Human-readable description */
+    $description?: string;
+    /** Extension data */
+    $extensions?: Record<string, unknown>;
+}
+/**
+ * Legacy Style Dictionary token format
+ */
+interface LegacyToken {
+    /** The resolved value of the token */
+    value: unknown;
+    /** Token type */
+    type?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Comment (older format) */
+    comment?: string;
+}
+/**
+ * Combined token type supporting both DTCG and legacy formats
+ */
+type Token = DTCGToken | LegacyToken;
+/**
+ * Token collection (nested structure of tokens or groups)
+ */
+interface TokenCollection {
+    [key: string]: Token | TokenCollection | unknown;
+}
+/**
+ * Figma export format (from Tokens Studio)
+ */
+interface FigmaExport {
+    [collectionName: string]: FigmaCollection;
+}
+/**
+ * Single Figma collection with optional modes
+ */
+interface FigmaCollection {
+    /** Mode-specific token values */
+    modes?: Record<string, TokenCollection>;
+    /** Direct tokens if no modes */
+    [key: string]: unknown;
+}
+/**
+ * Valid token types per DTCG specification
+ */
+declare const VALID_TOKEN_TYPES: readonly ["color", "dimension", "fontFamily", "fontWeight", "fontStyle", "shadow", "number", "string", "duration", "cubicBezier", "strokeStyle", "border", "transition", "gradient", "typography", "letterSpacing", "lineHeight", "paragraphSpacing", "textDecoration", "textCase"];
+/**
+ * Token type (DTCG specification)
+ */
+type TokenType = (typeof VALID_TOKEN_TYPES)[number];
+/**
+ * Severity level for validation issues
+ */
+type ValidationSeverity = 'error' | 'warning' | 'info';
+/**
+ * A single validation issue
+ */
+interface ValidationIssue {
+    /** Token path (e.g., "color.brand.primary") */
+    path: string;
+    /** Human-readable message */
+    message: string;
+    /** Issue severity */
+    severity: ValidationSeverity;
+    /** The problematic value (if applicable) */
+    value?: unknown;
+    /** Suggested fix (if applicable) */
+    suggestion?: string;
+}
+/**
+ * Result of token validation
+ */
+interface ValidationResult {
+    /** Whether validation passed (no errors) */
+    valid: boolean;
+    /** Validation errors (blocking issues) */
+    errors: ValidationIssue[];
+    /** Validation warnings (non-blocking) */
+    warnings: ValidationIssue[];
+    /** Total number of tokens validated */
+    tokenCount: number;
+    /** Number of files validated */
+    fileCount: number;
+    /** Validation duration in milliseconds */
+    duration?: number;
+}
+/**
+ * Options for validation
+ */
+interface ValidateOptions {
+    /** Directory containing token files */
+    collectionsDir?: string;
+    /** File patterns to validate */
+    patterns?: string[];
+    /** Enable verbose output */
+    verbose?: boolean;
+    /** Suppress output */
+    quiet?: boolean;
+    /** Treat warnings as errors */
+    strict?: boolean;
+}
+/**
+ * Options for Figma token transformation
+ */
+interface TransformOptions {
+    /** Source directory with Figma exports */
+    sourceDir: string;
+    /** Output directory for collections */
+    collectionsDir: string;
+    /**
+     * Glob patterns for finding source files
+     * @example ['theme.json', '*.tokens.json', 'figma-variables-*.json']
+     */
+    sourcePatterns?: string[];
+    /**
+     * Map of collection names to specific file paths
+     * @example { 'primitives': './colors.json', 'semantic': './semantic.json' }
+     */
+    collectionMapping?: Record<string, string>;
+    /** Preserve $codeSyntax references from Figma */
+    preserveCodeSyntax?: boolean;
+    /** Modes to ignore during transformation */
+    ignoreModes?: string[];
+    /** Default mode name */
+    defaultMode?: string;
+    /** Dry run (don't write files) */
+    dryRun?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+/**
+ * Result of token transformation
+ */
+interface TransformResult {
+    /** Whether transformation succeeded */
+    success: boolean;
+    /** Files written during transformation */
+    filesWritten: string[];
+    /** Number of tokens processed */
+    tokensProcessed: number;
+    /** Modes detected in Figma export */
+    modesDetected: string[];
+    /** Errors encountered */
+    errors: string[];
+    /** Warnings generated */
+    warnings: string[];
+    /** Duration in milliseconds */
+    duration?: number;
+}
+/**
+ * A single build step
+ */
+interface BuildStep {
+    /** Step name for display */
+    name: string;
+    /** Shell command to run (if external) */
+    command?: string;
+    /** Function to execute (if internal). Returns boolean for success/failure, or undefined */
+    fn?: () => boolean | undefined | Promise<boolean | undefined>;
+    /** Whether to skip this step */
+    skip?: boolean;
+    /** Working directory for command */
+    cwd?: string;
+}
+/**
+ * Options for token build
+ */
+interface BuildOptions {
+    /** Skip validation step */
+    skipValidate?: boolean;
+    /** Skip transformation step */
+    skipTransform?: boolean;
+    /** Only build theme CSS */
+    onlyTheme?: boolean;
+    /** Enable watch mode */
+    watch?: boolean;
+    /** Dry run (don't write files) */
+    dryRun?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+    /** Suppress output */
+    quiet?: boolean;
+    /** Output directory for all formats */
+    outputDir?: string;
+    /** Per-format output directories */
+    outputDirs?: Partial<Record<string, string>>;
+    /** Per-format output file names */
+    outputFileNames?: Partial<Record<string, string>>;
+    /** Additional SCSS directories to merge */
+    additionalScssDirectories?: string[];
+    /** Additional CSS directories to merge */
+    additionalCssDirectories?: string[];
+    /** Merge order for additional styles */
+    mergeOrder?: 'before' | 'after';
+    /** Create combined bundle files */
+    createBundle?: boolean;
+    /** Custom SCSS import header */
+    scssImportHeader?: string;
+    /** Additional directories to watch */
+    watchDirectories?: string[];
+    /** Build pipeline configuration */
+    pipeline?: {
+        /** Steps to include in the build */
+        steps?: Array<'validate' | 'transform' | 'style-dictionary' | 'sync' | 'sass-theme' | 'sass-theme-minified' | 'postprocess' | 'sass-utilities' | 'sass-utilities-minified' | 'bundle'>;
+        /** Paths configuration for build steps */
+        paths?: {
+            syncSource?: string;
+            syncTarget?: string;
+            sassThemeInput?: string;
+            sassThemeOutput?: string;
+            sassThemeMinifiedOutput?: string;
+            sassUtilitiesInput?: string;
+            sassUtilitiesOutput?: string;
+            sassUtilitiesMinifiedOutput?: string;
+        };
+        /** Style Dictionary config file name */
+        styleDictionaryConfig?: string;
+    };
+}
+/**
+ * Result of token build
+ */
+interface BuildResult {
+    /** Whether build succeeded */
+    success: boolean;
+    /** Steps that completed successfully */
+    stepsCompleted: string[];
+    /** Steps that failed */
+    stepsFailed: string[];
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Errors encountered */
+    errors: string[];
+    /** Warnings generated */
+    warnings: string[];
+    /** Generated output files */
+    outputFiles?: string[];
+}
+/**
+ * Options for token sync
+ */
+interface SyncOptions {
+    /** Source file (Style Dictionary output) */
+    sourceFile: string;
+    /** Target file (TypeScript source) */
+    targetFile: string;
+    /** Dry run (don't write files) */
+    dryRun?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+/**
+ * Result of token sync
+ */
+interface SyncResult {
+    /** Whether sync succeeded */
+    success: boolean;
+    /** Number of tokens synced */
+    tokensCount: number;
+    /** Whether file was changed */
+    changed: boolean;
+    /** Errors encountered */
+    errors?: string[];
+}
+/**
+ * A text replacement rule
+ */
+interface ReplacementRule {
+    /** Pattern to search for (string or regex) */
+    from: string | RegExp;
+    /** Replacement string */
+    to: string;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Options for CSS post-processing
+ */
+interface PostprocessOptions {
+    /** Input CSS file */
+    inputFile: string;
+    /** Output CSS file (defaults to input) */
+    outputFile?: string;
+    /** Replacements to make */
+    replacements?: ReplacementRule[];
+    /** Dry run (don't write files) */
+    dryRun?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+/**
+ * Result of post-processing
+ */
+interface PostprocessResult {
+    /** Whether post-processing succeeded */
+    success: boolean;
+    /** Number of replacements made */
+    replacementsMade: number;
+    /** Output file path */
+    outputFile: string;
+    /** Errors encountered */
+    errors?: string[];
+}
+/**
+ * Options for merging collections
+ */
+interface MergeOptions {
+    /** Source files to merge */
+    sourceFiles: string[];
+    /** Output file path */
+    outputFile: string;
+    /** Merge strategy for conflicts */
+    strategy?: 'first' | 'last' | 'error';
+    /** Dry run (don't write files) */
+    dryRun?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+/**
+ * Result of collection merge
+ */
+interface MergeResult {
+    /** Whether merge succeeded */
+    success: boolean;
+    /** Number of collections merged */
+    collectionsCount: number;
+    /** Number of tokens in result */
+    tokensCount: number;
+    /** Output file path */
+    outputFile: string;
+    /** Conflicts detected */
+    conflicts?: string[];
+    /** Errors encountered */
+    errors?: string[];
+}
+/**
+ * Check if an object is a DTCG token
+ */
+declare function isDTCGToken(obj: unknown): obj is DTCGToken;
+/**
+ * Check if an object is a legacy token
+ */
+declare function isLegacyToken(obj: unknown): obj is LegacyToken;
+/**
+ * Check if an object is any token type
+ */
+declare function isToken(obj: unknown): obj is Token;
+/**
+ * Check if a string is a valid token type
+ */
+declare function isValidTokenType(type: string): type is TokenType;
+/**
+ * Check if a value is a token reference
+ */
+declare function isTokenReference(value: unknown): boolean;
+/**
+ * Get the value from a token regardless of format
+ */
+declare function getTokenValue(token: Token): unknown;
+/**
+ * Get the type from a token regardless of format
+ */
+declare function getTokenType(token: Token): string | undefined;
+/**
+ * Get the description from a token regardless of format
+ */
+declare function getTokenDescription(token: Token): string | undefined;
+/**
+ * Convert a legacy token to DTCG format
+ */
+declare function toDTCGToken(token: LegacyToken): DTCGToken;
+/**
+ * Parse a token reference string
+ * @param ref - Reference string like "{color.brand.primary}"
+ * @returns Path segments like ["color", "brand", "primary"]
+ */
+declare function parseTokenReference(ref: string): string[] | null;
+
+/**
+ * Token validation module
+ *
+ * Validates design tokens for DTCG compliance and structural integrity.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Validate all tokens in a directory
+ *
+ * @param config - Resolved configuration
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validateTokens, loadConfig } from '@dsai-io/tools';
+ *
+ * const { config } = await loadConfig();
+ * const result = await validateTokens(config);
+ *
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+declare function validateTokens(config: ResolvedConfig, options?: ValidateOptions): Promise<ValidationResult>;
+/**
+ * Validate tokens and exit with code (for CLI usage)
+ *
+ * @param config - Resolved configuration
+ * @param options - Validation options
+ */
+declare function validateTokensCLI(config: ResolvedConfig, options?: ValidateOptions): Promise<void>;
+
+/**
+ * Figma Export Validation module
+ *
+ * Validates Figma token exports before transformation to ensure
+ * they meet the expected structure and format requirements.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Expected structure for a Figma collection
+ */
+interface ExpectedCollection {
+    /** File name for this collection */
+    input: string;
+    /** Whether the collection has mode variants (Light/Dark) */
+    modeAware: boolean;
+    /** Expected mode names */
+    modes?: string[];
+}
+/**
+ * Expected collections configuration
+ */
+interface ExpectedCollections {
+    [key: string]: ExpectedCollection;
+}
+/**
+ * Figma validation options
+ */
+interface ValidateFigmaOptions {
+    /** Path to the figma-exports directory */
+    exportsDir?: string;
+    /** Expected collection definitions */
+    collections?: ExpectedCollections;
+    /** Strict mode - treat warnings as errors */
+    strict?: boolean;
+    /** Skip missing files */
+    skipMissing?: boolean;
+    /** Configuration object */
+    config?: ResolvedConfig;
+}
+/**
+ * Figma validation result
+ */
+interface ValidateFigmaResult extends ValidationResult {
+    /** Per-file validation results */
+    files: Map<string, ValidationResult>;
+    /** Detected modes across all files */
+    detectedModes: Set<string>;
+    /** Missing expected files */
+    missingFiles: string[];
+}
+/**
+ * Validate a single Figma export file
+ */
+declare function validateFigmaFile(filePath: string, expectedCollection?: ExpectedCollection): ValidationResult & {
+    detectedModes: Set<string>;
+};
+/**
+ * Validate all Figma exports in a directory
+ */
+declare function validateFigmaExports(options?: ValidateFigmaOptions): ValidateFigmaResult;
+/**
+ * Detect modes from Figma export data
+ */
+declare function detectModes$1(data: FigmaExport, collectionName?: string): string[];
+/**
+ * CLI entry point for Figma validation
+ */
+declare function validateFigmaCLI(exportsDir: string, options?: Omit<ValidateFigmaOptions, 'exportsDir'>): boolean;
+
+/**
+ * Token Transformation module
+ *
+ * Transforms Figma token exports to Style Dictionary format with DTCG compliance.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Transform options specific to token values
+ */
+interface TokenTransformOptions {
+    /** Font stack to prepend font name to */
+    fontStack?: string;
+    /** Token path for context-aware transformations */
+    tokenPath?: string;
+    /** Token scopes from Figma */
+    scopes?: string[];
+    /** Whether value represents a circle (50%) */
+    isCircle?: boolean;
+    /** Whether value represents a pill (9999px) */
+    isPill?: boolean;
+}
+/**
+ * Transform value based on type
+ */
+declare function transformValue(value: unknown, type: string | undefined, options?: TokenTransformOptions): unknown;
+/**
+ * Transform type from Figma to DTCG standard
+ */
+declare function transformType(figmaType: string | undefined): TokenType | undefined;
+/**
+ * Transform a single token from Figma format to DTCG-compliant format
+ */
+declare function transformToken(figmaToken: unknown, options?: TokenTransformOptions): DTCGToken | null;
+/**
+ * Recursively transform nested token objects
+ */
+declare function transformTokenTree(obj: unknown, parentKey?: string, options?: Record<string, TokenTransformOptions>): Record<string, unknown>;
+/**
+ * Detect modes from Figma export data
+ */
+declare function detectModes(data: FigmaExport, collectionPath?: string): string[];
+/**
+ * Transform Figma tokens to Style Dictionary format
+ */
+declare function transformTokens(options: TransformOptions): TransformResult;
+/**
+ * CLI entry point for token transformation
+ */
+declare function transformTokensCLI(sourceDir: string, collectionsDir: string, options?: Partial<Omit<TransformOptions, 'sourceDir' | 'collectionsDir'>>): boolean;
+
+/**
+ * @file Token Sync Module
+ * @description Synchronizes generated tokens from Style Dictionary output to TypeScript source
+ *
+ * This module handles syncing the generated tokens from dist/js/tokens.js
+ * to src/tokens-flat.ts so that tsup can bundle them correctly.
+ *
+ * This ensures that when font families or other tokens change in Figma,
+ * the changes automatically propagate to the TypeScript source.
+ *
+ * @module @dsai-io/tools/tokens/sync
+ */
+
+/**
+ * Compute default file paths from tokens directory
+ */
+declare function getDefaultSyncPaths(tokensDir: string): {
+    sourceFile: string;
+    targetFile: string;
+};
+/**
+ * Sync tokens from Style Dictionary output to TypeScript source
+ *
+ * @example
+ * ```typescript
+ * // Sync with explicit paths
+ * const result = syncTokens({
+ *   sourceFile: './packages/@dsai-io/tokens/dist/js/tokens.js',
+ *   targetFile: './packages/@dsai-io/tokens/src/tokens-flat.ts',
+ * });
+ *
+ * // Sync with paths computed from tokens directory
+ * const paths = getDefaultSyncPaths('./packages/@dsai-io/tokens');
+ * const result = syncTokens(paths);
+ * ```
+ */
+declare function syncTokens(options: SyncOptions): SyncResult;
+/**
+ * CLI entry point for token sync
+ */
+declare function syncTokensCLI(tokensDir: string): boolean;
+
+/**
+ * @file Token Build Module
+ * @description Orchestrates the complete token build pipeline
+ *
+ * Runs all token build steps in sequence with clear logging:
+ * 1. Validate tokens
+ * 2. Transform Figma tokens
+ * 3. Build Style Dictionary outputs (CSS, JS, TS, SCSS, JSON)
+ * 4. Sync tokens-flat.ts
+ * 5. Compile Bootstrap theme SCSS → CSS
+ * 6. Post-process theme CSS (data-bs-theme → data-dsai-theme)
+ * 7. Compile DSAi utilities SCSS → CSS
+ * 8. Bundle with tsup (ESM + CJS)
+ *
+ * The pipeline is configurable via dsai.config.mjs tokens.pipeline section.
+ * Packages can specify which steps to run and customize paths.
+ *
+ * @module @dsai-io/tools/tokens/build
+ */
+
+/**
+ * Run the complete token build pipeline
+ *
+ * @example
+ * ```typescript
+ * // Full build
+ * const result = buildTokens({
+ *   tokensDir: './packages/@dsai-io/tokens',
+ *   toolsDir: './tools/scripts/tokens',
+ * });
+ *
+ * // Skip validation
+ * const result = buildTokens({
+ *   tokensDir: './packages/@dsai-io/tokens',
+ *   toolsDir: './tools/scripts/tokens',
+ *   skipValidate: true,
+ * });
+ *
+ * // Only build theme CSS
+ * const result = buildTokens({
+ *   tokensDir: './packages/@dsai-io/tokens',
+ *   toolsDir: './tools/scripts/tokens',
+ *   onlyTheme: true,
+ * });
+ * ```
+ */
+declare function buildTokens(tokensDir: string, toolsDir: string, options?: BuildOptions): BuildResult;
+/**
+ * CLI entry point for token build
+ */
+declare function buildTokensCLI(tokensDir: string, toolsDir: string, args?: string[]): boolean;
+/**
+ * Parse CLI arguments and run build
+ * Used as the main entry point when called directly
+ */
+declare function runBuildCLI(tokensDir: string, toolsDir: string): void;
+
+/**
+ * @file Token Clean Module
+ * @description Provides functionality to clean token output directories before builds.
+ *
+ * This module supports:
+ * - Cleaning individual output directories (dist/css, dist/js, etc.)
+ * - Cleaning all build outputs
+ * - Dry-run mode to preview what would be deleted
+ * - Safe deletion with directory validation
+ *
+ * @module @dsai-io/tools/tokens/clean
+ */
+/**
+ * Clean operation options
+ */
+interface CleanOptions {
+    /**
+     * Base directory for cleaning (typically the package root)
+     * @default process.cwd()
+     */
+    baseDir?: string;
+    /**
+     * Directories to clean relative to baseDir
+     * @default ['dist']
+     */
+    directories?: string[];
+    /**
+     * Show what would be deleted without actually deleting
+     * @default false
+     */
+    dryRun?: boolean;
+    /**
+     * Enable verbose logging
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * File patterns to preserve (glob patterns)
+     * Files matching these patterns will not be deleted
+     * @example ['.gitkeep', 'README.md']
+     */
+    preserve?: string[];
+}
+/**
+ * Information about a cleaned directory
+ */
+interface CleanedDirectory {
+    /** Path to the cleaned directory */
+    path: string;
+    /** Number of files removed */
+    filesRemoved: number;
+    /** Number of directories removed */
+    directoriesRemoved: number;
+    /** Whether the directory existed before cleaning */
+    existed: boolean;
+}
+/**
+ * Result of a clean operation
+ */
+interface CleanResult {
+    /** Whether the clean operation completed successfully */
+    success: boolean;
+    /** List of cleaned directories with details */
+    cleaned: CleanedDirectory[];
+    /** Total number of files removed */
+    totalFilesRemoved: number;
+    /** Total number of directories removed */
+    totalDirectoriesRemoved: number;
+    /** Any errors encountered */
+    errors: string[];
+    /** Any warnings (non-blocking issues) */
+    warnings: string[];
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Duration of the operation in milliseconds */
+    duration: number;
+}
+/**
+ * Default directories to clean for token builds
+ */
+declare const DEFAULT_CLEAN_DIRECTORIES: readonly ["dist"];
+/**
+ * Clean token output directories
+ *
+ * Removes build artifacts from output directories to ensure a fresh build.
+ * Supports dry-run mode, preserve patterns, and safety validation.
+ *
+ * @param options - Clean operation options
+ * @returns Clean operation result
+ *
+ * @example
+ * // Clean default dist directory
+ * const result = cleanTokenOutputs();
+ *
+ * @example
+ * // Clean specific directories with dry-run
+ * const result = cleanTokenOutputs({
+ *   directories: ['dist/css', 'dist/js'],
+ *   dryRun: true,
+ *   verbose: true,
+ * });
+ *
+ * @example
+ * // Clean with preserved files
+ * const result = cleanTokenOutputs({
+ *   preserve: ['README.md', '*.d.ts'],
+ * });
+ */
+declare function cleanTokenOutputs(options?: CleanOptions): CleanResult;
+/**
+ * CLI wrapper for cleanTokenOutputs
+ *
+ * Provides formatted output suitable for CLI usage.
+ *
+ * @param baseDir - Base directory for the clean operation
+ * @param options - Clean options
+ * @returns Whether the clean was successful
+ */
+declare function cleanTokensCLI(baseDir: string, options?: Omit<CleanOptions, 'baseDir'>): boolean;
+
+/**
+ * @file CSS Post-processing Module
+ * @description Post-processes CSS files after SASS compilation
+ *
+ * This module applies DSAi-specific transformations to compiled CSS:
+ * - Replaces `data-bs-theme` with `data-dsai-theme` for custom theme attribute
+ * - Applies configurable text replacements
+ *
+ * @module @dsai-io/tools/tokens/postprocess
+ */
+
+/**
+ * Post-process a single CSS file
+ *
+ * @example
+ * ```typescript
+ * const result = postprocessCss({
+ *   inputFile: './dist/css/theme.css',
+ *   replacements: [
+ *     { from: /data-bs-theme/g, to: 'data-dsai-theme', description: 'Theme attribute' }
+ *   ],
+ * });
+ * ```
+ */
+declare function postprocessCss(options: PostprocessOptions): PostprocessResult;
+/**
+ * Post-process multiple CSS files in a directory
+ *
+ * @example
+ * ```typescript
+ * const results = postprocessCssFiles({
+ *   cssDir: './packages/@dsai-io/tokens/dist/css',
+ *   files: ['dsai-theme-bs.css', 'dsai-theme-bs.min.css'],
+ * });
+ * ```
+ */
+declare function postprocessCssFiles(options: {
+    cssDir: string;
+    files?: string[];
+    replacements?: ReplacementRule[];
+    dryRun?: boolean;
+    verbose?: boolean;
+}): {
+    success: boolean;
+    filesModified: number;
+    totalReplacements: number;
+    errors: string[];
+};
+/**
+ * CLI entry point for CSS post-processing
+ */
+declare function postprocessCLI(tokensDir: string): boolean;
+/**
+ * Get the default CSS distribution directory path
+ */
+declare function getDefaultCssDir(tokensDir: string): string;
+/**
+ * Get the default files to process
+ */
+declare function getDefaultFiles(): string[];
+/**
+ * Get the default transformation rules
+ */
+declare function getDefaultTransformations(): ReplacementRule[];
+
+/**
+ * @file Token Collections Merge Module
+ * @description Merge multiple Figma Tokens Studio collection files into one unified collection
+ *
+ * Features:
+ * - Intelligently merges nested token structures
+ * - Preserves all metadata ($codeSyntax, $scopes, $type, etc.)
+ * - Maintains token references and aliases
+ * - Handles mode-based tokens (Light Mode, Dark Mode)
+ * - Deep merges sections without overwriting
+ * - Normalizes reference format to lowercase {colors.path}
+ * - Adds $libraryName and $collectionName to aliased tokens
+ * - Sorts properties alphabetically for consistency
+ * - Removes duplicate sections (like "hue" that duplicates "brand")
+ *
+ * @module @dsai-io/tools/tokens/merge
+ */
+
+/**
+ * Merge multiple collection files into one
+ *
+ * @example
+ * ```typescript
+ * const result = mergeCollections({
+ *   sourceFiles: ['colors-scales.json', 'colors.json'],
+ *   outputFile: 'merged-colors.json',
+ * });
+ * ```
+ */
+declare function mergeCollections(options: MergeOptions): MergeResult;
+/**
+ * CLI entry point for merging collections
+ */
+declare function mergeCollectionsCLI(source1: string, source2: string, output: string): boolean;
+
+/**
+ * Style merge and bundle type definitions
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Configuration for merging additional stylesheets
+ */
+interface MergeConfig {
+    /**
+     * Additional SCSS directories to scan
+     * Relative to config file location
+     */
+    scssDirectories: string[];
+    /**
+     * Additional CSS directories to scan
+     * Relative to config file location
+     */
+    cssDirectories: string[];
+    /**
+     * Order of merging
+     * - 'before': User styles before token styles
+     * - 'after': User styles after token styles
+     */
+    mergeOrder: 'before' | 'after';
+    /**
+     * Create combined bundle files
+     */
+    createBundle: boolean;
+    /**
+     * SCSS file to import at top of generated files
+     */
+    scssImportHeader?: string | string[];
+    /**
+     * File patterns to ignore when scanning
+     * @default ['_index.scss', '*.test.scss']
+     */
+    ignorePatterns?: string[];
+    /**
+     * Sort order for collected files
+     * - 'alphabetical': Sort A-Z by filename
+     * - 'directory-first': Group by directory, then alphabetical
+     * - 'explicit': Use order from config
+     */
+    sortOrder?: 'alphabetical' | 'directory-first' | 'explicit';
+}
+/**
+ * Configuration for output file locations
+ */
+interface OutputConfig {
+    /**
+     * Default output directory (applies to all formats)
+     */
+    baseDir: string;
+    /**
+     * Per-format output directories
+     * Overrides baseDir for specific formats
+     */
+    formatDirs: Partial<Record<OutputFormat, string>>;
+    /**
+     * Per-format file names with placeholder support
+     * Placeholders: {theme}, {name}, {format}, {date}
+     */
+    fileNames: Partial<Record<OutputFormat, string>>;
+    /**
+     * Create directories if they don't exist
+     * @default true
+     */
+    createDirs?: boolean;
+}
+/**
+ * Scanned stylesheet file information
+ */
+interface StyleScannedFile {
+    /** Absolute path to file */
+    absolutePath: string;
+    /** Relative path from source directory */
+    relativePath: string;
+    /** File name without extension */
+    name: string;
+    /** File extension (scss, css) */
+    extension: 'scss' | 'css';
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp */
+    mtime: Date;
+    /** Directory depth from source root */
+    depth: number;
+}
+/**
+ * Style scanner options
+ */
+interface StyleScannerOptions {
+    /** Directories to scan */
+    directories: string[];
+    /** File extension to look for */
+    extension: 'scss' | 'css';
+    /** Patterns to ignore */
+    ignorePatterns?: string[];
+    /** Follow symlinks */
+    followSymlinks?: boolean;
+    /** Max directory depth */
+    maxDepth?: number;
+}
+/**
+ * Style scanner result
+ */
+interface StyleScannerResult {
+    /** Scanned files */
+    files: StyleScannedFile[];
+    /** Directories that were scanned */
+    directories: string[];
+    /** Directories that were missing */
+    missingDirectories: string[];
+    /** Total file count */
+    totalFiles: number;
+    /** Total size in bytes */
+    totalSize: number;
+}
+/**
+ * Content to merge
+ */
+interface MergeContent {
+    /** Source file path */
+    source: string;
+    /** File content */
+    content: string;
+    /** Content type */
+    type: 'token' | 'user';
+    /** Format */
+    format: 'scss' | 'css';
+    /** Theme name (if applicable) */
+    theme?: string;
+}
+/**
+ * Merge result
+ */
+interface StyleMergeResult {
+    /** Merged content */
+    content: string;
+    /** Source map (if generated) */
+    sourceMap?: string;
+    /** Files included in merge */
+    sources: string[];
+    /** Warnings during merge */
+    warnings: string[];
+}
+/**
+ * Bundle configuration
+ */
+interface BundleConfig {
+    /** Bundle name (without extension) */
+    name: string;
+    /** Include source comments */
+    includeSourceComments: boolean;
+    /** Generate sourcemaps */
+    sourcemaps: boolean;
+    /** Minify output */
+    minify: boolean;
+    /** Output directory */
+    outputDir: string;
+}
+/**
+ * Bundle result
+ */
+interface BundleResult {
+    /** Bundle content */
+    content: string;
+    /** Sourcemap content (if generated) */
+    sourcemap?: string;
+    /** Output file path */
+    outputPath: string;
+    /** Files included in bundle */
+    files: string[];
+    /** Bundle size in bytes */
+    size: number;
+    /** Minified size (if minified) */
+    minifiedSize?: number;
+}
+/**
+ * Placeholder values for file naming
+ */
+interface PlaceholderValues {
+    /** Theme name (e.g., 'light', 'dark') */
+    theme?: string;
+    /** Token name or identifier */
+    name?: string;
+    /** Output format */
+    format?: OutputFormat;
+    /** Current date in ISO format */
+    date?: string;
+    /** Timestamp */
+    timestamp?: string;
+}
+
+/**
+ * Scanner for finding stylesheet files in directories
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Scan directories for stylesheet files
+ *
+ * @param options Scanner options
+ * @returns Scanner result with found files
+ *
+ * @example
+ * ```typescript
+ * const result = await scanDirectories({
+ *   directories: ['src/styles/overrides', 'src/styles/custom'],
+ *   extension: 'scss',
+ * });
+ *
+ * console.log(`Found ${result.totalFiles} files`);
+ * ```
+ */
+declare function scanDirectories(options: StyleScannerOptions): Promise<StyleScannerResult>;
+/**
+ * Sort scanned files according to specified order
+ *
+ * @param files Files to sort
+ * @param order Sort order
+ * @returns Sorted files
+ */
+declare function sortFiles(files: StyleScannedFile[], order?: 'alphabetical' | 'directory-first'): StyleScannedFile[];
+/**
+ * Filter files matching patterns
+ *
+ * @param files Files to filter
+ * @param patterns Glob patterns to match
+ * @param include If true, keep matching files; if false, exclude matching
+ * @returns Filtered files
+ */
+declare function filterFiles(files: StyleScannedFile[], patterns: string[], include?: boolean): StyleScannedFile[];
+/**
+ * Get default ignore patterns
+ */
+declare function getDefaultIgnorePatterns(): string[];
+
+/**
+ * Merge stylesheet content
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Merge stylesheet content in specified order
+ *
+ * @param tokenContent Generated token content
+ * @param userContent User stylesheet content
+ * @param config Merge configuration
+ * @returns Merged result
+ *
+ * @example
+ * ```typescript
+ * const result = await mergeContent(
+ *   { content: ':root { --color-primary: blue; }', format: 'css' },
+ *   [{ source: 'overrides.css', content: ':root { --color-bg: white; }' }],
+ *   { mergeOrder: 'after' }
+ * );
+ * ```
+ */
+declare function mergeContent(tokenContent: {
+    content: string;
+    format: 'scss' | 'css';
+}, userContent: MergeContent[], config?: Partial<MergeConfig>): Promise<StyleMergeResult>;
+/**
+ * Load content from files
+ *
+ * @param files File paths to load
+ * @param type Content type (token or user)
+ * @param format File format
+ * @returns Loaded content
+ */
+declare function loadContent(files: string[], type: 'token' | 'user', format: 'scss' | 'css'): Promise<MergeContent[]>;
+/**
+ * Process SCSS imports header
+ *
+ * @param importHeader Import header configuration
+ * @param configDir Config directory for resolving relative paths
+ * @returns Processed import statements
+ */
+declare function processScssImportHeader(importHeader: string | string[] | undefined, configDir: string): string;
+/**
+ * Add SCSS import header to content
+ *
+ * @param content SCSS content
+ * @param importHeader Import header to add
+ * @param configDir Config directory for resolving paths
+ * @returns Content with import header
+ */
+declare function addScssImportHeader(content: string, importHeader: string | string[] | undefined, configDir: string): string;
+
+/**
+ * Bundle generator for combined stylesheets
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create a stylesheet bundle
+ *
+ * @param mergeResult Result from merge operation
+ * @param config Bundle configuration
+ * @returns Bundle result
+ *
+ * @example
+ * ```typescript
+ * const bundle = await createBundle(mergeResult, {
+ *   name: 'tokens-bundle',
+ *   outputDir: 'dist',
+ *   includeSourceComments: true,
+ *   sourcemaps: true,
+ *   minify: false,
+ * });
+ * ```
+ */
+declare function createBundle(mergeResult: StyleMergeResult, config: BundleConfig): Promise<BundleResult>;
+/**
+ * Create both CSS and SCSS bundles
+ *
+ * @param tokenCss Generated CSS tokens
+ * @param tokenScss Generated SCSS tokens
+ * @param cssFiles User CSS files (StyleScannedFile objects)
+ * @param scssFiles User SCSS files (StyleScannedFile objects)
+ * @param config Bundle configuration
+ * @returns Map of bundle type to result
+ */
+declare function createBundles(tokenCss: string, tokenScss: string, cssFiles: StyleScannedFile[], scssFiles: StyleScannedFile[], config: Omit<BundleConfig, 'name'> & {
+    baseName?: string;
+}): Promise<{
+    css?: BundleResult;
+    scss?: BundleResult;
+}>;
+/**
+ * Create a bundle from scanned files (no token content)
+ *
+ * @param files Scanned files to bundle
+ * @param format Output format
+ * @param config Bundle configuration
+ * @returns Bundle result
+ */
+declare function createBundleFromFiles(files: StyleScannedFile[], format: 'css' | 'scss', config: BundleConfig): Promise<BundleResult>;
+
+/**
+ * Output path resolver with placeholder support
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Default file names per format
+ */
+declare const DEFAULT_FILE_NAMES: Record<OutputFormat, string>;
+/**
+ * Replace placeholders in a string
+ *
+ * @param template Template string with placeholders
+ * @param values Values to replace
+ * @returns String with placeholders replaced
+ */
+declare function replacePlaceholders(template: string, values: PlaceholderValues): string;
+/**
+ * Resolve output path for a specific format
+ *
+ * @param format Output format
+ * @param config Output configuration
+ * @param values Placeholder values
+ * @returns Resolved output path
+ *
+ * @example
+ * ```typescript
+ * const outputPath = resolveOutputPath('css', {
+ *   baseDir: 'dist',
+ *   formatDirs: { css: 'dist/css' },
+ *   fileNames: { css: 'design-tokens-{theme}.css' },
+ * }, { theme: 'light' });
+ *
+ * // Returns: 'dist/css/design-tokens-light.css'
+ * ```
+ */
+declare function resolveOutputPath(format: OutputFormat, config: OutputConfig, values?: PlaceholderValues): string;
+/**
+ * Resolve all output paths for all formats
+ *
+ * @param formats Formats to generate
+ * @param config Output configuration
+ * @param values Placeholder values
+ * @returns Map of format to output path
+ */
+declare function resolveAllOutputPaths(formats: OutputFormat[], config: OutputConfig, values?: PlaceholderValues): Record<OutputFormat, string>;
+/**
+ * Validate output paths don't conflict
+ *
+ * @param paths Output paths to validate
+ * @returns Validation result with any conflicts found
+ */
+declare function validateOutputPaths(paths: Record<string, string>): {
+    valid: boolean;
+    conflicts: [string, string][];
+};
+/**
+ * Ensure all output directories exist
+ *
+ * @param paths Output paths
+ * @returns Created directories
+ */
+declare function ensureOutputDirs(paths: Record<string, string>): Promise<string[]>;
+/**
+ * Create output configuration from token config
+ *
+ * @param tokenConfig Token configuration
+ * @returns Output configuration
+ */
+declare function createOutputConfig(tokenConfig: {
+    outputDir?: string;
+    outputDirs?: Partial<Record<OutputFormat, string>>;
+    outputFileNames?: Partial<Record<OutputFormat, string>>;
+}): OutputConfig;
+
+/**
+ * Style Dictionary Type Definitions
+ *
+ * Types for Style Dictionary integration including tokens, transforms,
+ * formats, preprocessors, and configuration.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/types
+ */
+/**
+ * Style Dictionary token (runtime representation)
+ */
+interface SDToken {
+    /** Token name (after name transforms) */
+    name: string;
+    /** Resolved value (after value transforms) */
+    value: unknown;
+    /** Original value (may contain references) */
+    original: {
+        value: unknown;
+        $value?: unknown;
+    };
+    /** Token path segments */
+    path: string[];
+    /** DTCG $value property */
+    $value?: unknown;
+    /** Token type */
+    type?: string;
+    /** DTCG $type property */
+    $type?: string;
+    /** Token description */
+    description?: string;
+    /** DTCG $description property */
+    $description?: string;
+    /** Comment for documentation */
+    comment?: string;
+    /** DTCG $extensions */
+    $extensions?: Record<string, unknown>;
+    /** DTCG $scopes (from Figma Variables) */
+    $scopes?: string[];
+    /** CTI (Category/Type/Item) attributes */
+    attributes?: {
+        category?: string;
+        type?: string;
+        item?: string;
+        subitem?: string;
+        state?: string;
+    };
+    /** File path where token was defined */
+    filePath?: string;
+    /** Whether token is a reference to another token */
+    isSource?: boolean;
+}
+/**
+ * Style Dictionary dictionary containing all tokens
+ */
+interface SDDictionary {
+    /** Flat array of all tokens */
+    allTokens: SDToken[];
+    /** Nested token structure */
+    tokens: Record<string, unknown>;
+    /** Unfiltered tokens (before platform filtering) */
+    unfilteredTokens: Record<string, unknown>;
+}
+/**
+ * Transform type - what aspect of the token is being transformed
+ */
+type TransformType = 'name' | 'value' | 'attribute';
+/**
+ * Options passed to transform functions
+ */
+interface SDTransformOptions {
+    /** Base font size for rem conversion (default: 16) */
+    basePxFontSize?: number;
+    /** CSS variable prefix */
+    prefix?: string;
+    /** Additional options */
+    [key: string]: unknown;
+}
+/**
+ * Transform definition for Style Dictionary
+ */
+interface TransformDefinition {
+    /** Unique transform name (e.g., 'fontWeight/unitless') */
+    name: string;
+    /** Transform type */
+    type: TransformType;
+    /**
+     * Filter function - return true to apply transform
+     * If omitted, transform applies to all tokens
+     */
+    filter?: (token: SDToken) => boolean;
+    /**
+     * Transform function
+     * @param token - The token being transformed
+     * @param options - Transform options from platform config
+     * @returns Transformed value
+     */
+    transform: (token: SDToken, options?: SDTransformOptions) => unknown;
+}
+/**
+ * Transform group definition
+ */
+interface TransformGroupDefinition {
+    /** Unique group name (e.g., 'custom/css') */
+    name: string;
+    /** Ordered list of transform names to apply */
+    transforms: string[];
+}
+/**
+ * Platform configuration passed to formats
+ */
+interface SDPlatform {
+    /** Transform group to use */
+    transformGroup?: string;
+    /** Individual transforms (alternative to transformGroup) */
+    transforms?: string[];
+    /** Output path prefix */
+    buildPath?: string;
+    /** Files to generate */
+    files?: SDFile[];
+    /** Platform-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * File configuration for platform output
+ */
+interface SDFile {
+    /** Output file name */
+    destination: string;
+    /** Format to use for generating content */
+    format: string;
+    /**
+     * Filter tokens to include in this file
+     * Can be a string (filter name) or function
+     */
+    filter?: string | ((token: SDToken) => boolean);
+    /** File-specific options passed to format */
+    options?: Record<string, unknown>;
+}
+/**
+ * Arguments passed to format functions
+ */
+interface SDFormatArgs {
+    /** Dictionary containing all tokens */
+    dictionary: SDDictionary;
+    /** Options from file config */
+    options: Record<string, unknown>;
+    /** Platform configuration */
+    platform: SDPlatform;
+    /** File configuration */
+    file: SDFile;
+}
+/**
+ * Format definition for Style Dictionary
+ */
+interface FormatDefinition {
+    /** Unique format name (e.g., 'css/variables-with-comments') */
+    name: string;
+    /**
+     * Format function - generates file content
+     * @param args - Format arguments
+     * @returns File content as string
+     */
+    format: (args: SDFormatArgs) => string;
+}
+/**
+ * Preprocessor definition for Style Dictionary
+ */
+interface PreprocessorDefinition {
+    /** Unique preprocessor name */
+    name: string;
+    /**
+     * Preprocessor function - modifies token dictionary before processing
+     * @param dictionary - Raw token dictionary
+     * @returns Modified dictionary
+     */
+    preprocessor: (dictionary: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Style Dictionary log configuration
+ */
+interface SDLogConfig {
+    /** Logging verbosity */
+    verbosity?: 'default' | 'silent' | 'verbose';
+    /** How to handle warnings */
+    warnings?: 'warn' | 'error' | 'disabled';
+    /** How to handle errors */
+    errors?: 'error' | 'throw';
+}
+/**
+ * Full Style Dictionary configuration
+ */
+interface SDConfig {
+    /** Logging configuration */
+    log?: SDLogConfig;
+    /** Preprocessors to run on source tokens */
+    preprocessors?: string[];
+    /** Source token file patterns */
+    source?: string[];
+    /** Additional files to include */
+    include?: string[];
+    /** Platform configurations */
+    platforms?: Record<string, SDPlatform>;
+}
+/**
+ * Options for creating Style Dictionary configuration
+ */
+interface CreateSDConfigOptions {
+    /** Token source files (glob patterns) */
+    source?: string[];
+    /** CSS variable prefix (default: '--dsai-') */
+    prefix?: string;
+    /** Output directory base path */
+    buildPath?: string;
+    /** Base font size for rem conversion (default: 16) */
+    baseFontSize?: number;
+    /** Whether to output references in generated files */
+    outputReferences?: boolean;
+    /** Additional transforms to register */
+    customTransforms?: TransformDefinition[];
+    /** Additional formats to register */
+    customFormats?: FormatDefinition[];
+    /** Additional preprocessors to register */
+    customPreprocessors?: PreprocessorDefinition[];
+    /** Platforms to include (default: all) */
+    platforms?: SDPlatformType[];
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Available platform types
+ */
+type SDPlatformType = 'css' | 'js' | 'ts' | 'scss' | 'scss-dist' | 'json';
+/**
+ * Style Dictionary instance type (for registration functions)
+ * This is a minimal interface - actual SD has more methods
+ */
+interface StyleDictionaryInstance {
+    registerTransform: (transform: {
+        name: string;
+        type: TransformType;
+        filter?: (token: SDToken) => boolean;
+        transform: (token: SDToken, options?: SDTransformOptions) => unknown;
+    }) => void;
+    registerTransformGroup: (group: {
+        name: string;
+        transforms: string[];
+    }) => void;
+    registerFormat: (format: {
+        name: string;
+        format: (args: SDFormatArgs) => string;
+    }) => void;
+    registerPreprocessor: (preprocessor: {
+        name: string;
+        preprocessor: (dictionary: Record<string, unknown>) => Record<string, unknown>;
+    }) => void;
+}
+/**
+ * Check if a value is an SD token
+ */
+declare function isSDToken(obj: unknown): obj is SDToken;
+/**
+ * Check if token has a DTCG $value
+ */
+declare function hasDTCGValue(token: SDToken): boolean;
+/**
+ * Get token value (DTCG or legacy format)
+ */
+declare function getSDTokenValue(token: SDToken): unknown;
+/**
+ * Get token type (DTCG or legacy format)
+ */
+declare function getSDTokenType(token: SDToken): string | undefined;
+
+/**
+ * Style Dictionary Configuration Generator
+ *
+ * Creates Style Dictionary configuration from DSAi config.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/config
+ */
+
+/**
+ * Create Style Dictionary configuration from DSAi config
+ *
+ * Generates a complete Style Dictionary configuration based on
+ * the resolved DSAi configuration, with sensible defaults.
+ *
+ * @param dsaiConfig - Resolved DSAi configuration
+ * @param options - Additional options to override defaults
+ * @returns Style Dictionary configuration object
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { loadConfig } from '@dsai-io/tools/config';
+ * import { createStyleDictionaryConfig, registerAll } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * const { config } = await loadConfig();
+ * const sdConfig = createStyleDictionaryConfig(config);
+ *
+ * registerAll(StyleDictionary);
+ *
+ * const sd = new StyleDictionary(sdConfig);
+ * await sd.buildAllPlatforms();
+ * ```
+ */
+declare function createStyleDictionaryConfig(dsaiConfig: ResolvedConfig, options?: Partial<CreateSDConfigOptions>): SDConfig;
+/**
+ * Register all custom transforms, formats, preprocessors, and groups
+ *
+ * Must be called before creating a Style Dictionary instance with
+ * a config generated by createStyleDictionaryConfig.
+ *
+ * @param sd - Style Dictionary instance (the imported module)
+ * @param options - Custom extensions to register
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { registerAll } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * registerAll(StyleDictionary, {
+ *   customTransforms: [myCustomTransform],
+ *   customFormats: [myCustomFormat],
+ * });
+ * ```
+ */
+declare function registerAll(sd: StyleDictionaryInstance, options?: Partial<CreateSDConfigOptions>): void;
+/**
+ * Create and register a complete Style Dictionary setup
+ *
+ * Convenience function that combines registerAll and createStyleDictionaryConfig.
+ *
+ * @param sd - Style Dictionary instance
+ * @param dsaiConfig - Resolved DSAi configuration
+ * @param options - Additional options
+ * @returns Style Dictionary configuration
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { loadConfig } from '@dsai-io/tools/config';
+ * import { setupStyleDictionary } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * const { config } = await loadConfig();
+ * const sdConfig = setupStyleDictionary(StyleDictionary, config);
+ *
+ * const sd = new StyleDictionary(sdConfig);
+ * await sd.buildAllPlatforms();
+ * ```
+ */
+declare function setupStyleDictionary(sd: StyleDictionaryInstance, dsaiConfig: ResolvedConfig, options?: Partial<CreateSDConfigOptions>): SDConfig;
+
+/**
+ * Font Weight Transform
+ *
+ * Keeps font-weight values as unitless numbers (300, 400, 700, etc.)
+ * CSS font-weight must be unitless for proper inheritance.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/transforms/font-weight
+ */
+
+/**
+ * fontWeight/unitless transform
+ *
+ * Ensures font-weight values are unitless numbers.
+ * Handles numeric values, string values, and named weights.
+ *
+ * @example
+ * // Numeric input
+ * Input: { $value: 700, $type: "fontWeight" }
+ * Output: 700
+ *
+ * @example
+ * // String input
+ * Input: { $value: "700", $type: "fontWeight" }
+ * Output: 700
+ *
+ * @example
+ * // Named weight
+ * Input: { $value: "bold", $type: "fontWeight" }
+ * Output: 700
+ */
+declare const fontWeightUnitless: TransformDefinition;
+
+/**
+ * Line Height Transform
+ *
+ * Keeps line-height values as unitless ratios (1, 1.5, 2, etc.)
+ * CSS line-height should be unitless for proper inheritance.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/line-height
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/transforms/line-height
+ */
+
+/**
+ * lineHeight/unitless transform
+ *
+ * Converts line-height values to unitless ratios.
+ * Handles numbers, percentages, and pixel values.
+ *
+ * @example
+ * // Percentage input
+ * Input: { $value: "150%", $type: "lineHeight" }
+ * Output: 1.5
+ *
+ * @example
+ * // Already unitless
+ * Input: { $value: 1.5, $type: "lineHeight" }
+ * Output: 1.5
+ *
+ * @example
+ * // Pixel value from Figma
+ * Input: { $value: 24, $type: "lineHeight" }
+ * Output: 1.5 (assuming 16px base)
+ */
+declare const lineHeightUnitless: TransformDefinition;
+
+/**
+ * Dimension Transform
+ *
+ * Converts dimension values to rem units.
+ * Handles raw numbers and pixel strings.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/transforms/dimension
+ */
+
+/**
+ * dimension/rem transform
+ *
+ * Converts dimension values to rem.
+ * Uses basePxFontSize from options (default: 16).
+ *
+ * @example
+ * // Numeric input
+ * Input: { $value: 16, $type: "dimension" }
+ * Output: "1rem"
+ *
+ * @example
+ * // Pixel string
+ * Input: { $value: "24px", $type: "dimension" }
+ * Output: "1.5rem"
+ *
+ * @example
+ * // Zero value
+ * Input: { $value: 0, $type: "dimension" }
+ * Output: "0"
+ */
+declare const dimensionRem: TransformDefinition;
+
+/**
+ * Name Transform
+ *
+ * Converts token paths to kebab-case names.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/transforms/name
+ */
+
+/**
+ * name/kebab transform
+ *
+ * Converts token path to kebab-case CSS variable name.
+ * Replaces underscores with hyphens and lowercases.
+ *
+ * @example
+ * Input: path = ['color', 'blue', '500']
+ * Output: "color-blue-500"
+ *
+ * @example
+ * Input: path = ['typography', 'fontWeight', 'bold']
+ * Output: "typography-fontweight-bold"
+ */
+declare const nameKebab: TransformDefinition;
+
+/**
+ * Style Dictionary Transforms
+ *
+ * Exports all built-in transforms and registration utilities.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/transforms
+ */
+
+/**
+ * All built-in transforms
+ */
+declare const builtInTransforms: TransformDefinition[];
+/**
+ * Register all transforms with Style Dictionary
+ *
+ * @param sd - Style Dictionary instance
+ * @param customTransforms - Additional custom transforms to register
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { registerTransforms } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * registerTransforms(StyleDictionary);
+ * ```
+ */
+declare function registerTransforms(sd: StyleDictionaryInstance, customTransforms?: TransformDefinition[]): void;
+
+/**
+ * CSS Variables Format
+ *
+ * Generates CSS custom properties with descriptive comments.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/formats/css-variables
+ */
+
+/**
+ * css/variables-with-comments format
+ *
+ * Generates CSS custom properties with descriptive comments.
+ * Supports configurable prefix via options.
+ *
+ * @example
+ * Output:
+ * ```css
+ * :root {
+ *   /* Primary brand color *\/
+ *   --dsai-color-primary: #007bff;
+ *   --dsai-spacing-md: 1rem;
+ * }
+ * ```
+ */
+declare const cssVariablesWithComments: FormatDefinition;
+
+/**
+ * TypeScript Declarations Format
+ *
+ * Generates TypeScript type declarations for design tokens.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/formats/typescript
+ */
+
+/**
+ * typescript/declarations format
+ *
+ * Generates TypeScript declarations with:
+ * - DesignTokens interface with nested structure
+ * - String literal types for each token category
+ * - Flat token exports with proper types
+ *
+ * @example
+ * Output:
+ * ```typescript
+ * export type ColorTokenName =
+ *   | 'color.primary'
+ *   | 'color.secondary';
+ *
+ * export interface DesignTokens {
+ *   color: {
+ *     primary: string;
+ *     secondary: string;
+ *   };
+ * }
+ *
+ * export declare const colorPrimary: string;
+ * export declare const tokens: DesignTokens;
+ * ```
+ */
+declare const typescriptDeclarations: FormatDefinition;
+
+/**
+ * Style Dictionary Formats
+ *
+ * Exports all built-in formats and registration utilities.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/formats
+ */
+
+/**
+ * All built-in formats
+ */
+declare const builtInFormats: FormatDefinition[];
+/**
+ * Register all formats with Style Dictionary
+ *
+ * @param sd - Style Dictionary instance
+ * @param customFormats - Additional custom formats to register
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { registerFormats } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * registerFormats(StyleDictionary);
+ * ```
+ */
+declare function registerFormats(sd: StyleDictionaryInstance, customFormats?: FormatDefinition[]): void;
+
+/**
+ * Fix References Preprocessor
+ *
+ * Fixes token reference paths that may be mismatched between
+ * Figma exports and the actual token structure.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/preprocessors/fix-references
+ */
+
+/**
+ * fix-references preprocessor
+ *
+ * Fixes token reference paths that may be mismatched.
+ * Our tokens use "color.blue.500" but Figma exports may reference
+ * "{colors.brand.blue.500}" - this preprocessor fixes the mismatch.
+ *
+ * @example
+ * Before: { $value: "{colors.brand.primary}" }
+ * After:  { $value: "{color.primary}" }
+ */
+declare const fixReferences: PreprocessorDefinition;
+/**
+ * Create a custom fix-references preprocessor with custom mappings
+ *
+ * @param mappings - Array of [from, to] path mapping pairs
+ * @returns Custom preprocessor definition
+ *
+ * @example
+ * ```typescript
+ * const customFixReferences = createFixReferencesPreprocessor([
+ *   ['{colors.brand.', '{color.'],
+ *   ['{acme.', '{brand.'],
+ * ]);
+ * ```
+ */
+declare function createFixReferencesPreprocessor(mappings: Array<[string, string]>): PreprocessorDefinition;
+
+/**
+ * Style Dictionary Preprocessors
+ *
+ * Exports all built-in preprocessors and registration utilities.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/preprocessors
+ */
+
+/**
+ * All built-in preprocessors
+ */
+declare const builtInPreprocessors: PreprocessorDefinition[];
+/**
+ * Register all preprocessors with Style Dictionary
+ *
+ * @param sd - Style Dictionary instance
+ * @param customPreprocessors - Additional custom preprocessors to register
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { registerPreprocessors } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * registerPreprocessors(StyleDictionary);
+ * ```
+ */
+declare function registerPreprocessors(sd: StyleDictionaryInstance, customPreprocessors?: PreprocessorDefinition[]): void;
+
+/**
+ * CSS Transform Group
+ *
+ * Transform group for generating CSS output.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/groups/css
+ */
+
+/**
+ * custom/css transform group
+ *
+ * Transforms for generating CSS custom properties:
+ * - attribute/cti: Add CTI attributes
+ * - name/kebab: kebab-case names
+ * - time/seconds: Convert time to seconds
+ * - fontWeight/unitless: Keep font weights unitless
+ * - lineHeight/unitless: Keep line heights unitless
+ * - dimension/rem: Convert dimensions to rem
+ * - color/css: Convert colors to CSS format
+ */
+declare const cssTransformGroup: TransformGroupDefinition;
+
+/**
+ * JavaScript Transform Group
+ *
+ * Transform group for generating JavaScript output.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/groups/js
+ */
+
+/**
+ * custom/js transform group
+ *
+ * Transforms for generating JavaScript/TypeScript exports:
+ * - attribute/cti: Add CTI attributes
+ * - name/camel: camelCase names
+ * - fontWeight/unitless: Keep font weights unitless
+ * - lineHeight/unitless: Keep line heights unitless
+ * - dimension/rem: Convert dimensions to rem
+ * - color/css: Convert colors to CSS format
+ */
+declare const jsTransformGroup: TransformGroupDefinition;
+
+/**
+ * SCSS Transform Group
+ *
+ * Transform group for generating SCSS output.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/groups/scss
+ */
+
+/**
+ * custom/scss transform group
+ *
+ * Transforms for generating SCSS variables:
+ * - attribute/cti: Add CTI attributes
+ * - name/kebab: kebab-case names
+ * - time/seconds: Convert time to seconds
+ * - fontWeight/unitless: Keep font weights unitless
+ * - lineHeight/unitless: Keep line heights unitless
+ * - dimension/rem: Convert dimensions to rem
+ * - color/css: Convert colors to CSS format
+ *
+ * This follows Style Dictionary v5 best practices:
+ * - Source tokens are raw numbers
+ * - Transforms add appropriate units (or keep unitless for font-weight/line-height)
+ */
+declare const scssTransformGroup: TransformGroupDefinition;
+
+/**
+ * Style Dictionary Transform Groups
+ *
+ * Exports all built-in transform groups and registration utilities.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/tokens/style-dictionary/groups
+ */
+
+/**
+ * All built-in transform groups
+ */
+declare const transformGroups: TransformGroupDefinition[];
+/**
+ * Register all transform groups with Style Dictionary
+ *
+ * @param sd - Style Dictionary instance
+ * @param customGroups - Additional custom transform groups to register
+ *
+ * @example
+ * ```typescript
+ * import StyleDictionary from 'style-dictionary';
+ * import { registerTransformGroups } from '@dsai-io/tools/tokens/style-dictionary';
+ *
+ * registerTransformGroups(StyleDictionary);
+ * ```
+ */
+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 };