AI CSS Generation and Design Token Extraction: From Design Files to Production Styles

May 14, 202698 min read0 views

ai css generation

design tokens

frontend architecture

AI CSS Generation and Design Token Extraction: From Design Files to Production Styles

Real-World Problem Context

A frontend team receives design updates from Figma weekly — new components, spacing adjustments, color palette tweaks, responsive breakpoints. The handoff process is manual: a developer opens Figma, inspects each element, reads off the font-size, padding, border-radius, and color values, then writes the CSS by hand. This takes 2-3 hours per design update and introduces errors — a designer specifies #1A73E8 but the developer types #1A73EB, spacing of 24px gets written as 20px. The design system has 40+ tokens (colors, spacing, typography scales) but they're not consistently applied — some components use hardcoded values instead of tokens. The team integrates AI at three points: (1) extracting design tokens automatically from Figma files using the API + LLM interpretation, (2) generating CSS/Tailwind classes from visual designs or screenshots, and (3) auditing existing CSS to replace hardcoded values with design tokens. This post covers how each pipeline works internally.

Problem Statements

Design Token Extraction: How do you automatically extract a consistent set of design tokens (colors, spacing, typography, shadows, radii) from Figma files? How does the AI resolve ambiguity — when a color appears 50 times with slight variations, which is the canonical token?
Design-to-CSS Generation: How does an AI model convert a visual design (Figma frame or screenshot) into production CSS? How does it handle responsive layouts, interaction states, and choosing between flexbox/grid — and how do you prevent it from generating pixel-perfect CSS that breaks at different viewports?
Token Audit and Migration: How do you use AI to scan an existing codebase, identify hardcoded CSS values that should be tokens, and generate the migration — replacing color: #1A73E8 with color: var(--color-primary) across thousands of files?

Deep Dive: Internal Mechanisms

1. Figma API Token Extraction Pipeline

/*
 * Figma exposes a REST API that returns the entire design file
 * as a JSON tree. Each node has style properties.
 *
 * Pipeline:
 * 1. Fetch Figma file via API
 * 2. Walk the node tree, collecting all style values
 * 3. Cluster similar values (e.g., #1A73E8 and #1A74E8)
 * 4. Use LLM to name tokens based on usage context
 * 5. Output token files (CSS custom properties, JSON, Tailwind config)
 *
 * ┌──────────────────────────────────────────────────┐
 * │ Figma API Response (simplified):                  │
 * │                                                   │
 * │ {                                                 │
 * │   "document": {                                   │
 * │     "children": [                                 │
 * │       { "name": "Button/Primary",                 │
 * │         "fills": [{ "color": { r: 0.10, ... } }], │
 * │         "style": {                                │
 * │           "fontSize": 16,                         │
 * │           "fontFamily": "Inter",                  │
 * │           "fontWeight": 600                       │
 * │         },                                        │
 * │         "paddingLeft": 24,                        │
 * │         "paddingTop": 12,                         │
 * │         "cornerRadius": 8                         │
 * │       }                                           │
 * │     ]                                             │
 * │   }                                               │
 * │ }                                                 │
 * └──────────────────────────────────────────────────┘
 */

async function extractTokensFromFigma(fileKey, apiToken) {
    // 1. Fetch the full file:
    const response = await fetch(
        `https://api.figma.com/v1/files/${fileKey}`,
        { headers: { 'X-Figma-Token': apiToken } }
    );
    const file = await response.json();
    
    // 2. Walk the tree and collect all style values:
    const rawValues = {
        colors: [],
        fontSizes: [],
        fontFamilies: [],
        fontWeights: [],
        spacings: [],
        radii: [],
        shadows: [],
    };
    
    walkFigmaTree(file.document, (node) => {
        // Colors from fills and strokes:
        if (node.fills) {
            for (const fill of node.fills) {
                if (fill.type === 'SOLID' && fill.color) {
                    rawValues.colors.push({
                        hex: figmaColorToHex(fill.color),
                        opacity: fill.opacity ?? 1,
                        nodeName: node.name,
                        nodePath: getNodePath(node),
                    });
                }
            }
        }
        
        // Typography:
        if (node.style?.fontSize) {
            rawValues.fontSizes.push({
                value: node.style.fontSize,
                nodeName: node.name,
            });
        }
        
        // Spacing (padding, gaps):
        for (const prop of ['paddingLeft', 'paddingRight', 'paddingTop', 'paddingBottom', 'itemSpacing']) {
            if (node[prop] !== undefined) {
                rawValues.spacings.push({
                    value: node[prop],
                    property: prop,
                    nodeName: node.name,
                });
            }
        }
        
        // Border radius:
        if (node.cornerRadius !== undefined) {
            rawValues.radii.push({
                value: node.cornerRadius,
                nodeName: node.name,
            });
        }
        
        // Shadows:
        if (node.effects) {
            for (const effect of node.effects) {
                if (effect.type === 'DROP_SHADOW') {
                    rawValues.shadows.push({
                        x: effect.offset.x,
                        y: effect.offset.y,
                        blur: effect.radius,
                        spread: effect.spread || 0,
                        color: figmaColorToHex(effect.color),
                        nodeName: node.name,
                    });
                }
            }
        }
    });
    
    return rawValues;
}

function figmaColorToHex({ r, g, b, a }) {
    const toHex = (v) => Math.round(v * 255).toString(16).padStart(2, '0');
    return `#${toHex(r)}${toHex(g)}${toHex(b)}${a !== undefined && a < 1 ? toHex(a) : ''}`;
}

2. Value Clustering and Deduplication

/*
 * Raw extraction yields hundreds of values with near-duplicates:
 *   #1A73E8 (used 47 times)
 *   #1A74E8 (used 3 times)  ← designer's rounding error
 *   #1A73E9 (used 1 time)   ← Figma precision artifact
 *
 * These should all be ONE token: --color-primary: #1A73E8
 *
 * Clustering strategy:
 * 1. Group by proximity in color space (CIELAB for perceptual distance)
 * 2. Pick the most frequent value as canonical
 * 3. For spacing/sizes: snap to a scale (4px grid)
 */

function clusterColors(rawColors, distanceThreshold = 3) {
    // Convert to CIELAB for perceptual comparison:
    const labColors = rawColors.map(c => ({
        ...c,
        lab: hexToLab(c.hex),
    }));
    
    // Greedy clustering:
    const clusters = [];
    const assigned = new Set();
    
    for (let i = 0; i < labColors.length; i++) {
        if (assigned.has(i)) continue;
        
        const cluster = [labColors[i]];
        assigned.add(i);
        
        for (let j = i + 1; j < labColors.length; j++) {
            if (assigned.has(j)) continue;
            
            // CIEDE2000 color difference:
            const distance = ciede2000(labColors[i].lab, labColors[j].lab);
            
            if (distance < distanceThreshold) {
                cluster.push(labColors[j]);
                assigned.add(j);
            }
        }
        
        // Canonical value = most frequent in cluster:
        const hexCounts = {};
        for (const c of cluster) {
            hexCounts[c.hex] = (hexCounts[c.hex] || 0) + 1;
        }
        const canonical = Object.entries(hexCounts)
            .sort(([, a], [, b]) => b - a)[0][0];
        
        clusters.push({
            canonical,
            variants: [...new Set(cluster.map(c => c.hex))],
            usageCount: cluster.length,
            usageContexts: cluster.map(c => c.nodeName),
        });
    }
    
    return clusters.sort((a, b) => b.usageCount - a.usageCount);
}

// Spacing snapping to a scale:
function snapToScale(values, baseUnit = 4) {
    const snapped = new Map();
    
    for (const item of values) {
        // Snap to nearest multiple of base unit:
        const rounded = Math.round(item.value / baseUnit) * baseUnit;
        
        if (!snapped.has(rounded)) {
            snapped.set(rounded, {
                canonical: rounded,
                rawValues: [],
                usageCount: 0,
                usageContexts: [],
            });
        }
        
        const entry = snapped.get(rounded);
        entry.rawValues.push(item.value);
        entry.usageCount++;
        entry.usageContexts.push(item.nodeName);
    }
    
    return [...snapped.values()].sort((a, b) => a.canonical - b.canonical);
}

3. LLM-Powered Token Naming

/*
 * Clustered values need MEANINGFUL names.
 * LLMs excel at this — given usage context, they can
 * infer semantic names like "primary", "surface", "muted".
 *
 * Input to LLM:
 *   Color #1A73E8 used in: Button/Primary, Link/Default, Icon/Active
 *   Color #E53935 used in: Alert/Error, Badge/Danger, Input/Error
 *   Color #F5F5F5 used in: Card/Background, Input/Disabled, Page/Surface
 *
 * Expected output:
 *   #1A73E8 → color-primary
 *   #E53935 → color-error
 *   #F5F5F5 → color-surface
 */

async function generateTokenNames(clusters, category) {
    const prompt = `You are a design system architect naming design tokens.

Given these ${category} values and where they're used in the design,
generate semantic token names following this convention:
- Use kebab-case
- Prefix with the category: color-, spacing-, font-size-, radius-, shadow-
- Use semantic names (primary, secondary, error, surface, muted)
- NOT arbitrary names (blue-1, spacing-3)
- For scales, use t-shirt sizes (xs, sm, md, lg, xl) or numbered scales (100-900)

Values and their usage contexts:

${clusters.map((c, i) => 
    `${i + 1}. Value: ${c.canonical} (used ${c.usageCount} times)
   Used in: ${[...new Set(c.usageContexts)].slice(0, 5).join(', ')}`
).join('\n\n')}

Return ONLY a JSON array of objects with "value" and "name" fields.
Example: [{"value": "#1A73E8", "name": "color-primary"}]`;
    
    const response = await callLLM(prompt, {
        model: 'gpt-4o',
        temperature: 0.1,
        response_format: { type: 'json_object' },
    });
    
    const names = JSON.parse(response);
    
    // Validate: no duplicate names, all values present:
    const nameSet = new Set();
    for (const item of names) {
        if (nameSet.has(item.name)) {
            item.name += `-${nameSet.size}`; // Deduplicate
        }
        nameSet.add(item.name);
    }
    
    return names;
}

// Generate multiple output formats:
function generateTokenFiles(tokens) {
    // CSS Custom Properties:
    const css = `:root {\n${tokens.map(t => 
        `  --${t.name}: ${t.value};`
    ).join('\n')}\n}`;
    
    // JSON (for tools and JavaScript):
    const json = JSON.stringify(
        Object.fromEntries(tokens.map(t => [t.name, t.value])),
        null, 2
    );
    
    // Tailwind config extension:
    const tailwind = generateTailwindConfig(tokens);
    
    // TypeScript constants:
    const ts = `export const tokens = {\n${tokens.map(t =>
        `  '${t.name}': '${t.value}',`
    ).join('\n')}\n} as const;\n\nexport type TokenName = keyof typeof tokens;`;
    
    return { css, json, tailwind, ts };
}

4. Screenshot-to-CSS Generation

/*
 * Converting a screenshot/design to CSS uses vision models.
 *
 * Pipeline:
 * 1. Input: screenshot or Figma frame export
 * 2. Vision model identifies UI elements (buttons, cards, inputs)
 * 3. Layout model determines flex/grid structure
 * 4. Style model extracts colors, sizes, spacing
 * 5. Code generator produces CSS with design tokens
 *
 * The key insight: DON'T generate pixel-exact CSS.
 * Generate SEMANTIC CSS using the team's design tokens.
 *
 * ┌──────────────────────────────────────────────────┐
 * │ Screenshot Input:                                 │
 * │ ┌─────────────────────────────────┐              │
 * │ │ ┌─────┐  ┌────────────────┐    │              │
 * │ │ │ IMG │  │ Title          │    │              │
 * │ │ │     │  │ Subtitle       │    │              │
 * │ │ └─────┘  │ [Button]       │    │              │
 * │ │          └────────────────┘    │              │
 * │ └─────────────────────────────────┘              │
 * │                                                   │
 * │ Generated CSS (semantic, not pixel-exact):        │
 * │                                                   │
 * │ .card {                                           │
 * │   display: flex;                                  │
 * │   gap: var(--spacing-md);                         │
 * │   padding: var(--spacing-lg);                     │
 * │   border-radius: var(--radius-md);                │
 * │ }                                                 │
 * │ .card__image { ... }                              │
 * │ .card__content { ... }                            │
 * └──────────────────────────────────────────────────┘
 */

async function generateCSSFromScreenshot(imageBuffer, designTokens, options = {}) {
    const {
        framework = 'css',       // 'css' | 'tailwind' | 'styled-components'
        methodology = 'bem',      // 'bem' | 'module' | 'utility'
        responsive = true,
    } = options;
    
    // Convert design tokens to a reference string for the prompt:
    const tokenReference = Object.entries(designTokens)
        .map(([name, value]) => `--${name}: ${value}`)
        .join('\n');
    
    const prompt = `Analyze this UI screenshot and generate production CSS.

DESIGN TOKENS (use these instead of hardcoded values):
${tokenReference}

REQUIREMENTS:
- Framework: ${framework}
- Naming: ${methodology}
- Use design tokens for ALL colors, spacing, typography, radii, shadows
- Use flexbox or grid for layout (prefer flexbox for simple layouts)
- ${responsive ? 'Include responsive breakpoints (mobile-first)' : 'Desktop only'}
- Generate semantic class names based on the component's purpose
- Do NOT use pixel values for spacing — map to the nearest token
- Include hover/focus states if buttons or interactive elements are visible

OUTPUT FORMAT:
1. HTML structure (semantic elements)
2. CSS (using var() references to design tokens)
3. Brief notes on any assumptions made

Analyze the image and generate the code.`;
    
    const response = await callVisionLLM(prompt, imageBuffer, {
        model: 'gpt-4o',
        temperature: 0.2,
        maxTokens: 2000,
    });
    
    // Parse and validate the response:
    const { html, css, notes } = parseCodeResponse(response);
    
    // Validate: check that CSS uses tokens, not hardcoded values:
    const validation = validateTokenUsage(css, designTokens);
    
    if (validation.hardcodedValues.length > 0) {
        // Auto-fix: replace hardcoded values with nearest tokens:
        const fixedCSS = replaceHardcodedWithTokens(css, validation.hardcodedValues, designTokens);
        return { html, css: fixedCSS, notes, fixes: validation.hardcodedValues };
    }
    
    return { html, css, notes };
}

// Validate that generated CSS uses tokens:
function validateTokenUsage(css, tokens) {
    const hardcodedValues = [];
    
    // Find hardcoded colors:
    const colorRegex = /#[0-9a-fA-F]{3,8}\b/g;
    let match;
    while ((match = colorRegex.exec(css)) !== null) {
        const hex = match[0];
        const nearestToken = findNearestColorToken(hex, tokens);
        if (nearestToken) {
            hardcodedValues.push({
                value: hex,
                suggestedToken: nearestToken.name,
                distance: nearestToken.distance,
                position: match.index,
            });
        }
    }
    
    // Find hardcoded pixel values for spacing:
    const pxRegex = /(?:padding|margin|gap|border-radius):\s*(\d+)px/g;
    while ((match = pxRegex.exec(css)) !== null) {
        const px = parseInt(match[1]);
        const nearestToken = findNearestSpacingToken(px, tokens);
        if (nearestToken) {
            hardcodedValues.push({
                value: `${px}px`,
                suggestedToken: nearestToken.name,
                position: match.index,
            });
        }
    }
    
    return { hardcodedValues };
}

5. Responsive Layout Inference

/*
 * AI models can infer responsive behavior from a single
 * desktop screenshot by understanding layout patterns:
 *
 * - Horizontal cards → stack vertically on mobile
 * - Multi-column grids → fewer columns on smaller screens
 * - Side navigation → hamburger menu on mobile
 * - Large hero text → scaled down
 *
 * The model doesn't "know" the mobile layout — it infers
 * standard responsive patterns from the desktop structure.
 */

async function generateResponsiveCSS(imageBuffer, tokens) {
    const prompt = `Analyze this desktop UI layout and generate responsive CSS
with mobile-first breakpoints.

BREAKPOINTS:
- Mobile: default (< 768px)
- Tablet: @media (min-width: 768px)
- Desktop: @media (min-width: 1024px)

RESPONSIVE RULES:
1. Multi-column layouts → single column on mobile
2. Horizontal flex containers → vertical on mobile if items are complex
3. Fixed widths → fluid widths (use %, max-width, clamp())
4. Font sizes → use clamp() for fluid typography
5. Padding/margins → reduce by one scale step on mobile
6. Navigation → assume hamburger menu pattern on mobile

DESIGN TOKENS:
${formatTokensForPrompt(tokens)}

Generate CSS starting from mobile layout, adding complexity at larger breakpoints.
Use container queries where appropriate for component-level responsiveness.`;
    
    const response = await callVisionLLM(prompt, imageBuffer, {
        model: 'gpt-4o',
        temperature: 0.2,
    });
    
    return parseCodeResponse(response);
}

// Post-processing: ensure fluid values
function ensureFluidCSS(css) {
    // Replace fixed font sizes with clamp():
    const fixedFontSizes = css.matchAll(/font-size:\s*(\d+)px/g);
    let result = css;
    
    for (const match of fixedFontSizes) {
        const px = parseInt(match[1]);
        const minPx = Math.round(px * 0.75);
        const vw = (px / 1440 * 100).toFixed(2);
        const clamp = `clamp(${minPx}px, ${vw}vw, ${px}px)`;
        result = result.replace(match[0], `font-size: ${clamp}`);
    }
    
    return result;
}

6. Existing Codebase Token Audit

/*
 * The hardest problem: auditing EXISTING CSS to find
 * hardcoded values that should be design tokens.
 *
 * Scale: 500 CSS/SCSS files, 20,000 declarations.
 * Can't manually review each one.
 *
 * Pipeline:
 * 1. Parse all CSS files into AST
 * 2. Extract every value for tokenizable properties
 * 3. Match against design token values (exact + fuzzy)
 * 4. Generate migration diff
 *
 * ┌──────────────────────────────────────────────────┐
 * │ Input: color: #1A73E8;                           │
 * │                                                   │
 * │ Token lookup:                                     │
 * │   Exact match: --color-primary: #1A73E8 ✓        │
 * │                                                   │
 * │ Output: color: var(--color-primary);              │
 * │                                                   │
 * │ Input: padding: 13px;                             │
 * │                                                   │
 * │ Token lookup:                                     │
 * │   Nearest: --spacing-md: 12px (distance: 1)      │
 * │   Nearest: --spacing-lg: 16px (distance: 3)      │
 * │                                                   │
 * │ AI decision: 13px is likely meant to be 12px     │
 * │ Output: padding: var(--spacing-md);               │
 * └──────────────────────────────────────────────────┘
 */

const postcss = require('postcss');

async function auditCSSForTokens(cssFiles, designTokens) {
    const audit = {
        exactMatches: [],     // Hardcoded value matches a token exactly
        fuzzyMatches: [],     // Close to a token (likely mistake)
        noMatch: [],          // Hardcoded value has no matching token
        alreadyTokenized: 0,  // Already using var(--token)
    };
    
    const tokenMap = buildTokenLookup(designTokens);
    
    for (const file of cssFiles) {
        const css = fs.readFileSync(file, 'utf8');
        const root = postcss.parse(css);
        
        root.walkDecls((decl) => {
            // Skip if already using a token:
            if (decl.value.includes('var(--')) {
                audit.alreadyTokenized++;
                return;
            }
            
            // Check property type:
            const tokenCategory = getTokenCategory(decl.prop);
            if (!tokenCategory) return; // Not a tokenizable property
            
            // Extract values:
            const values = extractValues(decl.value, tokenCategory);
            
            for (const value of values) {
                const match = findTokenMatch(value, tokenCategory, tokenMap);
                
                if (match.type === 'exact') {
                    audit.exactMatches.push({
                        file,
                        line: decl.source.start.line,
                        property: decl.prop,
                        currentValue: value.raw,
                        suggestedToken: match.token,
                        replacement: `var(--${match.token})`,
                    });
                } else if (match.type === 'fuzzy') {
                    audit.fuzzyMatches.push({
                        file,
                        line: decl.source.start.line,
                        property: decl.prop,
                        currentValue: value.raw,
                        suggestedToken: match.token,
                        distance: match.distance,
                        replacement: `var(--${match.token})`,
                    });
                } else {
                    audit.noMatch.push({
                        file,
                        line: decl.source.start.line,
                        property: decl.prop,
                        currentValue: value.raw,
                    });
                }
            }
        });
    }
    
    return audit;
}

function getTokenCategory(property) {
    if (/^(color|background-color|border-color|fill|stroke)$/.test(property)) return 'color';
    if (/^(padding|margin|gap|top|right|bottom|left)/.test(property)) return 'spacing';
    if (/^(font-size)$/.test(property)) return 'font-size';
    if (/^(font-weight)$/.test(property)) return 'font-weight';
    if (/^(font-family)$/.test(property)) return 'font-family';
    if (/^(border-radius)$/.test(property)) return 'radius';
    if (/^(box-shadow)$/.test(property)) return 'shadow';
    return null;
}

function findTokenMatch(value, category, tokenMap) {
    const candidates = tokenMap[category] || [];
    
    // Exact match:
    const exact = candidates.find(t => normalizeValue(t.value) === normalizeValue(value.normalized));
    if (exact) return { type: 'exact', token: exact.name };
    
    // Fuzzy match (within threshold):
    let bestFuzzy = null;
    let bestDistance = Infinity;
    
    for (const candidate of candidates) {
        const distance = computeValueDistance(value.normalized, candidate.value, category);
        if (distance < bestDistance) {
            bestDistance = distance;
            bestFuzzy = candidate;
        }
    }
    
    // Thresholds by category:
    const thresholds = {
        color: 3,        // CIEDE2000 distance
        spacing: 2,      // px difference
        'font-size': 1,  // px difference
        radius: 2,       // px difference
    };
    
    if (bestFuzzy && bestDistance <= (thresholds[category] || 2)) {
        return { type: 'fuzzy', token: bestFuzzy.name, distance: bestDistance };
    }
    
    return { type: 'none' };
}

7. Automated Migration Script Generation

/*
 * The audit produces a list of replacements.
 * The migration generates a codemod that applies them.
 *
 * For exact matches: auto-apply (safe)
 * For fuzzy matches: generate PR with explanations (needs review)
 * For no-match: flag for manual review (may need new tokens)
 */

async function generateMigration(audit) {
    const migration = {
        safe: [],      // Exact matches — can auto-apply
        review: [],    // Fuzzy matches — need human review
        manual: [],    // No match — needs new token or manual decision
    };
    
    // Group exact matches by file for efficient editing:
    const safeByFile = groupBy(audit.exactMatches, 'file');
    
    for (const [file, replacements] of Object.entries(safeByFile)) {
        let css = fs.readFileSync(file, 'utf8');
        const root = postcss.parse(css);
        
        // Apply replacements in reverse order (to preserve line numbers):
        const sorted = replacements.sort((a, b) => b.line - a.line);
        
        root.walkDecls((decl) => {
            const match = sorted.find(r => 
                r.line === decl.source.start.line && r.property === decl.prop
            );
            
            if (match) {
                decl.value = decl.value.replace(match.currentValue, match.replacement);
            }
        });
        
        migration.safe.push({
            file,
            original: css,
            migrated: root.toString(),
            changeCount: replacements.length,
        });
    }
    
    // For fuzzy matches, use LLM to explain the suggestion:
    for (const match of audit.fuzzyMatches) {
        const explanation = await callLLM(`
A CSS file has this declaration:
  ${match.property}: ${match.currentValue};

The nearest design token is:
  --${match.suggestedToken}: ${getTokenValue(match.suggestedToken)}

The difference is: ${match.distance} (${getCategoryUnit(match.property)})

Should this value be replaced with the token? Respond with:
- "yes" if this is likely an off-by-one error or rounding issue
- "no" if the value seems intentionally different
- "maybe" if you're unsure

One-line explanation.`,
            { model: 'gpt-4o-mini', temperature: 0, maxTokens: 50 }
        );
        
        migration.review.push({
            ...match,
            aiRecommendation: explanation,
        });
    }
    
    return migration;
}

// Generate a PR description for the migration:
function generateMigrationPR(migration) {
    return `## Design Token Migration

### Auto-applied (exact matches)
${migration.safe.length} values across ${new Set(migration.safe.map(s => s.file)).size} files
replaced with design token references.

### Needs review (fuzzy matches)
${migration.review.map(r => 
    `- \`${r.file}:${r.line}\`: \`${r.currentValue}\` → \`var(--${r.suggestedToken})\` ` +
    `(distance: ${r.distance}) — AI says: ${r.aiRecommendation}`
).join('\n')}

### Unmatched values (may need new tokens)
${migration.manual.length} hardcoded values don't match any existing token.
Consider creating new tokens or leaving as-is.
`;
}

8. Tailwind Class Generation from Design

/*
 * For Tailwind CSS projects, the AI generates utility classes
 * instead of custom CSS — mapping design values to Tailwind's
 * utility class system.
 *
 * Challenge: Tailwind has hundreds of utilities. The AI must
 * pick the right ones and handle custom values via arbitrary
 * value syntax [value] or theme extension.
 */

async function generateTailwindFromDesign(imageBuffer, tailwindConfig) {
    // Extract the current Tailwind theme for reference:
    const themeReference = extractTailwindTheme(tailwindConfig);
    
    const prompt = `Analyze this UI screenshot and generate Tailwind CSS markup.

TAILWIND THEME (use these values):
${JSON.stringify(themeReference, null, 2)}

RULES:
1. Use existing theme values (e.g., text-primary, bg-surface, p-4)
2. For values NOT in the theme, use arbitrary value syntax: text-[#1A73E8]
3. Prefer responsive prefixes: sm:, md:, lg:
4. Use flex/grid utilities for layout
5. Include hover:, focus:, dark: variants where appropriate
6. Group related classes logically

OUTPUT FORMAT:
\`\`\`html
<div class="flex gap-4 p-6 rounded-lg bg-surface">
  <!-- Component markup with Tailwind classes -->
</div>
\`\`\`

Also list any theme values that should be added to tailwind.config.js
to replace arbitrary values.`;
    
    const response = await callVisionLLM(prompt, imageBuffer, {
        model: 'gpt-4o',
        temperature: 0.2,
    });
    
    const { html, themeAdditions } = parseTailwindResponse(response);
    
    // Post-process: find arbitrary values that could be theme values:
    const arbitraryValues = extractArbitraryValues(html);
    const suggestions = arbitraryValues.map(av => ({
        arbitrary: av,
        suggestedThemeKey: inferThemeKey(av),
    }));
    
    return { html, themeAdditions, suggestions };
}

function extractArbitraryValues(html) {
    const regex = /\b\w+-\[([^\]]+)\]/g;
    const values = [];
    let match;
    
    while ((match = regex.exec(html)) !== null) {
        values.push({
            full: match[0],
            value: match[1],
            utility: match[0].split('-[')[0],
        });
    }
    
    return values;
}

9. Design Drift Detection

/*
 * Over time, code diverges from design — "design drift."
 * AI can detect this by comparing:
 *   1. Current code's rendered output (screenshot)
 *   2. Latest Figma design (exported frame)
 *
 * This is a specialized visual regression test:
 * instead of comparing code vs code, it compares code vs design.
 *
 * ┌──────────────────────────────────────────────────┐
 * │ Weekly Design Drift Report:                       │
 * │                                                   │
 * │ Component         │ Drift Score │ Issues          │
 * │───────────────────│────────────│────────────────│
 * │ Button/Primary    │ 0.98       │ None            │
 * │ Card/Product      │ 0.85       │ Spacing differs │
 * │ Nav/Header        │ 0.72       │ Color, layout   │
 * │ Input/Search      │ 0.95       │ Border radius   │
 * └──────────────────────────────────────────────────┘
 */

async function detectDesignDrift(components, figmaFileKey, apiToken) {
    const report = [];
    
    for (const component of components) {
        // 1. Capture current rendered component:
        const browser = await chromium.launch();
        const page = await browser.newPage();
        await page.goto(component.storybookUrl);
        const codeScreenshot = await page.screenshot({
            clip: component.viewport,
        });
        await browser.close();
        
        // 2. Export corresponding Figma frame:
        const figmaExport = await fetch(
            `https://api.figma.com/v1/images/${figmaFileKey}?ids=${component.figmaNodeId}&format=png&scale=2`,
            { headers: { 'X-Figma-Token': apiToken } }
        );
        const figmaImageUrl = (await figmaExport.json()).images[component.figmaNodeId];
        const designScreenshot = await fetch(figmaImageUrl).then(r => r.buffer());
        
        // 3. Compare using SSIM:
        const { mssim } = computeSSIM(
            await decodeImage(codeScreenshot),
            await decodeImage(designScreenshot)
        );
        
        // 4. If drift detected, use AI to describe what changed:
        let issues = [];
        if (mssim < 0.95) {
            issues = await describeVisualDifferences(codeScreenshot, designScreenshot);
        }
        
        report.push({
            component: component.name,
            driftScore: mssim,
            status: mssim >= 0.95 ? 'aligned' : mssim >= 0.85 ? 'minor-drift' : 'significant-drift',
            issues,
        });
    }
    
    return report;
}

async function describeVisualDifferences(codeImage, designImage) {
    const prompt = `Compare these two images of the same UI component.
Image 1 is the CURRENT CODE rendering.
Image 2 is the DESIGN specification.

List specific differences:
- Color mismatches (specify which element and the difference)
- Spacing differences (specify which gap/padding)
- Typography differences (size, weight, family)
- Border/radius differences
- Missing or extra elements

Be specific and actionable. Only list real differences, not rendering artifacts.`;
    
    const response = await callVisionLLM(prompt, [codeImage, designImage], {
        model: 'gpt-4o',
        temperature: 0.1,
    });
    
    return parseIssueList(response);
}

10. End-to-End Workflow Integration

/*
 * Full workflow: Figma change → token update → CSS migration → PR
 *
 * ┌──────────────────────────────────────────────────┐
 * │ 1. Figma Webhook: design file updated            │
 * │    ↓                                              │
 * │ 2. Extract tokens from updated Figma file        │
 * │    ↓                                              │
 * │ 3. Diff against current token file               │
 * │    ↓                                              │
 * │ 4. If tokens changed:                            │
 * │    a. Update token files (CSS, JSON, TS)         │
 * │    b. Audit codebase for affected hardcoded vals  │
 * │    c. Generate migration for affected files       │
 * │    d. Create PR with all changes                 │
 * │    ↓                                              │
 * │ 5. PR review:                                    │
 * │    - Auto-applied exact matches ✓                │
 * │    - Fuzzy matches need human review             │
 * │    - New tokens highlighted                      │
 * └──────────────────────────────────────────────────┘
 */

// Figma webhook handler:
async function handleFigmaWebhook(event) {
    if (event.event_type !== 'FILE_UPDATE') return;
    
    const fileKey = event.file_key;
    
    // 1. Extract new tokens:
    const rawValues = await extractTokensFromFigma(fileKey, process.env.FIGMA_TOKEN);
    
    // 2. Cluster and name:
    const colorClusters = clusterColors(rawValues.colors);
    const spacingClusters = snapToScale(rawValues.spacings);
    
    const colorTokens = await generateTokenNames(colorClusters, 'color');
    const spacingTokens = await generateTokenNames(spacingClusters, 'spacing');
    const allTokens = [...colorTokens, ...spacingTokens];
    
    // 3. Diff against current tokens:
    const currentTokens = JSON.parse(fs.readFileSync('tokens.json', 'utf8'));
    const diff = diffTokens(currentTokens, allTokens);
    
    if (diff.added.length === 0 && diff.changed.length === 0 && diff.removed.length === 0) {
        console.log('No token changes detected');
        return;
    }
    
    // 4. Generate updated token files:
    const tokenFiles = generateTokenFiles(allTokens);
    
    // 5. Audit codebase for affected values:
    const cssFiles = glob.sync('src/**/*.{css,scss,module.css}');
    const audit = await auditCSSForTokens(cssFiles, allTokens);
    
    // 6. Generate migration:
    const migration = await generateMigration(audit);
    
    // 7. Create branch and PR:
    execSync('git checkout -b design-token-sync/auto');
    
    // Write token files:
    fs.writeFileSync('src/tokens/tokens.css', tokenFiles.css);
    fs.writeFileSync('src/tokens/tokens.json', tokenFiles.json);
    fs.writeFileSync('src/tokens/tokens.ts', tokenFiles.ts);
    
    // Apply safe migrations:
    for (const { file, migrated } of migration.safe) {
        fs.writeFileSync(file, migrated);
    }
    
    execSync('git add -A');
    execSync('git commit -m "chore(tokens): sync design tokens from Figma"');
    
    // Create PR with migration report:
    const prBody = generateMigrationPR(migration);
    // ... create PR via GitHub API
    
    console.log(`PR created: ${diff.added.length} new tokens, ${diff.changed.length} updated, ${migration.safe.length} files migrated`);
}

Trade-offs & Considerations

Aspect	Manual Handoff	Token Extraction Only	Full AI Pipeline
Accuracy	High (human eye)	High (deterministic parse)	Medium (needs review)
Speed	2-3 hours/update	5 minutes/update	2 minutes/update
Consistency	Low (human error)	High	High
Design drift	Undetected	Detected (tokens only)	Detected + fixed
Setup cost	None	Medium (Figma API)	High (ML + CI)
Maintenance	None	Low	Medium
Token naming	Manual (inconsistent)	AI-assisted (review)	AI-assisted (review)

Best Practices

Extract tokens deterministically from Figma API, use AI only for naming and ambiguity resolution — the Figma API provides exact color values, font sizes, and spacing numerically; extraction should be deterministic code, not AI inference; use AI only where human judgment is needed: naming tokens semantically, resolving near-duplicate values, and deciding whether 13px should snap to the 12px token.
Cluster design values before creating tokens — designers inevitably introduce slight variations — a color used 50 times across a design file will have 2-3 slight hex variations from rounding or copy-paste errors; use CIELAB color distance (CIEDE2000) for perceptual clustering with a threshold of ΔE < 3; for spacing, snap to a base grid (4px or 8px) to normalize designer imprecision.
Always validate AI-generated CSS against the design token set — replace any hardcoded values — vision models generating CSS from screenshots will include hardcoded colors and pixel values; run a post-processing step that matches every value against the token set and replaces matches with var(--token-name); this ensures the generated code integrates with the design system rather than creating one-off styles.
Separate exact-match migrations (auto-apply) from fuzzy-match migrations (human review) — when auditing an existing codebase, exact matches (#1A73E8 → var(--color-primary)) are safe to auto-apply in bulk; fuzzy matches (13px → var(--spacing-md, 12px)) need human verification since the original value might be intentional; batch exact matches into auto-merged PRs and fuzzy matches into review-required PRs.
Run design drift detection weekly as a CI job comparing rendered components against Figma exports — capture screenshots of every Storybook story, export corresponding Figma frames, compute SSIM between each pair, and flag components where the score drops below 0.95; use a vision model to describe the specific differences (color, spacing, typography) so designers and developers can quickly identify and fix drift.

Conclusion

AI-powered CSS generation and design token management operates through three interconnected pipelines. Token extraction walks the Figma API's JSON tree to collect every color fill, font size, padding value, and border radius, then clusters near-duplicate values using perceptual color distance (CIEDE2000) and grid snapping, with an LLM assigning semantic names based on usage context (a blue used in buttons and links becomes color-primary, not blue-47). Design-to-CSS generation sends screenshots to vision models with the team's token set as context, requiring the AI to reference var(--spacing-md) instead of 16px, with a post-processing validation step that catches and replaces any hardcoded values the model outputs. Token audit parses the existing codebase's CSS into ASTs using PostCSS, matches every declaration value against the token set (exact match for auto-migration, fuzzy match for human review), and generates migration PRs that bulk-replace hardcoded values with token references. Design drift detection closes the loop by comparing rendered Storybook screenshots against Figma exports using SSIM, flagging components where code has diverged from design, and using vision models to describe the specific differences. The critical architectural decision is keeping extraction and matching deterministic (Figma API parsing, SSIM computation, PostCSS AST manipulation) while using AI only for tasks requiring human-like judgment (semantic naming, ambiguous value resolution, visual difference description).

What did you think?