Translation Engine

The TranslationEngine is the heart of TailTrace - a unified engine that translates CSS values to Tailwind tokens.

Architecture

CSS Values → TranslationEngine → Tailwind Tokens
                    │
                    ├── ColorMatcher (CIEDE2000)
                    ├── SpacingResolver
                    ├── TypographyMatcher
                    └── BorderRadiusResolver

Usage

import { TranslationEngine } from '@tailtrace/core';

const engine = new TranslationEngine({
  deltaEThreshold: 2.3,
  spacingThreshold: 2,
});

const result = engine.translate({
  'background-color': '#3b83f6',
  'padding': '15px',
  'font-size': '14px',
  'border-radius': '8px',
});

console.log(result.styles);
// [
//   { property: 'background-color', confidence: 'fuzzy', tailwindClass: 'bg-blue-500' },
//   { property: 'padding', confidence: 'fuzzy', tailwindClass: 'p-4' },
//   { property: 'font-size', confidence: 'exact', tailwindClass: 'text-sm' },
//   { property: 'border-radius', confidence: 'exact', tailwindClass: 'rounded-lg' },
// ]

console.log(result.stats);
// { total: 4, exact: 2, fuzzy: 2, none: 0 }

Caching

The engine uses an LRU cache to avoid re-computing translations:

const engine = new TranslationEngine();

// First call - computed
engine.translate({ 'color': '#3b82f6' });

// Second call - cached
engine.translate({ 'color': '#3b82f6' });

// Clear cache if needed
engine.clearCache();

Configuration

new TranslationEngine({
  // Color matching
  colors: { 'primary': '#3b82f6' },
  deltaEThreshold: 2.3,

  // Spacing
  spacing: { '4': '16px' },
  spacingThreshold: 2,

  // Typography
  fontSize: { 'sm': '14px' },
  fontFamily: { 'sans': 'Inter' },

  // Border radius
  borderRadius: { 'lg': '12px' },
});

Singleton Pattern

For convenience, use the singleton instance:

import { getTranslationEngine, resetTranslationEngine } from '@tailtrace/core';

const engine = getTranslationEngine();
engine.updateConfig({ deltaEThreshold: 5.0 });

// Reset to defaults
resetTranslationEngine();

Property Mapping

The engine automatically maps CSS properties to Tailwind prefixes:

CSS Property	Tailwind Prefix
background-color	bg-
color	text-
border-color	border-
padding	p-
margin	m-
gap	gap-
font-size	text-
border-radius	rounded-