figma-code-agent 1.0.0

package/knowledge/plugin-best-practices.md

@@ -0,0 +1,1206 @@
+# Figma Plugin Best Practices
+
+## Purpose
+
+Production-hardened best practices for Figma plugin development — covering error handling, performance optimization, memory management, caching strategies, async patterns, testing and debugging, and plugin distribution. These patterns are extracted from a production Figma plugin that extracts designs and generates HTML/CSS code. For plugin architecture patterns (project structure, IPC, data flow), see `plugin-architecture.md`. For the Plugin API reference, see `figma-api-plugin.md`.
+
+## When to Use
+
+Reference this module when you need to:
+
+- Implement robust error handling with structured error types and IPC propagation
+- Optimize plugin performance for large Figma files (1000+ elements)
+- Manage memory effectively when processing complex node trees
+- Cache Figma API results (variables, fonts, component references) to reduce repeated calls
+- Write correct async code with Figma's async APIs (getNodeByIdAsync, loadFontAsync, exportAsync)
+- Test and debug plugin logic without the Figma runtime environment
+- Prepare a plugin for publishing (permissions, manifest, versioning)
+
+---
+
+## Content
+
+### 1. Error Handling Patterns
+
+Reliable error handling is the difference between a plugin that users trust and one they abandon. Every error in a Figma plugin falls into one of three categories: validation errors (bad input), processing errors (extraction/generation failures), and infrastructure errors (Figma API failures).
+
+#### Structured Error Types
+
+Define error data that the UI can display and act upon. A structured error includes a machine-readable code, a human-readable message, and optional technical details:
+
+```ts
+// Error code enum — one code per failure category
+export const ERROR_CODES = {
+  NO_SELECTION: 'NO_SELECTION',
+  INVALID_NODE: 'INVALID_NODE',
+  EXTRACTION_FAILED: 'EXTRACTION_FAILED',
+  GENERATION_FAILED: 'GENERATION_FAILED',
+  EXPORT_FAILED: 'EXPORT_FAILED',
+  THUMBNAIL_FAILED: 'THUMBNAIL_FAILED',
+} as const;
+
+export type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+
+// Structured error data for UI display
+export interface ErrorData {
+  code: ErrorCode;
+  message: string;      // User-facing message (non-technical)
+  details?: string;     // Technical details (from caught exception)
+}
+```
+
+Why codes instead of just messages:
+- The UI can show different recovery actions per error code
+- Error codes are stable across refactors (messages can change)
+- Logging and analytics can aggregate by code
+- Localization can map codes to translated messages
+
+#### Error Propagation Across IPC
+
+Errors originating in the main thread must be propagated to the UI thread through IPC. Use a centralized `emitError` helper so every error follows the same pattern:
+
+```ts
+import { emit } from '@create-figma-plugin/utilities';
+
+function emitError(code: ErrorData['code'], message: string, error?: unknown): void {
+  const details = error instanceof Error
+    ? error.message
+    : error ? String(error) : undefined;
+
+  // Always log to console for developer debugging
+  console.error(`[Error] ${code}: ${message}`, details || '');
+
+  // Emit structured error to UI
+  emit<ErrorHandler>(EVENTS.ERROR, { code, message, details });
+}
+```
+
+Benefits of a centralized helper:
+- Console logging is automatic (developers see errors during development)
+- Error structure is consistent (UI can always expect the same shape)
+- Unknown error types are safely converted to strings
+- The `code` field enables the UI to show contextual recovery suggestions
+
+#### Try/Catch Placement
+
+Wrap the entire body of each IPC event handler in a single try/catch. Do NOT wrap individual operations within a handler — that fragments error handling and makes it easy to miss paths:
+
+```ts
+// GOOD: Single try/catch per handler
+on<ExtractFrameHandler>(EVENTS.EXTRACT_FRAME, async (nodeId: string) => {
+  try {
+    const node = await figma.getNodeByIdAsync(nodeId);
+    if (!node) {
+      emitError(ERROR_CODES.INVALID_NODE, 'Node not found. It may have been deleted.');
+      return;
+    }
+    if (!('children' in node)) {
+      emitError(ERROR_CODES.INVALID_NODE, 'Selected node is not a frame or group.');
+      return;
+    }
+
+    const extracted = await extractNodeTree(node as SceneNode);
+    emit<FrameExtractedHandler>(EVENTS.FRAME_EXTRACTED, extracted);
+  } catch (error) {
+    emitError(ERROR_CODES.EXTRACTION_FAILED, 'Failed to extract frame data.', error);
+  }
+});
+
+// BAD: Multiple try/catch blocks per handler
+on<ExtractFrameHandler>(EVENTS.EXTRACT_FRAME, async (nodeId: string) => {
+  let node;
+  try {
+    node = await figma.getNodeByIdAsync(nodeId);
+  } catch (e) {
+    emitError(ERROR_CODES.INVALID_NODE, 'Node lookup failed.', e);
+    return;
+  }
+  let extracted;
+  try {
+    extracted = await extractNodeTree(node as SceneNode);
+  } catch (e) {
+    emitError(ERROR_CODES.EXTRACTION_FAILED, 'Extraction failed.', e);
+    return;
+  }
+  // ... more fragmented try/catch blocks
+});
+```
+
+The exception to this rule is operations where you want to skip a failure and continue (e.g., asset export for individual files where one failure should not block others).
+
+#### Graceful Degradation
+
+When processing a tree of nodes, skip unsupported or problematic nodes rather than failing the entire operation:
+
+```ts
+// Asset export: skip failures, continue with remaining assets
+for (let i = 0; i < nodesWithAssets.length; i++) {
+  const assetNode = nodesWithAssets[i];
+  try {
+    const data = await exportAsset(assetNode.id, format);
+    assets.push({ filename, data, mimeType });
+  } catch (error) {
+    // Log but continue with other assets
+    console.warn(`[Export] Failed to export asset "${assetNode.name}":`, error);
+  }
+}
+
+// Thumbnail generation: add placeholder on failure
+try {
+  const bytes = await node.exportAsync({ format: 'PNG', constraint: { type: 'WIDTH', value: 200 } });
+  thumbnails.push({ id: nodeId, name: node.name, thumbnail: base64Data });
+} catch (error) {
+  console.error('[Thumbnails] Failed for node:', nodeId, error);
+  // Still include the frame with empty thumbnail — UI shows placeholder
+  thumbnails.push({ id: nodeId, name: node.name, thumbnail: '' });
+}
+```
+
+#### UI Error Display and Recovery
+
+On the UI side, handle error events by showing actionable messages with recovery options:
+
+```tsx
+on<ErrorHandler>(EVENTS.ERROR, (error: ErrorData) => {
+  setError(error);
+});
+
+function ErrorState({ error, onRetry }: { error: ErrorData; onRetry?: () => void }) {
+  const recoveryHint = getRecoveryHint(error.code);
+
+  return (
+    <Container space="medium">
+      <Text style="bold">{error.message}</Text>
+      {recoveryHint && <Text style="muted">{recoveryHint}</Text>}
+      {error.details && <Text style="code">{error.details}</Text>}
+      {onRetry && <Button onClick={onRetry}>Retry</Button>}
+    </Container>
+  );
+}
+
+function getRecoveryHint(code: ErrorCode): string | null {
+  switch (code) {
+    case 'NO_SELECTION':
+      return 'Select a frame or component in the Figma canvas.';
+    case 'INVALID_NODE':
+      return 'Select a frame, component, or group — not a page or individual shape.';
+    case 'EXTRACTION_FAILED':
+      return 'The design may be too complex. Try selecting a smaller section.';
+    case 'EXPORT_FAILED':
+      return 'Export failed. Try again or check if any images are missing.';
+    default:
+      return null;
+  }
+}
+```
+
+---
+
+### 2. Performance Patterns
+
+Performance is critical for plugin adoption. A plugin that freezes Figma for 5 seconds on every interaction will be uninstalled immediately. The key insight: the extraction phase (reading Figma nodes) is the bottleneck, not generation (pure data transformation).
+
+#### Progress Tracking for Long Operations
+
+For any operation that processes more than ~100 nodes, report progress to the UI so users see that the plugin is working:
+
+```ts
+// Extraction statistics for performance monitoring
+export interface ExtractionStats {
+  elementCount: number;
+  maxDepthReached: number;
+  depthLimitHit: boolean;
+  extractionTimeMs: number;
+}
+
+// Internal mutable state during extraction
+interface ExtractionState {
+  elementCount: number;
+  maxDepthReached: number;
+  depthLimitHit: boolean;
+  onProgress?: (current: number, total: number) => void;
+  maxDepth: number;
+}
+
+// Emit progress every N elements
+if (state.onProgress && state.elementCount % 50 === 0) {
+  state.onProgress(state.elementCount, state.elementCount + 100); // Estimate total
+}
+```
+
+Wire progress to the UI through IPC:
+
+```ts
+const extracted = await extractNodeTree(node, {
+  onProgress: (current, total) => {
+    emit<ExtractionProgressHandler>(EVENTS.EXTRACTION_PROGRESS, {
+      current,
+      total,
+      phase: 'extracting',
+    });
+  },
+});
+```
+
+#### Pipeline Timing Instrumentation
+
+Log timing for each stage of the extraction-generation-export pipeline to identify bottlenecks:
+
+```ts
+// Extraction phase
+const extractStart = Date.now();
+const extracted = await extractNodeTree(node as SceneNode);
+const extractTime = Date.now() - extractStart;
+
+// Generation phase
+const genStart = Date.now();
+const output = await generateOutput(extracted, options);
+const genTime = Date.now() - genStart;
+
+const elementCount = countElements(extracted);
+console.log(
+  `[Pipeline] ${elementCount} elements: ` +
+  `extraction ${extractTime}ms, generation ${genTime}ms, ` +
+  `total ${extractTime + genTime}ms`
+);
+
+// Warn about large frames
+if (elementCount > 1000) {
+  console.warn(
+    `[Extraction] Large frame detected (${elementCount} elements). ` +
+    `Performance may be affected.`
+  );
+}
+```
+
+This instrumentation reveals where to invest optimization effort. In practice, extraction typically accounts for 60-80% of total time because it involves async Figma API calls, while generation is pure synchronous computation.
+
+#### Depth Limits on Recursive Traversal
+
+Cap tree traversal depth to prevent performance degradation on deeply nested designs. Figma designs rarely exceed 15-20 levels of nesting intentionally — deeper nesting usually indicates auto-layout structure rather than meaningful visual hierarchy:
+
+```ts
+const MAX_DEPTH = 30;
+
+async function extractNode(
+  node: SceneNode,
+  parent: SceneNode | null,
+  depth: number,
+  state: ExtractionState
+): Promise<ExtractedNode | null> {
+  // Check depth limit before recursing
+  if ('children' in node) {
+    if (depth >= state.maxDepth) {
+      state.depthLimitHit = true;
+      console.warn(
+        `[Extraction] Depth limit (${state.maxDepth}) reached at "${node.name}", ` +
+        `truncating ${node.children.length} children`
+      );
+      return extracted; // Return node without children
+    }
+
+    const visibleChildren = node.children.filter(child => child.visible);
+    extracted.children = await Promise.all(
+      visibleChildren.map(child => extractNode(child, node, depth + 1, state))
+    );
+  }
+
+  return extracted;
+}
+```
+
+A depth of 30 is a safe production default — it accommodates complex designs while preventing runaway recursion on pathological files.
+
+#### Batch Sequential Operations
+
+When processing children of a node, batch operations sequentially rather than firing all at once. Figma's API can handle some parallelism, but excessive concurrent calls can cause issues:
+
+```ts
+// GOOD: Process children with controlled parallelism
+const visibleChildren = containerNode.children.filter(child => child.visible);
+const childResults = await Promise.all(
+  visibleChildren.map(child => extractNode(child, node, depth + 1, state))
+);
+
+// GOOD: Sequential for Figma API calls that modify state
+for (const font of fontsToLoad) {
+  await figma.loadFontAsync(font);
+}
+
+// BAD: Unbounded parallelism on heavy Figma API operations
+const allExports = await Promise.all(
+  allNodes.map(node => node.exportAsync({ format: 'PNG' })) // Can overwhelm Figma
+);
+```
+
+For pure extraction (reading properties), parallel `Promise.all` on children is fine. For operations that involve I/O like `exportAsync`, process sequentially or in small batches.
+
+#### UI Responsiveness During Extraction
+
+The main thread shares execution time with Figma's renderer. Long synchronous operations block the UI. Use progress callbacks and chunked processing to keep the plugin responsive:
+
+```ts
+// Report progress periodically during traversal
+if (state.onProgress && state.elementCount % 50 === 0) {
+  state.onProgress(state.elementCount, state.elementCount + 100);
+}
+```
+
+For asset export (the slowest operation), log per-asset timing to help identify slow exports:
+
+```ts
+for (const asset of assets) {
+  const assetStartTime = Date.now();
+  const base64 = uint8ArrayToBase64(asset.data);
+  const assetTime = Date.now() - assetStartTime;
+  if (assetTime > 100) {
+    console.log(
+      `[Export] Base64 conversion: ${asset.filename} ` +
+      `(${asset.data.length} bytes) took ${assetTime}ms`
+    );
+  }
+}
+```
+
+#### Bundle Size Optimization
+
+Plugin load time affects perceived performance. The UI iframe must load all JavaScript before the plugin becomes interactive:
+
+| Library | Minified Size | Recommendation |
+|---------|:------------:|----------------|
+| Preact | ~4 KB | Use this for plugin UI |
+| React + ReactDOM | ~40 KB | Avoid — 10x larger than Preact |
+| CodeMirror (basic) | ~150 KB | Worth it for code editing features |
+| JSZip | ~100 KB | Load only when export is triggered |
+
+Optimization strategies:
+- Use Preact (not React) with `@create-figma-plugin/ui` components
+- Enable `--minify` in the build script (`build-figma-plugin --typecheck --minify`)
+- Tree shake unused modules by using named imports
+- Consider dynamic import for heavy libraries (CodeMirror, JSZip) loaded only when needed
+
+> **Cross-reference:** See `plugin-architecture.md` for the Preact vs React comparison and `@create-figma-plugin` build configuration.
+
+---
+
+### 3. Memory Management
+
+Figma plugins run in a constrained environment. The main thread sandbox has limited memory, and the IPC bridge can only transfer JSON-serializable data. Memory mismanagement causes crashes on large files.
+
+#### JSON-Serializable Intermediate Format
+
+The most critical architectural decision in any design-to-code plugin: the extraction stage must produce a **JSON-serializable** intermediate format. You cannot pass Figma `SceneNode` objects across the IPC boundary — they are live references to the document graph, not plain data.
+
+```ts
+// WRONG: Trying to pass Figma nodes to the UI
+figma.ui.postMessage({
+  type: 'NODE_DATA',
+  node: figma.currentPage.selection[0], // Fails — not serializable
+});
+
+// RIGHT: Extract to a plain data structure first
+export interface ExtractedNode {
+  id: string;
+  name: string;
+  type: string;
+  bounds: { x: number; y: number; width: number; height: number };
+  opacity: number;
+  visible: boolean;
+  layout?: LayoutProperties;
+  fills?: FillData[];
+  strokes?: StrokeData[];
+  effects?: EffectData[];
+  text?: TextData;
+  asset?: AssetData;
+  children?: ExtractedNode[];
+}
+
+// Extract first, then pass across IPC
+const extracted = await extractNodeTree(node);
+emit<FrameExtractedHandler>(EVENTS.FRAME_EXTRACTED, extracted);
+```
+
+This pattern also provides a clean separation between Figma API access (main thread only) and code generation (can run on either side).
+
+#### Selective Property Extraction
+
+Extract only the properties that your generation pipeline needs. Reading every property on every node wastes time and memory:
+
+```ts
+// GOOD: Extract only what generation needs
+const extracted: ExtractedNode = {
+  id: node.id,
+  name: node.name,
+  type: node.type,
+  bounds: {
+    x: Math.round(node.x),
+    y: Math.round(node.y),
+    width: Math.round(node.width),
+    height: Math.round(node.height),
+  },
+  opacity: 'opacity' in node ? node.opacity : 1,
+  visible: node.visible,
+};
+
+// Only extract layout if the node has Auto Layout
+const layout = await extractLayout(node);
+if (layout) extracted.layout = layout;
+
+// Only extract text if it's a TEXT node
+const text = await extractText(node);
+if (text) extracted.text = text;
+```
+
+Each domain extraction module (layout, visual, text, assets) runs independently and only populates its fields when relevant. Nodes that are plain rectangles with no special properties carry minimal extracted data.
+
+#### Asset Deduplication by Hash
+
+Figma files commonly reuse the same image across multiple nodes (a logo, avatar, pattern). Export each unique image once, not once per usage:
+
+```ts
+// Track already-exported imageHashes to avoid duplicates
+const exportedImageHashes = new Map<string, string>(); // imageHash -> filename
+
+for (const assetNode of nodesWithAssets) {
+  const imageHash = assetNode.asset!.imageHash;
+
+  // Skip duplicate image exports — same imageHash means same image
+  if (imageHash && exportedImageHashes.has(imageHash)) {
+    console.log(`[Export] Skipping duplicate image "${assetNode.name}" (same hash)`);
+    continue;
+  }
+
+  const data = await exportAsset(assetNode.id, format);
+  assets.push({ filename, data, mimeType });
+
+  // Track exported hash
+  if (imageHash) {
+    exportedImageHashes.set(imageHash, filename);
+  }
+}
+```
+
+The same deduplication applies to the asset map used by the generation pipeline:
+
+```ts
+// Build a map from node ID and imageHash to asset filename
+export function buildAssetMap(node: ExtractedNode): Map<string, string> {
+  const assetMap = new Map<string, string>();
+  const imageHashToFilename = new Map<string, string>();
+
+  for (const assetNode of nodesWithAssets) {
+    const imageHash = assetNode.asset!.imageHash;
+
+    // Reuse existing filename for same hash
+    if (imageHash && imageHashToFilename.has(imageHash)) {
+      assetMap.set(assetNode.id, imageHashToFilename.get(imageHash)!);
+      continue;
+    }
+
+    const filename = filenameTracker.getUnique(baseName, extension);
+    assetMap.set(assetNode.id, filename);
+
+    if (imageHash) {
+      assetMap.set(imageHash, filename);
+      imageHashToFilename.set(imageHash, filename);
+    }
+  }
+
+  return assetMap;
+}
+```
+
+#### Large File Handling
+
+For files with hundreds of frames or thousands of nodes, implement safeguards:
+
+- **Element count warnings:** Log warnings at thresholds (e.g., 1000+ elements) so developers know to optimize
+- **Depth limiting:** Cap recursion depth to prevent stack overflow (see Performance Patterns above)
+- **Pagination:** For multi-frame export, process frames sequentially rather than loading all into memory at once
+- **Asset budget:** Log asset count and total size estimates before starting export
+
+```ts
+// Pre-flight check before starting heavy export
+const elementCount = countElements(extracted);
+let assetCount = 0;
+const countAssets = (n: ExtractedNode) => {
+  if (n.asset) assetCount++;
+  n.children?.forEach(countAssets);
+};
+countAssets(extracted);
+
+console.log(`[Export] Pre-flight: ${elementCount} elements, ${assetCount} assets`);
+```
+
+#### Clean Up References
+
+Null out large cached data structures when they are no longer needed. Module-level caches in the main thread persist for the plugin's entire lifetime:
+
+```ts
+// Module-level variable cache
+let localVariableIds: Set<string> | null = null;
+
+// Clear when starting a new extraction run
+export function clearVariableCache(): void {
+  localVariableIds = null;
+}
+```
+
+---
+
+### 4. Caching Strategies
+
+Figma's async APIs have non-trivial overhead. Caching results of repeated calls dramatically improves performance, especially during tree traversal where the same information is needed for every node.
+
+#### Variable Cache (Lazy-Load Once, Reuse)
+
+The most impactful cache in a design-to-code plugin: loading local variables once and reusing the set for every node's variable bindings check:
+
+```ts
+// Cache for local variable IDs — populated once per extraction run
+let localVariableIds: Set<string> | null = null;
+
+async function isLocalVariable(variableId: string): Promise<boolean> {
+  if (localVariableIds === null) {
+    // Lazy-load: first call populates the cache
+    try {
+      const localVars = await figma.variables.getLocalVariablesAsync();
+      localVariableIds = new Set(localVars.map(v => v.id));
+    } catch {
+      localVariableIds = new Set();
+    }
+  }
+  return localVariableIds.has(variableId);
+}
+```
+
+Without this cache, every fill/stroke/effect extraction that checks for variable bindings would call `getLocalVariablesAsync()` — a slow async operation. With the cache, the first node pays the cost and all subsequent nodes get an O(1) Set lookup.
+
+#### Font Loading Cache
+
+Font loading is required before text node modification but not before text node reading during extraction. For operations that modify text nodes (like bidirectional sync), cache already-loaded fonts:
+
+```ts
+const loadedFonts = new Set<string>();
+
+async function ensureFontLoaded(fontName: FontName): Promise<void> {
+  const key = `${fontName.family}-${fontName.style}`;
+  if (loadedFonts.has(key)) return;
+
+  await figma.loadFontAsync(fontName);
+  loadedFonts.add(key);
+}
+
+// Usage in text sync handler
+if (textNode.fontName === figma.mixed) {
+  const len = textNode.characters.length;
+  for (let i = 0; i < len; i++) {
+    const font = textNode.getRangeFontName(i, i + 1) as FontName;
+    await ensureFontLoaded(font);
+  }
+} else {
+  await ensureFontLoaded(textNode.fontName as FontName);
+}
+```
+
+#### Component Reference Cache
+
+When processing instances, cache the mapping from component IDs to component names to avoid repeated `getMainComponentAsync()` calls:
+
+```ts
+const componentNameCache = new Map<string, string>();
+
+async function getComponentName(instance: InstanceNode): Promise<string | null> {
+  const mainComponent = instance.mainComponent;
+  if (!mainComponent) return null;
+
+  const cached = componentNameCache.get(mainComponent.id);
+  if (cached) return cached;
+
+  componentNameCache.set(mainComponent.id, mainComponent.name);
+  return mainComponent.name;
+}
+```
+
+#### Cache Invalidation
+
+Caches must be invalidated when the underlying data changes:
+
+| Cache | Invalidation Trigger | Strategy |
+|-------|---------------------|----------|
+| Variable IDs | New extraction run | Clear at extraction start |
+| Loaded fonts | Never (fonts don't change) | Persist for plugin lifetime |
+| Component names | Page change | Clear on `currentpagechange` |
+| Extracted node data | Selection change | Clear and re-extract |
+| Asset map | New extraction run | Rebuild per extraction |
+
+```ts
+// Clear caches on page change
+figma.on('currentpagechange', () => {
+  componentNameCache.clear();
+  clearVariableCache();
+});
+```
+
+#### Session vs Persistent Caching
+
+Two storage mechanisms are available for caching:
+
+**Session-scoped (module-level variables):**
+- Lives in memory for the plugin's lifetime
+- Lost when plugin is closed
+- Use for: variable IDs, font caches, component names, extracted data
+
+**Persistent (`figma.clientStorage`):**
+- Survives plugin restarts
+- Local to user's machine and plugin ID
+- Use for: user preferences, export settings, component mapping configs
+
+```ts
+// Persistent: User settings survive restarts
+const SETTINGS_KEY = 'pluginSettings';
+await figma.clientStorage.setAsync(SETTINGS_KEY, settings);
+const settings = await figma.clientStorage.getAsync(SETTINGS_KEY);
+
+// Persistent: Clear all stored data
+const keys = await figma.clientStorage.keysAsync();
+for (const key of keys) {
+  await figma.clientStorage.deleteAsync(key);
+}
+```
+
+**Node-level (`pluginData`):**
+- Stored on individual Figma nodes
+- Persists with the file, visible only to your plugin
+- Use for: per-node metadata, export markers, last-generated state
+
+```ts
+// Store export metadata on a node
+node.setPluginData('lastExport', JSON.stringify({ timestamp: Date.now(), format: 'html' }));
+const meta = JSON.parse(node.getPluginData('lastExport') || 'null');
+```
+
+---
+
+### 5. Async Patterns
+
+Figma's Plugin API is heavily async. The most common plugin bugs come from incorrect async handling — using sync methods in dynamic-page plugins, forgetting to load fonts, or not handling timeouts.
+
+#### getNodeByIdAsync for Dynamic-Page Plugins
+
+All new plugins must use `documentAccess: "dynamic-page"`. This means pages load on demand and node access is async:
+
+```ts
+// CORRECT: Async node access (required for dynamic-page)
+const node = await figma.getNodeByIdAsync(nodeId);
+
+// WRONG: Sync access (deprecated, fails with dynamic-page)
+const node = figma.getNodeById(nodeId); // Don't use this
+```
+
+Always null-check the result — nodes can be deleted, on unloaded pages, or invalid:
+
+```ts
+const node = await figma.getNodeByIdAsync(nodeId);
+if (!node) {
+  emitError(ERROR_CODES.INVALID_NODE, 'Node not found. It may have been deleted.');
+  return;
+}
+```
+
+#### loadFontAsync Before Text Modifications
+
+Font loading is **mandatory** before modifying text node content or style properties. Reading text content (during extraction) does not require font loading:
+
+```ts
+// Reading text — NO font loading needed
+const content = textNode.characters; // Works without loading fonts
+const fontSize = textNode.fontSize;  // Works without loading fonts
+
+// Modifying text — MUST load fonts first
+await figma.loadFontAsync(textNode.fontName as FontName);
+textNode.characters = 'New text'; // Throws if font not loaded
+
+// Mixed fonts — must load each font range
+if (textNode.fontName === figma.mixed) {
+  const len = textNode.characters.length;
+  const loaded = new Set<string>();
+  for (let i = 0; i < len; i++) {
+    const font = textNode.getRangeFontName(i, i + 1) as FontName;
+    const key = `${font.family}-${font.style}`;
+    if (!loaded.has(key)) {
+      loaded.add(key);
+      await figma.loadFontAsync(font);
+    }
+  }
+}
+```
+
+#### exportAsync for Images and SVGs
+
+`exportAsync()` is the most time-consuming Figma API call. Use it carefully:
+
+```ts
+// PNG/JPG export with retina scaling
+const pngBytes = await node.exportAsync({
+  format: 'PNG',
+  constraint: { type: 'SCALE', value: 2 }, // 2x for retina
+});
+
+// SVG export (vector-native, no scaling needed)
+const svgBytes = await node.exportAsync({ format: 'SVG' });
+
+// Thumbnail export with fixed width (consistent quality)
+const thumbBytes = await node.exportAsync({
+  format: 'PNG',
+  constraint: { type: 'WIDTH', value: 200 },
+});
+```
+
+For image fills, prefer exporting from Figma's image store directly to get original quality:
+
+```ts
+async function exportImageByHash(imageHash: string): Promise<Uint8Array> {
+  const image = figma.getImageByHash(imageHash);
+  if (!image) throw new Error(`Image not found: ${imageHash}`);
+  return image.getBytesAsync();
+}
+```
+
+#### Timeout Handling for Long Operations
+
+Wrap long-running operations with timeouts to prevent the plugin from appearing frozen:
+
+```ts
+const EXPORT_TIMEOUT_MS = 10000;
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Export timeout after ${ms}ms for: ${label}`));
+    }, ms);
+
+    promise
+      .then((result) => {
+        clearTimeout(timer);
+        resolve(result);
+      })
+      .catch((error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+  });
+}
+
+// Usage
+const svgData = await withTimeout(
+  node.exportAsync({ format: 'SVG' }),
+  EXPORT_TIMEOUT_MS,
+  `SVG export of "${node.name}"`
+);
+```
+
+> **Note:** The main thread sandbox does not have `setTimeout`. This `withTimeout` pattern works because the timer is created inside a Promise executor, using the Promise-based timing that the sandbox does support. For codegen plugins, the 3-second hard timeout set by Figma itself is the limiting factor — see `plugin-codegen.md`.
+
+#### Sequential vs Parallel Async
+
+Use this decision guide for async patterns:
+
+| Operation | Strategy | Why |
+|-----------|:--------:|-----|
+| Extract child node properties | Parallel (`Promise.all`) | Read-only, no contention |
+| Export multiple assets | Sequential (for loop) | Each `exportAsync` is heavy, avoids overwhelming Figma |
+| Load multiple fonts | Sequential (for loop) | Font loading can fail if too many concurrent |
+| Process multiple frames | Sequential (for loop) | Each frame extraction is memory-intensive |
+| Generate code from extracted data | Synchronous | Pure data transformation, no async needed |
+
+```ts
+// Parallel: extracting children (read-only, safe)
+const childResults = await Promise.all(
+  visibleChildren.map(child => extractNode(child, node, depth + 1, state))
+);
+
+// Sequential: exporting assets (heavy I/O, one at a time)
+for (const assetNode of nodesWithAssets) {
+  const data = await exportAsset(assetNode.id, format);
+  assets.push({ filename, data, mimeType });
+}
+```
+
+#### Cancellation Patterns
+
+For long-running operations, check whether the plugin is still active before continuing:
+
+```ts
+// Check if plugin was closed during a long operation
+let pluginActive = true;
+figma.on('close', () => { pluginActive = false; });
+
+async function extractLargeTree(root: SceneNode): Promise<ExtractedNode> {
+  for (const child of root.children) {
+    if (!pluginActive) {
+      console.log('[Extraction] Plugin closed, aborting');
+      throw new Error('Plugin closed during extraction');
+    }
+    await extractNode(child);
+  }
+}
+```
+
+---
+
+### 6. Testing and Debugging
+
+Plugin code is challenging to test because extraction modules depend on the Figma API runtime. The key strategy: isolate Figma API calls to a thin extraction layer and make everything else pure functions on plain data.
+
+#### Console Logging Strategy
+
+Use prefixed, structured console logging throughout the plugin for debugging:
+
+```ts
+// Good: prefixed, contextual, with relevant data
+console.log('[Extraction] 450 elements in 234ms');
+console.log('[Export] Processing asset 3/12: "hero-image" as PNG');
+console.log('[Settings] Saved settings to client storage');
+console.warn('[Extraction] Depth limit (30) reached at "deeply-nested-frame"');
+console.error('[Export] Failed to export asset "broken-image":', error);
+
+// Bad: unprefixed, no context
+console.log('done');
+console.log(node.name);
+console.log('error', e);
+```
+
+Use consistent prefixes per domain:
+- `[Extraction]` — Node tree traversal and property extraction
+- `[Generation]` — HTML/CSS code generation
+- `[Export]` — Asset export and bundle preparation
+- `[Settings]` — Settings persistence
+- `[TextSync]` — Bidirectional text sync
+- `[LayoutSync]` — Bidirectional layout sync
+- `[Cache]` — Cache operations
+- `[Thumbnails]` — Thumbnail generation
+- `[Error]` — Error propagation
+- `[Pipeline]` — Overall pipeline timing
+- `[Variants]` — Component variant resolution
+
+#### Code Validation
+
+Validate generated HTML and CSS before displaying to users. Broken output erodes trust:
+
+```ts
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  sanitizedCode: string;
+}
+
+// HTML validation: tag structure, bracket matching, script removal
+function validateHTML(html: string): ValidationResult {
+  const errors: ValidationError[] = [];
+  let sanitized = html;
+
+  sanitized = removeJavaScript(sanitized, errors);  // Security
+  validateTagStructure(sanitized, errors);           // Unclosed tags
+  validateBrackets(sanitized, errors);               // Quote matching
+
+  return { valid: errors.filter(e => e.type === 'error').length === 0, errors, sanitizedCode: sanitized };
+}
+
+// CSS validation: bracket matching, property syntax, JS removal
+function validateCSS(css: string): ValidationResult {
+  const errors: ValidationError[] = [];
+  let sanitized = css;
+
+  sanitized = removeJSFromCSS(sanitized, errors);   // Security
+  validateCSSBrackets(sanitized, errors);            // Brace matching
+  validateCSSProperties(sanitized, errors);          // Semicolons, colons
+
+  return { valid: errors.filter(e => e.type === 'error').length === 0, errors, sanitizedCode: sanitized };
+}
+```
+
+Always strip JavaScript from generated output for security — generated HTML should never contain executable code:
+
+```ts
+function removeJavaScript(html: string, errors: ValidationError[]): string {
+  let result = html;
+  // Remove <script> tags
+  result = result.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+  // Remove inline event handlers (onclick, onerror, etc.)
+  result = result.replace(/\s(on\w+)=["'][^"']*["']/gi, '');
+  // Remove javascript: URLs
+  result = result.replace(/href=["']javascript:[^"']*["']/gi, 'href="#"');
+  return result;
+}
+```
+
+> **Cross-reference:** See `plugin-codegen.md` for code quality patterns specific to codegen plugins (HTML validation, CSS validation, formatting).
+
+#### Mock Data for UI Development
+
+Develop and test the plugin UI independently of the Figma runtime by creating mock data fixtures:
+
+```ts
+// test/fixtures/mock-extracted.ts
+export const mockExtractedFrame: ExtractedNode = {
+  id: '1:100',
+  name: 'Hero Section',
+  type: 'FRAME',
+  bounds: { x: 0, y: 0, width: 1440, height: 600 },
+  opacity: 1,
+  visible: true,
+  layout: {
+    mode: 'FLEX_COLUMN',
+    gap: 24,
+    padding: { top: 48, right: 64, bottom: 48, left: 64 },
+    primaryAlign: 'CENTER',
+    crossAlign: 'CENTER',
+  },
+  children: [
+    {
+      id: '1:101',
+      name: 'Title',
+      type: 'TEXT',
+      bounds: { x: 0, y: 0, width: 800, height: 48 },
+      opacity: 1,
+      visible: true,
+      text: {
+        content: 'Welcome to Our Platform',
+        font: { family: 'Inter', style: 'Bold', size: 48, weight: 700 },
+      },
+    },
+    // ... more mock children
+  ],
+};
+```
+
+Use these fixtures for:
+- UI component development (render with mock data, no Figma needed)
+- Unit tests for generation modules
+- Visual regression testing of generated HTML output
+- Developing export features offline
+
+#### Testing Pure Generation Functions
+
+The generation pipeline operates on `ExtractedNode` data, not Figma API objects. This makes it fully testable with standard test frameworks:
+
+```ts
+// generation/layout.test.ts
+import { describe, it, expect } from 'vitest';
+import { generateLayoutStyles } from './layout';
+
+describe('generateLayoutStyles', () => {
+  it('generates flex-direction: row for horizontal layout', () => {
+    const node = {
+      layout: {
+        mode: 'FLEX_ROW',
+        gap: 8,
+        padding: { top: 0, right: 0, bottom: 0, left: 0 },
+      },
+    };
+    const styles = generateLayoutStyles(node);
+    expect(styles.display).toBe('flex');
+    expect(styles.flexDirection).toBe('row');
+    expect(styles.gap).toBe('8px');
+  });
+
+  it('generates flex-wrap for wrapping layouts', () => {
+    const node = {
+      layout: { mode: 'FLEX_ROW', wrap: true, gap: 16 },
+    };
+    const styles = generateLayoutStyles(node);
+    expect(styles.flexWrap).toBe('wrap');
+  });
+});
+```
+
+#### Edge Case Handling
+
+Common edge cases that cause plugin crashes or incorrect output:
+
+| Edge Case | Symptom | Defense |
+|-----------|---------|--------|
+| Empty selection | `figma.currentPage.selection` is `[]` | Check length before processing |
+| Text without fonts loaded | `fontName === figma.mixed` | Handle mixed fonts with range iteration |
+| Zero-size frames | `width: 0, height: 0` | Filter out or skip in generation |
+| SLICE nodes | Not renderable, no visual output | Skip during traversal (`node.type === 'SLICE'`) |
+| Invisible nodes | `visible: false` | Filter during extraction |
+| Detached instances | `instance.mainComponent` is `null` | Null-check before accessing component |
+| Deeply nested groups | 50+ levels of nesting | Depth limit (MAX_DEPTH = 30) |
+| Deleted nodes | `getNodeByIdAsync` returns `null` | Null-check after every async lookup |
+| Stale selection | Node deleted after selection event | Re-validate before processing |
+| Missing image fills | Image removed from library | Try/catch around image export |
+
+```ts
+// SLICE node handling in traversal
+if (node.type === 'SLICE') {
+  return null; // Skip entirely — SLICE nodes are export regions, not visual elements
+}
+
+// Zero-size frame handling
+if (node.width === 0 || node.height === 0) {
+  console.warn(`[Extraction] Skipping zero-size node: "${node.name}"`);
+  return null;
+}
+
+// Detached instance handling
+if (node.type === 'INSTANCE') {
+  const mainComponent = instance.mainComponent;
+  if (!mainComponent) {
+    console.warn(`[Extraction] Detached instance: "${instance.name}"`);
+    // Continue extraction without component reference
+  }
+}
+```
+
+#### Common Pitfalls Checklist
+
+Before publishing, verify your plugin handles these scenarios:
+
+1. **Accessing node after deletion** — Always use `getNodeByIdAsync` and null-check the result
+2. **Font not loaded before text modification** — Call `loadFontAsync` before setting `characters`
+3. **Stale selection data** — Re-fetch selection on each operation, do not cache selection state
+4. **Sync API in dynamic-page plugin** — Use async variants (`getNodeByIdAsync`, not `getNodeById`)
+5. **Binary data across IPC** — Convert `Uint8Array` to base64 string before `postMessage`
+6. **Missing `figma.mixed` handling** — Properties like `fontName`, `cornerRadius`, `fills` can be `figma.mixed`
+7. **Module-level cache leaks** — Clear caches between extraction runs or on page change
+8. **Unbounded `findAll()` calls** — Never call `figma.root.findAll()` on large files; scope to current page or selected subtree
+9. **Unhandled promise rejections** — Wrap every async handler in try/catch
+10. **Plugin close during async operation** — Check `pluginActive` flag in long operations
+
+---
+
+### 7. Plugin Distribution
+
+Preparing a plugin for publishing requires attention to manifest metadata, permissions, and version management.
+
+#### Manifest Metadata
+
+For `@create-figma-plugin` projects, metadata is configured in the `figma-plugin` section of `package.json`. For manual projects, it goes in `manifest.json`:
+
+```json
+{
+  "figma-plugin": {
+    "name": "My Plugin",
+    "id": "YOUR_PLUGIN_ID",
+    "editorType": ["figma"],
+    "main": "src/main.ts",
+    "ui": "src/ui.tsx",
+    "documentAccess": "dynamic-page"
+  }
+}
+```
+
+Publishing checklist:
+- **Name:** Clear, descriptive, max 50 characters
+- **Description:** Explain what the plugin does in 1-2 sentences
+- **Icon:** 128x128 PNG with rounded corners (Figma enforces this)
+- **Cover image:** 1920x960 PNG showing the plugin in action
+- **Tags:** Choose relevant tags for discoverability (up to 5)
+
+#### Permission Minimization
+
+Request only the permissions your plugin actually needs. Figma reviews permissions during publishing:
+
+| Permission | Grants | When to Use |
+|-----------|--------|-------------|
+| `currentuser` | Read current user's name and ID | Personalized settings, analytics |
+| `activeusers` | Read names/IDs of users currently viewing the file | Collaborative features |
+| `fileusers` | Read all file collaborators | Collaboration tracking |
+| `payments` | Access payment/licensing APIs | Paid plugins |
+| `teamlibrary` | Access team library styles/components | Design system tools |
+
+```json
+{
+  "permissions": ["currentuser"]
+}
+```
+
+Most plugins need **zero** permissions. Only add permissions you actively use and can justify.
+
+#### Network Access Justification
+
+If your plugin makes network requests (through the UI iframe), declare the domains and provide reasoning:
+
+```json
+{
+  "networkAccess": {
+    "allowedDomains": [
+      "https://fonts.googleapis.com",
+      "https://fonts.gstatic.com"
+    ],
+    "reasoning": "Google Fonts: Used to preview generated HTML with the correct fonts."
+  }
+}
+```
+
+Figma reviewers check network access claims. Use the narrowest domain scope possible:
+
+```json
+// GOOD: Specific domains
+{ "allowedDomains": ["https://api.example.com"] }
+
+// ACCEPTABLE: Wildcard subdomain
+{ "allowedDomains": ["https://*.example.com"] }
+
+// BAD: Open access (requires strong justification)
+{ "allowedDomains": ["*"] }
+
+// BEST: No network access
+{ "allowedDomains": ["none"] }
+```
+
+#### Version Management with @create-figma-plugin
+
+Version your plugin through `package.json`. The build tool includes the version in the generated manifest:
+
+```json
+{
+  "version": "1.2.0",
+  "figma-plugin": {
+    "name": "My Plugin v1.2.0"
+  }
+}
+```
+
+Use semantic versioning:
+- **Major:** Breaking changes (UI redesign, data format changes)
+- **Minor:** New features (new export format, new settings)
+- **Patch:** Bug fixes (crash fix, rendering correction)
+
+Build and publish workflow:
+
+```bash
+# Development
+npm run watch                          # Rebuild on changes
+
+# Production build
+npm run build                          # build-figma-plugin --typecheck --minify
+
+# Testing
+npm test                               # vitest run
+
+# Publishing
+# 1. Update version in package.json
+# 2. Build production bundle
+# 3. In Figma desktop app: Plugins > Manage plugins > Publish
+# 4. Upload build/main.js and build/ui.js
+# 5. Add description, tags, cover image
+# 6. Submit for review
+```
+
+> **Cross-reference:** See `plugin-architecture.md` for the complete `@create-figma-plugin` project setup and build configuration.
+
+---
+
+## Cross-References
+
+- **`plugin-architecture.md`** — Production plugin architecture patterns: project setup with `@create-figma-plugin`, project structure, IPC event system, data flow pipeline (extraction → generation → export), UI architecture. This module builds on that foundation with quality and reliability patterns.
+- **`plugin-codegen.md`** — Codegen plugin development patterns: Dev Mode integration, generate callback, preferences system, code quality. Shares many best practices from this module (error handling, caching, code validation) applied to the codegen context.
+- **`figma-api-plugin.md`** — Plugin API reference: sandbox model, SceneNode types, manifest fields, key API methods, constraints. This module provides the production patterns for using those APIs correctly.
+- **`figma-api-devmode.md`** — Dev Mode and codegen API reference. Codegen plugins face additional constraints (3-second timeout) that amplify the need for caching and performance optimization documented here.
+- **`design-to-code-layout.md`** — Auto Layout to Flexbox mapping rules consumed by extraction and generation modules.
+- **`design-to-code-visual.md`** — Visual property extraction patterns consumed by extraction modules.
+- **`design-to-code-assets.md`** — Asset detection and export patterns. The deduplication and timeout patterns in this module apply directly to asset export.
+- **`design-tokens-variables.md`** — Figma Variables to CSS custom property mapping. The variable caching pattern in this module optimizes the variable resolution described there.