@fragments-sdk/cli 0.2.2

package/src/viewer/style-utils.ts

@@ -0,0 +1,414 @@
+/**
+ * Style comparison utilities for comparing Figma design properties
+ * with rendered component computed styles.
+ */
+
+/**
+ * Style diff result for a single CSS property
+ */
+export interface StyleDiffItem {
+  /** CSS property name */
+  property: string;
+  /** Expected value from Figma */
+  figma: string;
+  /** Actual value from rendered component */
+  rendered: string;
+  /** Whether values match (within tolerance) */
+  match: boolean;
+}
+
+/**
+ * Result of comparing styles
+ */
+export interface StyleComparisonResult {
+  /** Whether all styles match */
+  match: boolean;
+  /** Individual property comparisons */
+  properties: StyleDiffItem[];
+  /** CSS properties from Figma design */
+  figmaStyles: Record<string, string>;
+  /** Computed CSS properties from rendered component */
+  renderedStyles: Record<string, string>;
+}
+
+/**
+ * Compare Figma CSS properties with rendered computed styles.
+ */
+export function compareStyles(
+  figmaStyles: Record<string, string | undefined>,
+  renderedStyles: Record<string, string>
+): StyleComparisonResult {
+  const properties: StyleDiffItem[] = [];
+  const cleanFigmaStyles: Record<string, string> = {};
+
+  // Properties to compare
+  const propsToCompare = [
+    "backgroundColor",
+    "borderColor",
+    "borderWidth",
+    "borderRadius",
+    "fontFamily",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+    "textAlign",
+    "boxShadow",
+    "padding",
+    "gap",
+    "opacity",
+  ];
+
+  for (const prop of propsToCompare) {
+    const figmaValue = figmaStyles[prop];
+    const renderedValue = renderedStyles[prop];
+
+    if (figmaValue !== undefined) {
+      cleanFigmaStyles[prop] = figmaValue;
+
+      const match = compareStyleValue(prop, figmaValue, renderedValue || "");
+      properties.push({
+        property: prop,
+        figma: figmaValue,
+        rendered: renderedValue || "(not set)",
+        match,
+      });
+    }
+  }
+
+  const allMatch = properties.every((p) => p.match);
+
+  return {
+    match: allMatch,
+    properties,
+    figmaStyles: cleanFigmaStyles,
+    renderedStyles,
+  };
+}
+
+/**
+ * Compare a single style value with tolerance for color and numeric differences.
+ */
+export function compareStyleValue(
+  prop: string,
+  figma: string,
+  rendered: string
+): boolean {
+  // Normalize values for comparison
+  const normalizedFigma = normalizeStyleValue(prop, figma);
+  const normalizedRendered = normalizeStyleValue(prop, rendered);
+
+  // Direct match
+  if (normalizedFigma === normalizedRendered) {
+    return true;
+  }
+
+  // Color comparison with tolerance
+  if (prop === "backgroundColor" || prop === "borderColor") {
+    return compareColors(normalizedFigma, normalizedRendered, 5);
+  }
+
+  // Numeric comparison with tolerance (for pixels)
+  if (
+    ["borderWidth", "borderRadius", "fontSize", "padding", "gap"].includes(prop)
+  ) {
+    return compareNumericValues(normalizedFigma, normalizedRendered, 1);
+  }
+
+  return false;
+}
+
+/**
+ * Normalize a style value for comparison.
+ */
+export function normalizeStyleValue(prop: string, value: string): string {
+  // Remove extra whitespace
+  let normalized = value.trim().replace(/\s+/g, " ");
+
+  // Normalize "none" shadow to empty
+  if (prop === "boxShadow" && normalized === "none") {
+    normalized = "";
+  }
+
+  // Normalize rgba(0, 0, 0, 0) to "transparent"
+  if (normalized.match(/rgba\(\s*0\s*,\s*0\s*,\s*0\s*,\s*0\s*\)/)) {
+    normalized = "transparent";
+  }
+
+  return normalized;
+}
+
+/**
+ * Compare two color values with tolerance.
+ */
+export function compareColors(
+  color1: string,
+  color2: string,
+  tolerance: number
+): boolean {
+  const rgb1 = parseColor(color1);
+  const rgb2 = parseColor(color2);
+
+  if (!rgb1 || !rgb2) {
+    return color1 === color2;
+  }
+
+  return (
+    Math.abs(rgb1.r - rgb2.r) <= tolerance &&
+    Math.abs(rgb1.g - rgb2.g) <= tolerance &&
+    Math.abs(rgb1.b - rgb2.b) <= tolerance &&
+    Math.abs((rgb1.a ?? 1) - (rgb2.a ?? 1)) <= 0.05
+  );
+}
+
+/**
+ * Parse a color string to RGB values.
+ */
+export function parseColor(
+  color: string
+): { r: number; g: number; b: number; a?: number } | null {
+  // Handle hex colors
+  const hexMatch = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+  if (hexMatch) {
+    return {
+      r: parseInt(hexMatch[1], 16),
+      g: parseInt(hexMatch[2], 16),
+      b: parseInt(hexMatch[3], 16),
+    };
+  }
+
+  // Handle rgb/rgba
+  const rgbaMatch = color.match(
+    /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)/
+  );
+  if (rgbaMatch) {
+    return {
+      r: parseInt(rgbaMatch[1], 10),
+      g: parseInt(rgbaMatch[2], 10),
+      b: parseInt(rgbaMatch[3], 10),
+      a: rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Compare numeric values (e.g., "10px" vs "11px") with tolerance.
+ */
+export function compareNumericValues(
+  value1: string,
+  value2: string,
+  tolerance: number
+): boolean {
+  const num1 = parseFloat(value1);
+  const num2 = parseFloat(value2);
+
+  if (isNaN(num1) || isNaN(num2)) {
+    return value1 === value2;
+  }
+
+  return Math.abs(num1 - num2) <= tolerance;
+}
+
+// ----- Enhanced Token-Aware Style Comparison -----
+
+import type {
+  EnhancedStyleDiffItem,
+  TokenFix,
+  TokenUsageSummary,
+  DesignToken,
+} from "../core/index.js";
+
+/**
+ * Enhanced style diff result with token information
+ */
+export interface EnhancedStyleComparisonResult extends StyleComparisonResult {
+  /** Individual property comparisons with token info */
+  properties: EnhancedStyleDiffItem[];
+  /** Token usage summary */
+  tokenSummary?: TokenUsageSummary;
+}
+
+/**
+ * Token registry interface for style comparison
+ * (subset of TokenRegistryManager methods needed here)
+ */
+export interface TokenLookup {
+  findByValue(value: string, theme?: string): string[];
+  getToken(name: string): DesignToken | undefined;
+  calculateUsageSummary(
+    styleDiffs: Array<{
+      property: string;
+      figma: string;
+      rendered: string;
+      match: boolean;
+    }>,
+    theme?: string
+  ): TokenUsageSummary;
+}
+
+/**
+ * Compare styles with token awareness.
+ *
+ * This enhanced version:
+ * 1. Performs normal style comparison
+ * 2. Identifies which values match design tokens
+ * 3. Flags hardcoded values that should use tokens
+ * 4. Generates fix suggestions
+ */
+export function compareStylesWithTokens(
+  figmaStyles: Record<string, string | undefined>,
+  renderedStyles: Record<string, string>,
+  tokenLookup?: TokenLookup,
+  theme = "default"
+): EnhancedStyleComparisonResult {
+  const properties: EnhancedStyleDiffItem[] = [];
+  const cleanFigmaStyles: Record<string, string> = {};
+
+  // Properties to compare
+  const propsToCompare = [
+    "backgroundColor",
+    "borderColor",
+    "borderWidth",
+    "borderRadius",
+    "fontFamily",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+    "textAlign",
+    "boxShadow",
+    "padding",
+    "gap",
+    "opacity",
+    "color",
+  ];
+
+  for (const prop of propsToCompare) {
+    const figmaValue = figmaStyles[prop];
+    const renderedValue = renderedStyles[prop];
+
+    if (figmaValue !== undefined) {
+      cleanFigmaStyles[prop] = figmaValue;
+
+      const match = compareStyleValue(prop, figmaValue, renderedValue || "");
+
+      // Build enhanced diff item
+      const item: EnhancedStyleDiffItem = {
+        property: prop,
+        figma: figmaValue,
+        rendered: renderedValue || "(not set)",
+        match,
+        isHardcoded: false,
+      };
+
+      // Add token information if registry is available
+      if (tokenLookup) {
+        const figmaTokens = tokenLookup.findByValue(figmaValue, theme);
+        const renderedTokens = renderedValue
+          ? tokenLookup.findByValue(renderedValue, theme)
+          : [];
+
+        if (figmaTokens.length > 0) {
+          item.figmaToken = figmaTokens[0];
+        }
+
+        if (renderedTokens.length > 0) {
+          item.renderedToken = renderedTokens[0];
+        }
+
+        // Determine if this is a hardcoded value
+        // Hardcoded = Figma matches a token, but rendered doesn't use a token
+        item.isHardcoded = !!item.figmaToken && !item.renderedToken;
+
+        // Generate fix suggestion if hardcoded
+        if (item.isHardcoded && item.figmaToken) {
+          const token = tokenLookup.getToken(item.figmaToken);
+          if (token) {
+            const cssProperty = toCssProperty(prop);
+            item.suggestedFix = {
+              tokenName: item.figmaToken,
+              tokenValue: token.resolvedValue,
+              codeFix: `${cssProperty}: var(${item.figmaToken});`,
+              confidence: 0.9,
+              reason: `Figma uses token ${item.figmaToken} (${token.resolvedValue}). Replace hardcoded value with token for consistency.`,
+            };
+          }
+        }
+      }
+
+      properties.push(item);
+    }
+  }
+
+  const allMatch = properties.every((p) => p.match);
+
+  // Calculate token summary if registry available
+  let tokenSummary: TokenUsageSummary | undefined;
+  if (tokenLookup) {
+    tokenSummary = tokenLookup.calculateUsageSummary(
+      properties.map((p) => ({
+        property: p.property,
+        figma: p.figma,
+        rendered: p.rendered,
+        match: p.match,
+      })),
+      theme
+    );
+  }
+
+  return {
+    match: allMatch,
+    properties,
+    figmaStyles: cleanFigmaStyles,
+    renderedStyles,
+    tokenSummary,
+  };
+}
+
+/**
+ * Convert camelCase to kebab-case CSS property
+ */
+function toCssProperty(prop: string): string {
+  return prop.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+
+/**
+ * Format token summary for display
+ */
+export function formatTokenSummary(summary: TokenUsageSummary): string {
+  const lines: string[] = [];
+
+  lines.push(`Token Compliance: ${summary.compliancePercent}%`);
+  lines.push(
+    `${summary.usingTokens}/${summary.totalProperties} properties using tokens`
+  );
+
+  if (summary.hardcoded > 0) {
+    lines.push(`${summary.hardcoded} hardcoded value(s) detected`);
+  }
+
+  if (summary.implicitMatches > 0) {
+    lines.push(`${summary.implicitMatches} implicit match(es)`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Get status badge for token compliance
+ */
+export function getComplianceBadge(
+  compliancePercent: number
+): { label: string; color: string } {
+  if (compliancePercent >= 100) {
+    return { label: "Excellent", color: "green" };
+  } else if (compliancePercent >= 80) {
+    return { label: "Good", color: "blue" };
+  } else if (compliancePercent >= 50) {
+    return { label: "Fair", color: "yellow" };
+  } else {
+    return { label: "Poor", color: "red" };
+  }
+}