@fragments-sdk/cli 0.2.2

package/src/service/figma.ts

@@ -0,0 +1,1008 @@
+/**
+ * Figma API client for fetching design frames.
+ * Includes caching for performance during iteration loops.
+ *
+ * Uses official types from @figma/rest-api-spec for type safety.
+ */
+
+import { BRAND } from '../core/index.js';
+import { ServiceError } from './utils.js';
+import type {
+  GetFileResponse,
+  GetFileNodesResponse,
+  Node as FigmaAPINode,
+} from '@figma/rest-api-spec';
+
+/**
+ * Configuration for FigmaClient
+ */
+export interface FigmaClientConfig {
+  /** Figma Personal Access Token */
+  accessToken: string;
+
+  /** Cache TTL in milliseconds (default: 5 minutes) */
+  cacheTtlMs?: number;
+}
+
+/**
+ * Result of fetching a Figma image
+ */
+export interface FigmaImageResult {
+  /** PNG image buffer */
+  data: Buffer;
+
+  /** Original CDN URL (expires after ~30 days) */
+  cdnUrl: string;
+
+  /** Whether this result was served from cache */
+  fromCache: boolean;
+}
+
+/**
+ * Parsed Figma URL components
+ */
+export interface FigmaUrlParts {
+  /** File key from URL */
+  fileKey: string;
+
+  /** Node ID from URL */
+  nodeId: string;
+}
+
+/**
+ * Extended Figma component metadata.
+ * Compatible with both Component and ComponentSet from @figma/rest-api-spec.
+ */
+export interface FigmaComponent {
+  /** Component key */
+  key: string;
+
+  /** Component name */
+  name: string;
+
+  /** Description */
+  description: string;
+
+  /** File key (added by us - not in API response directly) */
+  file_key: string;
+
+  /** Node ID within the file (from response object keys) */
+  node_id: string;
+
+  /** Component set ID if component belongs to one */
+  componentSetId?: string;
+
+  /** Documentation links (optional for compatibility with ComponentSet) */
+  documentationLinks?: Array<{ uri: string }>;
+
+  /** Whether this is a remote component */
+  remote?: boolean;
+}
+
+/**
+ * Result of fetching file components
+ */
+export interface FigmaFileComponents {
+  /** All components in the file */
+  components: FigmaComponent[];
+
+  /** Component sets (variants) */
+  componentSets: FigmaComponent[];
+
+  /** File name */
+  fileName: string;
+}
+
+/**
+ * A variant within a component set
+ */
+export interface FigmaVariant {
+  /** Node ID of the variant */
+  node_id: string;
+
+  /** Full variant name (e.g., "State=Primary, Size=Medium") */
+  name: string;
+
+  /** Parsed properties from the name */
+  properties: Record<string, string>;
+
+  /** Individual property values for matching */
+  values: string[];
+}
+
+/**
+ * Component set with its variants
+ */
+export interface FigmaComponentSetWithVariants {
+  /** The component set */
+  componentSet: FigmaComponent;
+
+  /** All variants within this component set */
+  variants: FigmaVariant[];
+}
+
+// ============================================================================
+// Design Property Types (for CSS comparison)
+// ============================================================================
+
+/**
+ * RGBA color in Figma format (0-1 range)
+ */
+export interface FigmaColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/**
+ * Figma fill/paint object
+ */
+export interface FigmaFill {
+  type: 'SOLID' | 'GRADIENT_LINEAR' | 'GRADIENT_RADIAL' | 'GRADIENT_ANGULAR' | 'GRADIENT_DIAMOND' | 'IMAGE' | 'EMOJI';
+  color?: FigmaColor;
+  opacity?: number;
+  visible?: boolean;
+}
+
+/**
+ * Figma stroke object
+ */
+export interface FigmaStroke {
+  type: 'SOLID' | 'GRADIENT_LINEAR' | 'GRADIENT_RADIAL' | 'GRADIENT_ANGULAR' | 'GRADIENT_DIAMOND';
+  color?: FigmaColor;
+  opacity?: number;
+  visible?: boolean;
+}
+
+/**
+ * Figma effect (shadow, blur, etc.)
+ */
+export interface FigmaEffect {
+  type: 'DROP_SHADOW' | 'INNER_SHADOW' | 'LAYER_BLUR' | 'BACKGROUND_BLUR';
+  visible?: boolean;
+  color?: FigmaColor;
+  offset?: { x: number; y: number };
+  radius?: number;
+  spread?: number;
+}
+
+/**
+ * Figma typography properties
+ */
+export interface FigmaTypography {
+  fontFamily: string;
+  fontStyle: string;
+  fontSize: number;
+  fontWeight?: number;
+  lineHeight?: { value: number; unit: 'PIXELS' | 'PERCENT' | 'AUTO' };
+  letterSpacing?: number;
+  textAlignHorizontal?: 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED';
+}
+
+/**
+ * Extracted design properties from a Figma node
+ */
+export interface FigmaDesignProperties {
+  /** Node ID */
+  nodeId: string;
+
+  /** Node name */
+  name: string;
+
+  /** Node type */
+  type: string;
+
+  /** Dimensions */
+  width?: number;
+  height?: number;
+
+  /** Fill colors */
+  fills?: FigmaFill[];
+
+  /** Stroke/border */
+  strokes?: FigmaStroke[];
+  strokeWeight?: number;
+  strokeAlign?: 'INSIDE' | 'CENTER' | 'OUTSIDE';
+
+  /** Corner radius */
+  cornerRadius?: number;
+  topLeftRadius?: number;
+  topRightRadius?: number;
+  bottomLeftRadius?: number;
+  bottomRightRadius?: number;
+
+  /** Effects (shadows, blur) */
+  effects?: FigmaEffect[];
+
+  /** Typography (for text nodes) */
+  typography?: FigmaTypography;
+
+  /** Auto-layout properties */
+  padding?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+  };
+  itemSpacing?: number;
+
+  /** Opacity */
+  opacity?: number;
+}
+
+/**
+ * CSS-formatted design properties for comparison
+ */
+export interface CSSDesignProperties {
+  /** Background color */
+  backgroundColor?: string;
+
+  /** Border */
+  borderColor?: string;
+  borderWidth?: string;
+  borderRadius?: string;
+
+  /** Typography */
+  fontFamily?: string;
+  fontSize?: string;
+  fontWeight?: string;
+  lineHeight?: string;
+  letterSpacing?: string;
+  textAlign?: string;
+
+  /** Shadow */
+  boxShadow?: string;
+
+  /** Spacing */
+  padding?: string;
+  gap?: string;
+
+  /** Opacity */
+  opacity?: string;
+
+  /** Dimensions */
+  width?: string;
+  height?: string;
+}
+
+/**
+ * Style comparison result
+ */
+export interface StyleDiffResult {
+  /** Property name */
+  property: string;
+
+  /** Expected value from Figma */
+  figma: string;
+
+  /** Actual value from rendered component */
+  rendered: string;
+
+  /** Whether values match (within tolerance) */
+  match: boolean;
+}
+
+interface CacheEntry {
+  data: Buffer;
+  cdnUrl: string;
+  timestamp: number;
+}
+
+/**
+ * Figma API client with caching.
+ * Fetches design frames as PNG images for comparison.
+ */
+export class FigmaClient {
+  private readonly accessToken: string;
+  private readonly cacheTtlMs: number;
+  private readonly cache = new Map<string, CacheEntry>();
+
+  constructor(config: FigmaClientConfig) {
+    this.accessToken = config.accessToken;
+    this.cacheTtlMs = config.cacheTtlMs ?? 5 * 60 * 1000; // 5 minutes default
+  }
+
+  /**
+   * Parse a Figma URL to extract file key and node ID.
+   *
+   * Supported formats:
+   * - https://figma.com/file/abc123/name?node-id=1-2
+   * - https://figma.com/design/abc123/name?node-id=1-2
+   * - https://www.figma.com/file/abc123/name?node-id=1%3A2 (URL-encoded)
+   */
+  parseUrl(url: string): FigmaUrlParts {
+    // Match both /file/ and /design/ paths
+    const urlPattern = /figma\.com\/(?:file|design)\/([^\/]+)\/[^?]*\?.*node-id=([^&]+)/i;
+    const match = url.match(urlPattern);
+
+    if (!match) {
+      throw new FigmaError(
+        `Invalid Figma URL format: ${url}`,
+        'INVALID_URL',
+        'Expected format: https://figma.com/file/{fileKey}/name?node-id={nodeId}'
+      );
+    }
+
+    const fileKey = match[1];
+    // Decode URL-encoded node IDs (1%3A2 -> 1:2, 1%2D2 -> 1-2)
+    const nodeId = decodeURIComponent(match[2]);
+
+    return { fileKey, nodeId };
+  }
+
+  /**
+   * Fetch an image from Figma by URL.
+   * Uses cache if available and not expired.
+   */
+  async getImageFromUrl(
+    url: string,
+    options: { scale?: number; format?: 'png' | 'jpg' } = {}
+  ): Promise<FigmaImageResult> {
+    const { fileKey, nodeId } = this.parseUrl(url);
+    return this.getNodeImage(fileKey, nodeId, options);
+  }
+
+  /**
+   * Fetch an image for a specific node.
+   */
+  async getNodeImage(
+    fileKey: string,
+    nodeId: string,
+    options: { scale?: number; format?: 'png' | 'jpg' } = {}
+  ): Promise<FigmaImageResult> {
+    const { scale = 2, format = 'png' } = options;
+
+    // Check cache first
+    const cacheKey = `${fileKey}:${nodeId}:${scale}:${format}`;
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && Date.now() - cached.timestamp < this.cacheTtlMs) {
+      return {
+        data: cached.data,
+        cdnUrl: cached.cdnUrl,
+        fromCache: true,
+      };
+    }
+
+    // Fetch from Figma API
+    const cdnUrl = await this.fetchImageUrl(fileKey, nodeId, scale, format);
+    const data = await this.downloadImage(cdnUrl);
+
+    // Update cache
+    this.cache.set(cacheKey, {
+      data,
+      cdnUrl,
+      timestamp: Date.now(),
+    });
+
+    return {
+      data,
+      cdnUrl,
+      fromCache: false,
+    };
+  }
+
+  /**
+   * Clear the cache (useful for forcing fresh fetches)
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache stats for debugging
+   */
+  getCacheStats(): { size: number; oldestMs: number } {
+    let oldest = Date.now();
+    for (const entry of this.cache.values()) {
+      oldest = Math.min(oldest, entry.timestamp);
+    }
+    return {
+      size: this.cache.size,
+      oldestMs: this.cache.size > 0 ? Date.now() - oldest : 0,
+    };
+  }
+
+  /**
+   * Parse a Figma file URL to extract the file key.
+   * Works with URLs that may or may not have a node-id.
+   */
+  parseFileUrl(url: string): { fileKey: string; nodeId?: string } {
+    // Match both /file/ and /design/ paths
+    const urlPattern = /figma\.com\/(?:file|design)\/([^\/]+)/i;
+    const match = url.match(urlPattern);
+
+    if (!match) {
+      throw new FigmaError(
+        `Invalid Figma URL format: ${url}`,
+        'INVALID_URL',
+        'Expected format: https://figma.com/file/{fileKey}/...'
+      );
+    }
+
+    const fileKey = match[1];
+
+    // Try to extract node-id if present
+    const nodeMatch = url.match(/node-id=([^&]+)/i);
+    const nodeId = nodeMatch ? decodeURIComponent(nodeMatch[1]) : undefined;
+
+    return { fileKey, nodeId };
+  }
+
+  /**
+   * Fetch all components from a Figma file.
+   * Uses the /v1/files/:key endpoint to get component metadata.
+   */
+  async getFileComponents(fileKey: string): Promise<FigmaFileComponents> {
+    const apiUrl = `https://api.figma.com/v1/files/${fileKey}`;
+
+    const response = await fetch(apiUrl, {
+      headers: {
+        'X-Figma-Token': this.accessToken,
+      },
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'Unknown error');
+
+      if (response.status === 403) {
+        throw new FigmaError(
+          'Figma access denied',
+          'ACCESS_DENIED',
+          'Check your access token and ensure the file is shared with you'
+        );
+      }
+
+      if (response.status === 404) {
+        throw new FigmaError(
+          `Figma file not found: ${fileKey}`,
+          'NOT_FOUND',
+          'Verify the file key is correct'
+        );
+      }
+
+      throw new FigmaError(
+        `Figma API error (${response.status}): ${errorBody}`,
+        'API_ERROR'
+      );
+    }
+
+    // Use official GetFileResponse type
+    const data = (await response.json()) as GetFileResponse;
+
+    // Convert the component maps to arrays with extended info
+    const components: FigmaComponent[] = Object.entries(data.components || {}).map(
+      ([nodeId, comp]) => ({
+        key: comp.key,
+        name: comp.name,
+        description: comp.description,
+        file_key: fileKey,
+        node_id: nodeId,
+        componentSetId: comp.componentSetId,
+        documentationLinks: comp.documentationLinks,
+        remote: comp.remote,
+      })
+    );
+
+    const componentSets: FigmaComponent[] = Object.entries(data.componentSets || {}).map(
+      ([nodeId, comp]) => ({
+        key: comp.key,
+        name: comp.name,
+        description: comp.description,
+        file_key: fileKey,
+        node_id: nodeId,
+        documentationLinks: comp.documentationLinks,
+        remote: comp.remote,
+      })
+    );
+
+    return {
+      components,
+      componentSets,
+      fileName: data.name,
+    };
+  }
+
+  /**
+   * Fetch variants for specific component sets.
+   * Uses the /v1/files/:key/nodes endpoint to get children of component sets.
+   */
+  async getComponentSetVariants(
+    fileKey: string,
+    componentSets: FigmaComponent[]
+  ): Promise<FigmaComponentSetWithVariants[]> {
+    if (componentSets.length === 0) {
+      return [];
+    }
+
+    // Fetch nodes for all component sets
+    const nodeIds = componentSets.map((cs) => cs.node_id).join(',');
+    const apiUrl = `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${nodeIds}`;
+
+    const response = await fetch(apiUrl, {
+      headers: {
+        'X-Figma-Token': this.accessToken,
+      },
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'Unknown error');
+      throw new FigmaError(
+        `Figma API error (${response.status}): ${errorBody}`,
+        'API_ERROR'
+      );
+    }
+
+    // Use official GetFileNodesResponse type
+    const data = (await response.json()) as GetFileNodesResponse;
+
+    const results: FigmaComponentSetWithVariants[] = [];
+
+    for (const componentSet of componentSets) {
+      const nodeData = data.nodes[componentSet.node_id];
+      if (!nodeData?.document) {
+        continue;
+      }
+
+      // Type guard: check if document has children (ComponentSetNode does)
+      const doc = nodeData.document as FigmaAPINode & { children?: FigmaAPINode[] };
+      if (!doc.children) {
+        continue;
+      }
+
+      const variants: FigmaVariant[] = [];
+
+      for (const child of doc.children) {
+        // Only process COMPONENT type nodes (the variants)
+        if (child.type !== 'COMPONENT') {
+          continue;
+        }
+
+        // Parse the variant name (e.g., "State=Primary, Size=Medium")
+        const properties = this.parseVariantName(child.name);
+        const values = Object.values(properties);
+
+        variants.push({
+          node_id: child.id,
+          name: child.name,
+          properties,
+          values,
+        });
+      }
+
+      results.push({
+        componentSet,
+        variants,
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Parse a Figma variant name into properties.
+   * "State=Primary, Size=Medium" → { State: "Primary", Size: "Medium" }
+   */
+  parseVariantName(name: string): Record<string, string> {
+    const properties: Record<string, string> = {};
+
+    // Split by comma and parse each property
+    const parts = name.split(',').map((p) => p.trim());
+
+    for (const part of parts) {
+      const eqIndex = part.indexOf('=');
+      if (eqIndex > 0) {
+        const key = part.slice(0, eqIndex).trim();
+        const value = part.slice(eqIndex + 1).trim();
+        properties[key] = value;
+      }
+    }
+
+    return properties;
+  }
+
+  /**
+   * Build a Figma URL for a specific node in a file.
+   */
+  buildNodeUrl(fileKey: string, nodeId: string, fileName?: string): string {
+    // URL-encode the node ID (: -> %3A, - is fine)
+    const encodedNodeId = encodeURIComponent(nodeId);
+    const name = fileName ? encodeURIComponent(fileName.replace(/\s+/g, '-')) : 'Design';
+    return `https://www.figma.com/design/${fileKey}/${name}?node-id=${encodedNodeId}`;
+  }
+
+  /**
+   * Fetch design properties from a Figma node.
+   * Extracts colors, typography, spacing, borders, shadows, etc.
+   */
+  async getNodeProperties(
+    fileKey: string,
+    nodeId: string
+  ): Promise<FigmaDesignProperties> {
+    const apiNodeId = nodeId.replace(/-/g, ':');
+    const apiUrl = `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${apiNodeId}`;
+
+    const response = await fetch(apiUrl, {
+      headers: {
+        'X-Figma-Token': this.accessToken,
+      },
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'Unknown error');
+      throw new FigmaError(
+        `Figma API error (${response.status}): ${errorBody}`,
+        'API_ERROR'
+      );
+    }
+
+    const data = (await response.json()) as GetFileNodesResponse;
+    const nodeData = data.nodes[apiNodeId];
+
+    if (!nodeData?.document) {
+      throw new FigmaError(
+        `Node not found: ${nodeId}`,
+        'NOT_FOUND',
+        'Verify the node ID is correct'
+      );
+    }
+
+    const node = nodeData.document as FigmaAPINode & Record<string, unknown>;
+
+    // Extract design properties from the node
+    const properties: FigmaDesignProperties = {
+      nodeId: node.id,
+      name: node.name,
+      type: node.type,
+    };
+
+    // Dimensions
+    if ('absoluteBoundingBox' in node) {
+      const bbox = node.absoluteBoundingBox as { width?: number; height?: number };
+      properties.width = bbox?.width;
+      properties.height = bbox?.height;
+    }
+
+    // Fills (background colors)
+    if ('fills' in node && Array.isArray(node.fills)) {
+      properties.fills = (node.fills as FigmaFill[]).filter((f) => f.visible !== false);
+    }
+
+    // Strokes (borders)
+    if ('strokes' in node && Array.isArray(node.strokes)) {
+      properties.strokes = (node.strokes as FigmaStroke[]).filter((s) => s.visible !== false);
+    }
+    if ('strokeWeight' in node) {
+      properties.strokeWeight = node.strokeWeight as number;
+    }
+    if ('strokeAlign' in node) {
+      properties.strokeAlign = node.strokeAlign as 'INSIDE' | 'CENTER' | 'OUTSIDE';
+    }
+
+    // Corner radius
+    if ('cornerRadius' in node) {
+      properties.cornerRadius = node.cornerRadius as number;
+    }
+    if ('topLeftRadius' in node) {
+      properties.topLeftRadius = node.topLeftRadius as number;
+    }
+    if ('topRightRadius' in node) {
+      properties.topRightRadius = node.topRightRadius as number;
+    }
+    if ('bottomLeftRadius' in node) {
+      properties.bottomLeftRadius = node.bottomLeftRadius as number;
+    }
+    if ('bottomRightRadius' in node) {
+      properties.bottomRightRadius = node.bottomRightRadius as number;
+    }
+
+    // Effects (shadows, blur)
+    if ('effects' in node && Array.isArray(node.effects)) {
+      properties.effects = (node.effects as FigmaEffect[]).filter((e) => e.visible !== false);
+    }
+
+    // Typography (for text nodes)
+    if (node.type === 'TEXT') {
+      const fontName = node.fontName as { family?: string; style?: string } | undefined;
+      const fontSize = node.fontSize as number | undefined;
+      const lineHeight = node.lineHeight as { value?: number; unit?: 'PIXELS' | 'PERCENT' | 'AUTO' } | undefined;
+      const letterSpacing = node.letterSpacing as number | undefined;
+      const textAlignHorizontal = node.textAlignHorizontal as 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED' | undefined;
+
+      if (fontName && fontSize) {
+        properties.typography = {
+          fontFamily: fontName.family || 'sans-serif',
+          fontStyle: fontName.style || 'Regular',
+          fontSize,
+          lineHeight: lineHeight ? { value: lineHeight.value || 0, unit: lineHeight.unit || 'AUTO' } : undefined,
+          letterSpacing,
+          textAlignHorizontal,
+        };
+      }
+    }
+
+    // Auto-layout padding
+    if ('paddingTop' in node || 'paddingRight' in node || 'paddingBottom' in node || 'paddingLeft' in node) {
+      properties.padding = {
+        top: node.paddingTop as number | undefined,
+        right: node.paddingRight as number | undefined,
+        bottom: node.paddingBottom as number | undefined,
+        left: node.paddingLeft as number | undefined,
+      };
+    }
+    if ('itemSpacing' in node) {
+      properties.itemSpacing = node.itemSpacing as number;
+    }
+
+    // Opacity
+    if ('opacity' in node) {
+      properties.opacity = node.opacity as number;
+    }
+
+    return properties;
+  }
+
+  /**
+   * Convert Figma design properties to CSS-formatted values.
+   */
+  convertToCSS(props: FigmaDesignProperties): CSSDesignProperties {
+    const css: CSSDesignProperties = {};
+
+    // Background color (first visible solid fill)
+    if (props.fills && props.fills.length > 0) {
+      const solidFill = props.fills.find(
+        (f) => f.type === 'SOLID' && f.color && f.visible !== false
+      );
+      if (solidFill?.color) {
+        css.backgroundColor = this.colorToCSS(solidFill.color, solidFill.opacity);
+      }
+    }
+
+    // Border color (first visible solid stroke)
+    if (props.strokes && props.strokes.length > 0) {
+      const solidStroke = props.strokes.find(
+        (s) => s.type === 'SOLID' && s.color && s.visible !== false
+      );
+      if (solidStroke?.color) {
+        css.borderColor = this.colorToCSS(solidStroke.color, solidStroke.opacity);
+      }
+    }
+
+    // Border width
+    if (props.strokeWeight !== undefined) {
+      css.borderWidth = `${props.strokeWeight}px`;
+    }
+
+    // Border radius
+    if (props.cornerRadius !== undefined) {
+      css.borderRadius = `${props.cornerRadius}px`;
+    } else if (
+      props.topLeftRadius !== undefined ||
+      props.topRightRadius !== undefined ||
+      props.bottomRightRadius !== undefined ||
+      props.bottomLeftRadius !== undefined
+    ) {
+      css.borderRadius = `${props.topLeftRadius || 0}px ${props.topRightRadius || 0}px ${props.bottomRightRadius || 0}px ${props.bottomLeftRadius || 0}px`;
+    }
+
+    // Box shadow (visible drop shadows only)
+    if (props.effects && props.effects.length > 0) {
+      const shadows = props.effects
+        .filter(
+          (e) =>
+            e.type === 'DROP_SHADOW' &&
+            e.color &&
+            e.offset &&
+            e.visible !== false
+        )
+        .map((e) => {
+          const color = this.colorToCSS(e.color!, 1);
+          const x = e.offset?.x || 0;
+          const y = e.offset?.y || 0;
+          const blur = e.radius || 0;
+          const spread = e.spread || 0;
+          return `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+        });
+
+      if (shadows.length > 0) {
+        css.boxShadow = shadows.join(', ');
+      }
+    }
+
+    // Typography
+    if (props.typography) {
+      css.fontFamily = props.typography.fontFamily;
+      css.fontSize = `${props.typography.fontSize}px`;
+
+      // Map font style to weight
+      const styleToWeight: Record<string, string> = {
+        Thin: '100',
+        ExtraLight: '200',
+        Light: '300',
+        Regular: '400',
+        Medium: '500',
+        SemiBold: '600',
+        Bold: '700',
+        ExtraBold: '800',
+        Black: '900',
+      };
+      css.fontWeight = styleToWeight[props.typography.fontStyle] || '400';
+
+      if (props.typography.lineHeight) {
+        if (props.typography.lineHeight.unit === 'PIXELS') {
+          css.lineHeight = `${props.typography.lineHeight.value}px`;
+        } else if (props.typography.lineHeight.unit === 'PERCENT') {
+          css.lineHeight = `${props.typography.lineHeight.value}%`;
+        }
+      }
+
+      if (props.typography.letterSpacing !== undefined) {
+        css.letterSpacing = `${props.typography.letterSpacing}px`;
+      }
+
+      if (props.typography.textAlignHorizontal) {
+        css.textAlign = props.typography.textAlignHorizontal.toLowerCase();
+      }
+    }
+
+    // Padding
+    if (props.padding) {
+      const { top = 0, right = 0, bottom = 0, left = 0 } = props.padding;
+      if (top === right && right === bottom && bottom === left) {
+        css.padding = `${top}px`;
+      } else if (top === bottom && left === right) {
+        css.padding = `${top}px ${right}px`;
+      } else {
+        css.padding = `${top}px ${right}px ${bottom}px ${left}px`;
+      }
+    }
+
+    // Gap
+    if (props.itemSpacing !== undefined) {
+      css.gap = `${props.itemSpacing}px`;
+    }
+
+    // Opacity
+    if (props.opacity !== undefined && props.opacity !== 1) {
+      css.opacity = props.opacity.toFixed(2);
+    }
+
+    // Dimensions
+    if (props.width !== undefined) {
+      css.width = `${Math.round(props.width)}px`;
+    }
+    if (props.height !== undefined) {
+      css.height = `${Math.round(props.height)}px`;
+    }
+
+    return css;
+  }
+
+  /**
+   * Convert Figma RGBA color (0-1 range) to CSS rgba() string.
+   */
+  colorToCSS(color: FigmaColor, opacity?: number): string {
+    const r = Math.round(color.r * 255);
+    const g = Math.round(color.g * 255);
+    const b = Math.round(color.b * 255);
+    const a = opacity !== undefined ? opacity * color.a : color.a;
+
+    if (a === 1) {
+      // Use hex for fully opaque colors
+      return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+    }
+
+    return `rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})`;
+  }
+
+  /**
+   * Fetch image URL from Figma API
+   */
+  private async fetchImageUrl(
+    fileKey: string,
+    nodeId: string,
+    scale: number,
+    format: string
+  ): Promise<string> {
+    // Figma API expects node IDs with colons, but URLs may use dashes
+    // Both formats should work, but let's normalize to what Figma expects
+    const apiNodeId = nodeId.replace(/-/g, ':');
+
+    const apiUrl = new URL(`https://api.figma.com/v1/images/${fileKey}`);
+    apiUrl.searchParams.set('ids', apiNodeId);
+    apiUrl.searchParams.set('scale', scale.toString());
+    apiUrl.searchParams.set('format', format);
+
+    const response = await fetch(apiUrl.toString(), {
+      headers: {
+        'X-Figma-Token': this.accessToken,
+      },
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'Unknown error');
+
+      if (response.status === 403) {
+        throw new FigmaError(
+          'Figma access denied',
+          'ACCESS_DENIED',
+          'Check your access token and ensure the file is shared with you'
+        );
+      }
+
+      if (response.status === 404) {
+        throw new FigmaError(
+          `Figma file or node not found: ${fileKey}/${nodeId}`,
+          'NOT_FOUND',
+          'Verify the file key and node ID are correct'
+        );
+      }
+
+      throw new FigmaError(
+        `Figma API error (${response.status}): ${errorBody}`,
+        'API_ERROR'
+      );
+    }
+
+    const data = await response.json() as {
+      images: Record<string, string | null>;
+      err?: string;
+    };
+
+    if (data.err) {
+      throw new FigmaError(
+        `Figma API error: ${data.err}`,
+        'API_ERROR'
+      );
+    }
+
+    // The images object uses the node ID as key
+    const imageUrl = data.images[apiNodeId];
+
+    if (!imageUrl) {
+      throw new FigmaError(
+        `No image returned for node ${nodeId}`,
+        'NO_IMAGE',
+        'The node may not be exportable or may be empty'
+      );
+    }
+
+    return imageUrl;
+  }
+
+  /**
+   * Download image from CDN URL
+   */
+  private async downloadImage(url: string): Promise<Buffer> {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new FigmaError(
+        `Failed to download Figma image: ${response.status}`,
+        'DOWNLOAD_ERROR',
+        'The CDN URL may have expired. Try again.'
+      );
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+}
+
+/**
+ * Error class for Figma-related errors
+ */
+export class FigmaError extends ServiceError {
+  constructor(message: string, code: string, suggestion?: string) {
+    super(message, code, suggestion);
+    this.name = `${BRAND.name}FigmaError`;
+  }
+}
+
+/**
+ * Create a FigmaClient instance
+ */
+export function createFigmaClient(accessToken: string): FigmaClient {
+  return new FigmaClient({ accessToken });
+}