@fragments-sdk/viewer 0.2.1

package/src/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" };
+  }
+}

package/src/styles/globals.css

@@ -0,0 +1,278 @@
+/* ============================================
+ * Fragments Viewer Shell Styles
+ * ============================================
+ * Viewer-specific token aliases and utility classes.
+ * Base resets (box-sizing, body, scrollbars) come from
+ * @fragments/ui globals imported via entry.tsx.
+ * ============================================ */
+
+/* ============================================
+ * Token Aliases
+ * ============================================
+ * Shorthand aliases mapping to --fui-* tokens so the viewer
+ * shell CSS can use shorter variable names.
+ */
+
+:root {
+  --bg-primary: var(--fui-bg-primary, #ffffff);
+  --bg-secondary: var(--fui-bg-secondary, #f7f7f8);
+  --bg-tertiary: var(--fui-bg-tertiary, #f2f2f2);
+  --bg-elevated: var(--fui-bg-elevated, #ffffff);
+  --bg-hover: var(--fui-bg-hover, rgba(0, 0, 0, 0.06));
+  --bg-active: var(--fui-bg-active, rgba(0, 0, 0, 0.1));
+
+  --text-primary: var(--fui-text-primary, #171717);
+  --text-secondary: var(--fui-text-secondary, #525252);
+  --text-tertiary: var(--fui-text-tertiary, #8a8a8a);
+  --text-muted: var(--fui-text-tertiary, #8a8a8a);
+
+  --border: var(--fui-border, rgba(0, 0, 0, 0.1));
+  --border-subtle: var(--fui-border, rgba(0, 0, 0, 0.1));
+  --border-strong: var(--fui-border-strong, rgba(0, 0, 0, 0.16));
+
+  --color-accent: var(--fui-color-accent, #10a37f);
+  --color-accent-hover: var(--fui-color-accent-hover, #0d8a6a);
+  --color-accent-subtle: var(--fui-color-success-bg, rgba(16, 163, 127, 0.1));
+
+  --color-success: var(--fui-color-success, #10a37f);
+  --color-success-bg: var(--fui-color-success-bg, rgba(16, 163, 127, 0.1));
+  --color-warning: var(--fui-color-warning, #f59e0b);
+  --color-warning-bg: var(--fui-color-warning-bg, rgba(245, 158, 11, 0.1));
+  --color-danger: var(--fui-color-danger, #ef4444);
+  --color-danger-bg: var(--fui-color-danger-bg, rgba(239, 68, 68, 0.1));
+  --color-info: var(--fui-color-info, #3b82f6);
+  --color-info-bg: var(--fui-color-info-bg, rgba(59, 130, 246, 0.1));
+
+  --shadow-sm: var(--fui-shadow-sm, 0 1px 2px rgba(0, 0, 0, 0.05));
+  --shadow-md: var(--fui-shadow-md, 0 4px 6px -1px rgba(0, 0, 0, 0.08));
+  --shadow-lg: var(--fui-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.12));
+
+  --radius-sm: var(--fui-radius-sm, 6px);
+  --radius-md: var(--fui-radius-md, 8px);
+  --radius-lg: var(--fui-radius-lg, 12px);
+
+  --transition-fast: var(--fui-transition-fast, 150ms ease);
+  --transition-normal: var(--fui-transition-normal, 200ms ease);
+}
+
+/* ============================================
+ * Viewer-specific overrides
+ * ============================================ */
+
+* {
+  border-color: var(--border);
+}
+
+/* ============================================
+ * Theme-aware Utility Classes
+ * ============================================ */
+
+.bg-primary { background-color: var(--bg-primary); }
+.bg-secondary { background-color: var(--bg-secondary); }
+.bg-tertiary { background-color: var(--bg-tertiary); }
+.bg-elevated { background-color: var(--bg-elevated); }
+
+.text-primary { color: var(--text-primary); }
+.text-secondary { color: var(--text-secondary); }
+.text-tertiary { color: var(--text-tertiary); }
+.text-accent { color: var(--color-accent); }
+
+.border-subtle { border-color: var(--border-subtle); }
+.border-strong { border-color: var(--border-strong); }
+
+/* ============================================
+ * Surface Styles
+ * ============================================ */
+
+.surface {
+  background-color: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+}
+
+.surface-interactive {
+  background-color: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  transition: all var(--transition-fast);
+}
+
+.surface-interactive:hover {
+  border-color: var(--border-strong);
+  box-shadow: var(--shadow-sm);
+}
+
+/* ============================================
+ * Badge Styles
+ * ============================================ */
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 3px 8px;
+  border-radius: var(--radius-sm);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.01em;
+  transition: all var(--transition-fast);
+}
+
+.badge-default {
+  background-color: var(--bg-tertiary);
+  color: var(--text-secondary);
+  border: 1px solid var(--border-subtle);
+}
+
+.badge-success {
+  background-color: var(--color-success-bg);
+  color: var(--color-success);
+}
+
+.badge-warning {
+  background-color: var(--color-warning-bg);
+  color: var(--color-warning);
+}
+
+.badge-danger {
+  background-color: var(--color-danger-bg);
+  color: var(--color-danger);
+}
+
+/* ============================================
+ * Focus Ring
+ * ============================================ */
+
+.focus-ring:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--bg-primary), 0 0 0 4px var(--color-accent);
+}
+
+/* ============================================
+ * Transition Utilities
+ * ============================================ */
+
+.transition-colors {
+  transition: color var(--transition-fast), background-color var(--transition-fast), border-color var(--transition-fast);
+}
+
+.transition-all {
+  transition: all var(--transition-fast);
+}
+
+/* ============================================
+ * Code Styling
+ * ============================================ */
+
+code {
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  font-size: 0.875em;
+  background-color: var(--bg-tertiary);
+  padding: 2px 6px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-subtle);
+}
+
+pre code {
+  background: none;
+  padding: 0;
+  border: none;
+}
+
+/* ============================================
+ * Table Base Styles
+ * ============================================ */
+
+table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+th {
+  text-align: left;
+  font-weight: 500;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-tertiary);
+}
+
+td {
+  border-top: 1px solid var(--border-subtle);
+}
+
+/* ============================================
+ * Utility Classes
+ * ============================================ */
+
+.divider {
+  height: 1px;
+  background-color: var(--border);
+}
+
+.text-balance {
+  text-wrap: balance;
+}
+
+/* Scroll utilities */
+.scroll-smooth {
+  scroll-behavior: smooth;
+}
+
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}
+
+/* ============================================
+ * Gradient Utilities
+ * ============================================ */
+
+.gradient-fade-b {
+  background: linear-gradient(to bottom, transparent, var(--bg-primary));
+}
+
+.gradient-fade-t {
+  background: linear-gradient(to top, transparent, var(--bg-primary));
+}
+
+/* Subtle glow effect for interactive elements */
+.glow-accent:hover {
+  box-shadow: 0 0 20px rgba(16, 163, 127, 0.15);
+}
+
+/* ============================================
+ * Animations
+ * ============================================ */
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-fadeIn {
+  animation: fadeIn var(--transition-normal) ease-out;
+}
+
+.animate-slideIn {
+  animation: slideIn var(--transition-normal) ease-out;
+}