@3fn/core 14.0.0 → 15.0.0

package/src/figma/DesignExtractor.ts

@@ -1,3620 +0,0 @@
-/**
- * DesignExtractor — Reads Figma designs via dual-MCP strategy and generates
- * design-outline.md documents with confidence flags.
- *
- * Uses Kiro Figma Power for rich design context and figma-console-mcp for
- * variable/style data. Orchestrates TokenTranslator for value matching and
- * VariantAnalyzer for context-aware recommendations.
- *
- * @see Design: .kiro/specs/054b-figma-design-extract/design.md
- * @requirements Req 1 (DesignExtractor Implementation)
- * @spec 054b-figma-design-extract
- */
-
-import type { ConsoleMCPClient } from './ConsoleMCPClient';
-import type { TokenTranslator, TranslationResult, TokenCategory } from './TokenTranslator';
-import type { VariantAnalyzer, ExtractionContext, VariantMapping, MCPDocClient } from './VariantAnalyzer';
-import type { DTCGTokenFile } from '../generators/types/DTCGTypes';
-import type { NodeWithClassifications, FigmaNodeType, CompositionPattern, UnresolvedBinding, UnresolvedBindingReason, ScreenshotMetadata, ComponentAnalysis, ClassifiedToken } from './ComponentAnalysis';
-import * as fs from 'fs';
-import * as path from 'path';
-import https from 'https';
-import http from 'http';
-
-// ---------------------------------------------------------------------------
-// Kiro Figma Power Client Interface
-// ---------------------------------------------------------------------------
-
-/**
- * Response from Kiro Figma Power `get_design_context` tool.
- *
- * Contains generated code and asset download URLs. The code string
- * is parsed to extract component structure, layout, and visual properties.
- */
-export interface DesignContextResponse {
-  /** Generated code string (HTML/CSS/TS) describing the component. */
-  code?: string;
-  /** Asset download URLs referenced in the code. */
-  assets?: Record<string, string>;
-  /** Raw response metadata. */
-  [key: string]: unknown;
-}
-
-/**
- * Response from Kiro Figma Power `get_metadata` tool.
- *
- * XML-formatted metadata containing node IDs, layer types, names,
- * positions, and sizes for structural overview.
- */
-export interface MetadataResponse {
-  /** XML string describing the node tree structure. */
-  xml?: string;
-  /** Raw response metadata. */
-  [key: string]: unknown;
-}
-
-/**
- * Response from figma-console-mcp `figma_get_component` tool.
- *
- * Contains component reconstruction spec with variants, properties,
- * and structure information.
- */
-export interface FigmaComponentResponse {
-  /** Component name. */
-  name?: string;
-  /** Component description. */
-  description?: string;
-  /** Component key. */
-  key?: string;
-  /** Variant properties and their options. */
-  variantProperties?: Record<string, string[]>;
-  /** Raw component data. */
-  [key: string]: unknown;
-}
-
-/**
- * Client interface for Kiro Figma Power MCP operations.
- *
- * Provides design context and metadata queries for rich component
- * structure extraction. Abstracted for testability.
- */
-export interface KiroFigmaPowerClient {
-  /**
-   * Get rich design context for a Figma node.
-   *
-   * Returns generated code and assets that describe the component's
-   * layout, properties, and visual states.
-   */
-  getDesignContext(
-    fileKey: string,
-    nodeId: string,
-  ): Promise<DesignContextResponse>;
-
-  /**
-   * Get structural metadata for a Figma node.
-   *
-   * Returns XML-formatted overview of node tree with IDs, types,
-   * names, positions, and sizes.
-   */
-  getMetadata(
-    fileKey: string,
-    nodeId: string,
-  ): Promise<MetadataResponse>;
-}
-
-// ---------------------------------------------------------------------------
-// Extracted Component (rich representation from dual-MCP)
-// ---------------------------------------------------------------------------
-
-/**
- * Layout information extracted from a Figma component.
- */
-export interface ExtractedLayout {
-  /** Layout mode: auto-layout direction or none. */
-  mode: 'horizontal' | 'vertical' | 'none';
-  /** Spacing between children (px). */
-  itemSpacing?: number;
-  /** Padding values (px). */
-  padding?: {
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
-  };
-}
-
-/**
- * Rich component representation extracted from Figma via dual-MCP.
- *
- * Extends the minimal FigmaComponent from VariantAnalyzer with layout,
- * property definitions, and raw source data for downstream processing.
- */
-export interface ExtractedComponent {
-  /** Component name from Figma. */
-  name: string;
-  /** Component description from Figma. */
-  description: string;
-  /** Variant definitions with their property values. */
-  variants: VariantDefinition[];
-  /** Visual states detected (hover, focus, disabled, pressed). */
-  states: StateDefinition[];
-  /** Component properties (boolean, text, instance swap, etc.). */
-  properties: PropertyDefinition[];
-  /** Layout information (auto-layout, spacing, padding). */
-  layout: ExtractedLayout;
-  /** Raw design context code from Kiro Power (for downstream parsing). */
-  rawDesignContext?: string;
-  /** Raw metadata XML from Kiro Power (for downstream parsing). */
-  rawMetadata?: string;
-  /** Which MCP source provided the primary data. */
-  source: 'kiro-power' | 'console-mcp-fallback';
-  /**
-   * Direct variable bindings from Figma component children.
-   *
-   * Maps Figma property names (e.g. "paddingLeft", "itemSpacing", "cornerRadius")
-   * to their bound variable names (e.g. "space/100", "radius/200").
-   * Extracted from `boundVariables` on child nodes via Console MCP.
-   * Enables binding-first token translation without value scanning.
-   */
-  boundVariableMap?: Map<string, string>;
-  /** Corner radius value (px) extracted from component children. */
-  cornerRadius?: number;
-  /** Fill colors extracted from component children (hex or rgba). */
-  fills?: Array<{ type: string; color?: string; opacity?: number }>;
-}
-
-// ---------------------------------------------------------------------------
-// Interfaces
-// ---------------------------------------------------------------------------
-
-/** Confidence level for an extracted value. */
-export type ConfidenceLevel = 'exact' | 'approximate' | 'no-match';
-
-/** How a token match was found. */
-export type MatchMethod = 'binding' | 'value';
-
-/**
- * A single token reference extracted from a Figma component property.
- */
-export interface TokenReference {
-  /** CSS property or Figma property name (e.g. "padding-left", "fill"). */
-  property: string;
-  /** Matched DesignerPunk token path (dot notation). */
-  token: string;
-  /** Match confidence. */
-  confidence: ConfidenceLevel;
-  /** How the match was found. */
-  matchMethod: MatchMethod;
-  /** Primitive token path if resolved. */
-  primitive?: string;
-  /** Semantic token path if resolved. */
-  semantic?: string;
-  /** Difference from matched token value (e.g. "±1px"). */
-  delta?: string;
-  /** Original Figma value as string (preserved for no-match reporting). */
-  rawValue?: string;
-  /** Suggested closest token when no exact match found. */
-  suggestion?: string;
-}
-
-/**
- * Aggregated token usage across all properties of a component.
- */
-export interface TokenUsage {
-  spacing: TokenReference[];
-  colors: TokenReference[];
-  typography: TokenReference[];
-  radius: TokenReference[];
-  shadows: TokenReference[];
-}
-
-/**
- * A Figma variable binding on a component element.
- *
- * Represents the relationship between a Figma variable and its resolved
- * values across modes (light/dark).
- */
-export interface TokenBinding {
-  /** Figma variable name in slash notation (e.g. "space/100"). */
-  variableName: string;
-  /** Figma variable ID. */
-  variableId: string;
-  /** Collection name (e.g. "Primitives", "Semantics"). */
-  collectionName: string;
-  /** Resolved variable type: FLOAT, COLOR, STRING. */
-  resolvedType: string;
-  /** Values keyed by mode name or mode ID. */
-  valuesByMode: Record<string, unknown>;
-  /** Whether this variable is a semantic alias. */
-  isAlias: boolean;
-  /** Primitive variable name if this is an alias. */
-  aliasTarget?: string;
-}
-
-/**
- * A Figma style (effect or text) read from the file.
- */
-export interface FigmaStyle {
-  /** Style name (e.g. "shadow.elevation200", "typography.heading200"). */
-  name: string;
-  /** Style type. */
-  type: 'EFFECT' | 'TEXT';
-  /** Raw style properties from Figma. */
-  properties: Record<string, unknown>;
-}
-
-/**
- * Variant definition extracted from a Figma component.
- */
-export interface VariantDefinition {
-  name: string;
-  properties: Record<string, string>;
-}
-
-/**
- * Visual state extracted from a Figma component (e.g. hover, focus, disabled).
- */
-export interface StateDefinition {
-  name: string;
-  description?: string;
-}
-
-/**
- * A component property extracted from Figma.
- */
-export interface PropertyDefinition {
-  name: string;
-  type: string;
-  defaultValue?: string;
-}
-
-/**
- * Inheritance pattern for a component within its family.
- */
-export interface InheritancePattern {
-  familyName: string;
-  pattern: string;
-  baseComponent?: string;
-}
-
-/**
- * Status of behavioral contracts for a component.
- *
- * Interactive components (buttons, inputs) require explicit behavioral
- * contracts. Static components (badges, dividers) get auto-generated
- * "no interaction" contracts.
- */
-export interface BehavioralContractStatus {
-  /** Whether the component is classified as interactive or static. */
-  classification: 'interactive' | 'static';
-  /** Visual states detected from Figma (hover, focus, disabled, pressed). */
-  detectedStates: string[];
-  /** Whether behavioral contracts are defined. */
-  contractsDefined: boolean;
-  /** Auto-generated contract for static components, or undefined for interactive. */
-  autoContract?: string;
-  /** Confidence flag for the behavioral contract status. */
-  confidence: '✅' | '⚠️' | '❌';
-}
-
-/**
- * Platform parity check result for a component.
- *
- * Flags platform-specific interactions (hover = web-only, press = mobile)
- * and provides recommendations for cross-platform consistency.
- */
-export interface PlatformParityCheck {
-  /** Platform-specific interactions detected. */
-  interactions: PlatformInteraction[];
-  /** Overall parity status. */
-  hasConcerns: boolean;
-}
-
-/** A single platform-specific interaction. */
-export interface PlatformInteraction {
-  /** Interaction name (e.g. "hover", "press", "long-press"). */
-  interaction: string;
-  /** Which platforms support this interaction. */
-  platforms: ('web' | 'ios' | 'android')[];
-  /** Recommendation for cross-platform handling. */
-  recommendation: string;
-}
-
-/**
- * A component token decision point surfaced for Ada's review.
- *
- * Detects repeated primitive token usage and provides illustrative
- * component token suggestions. All suggestions are explicitly labeled
- * as pending human review.
- */
-export interface ComponentTokenDecision {
-  /** The primitive token being used repeatedly. */
-  primitiveToken: string;
-  /** Number of times the primitive is used across component properties. */
-  usageCount: number;
-  /** Where the primitive is used (e.g. "padding-left: 5 variants"). */
-  locations: string[];
-  /** Illustrative component token name suggestion. */
-  illustrativeSuggestion: string;
-  /** Why this pattern is notable. */
-  rationale: string;
-}
-
-/**
- * Mode validation result for token bindings.
- */
-export interface ModeValidationResult {
-  /** Discrepancies found between modes. */
-  discrepancies: ModeDiscrepancy[];
-  /** Whether any unexpected discrepancies were found. */
-  hasUnexpectedDiscrepancies: boolean;
-}
-
-/** A single mode discrepancy for a token binding. */
-export interface ModeDiscrepancy {
-  /** Variable name with the discrepancy. */
-  variableName: string;
-  /** Light mode value. */
-  lightValue: unknown;
-  /** Dark mode value. */
-  darkValue: unknown;
-  /** Whether this discrepancy is expected or unexpected. */
-  category: 'expected' | 'unexpected';
-}
-
-/**
- * Confidence report for the overall extraction.
- */
-export interface ConfidenceReport {
-  /** Overall confidence: high, medium, or low. */
-  overall: 'high' | 'medium' | 'low';
-  /** Number of exact matches. */
-  exactMatches: number;
-  /** Number of approximate matches. */
-  approximateMatches: number;
-  /** Number of no-match values. */
-  noMatches: number;
-  /** Whether human input is required before proceeding. */
-  requiresHumanInput: boolean;
-  /** Specific items requiring human review. */
-  reviewItems: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Bound Variable Batch Resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Entry representing a single bound variable found during node tree traversal.
- *
- * Captures the variable ID, the property it was bound to, and full node
- * context (nodeId, nodeName, ancestorChain) so that unresolved bindings
- * can be reported with enough information for human review.
- */
-export interface BoundVariableEntry {
-  /** Figma variable ID (e.g. 'VariableID:1224:14083'). */
-  variableId: string;
-  /** Property where the binding was found (e.g. 'padding-top', 'fill'). */
-  property: string;
-  /** Figma node ID where the binding was found. */
-  nodeId: string;
-  /** Name of the node where the binding was found. */
-  nodeName: string;
-  /** Ancestor chain of the node for context. */
-  ancestorChain: string[];
-  /** Raw Figma value for the property. */
-  rawValue: number | string;
-  /** Token category for translation. */
-  category: TokenCategory;
-}
-
-// ---------------------------------------------------------------------------
-// DesignExtractor
-// ---------------------------------------------------------------------------
-
-/**
- * Orchestrates extraction from Figma via dual-MCP strategy and generates
- * design-outline.md documents.
- *
- * Uses:
- * - Kiro Figma Power for rich design context (component structure, layout)
- * - figma-console-mcp via ConsoleMCPClient for variables and styles
- * - TokenTranslator for Figma value → DesignerPunk token matching
- * - VariantAnalyzer for context-aware variant mapping recommendations
- */
-export class DesignExtractor {
-  /** Platform-interaction heuristics: interaction → supported platforms. */
-  private static readonly PLATFORM_HEURISTICS: Record<string, ('web' | 'ios' | 'android')[]> = {
-    hover: ['web'],
-    focus: ['web', 'ios', 'android'],
-    pressed: ['web', 'ios', 'android'],
-    disabled: ['web', 'ios', 'android'],
-    active: ['web', 'ios', 'android'],
-    selected: ['web', 'ios', 'android'],
-    'long-press': ['ios', 'android'],
-    loading: ['web', 'ios', 'android'],
-    error: ['web', 'ios', 'android'],
-  };
-
-  constructor(
-    private readonly consoleMcp: ConsoleMCPClient,
-    private readonly translator: TokenTranslator,
-    private readonly analyzer: VariantAnalyzer,
-    private readonly kiroPower?: KiroFigmaPowerClient,
-    private readonly mcpDocs?: MCPDocClient,
-  ) {}
-
-  // -------------------------------------------------------------------------
-  // readFigmaComponent (Task 3.2)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Read a Figma component via dual-MCP strategy.
-   *
-   * Primary: Kiro Figma Power `get_design_context` for rich component
-   * structure (layout, properties, visual states).
-   * Fallback: `get_metadata` + figma-console-mcp `figma_get_component`
-   * if `get_design_context` lacks detail or Kiro Power is unavailable.
-   *
-   * @param fileKey - The Figma file key.
-   * @param nodeId - The node ID of the component to extract.
-   * @returns An ExtractedComponent with structure, layout, and states.
-   * @throws Error if component cannot be read from either MCP source.
-   */
-  async readFigmaComponent(
-    fileKey: string,
-    nodeId: string,
-  ): Promise<ExtractedComponent> {
-    // Try primary path: Kiro Figma Power
-    if (this.kiroPower) {
-      try {
-        const designContext = await this.kiroPower.getDesignContext(fileKey, nodeId);
-
-        if (designContext.code && designContext.code.trim().length > 0) {
-          const extracted = this.parseDesignContext(designContext);
-          if (extracted.name) {
-            return {
-              ...extracted,
-              rawDesignContext: designContext.code,
-              source: 'kiro-power',
-            };
-          }
-        }
-      } catch {
-        // Kiro Power failed — fall through to fallback
-      }
-    }
-
-    // Fallback: get_metadata + figma_get_component
-    return this.readFigmaComponentFallback(fileKey, nodeId);
-  }
-
-  /**
-   * Parse Kiro Figma Power `get_design_context` response into an
-   * ExtractedComponent.
-   *
-   * Extracts component name, description, variants, states, properties,
-   * and layout from the generated code string.
-   */
-  private parseDesignContext(response: DesignContextResponse): ExtractedComponent {
-    const code = response.code ?? '';
-
-    return {
-      name: this.extractComponentName(code),
-      description: this.extractDescription(code),
-      variants: this.extractVariants(code),
-      states: this.extractStates(code),
-      properties: this.extractProperties(code),
-      layout: this.extractLayout(code),
-      source: 'kiro-power',
-    };
-  }
-
-  /**
-   * Fallback component reading via get_metadata + figma_get_component.
-   *
-   * Primary extraction path when Kiro Power is unavailable (which is the
-   * common case). Extracts structured layout data, boundVariables, fills,
-   * and cornerRadius directly from the Console MCP component response.
-   */
-  private async readFigmaComponentFallback(
-      fileKey: string,
-      nodeId: string,
-    ): Promise<ExtractedComponent> {
-      // Try metadata from Kiro Power if available
-      let rawMetadata: string | undefined;
-      if (this.kiroPower) {
-        try {
-          const metadata = await this.kiroPower.getMetadata(fileKey, nodeId);
-          rawMetadata = metadata.xml;
-        } catch {
-          // Metadata unavailable — continue without it
-        }
-      }
-
-      // Get component data from figma-console-mcp
-      let componentData: FigmaComponentResponse;
-      try {
-        componentData = await this.consoleMcp.getComponent(fileKey, nodeId);
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        throw new Error(
-          `Failed to read Figma component (file: ${fileKey}, node: ${nodeId}): ${msg}`,
-        );
-      }
-
-      if (!componentData.name) {
-        throw new Error(
-          `Component not found or invalid node ID (file: ${fileKey}, node: ${nodeId})`,
-        );
-      }
-
-      // Build variants from variantProperties map
-      const variants: VariantDefinition[] = [];
-      if (componentData.variantProperties) {
-        const propEntries = Object.entries(componentData.variantProperties);
-        if (propEntries.length > 0) {
-          // Generate variant combinations from the first property's values
-          const [firstProp, firstValues] = propEntries[0];
-          for (const val of firstValues) {
-            variants.push({
-              name: `${firstProp}=${val}`,
-              properties: { [firstProp]: val },
-            });
-          }
-        }
-      }
-
-      // Extract component properties and states from children's componentProperties.
-      // Children of a COMPONENT_SET carry componentProperties like:
-      //   { "State": { value: "Incomplete", type: "VARIANT" },
-      //     "Size": { value: "Sm", type: "VARIANT" },
-      //     "Show Label#1231:0": { type: "BOOLEAN", value: false } }
-      const { properties, states: childStates } = this.extractChildComponentProperties(componentData);
-
-      // Extract states from metadata XML if available, merge with child states
-      const metadataStates = rawMetadata ? this.extractStatesFromMetadata(rawMetadata) : [];
-      const stateNames = new Set(metadataStates.map(s => s.name));
-      for (const cs of childStates) {
-        if (!stateNames.has(cs.name)) {
-          metadataStates.push(cs);
-          stateNames.add(cs.name);
-        }
-      }
-
-      // Extract structured layout data from component children
-      const { layout, boundVariableMap, cornerRadius, fills } =
-        this.extractLayoutFromComponentData(componentData);
-
-      return {
-        name: componentData.name,
-        description: componentData.description ?? '',
-        variants,
-        states: metadataStates,
-        properties,
-        layout,
-        boundVariableMap,
-        cornerRadius,
-        fills,
-        rawMetadata,
-        source: 'console-mcp-fallback',
-      };
-    }
-
-  /**
-   * Extract structured layout data from a Console MCP component response.
-   *
-   * Walks the component's children (variant instances in a component set)
-   * to extract padding, itemSpacing, cornerRadius, fills, and boundVariables.
-   * Uses the first child with layout data as the representative, since
-   * variant children typically share the same structural tokens.
-   *
-   * boundVariables entries use VARIABLE_ALIAS format:
-   *   { "paddingLeft": { "type": "VARIABLE_ALIAS", "id": "VariableID:..." } }
-   *
-   * We resolve variable IDs to names via the bindings loaded separately
-   * in readTokenBindings(). Here we store the raw property→variableId map
-   * and also extract any inline variable name references.
-   */
-  /**
-     * Extract structured layout data from a Console MCP component response.
-     *
-     * Walks the component's children recursively to extract padding,
-     * itemSpacing, cornerRadius, fills, and boundVariables. Uses the first
-     * child with layout data as the representative for spacing/layout, and
-     * collects boundVariables from all levels of the tree (since bindings
-     * often live on grandchildren — e.g. fill color bindings on inner frames).
-     *
-     * boundVariables entries use VARIABLE_ALIAS format:
-     *   { "paddingLeft": { "type": "VARIABLE_ALIAS", "id": "VariableID:..." } }
-     *
-     * Fill-level boundVariables are nested inside the fills array:
-     *   fills: [{ color: {...}, boundVariables: { color: { id: "..." } } }]
-     *
-     * We resolve variable IDs to names via the bindings loaded separately
-     * in readTokenBindings(). Here we store the raw property→variableId map.
-     */
-    private extractLayoutFromComponentData(
-      componentData: FigmaComponentResponse,
-    ): {
-      layout: ExtractedLayout;
-      boundVariableMap: Map<string, string>;
-      cornerRadius?: number;
-      fills?: Array<{ type: string; color?: string; opacity?: number }>;
-    } {
-      const boundVariableMap = new Map<string, string>();
-      let layout: ExtractedLayout = { mode: 'none' };
-      let cornerRadius: number | undefined;
-      let fills: Array<{ type: string; color?: string; opacity?: number }> | undefined;
-
-      // The component data may be a component set (with children) or a single component.
-      // Try children first, then fall back to the component itself.
-      const raw = componentData as Record<string, unknown>;
-      const children = raw.children as Array<Record<string, unknown>> | undefined;
-      const nodesToInspect = children && children.length > 0
-        ? children
-        : [raw];
-
-      for (const node of nodesToInspect) {
-        // Extract layout mode from layoutMode field
-        const layoutMode = node.layoutMode as string | undefined;
-        if (layoutMode && layout.mode === 'none') {
-          if (layoutMode === 'HORIZONTAL') layout.mode = 'horizontal';
-          else if (layoutMode === 'VERTICAL') layout.mode = 'vertical';
-        }
-
-        // Extract spacing values — use first node that has them
-        const itemSpacing = node.itemSpacing as number | undefined;
-        if (itemSpacing != null && layout.itemSpacing == null) {
-          layout.itemSpacing = itemSpacing;
-        }
-
-        // Extract padding
-        const pTop = node.paddingTop as number | undefined;
-        const pRight = node.paddingRight as number | undefined;
-        const pBottom = node.paddingBottom as number | undefined;
-        const pLeft = node.paddingLeft as number | undefined;
-        if ((pTop != null || pRight != null || pBottom != null || pLeft != null) && !layout.padding) {
-          layout.padding = {
-            top: pTop,
-            right: pRight,
-            bottom: pBottom,
-            left: pLeft,
-          };
-        }
-
-        // Extract corner radius
-        const cr = node.cornerRadius as number | undefined;
-        if (cr != null && cornerRadius == null) {
-          cornerRadius = cr;
-        }
-
-        // Extract fills from this node (top-level fills for the component)
-        const nodeFills = node.fills as Array<Record<string, unknown>> | undefined;
-        if (nodeFills && nodeFills.length > 0 && !fills) {
-          fills = nodeFills.map((f) => {
-            const color = f.color as Record<string, number> | undefined;
-            let colorStr: string | undefined;
-            if (color) {
-              const r = Math.round((color.r ?? 0) * 255);
-              const g = Math.round((color.g ?? 0) * 255);
-              const b = Math.round((color.b ?? 0) * 255);
-              colorStr = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
-            }
-            // Extract fill-level boundVariables (e.g. color bound to a variable)
-            const fillBoundVars = f.boundVariables as Record<string, unknown> | undefined;
-            if (fillBoundVars) {
-              this.extractBoundVariables(fillBoundVars, boundVariableMap);
-            }
-            return {
-              type: String(f.type ?? 'SOLID'),
-              color: colorStr,
-              opacity: f.opacity as number | undefined,
-            };
-          });
-        }
-
-        // Extract node-level boundVariables (spacing, padding, radius bindings)
-        const boundVars = node.boundVariables as Record<string, unknown> | undefined;
-        if (boundVars) {
-          this.extractBoundVariables(boundVars, boundVariableMap);
-        }
-
-        // Stop scanning siblings once we have layout data (spacing/padding)
-        if (layout.mode !== 'none') break;
-      }
-
-      // Always walk the full tree for boundVariables and deep fills.
-      // boundVariables and color bindings often live on grandchildren
-      // (e.g. fill color bindings on inner frames within instance children).
-      // We collect ALL of them, not just the first match.
-      for (const node of nodesToInspect) {
-        this.collectBoundVariablesRecursive(node, boundVariableMap, 0, 4);
-      }
-
-      // Collect fills from deep children that have boundVariables on their
-      // fills — these represent designer-intentional color assignments that
-      // the top-level fills may not capture.
-      const deepFills = this.collectDeepFills(nodesToInspect);
-      if (deepFills.length > 0) {
-        // Merge deep fills with top-level fills, deduplicating by color value
-        const existingColors = new Set((fills ?? []).map(f => f.color));
-        for (const df of deepFills) {
-          if (df.color && !existingColors.has(df.color)) {
-            if (!fills) fills = [];
-            fills.push(df);
-            existingColors.add(df.color);
-          }
-        }
-      }
-
-      return { layout, boundVariableMap, cornerRadius, fills };
-    }
-
-    /**
-     * Extract component properties and visual states from children's
-     * componentProperties fields.
-     *
-     * Walks all children (and grandchildren) looking for `componentProperties`
-     * objects. Extracts:
-     * - VARIANT properties with value matching known state names → StateDefinition
-     * - VARIANT properties → PropertyDefinition (with type from variant options)
-     * - BOOLEAN properties → PropertyDefinition
-     *
-     * Deduplicates by property name (strips Figma hash suffixes like "#1231:0").
-     */
-    private extractChildComponentProperties(
-      componentData: FigmaComponentResponse,
-    ): { properties: PropertyDefinition[]; states: StateDefinition[] } {
-      const properties: PropertyDefinition[] = [];
-      const states: StateDefinition[] = [];
-      const seenProps = new Set<string>();
-      const seenStates = new Set<string>();
-
-      const stateKeywords = new Set([
-        'hover', 'focus', 'disabled', 'pressed', 'active', 'selected',
-        'error', 'loading', 'incomplete', 'complete', 'current',
-      ]);
-
-      const raw = componentData as Record<string, unknown>;
-      const children = raw.children as Array<Record<string, unknown>> | undefined;
-      if (!children) return { properties, states };
-
-      const walkNode = (node: Record<string, unknown>): void => {
-        const cp = node.componentProperties as
-          Record<string, { type: string; value: unknown; boundVariables?: unknown }> | undefined;
-
-        if (cp) {
-          for (const [rawName, def] of Object.entries(cp)) {
-            // Strip Figma hash suffix (e.g. "Show Label#1231:0" → "Show Label")
-            const cleanName = rawName.replace(/#[\d:]+$/, '').trim();
-            if (seenProps.has(cleanName)) continue;
-            seenProps.add(cleanName);
-
-            if (def.type === 'VARIANT') {
-              const value = String(def.value ?? '');
-
-              // Check if this variant value is a visual state
-              if (stateKeywords.has(value.toLowerCase()) && !seenStates.has(value.toLowerCase())) {
-                states.push({ name: value.toLowerCase() });
-                seenStates.add(value.toLowerCase());
-              }
-
-              properties.push({
-                name: cleanName,
-                type: 'variant',
-                defaultValue: value,
-              });
-            } else if (def.type === 'BOOLEAN') {
-              properties.push({
-                name: cleanName,
-                type: 'boolean',
-                defaultValue: String(def.value ?? 'false'),
-              });
-            }
-          }
-        }
-
-        // Recurse into children
-        const nodeChildren = node.children as Array<Record<string, unknown>> | undefined;
-        if (nodeChildren) {
-          for (const child of nodeChildren) {
-            walkNode(child);
-          }
-        }
-      };
-
-      for (const child of children) {
-        walkNode(child);
-      }
-
-      return { properties, states };
-    }
-
-    // -------------------------------------------------------------------------
-    // Hierarchical Node Tree Construction (Task 1.3)
-    // -------------------------------------------------------------------------
-
-    /**
-     * Build a hierarchical node tree with per-node token classifications.
-     *
-     * Recursively walks the Figma node tree preserving parent-child
-     * relationships. Each node carries its own token classifications
-     * (semantic, primitive, unidentified) rather than flattening them.
-     *
-     * @param figmaNode - Raw Figma node object from API response
-     * @param depth - Current depth in the tree (root = 0)
-     * @param ancestors - Ancestor node types from root to parent
-     * @returns NodeWithClassifications tree
-     * @requirements Req 2 (Hierarchical Node Tree Preservation)
-     */
-    buildNodeTree(
-      figmaNode: Record<string, unknown>,
-      depth: number = 0,
-      ancestors: string[] = [],
-    ): NodeWithClassifications {
-      const nodeType = (figmaNode.type as string) ?? 'FRAME';
-      const validTypes = new Set<string>([
-        'COMPONENT_SET', 'COMPONENT', 'INSTANCE', 'FRAME', 'TEXT',
-      ]);
-      const type: FigmaNodeType = validTypes.has(nodeType)
-        ? (nodeType as FigmaNodeType)
-        : 'FRAME';
-
-      const node: NodeWithClassifications = {
-        id: String(figmaNode.id ?? ''),
-        name: String(figmaNode.name ?? ''),
-        type,
-        depth,
-        ancestorChain: ancestors,
-        tokenClassifications: {
-          semanticIdentified: [],
-          primitiveIdentified: [],
-          unidentified: [],
-        },
-        children: [],
-      };
-
-      // Extract layout properties
-      node.layout = this.extractNodeLayout(figmaNode);
-
-      // Extract text style for TEXT nodes
-      if (type === 'TEXT') {
-        node.textStyle = this.extractTextStyle(figmaNode);
-      }
-
-      // Extract stroke colors
-      const strokes = figmaNode.strokes as Array<Record<string, unknown>> | undefined;
-      if (strokes?.length) {
-        const extracted: Array<{ color: string }> = [];
-        for (const stroke of strokes) {
-          const c = stroke.color as Record<string, number> | undefined;
-          if (!c) continue;
-          const r = Math.round((c.r ?? 0) * 255);
-          const g = Math.round((c.g ?? 0) * 255);
-          const b = Math.round((c.b ?? 0) * 255);
-          const a = (c.a ?? 1) * ((stroke.opacity as number) ?? 1);
-          extracted.push({ color: `rgba(${r}, ${g}, ${b}, ${a})` });
-        }
-        if (extracted.length) node.strokes = extracted;
-      }
-
-      // Extract componentProperties for INSTANCE nodes
-      if (type === 'INSTANCE') {
-        node.componentProperties = this.extractNodeComponentProperties(figmaNode);
-      }
-
-      // Classify tokens for this node
-      this.classifyNodeTokens(figmaNode, node);
-
-      // Recursively build children
-      const children = figmaNode.children as
-        Array<Record<string, unknown>> | undefined;
-      if (children) {
-        const newAncestors = [...ancestors, nodeType];
-        node.children = children.map(child =>
-          this.buildNodeTree(child, depth + 1, newAncestors),
-        );
-      }
-
-      return node;
-    }
-
-    /**
-     * Detect composition patterns in a node tree.
-     *
-     * Groups INSTANCE children by component name and identifies repeated
-     * usage patterns with shared properties and property variations.
-     * Applies recursively at every level of the node tree.
-     *
-     * @param nodeTree - Root of the classified node tree
-     * @returns Array of detected composition patterns across all tree levels
-     * @requirements Req 3 (Composition Pattern Detection)
-     */
-    detectCompositionPatterns(
-      nodeTree: NodeWithClassifications,
-    ): CompositionPattern[] {
-      const patterns: CompositionPattern[] = [];
-      this.detectPatternsAtLevel(nodeTree, patterns);
-      return patterns;
-    }
-
-    /**
-     * Detect composition patterns at a single level and recurse into children.
-     */
-    private detectPatternsAtLevel(
-      node: NodeWithClassifications,
-      patterns: CompositionPattern[],
-    ): void {
-      if (node.children.length > 0) {
-        // Group INSTANCE children by component name
-        const grouped = new Map<string, NodeWithClassifications[]>();
-        for (const child of node.children) {
-          if (child.type === 'INSTANCE') {
-            const existing = grouped.get(child.name);
-            if (existing) {
-              existing.push(child);
-            } else {
-              grouped.set(child.name, [child]);
-            }
-          }
-        }
-
-        // Build patterns for groups with 2+ instances
-        for (const [componentName, instances] of grouped) {
-          if (instances.length < 2) continue;
-
-          const shared = this.findSharedProperties(instances);
-          const variations = this.groupByPropertyVariations(instances, shared);
-
-          patterns.push({
-            componentName,
-            count: instances.length,
-            sharedProperties: shared,
-            propertyVariations: variations,
-            depth: instances[0].depth,
-          });
-        }
-
-        // Recurse into all children (not just INSTANCE)
-        for (const child of node.children) {
-          this.detectPatternsAtLevel(child, patterns);
-        }
-      }
-    }
-
-    /**
-     * Find properties shared across all instances in a group.
-     *
-     * A property is "shared" when every instance has the same value for it.
-     */
-    private findSharedProperties(
-      instances: NodeWithClassifications[],
-    ): Record<string, unknown> {
-      const first = instances[0].componentProperties;
-      if (!first || instances.length === 0) return {};
-
-      const shared: Record<string, unknown> = {};
-      for (const [key, def] of Object.entries(first)) {
-        const allSame = instances.every(inst => {
-          const cp = inst.componentProperties;
-          if (!cp || !(key in cp)) return false;
-          return this.valuesEqual(cp[key].value, def.value);
-        });
-        if (allSame) {
-          shared[key] = def.value;
-        }
-      }
-      return shared;
-    }
-
-    /**
-     * Group instances by their non-shared property combinations.
-     *
-     * Returns distinct property value combinations with counts.
-     */
-    private groupByPropertyVariations(
-      instances: NodeWithClassifications[],
-      sharedProperties: Record<string, unknown>,
-    ): CompositionPattern['propertyVariations'] {
-      const variationMap = new Map<string, { properties: Record<string, unknown>; count: number }>();
-
-      for (const inst of instances) {
-        const cp = inst.componentProperties;
-        const varying: Record<string, unknown> = {};
-        if (cp) {
-          for (const [key, def] of Object.entries(cp)) {
-            if (!(key in sharedProperties)) {
-              varying[key] = def.value;
-            }
-          }
-        }
-
-        const key = JSON.stringify(varying, Object.keys(varying).sort());
-        const existing = variationMap.get(key);
-        if (existing) {
-          existing.count++;
-        } else {
-          variationMap.set(key, { properties: varying, count: 1 });
-        }
-      }
-
-      return Array.from(variationMap.values());
-    }
-
-    // -----------------------------------------------------------------------
-    // Screenshot Capture (Task 2.3)
-    // -----------------------------------------------------------------------
-
-    /**
-     * Capture a component screenshot via figma-console-mcp.
-     *
-     * Calls `figma_get_component_image` at 2x scale in PNG format.
-     * On failure, logs a warning and returns null so extraction can
-     * continue without a screenshot.
-     *
-     * @param fileKey - The Figma file key.
-     * @param nodeId - The node ID of the component to capture.
-     * @param outputDir - Directory for storing screenshot images.
-     * @param componentName - Component name for the filename.
-     * @param variant - Optional variant identifier for the filename.
-     * @returns ScreenshotMetadata or null if capture failed.
-     * @requirements Req 5 (Component Screenshots)
-     */
-    async captureComponentScreenshot(
-      fileUrl: string,
-      nodeId: string,
-      outputDir: string,
-      componentName: string,
-      variant?: string,
-    ): Promise<ScreenshotMetadata | null> {
-      try {
-        const result = await this.consoleMcp.getComponentImage(fileUrl, nodeId, {
-          scale: 2,
-          format: 'png',
-        });
-
-        if (!result.imageUrl) {
-          console.warn(`[DesignExtractor] Screenshot capture returned no image URL for "${componentName}"`);
-          return null;
-        }
-
-        // Build filename
-        const safeName = componentName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-        const safeVariant = variant
-          ? '-' + variant.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
-          : '';
-        const filename = `${safeName}${safeVariant}.png`;
-        const relativePath = `./images/${filename}`;
-
-        // Download image to disk
-        const absPath = path.join(outputDir, 'images', filename);
-        try {
-          await this.downloadFile(result.imageUrl, absPath);
-        } catch (dlErr) {
-          const msg = dlErr instanceof Error ? dlErr.message : String(dlErr);
-          console.warn(`[DesignExtractor] Image download failed for "${componentName}": ${msg}`);
-        }
-
-        return {
-          filePath: relativePath,
-          url: result.imageUrl,
-          format: 'png',
-          scale: 2,
-          variant,
-          capturedAt: new Date().toISOString(),
-        };
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        console.warn(`[DesignExtractor] Screenshot capture failed for "${componentName}": ${msg}`);
-        return null;
-      }
-    }
-
-    /** Download a file from a URL to a local path. */
-    private downloadFile(url: string, dest: string): Promise<void> {
-      return new Promise((resolve, reject) => {
-        const mod = url.startsWith('https') ? https : http;
-        const file = fs.createWriteStream(dest);
-        mod.get(url, (res) => {
-          if (res.statusCode === 301 || res.statusCode === 302) {
-            file.close();
-            fs.unlinkSync(dest);
-            this.downloadFile(res.headers.location!, dest).then(resolve, reject);
-            return;
-          }
-          if (res.statusCode !== 200) {
-            file.close();
-            fs.unlinkSync(dest);
-            reject(new Error(`HTTP ${res.statusCode}`));
-            return;
-          }
-          res.pipe(file);
-          file.on('finish', () => { file.close(); resolve(); });
-        }).on('error', (err) => {
-          file.close();
-          fs.unlinkSync(dest);
-          reject(err);
-        });
-      });
-    }
-
-    /**
-     * Deep equality check for property values.
-     */
-    private valuesEqual(a: unknown, b: unknown): boolean {
-      if (a === b) return true;
-      if (a === null || b === null) return false;
-      if (typeof a !== typeof b) return false;
-      if (typeof a === 'object') {
-        return JSON.stringify(a) === JSON.stringify(b);
-      }
-      return false;
-    }
-
-    /**
-     * Extract layout properties from a single Figma node.
-     *
-     * Returns undefined when the node has no layout-related properties,
-     * keeping the node tree compact.
-     */
-    private extractNodeLayout(
-      node: Record<string, unknown>,
-    ): NodeWithClassifications['layout'] | undefined {
-      const layoutMode = node.layoutMode as string | undefined;
-      const pTop = node.paddingTop as number | undefined;
-      const pRight = node.paddingRight as number | undefined;
-      const pBottom = node.paddingBottom as number | undefined;
-      const pLeft = node.paddingLeft as number | undefined;
-      const itemSpacing = node.itemSpacing as number | undefined;
-      const counterAxisSpacing = node.counterAxisSpacing as number | undefined;
-      const cornerRadius = node.cornerRadius as number | undefined;
-      const width = node.width as number | undefined;
-      const height = node.height as number | undefined;
-      const layoutSizingH = node.layoutSizingHorizontal as string | undefined;
-      const layoutSizingV = node.layoutSizingVertical as string | undefined;
-      const primaryAlign = node.primaryAxisAlignItems as string | undefined;
-      const counterAlign = node.counterAxisAlignItems as string | undefined;
-      const layoutAlign = node.layoutAlign as string | undefined;
-      const layoutGrow = node.layoutGrow as number | undefined;
-      const opacity = node.opacity as number | undefined;
-      const strokeWeight = node.strokeWeight as number | undefined;
-      const strokeAlign = node.strokeAlign as string | undefined;
-
-      const hasLayout =
-        layoutMode != null ||
-        pTop != null || pRight != null || pBottom != null || pLeft != null ||
-        itemSpacing != null || counterAxisSpacing != null || cornerRadius != null ||
-        width != null || height != null || opacity != null || strokeWeight != null;
-
-      if (!hasLayout) return undefined;
-
-      const layout: NonNullable<NodeWithClassifications['layout']> = {};
-
-      if (layoutMode === 'HORIZONTAL' || layoutMode === 'VERTICAL') {
-        layout.layoutMode = layoutMode;
-      } else if (layoutMode) {
-        layout.layoutMode = 'NONE';
-      }
-
-      if (pTop != null || pRight != null || pBottom != null || pLeft != null) {
-        layout.padding = {
-          top: pTop ?? 0,
-          right: pRight ?? 0,
-          bottom: pBottom ?? 0,
-          left: pLeft ?? 0,
-        };
-      }
-
-      if (itemSpacing != null) layout.itemSpacing = itemSpacing;
-      if (counterAxisSpacing != null) layout.counterAxisSpacing = counterAxisSpacing;
-      if (cornerRadius != null) layout.cornerRadius = cornerRadius;
-      if (width != null) layout.width = width;
-      if (height != null) layout.height = height;
-      if (layoutSizingH === 'FIXED' || layoutSizingH === 'HUG' || layoutSizingH === 'FILL') {
-        layout.layoutSizingHorizontal = layoutSizingH;
-      }
-      if (layoutSizingV === 'FIXED' || layoutSizingV === 'HUG' || layoutSizingV === 'FILL') {
-        layout.layoutSizingVertical = layoutSizingV;
-      }
-      if (primaryAlign) layout.primaryAxisAlignItems = primaryAlign;
-      if (counterAlign) layout.counterAxisAlignItems = counterAlign;
-      if (layoutAlign) layout.layoutAlign = layoutAlign;
-      if (layoutGrow != null) layout.layoutGrow = layoutGrow;
-      if (opacity != null && opacity !== 1) layout.opacity = opacity;
-      if (strokeWeight != null && strokeWeight > 0) layout.strokeWeight = strokeWeight;
-      if (strokeAlign) layout.strokeAlign = strokeAlign;
-
-      return layout;
-    }
-
-    /**
-     * Extract text style properties from a TEXT node.
-     */
-    private extractTextStyle(
-      node: Record<string, unknown>,
-    ): NodeWithClassifications['textStyle'] | undefined {
-      const style: NonNullable<NodeWithClassifications['textStyle']> = {};
-      let hasData = false;
-
-      const chars = node.characters as string | undefined;
-      if (chars != null) { style.characters = chars; hasData = true; }
-
-      const fontSize = node.fontSize as number | undefined;
-      if (fontSize != null) { style.fontSize = fontSize; hasData = true; }
-
-      const fontName = node.fontName as { family?: string; style?: string } | undefined;
-      if (fontName?.family) { style.fontFamily = fontName.family; hasData = true; }
-      if (fontName?.style) { style.fontStyle = fontName.style; hasData = true; }
-
-      const fontWeight = node.fontWeight as number | undefined;
-      if (fontWeight != null) { style.fontWeight = fontWeight; hasData = true; }
-
-      const lh = node.lineHeight as { value?: number; unit?: string } | undefined;
-      if (lh?.value != null && lh.unit !== 'AUTO') { style.lineHeight = lh.value; hasData = true; }
-
-      const ls = node.letterSpacing as { value?: number } | undefined;
-      if (ls?.value != null && ls.value !== 0) { style.letterSpacing = ls.value; hasData = true; }
-
-      const tah = node.textAlignHorizontal as string | undefined;
-      if (tah) { style.textAlignHorizontal = tah; hasData = true; }
-
-      const tav = node.textAlignVertical as string | undefined;
-      if (tav) { style.textAlignVertical = tav; hasData = true; }
-
-      return hasData ? style : undefined;
-    }
-
-    /**
-     * Extract componentProperties from an INSTANCE node.
-     *
-     * Strips Figma hash suffixes (e.g. "Show Label#1231:0" → "Show Label")
-     * and returns undefined when no properties exist.
-     */
-    private extractNodeComponentProperties(
-      node: Record<string, unknown>,
-    ): NodeWithClassifications['componentProperties'] | undefined {
-      const cp = node.componentProperties as
-        Record<string, { type: string; value: unknown }> | undefined;
-      if (!cp || Object.keys(cp).length === 0) return undefined;
-
-      const result: NonNullable<NodeWithClassifications['componentProperties']> = {};
-      for (const [rawName, def] of Object.entries(cp)) {
-        const cleanName = rawName.replace(/#[\d:]+$/, '').trim();
-        const type = def.type as 'VARIANT' | 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP';
-        result[cleanName] = { type, value: def.value };
-      }
-      return result;
-    }
-
-    /**
-     * Classify tokens for a single Figma node using TokenTranslator.
-     *
-     * Collects spacing, radius, and fill-color properties from the node,
-     * translates each via the translator, and sorts results into the
-     * three-tier classification buckets on the node.
-     */
-    private classifyNodeTokens(
-      figmaNode: Record<string, unknown>,
-      node: NodeWithClassifications,
-    ): void {
-      const propertiesToClassify: Array<{
-        property: string;
-        figmaVarName?: string;
-        rawValue: number | string;
-        category: TokenCategory;
-      }> = [];
-
-      // Spacing properties
-      const spacingProps: Array<[string, string]> = [
-        ['paddingTop', 'padding-top'],
-        ['paddingRight', 'padding-right'],
-        ['paddingBottom', 'padding-bottom'],
-        ['paddingLeft', 'padding-left'],
-        ['itemSpacing', 'item-spacing'],
-        ['counterAxisSpacing', 'counter-axis-spacing'],
-      ];
-
-      const boundVars = figmaNode.boundVariables as
-        Record<string, unknown> | undefined;
-      const layoutMode = figmaNode.layoutMode as string | undefined;
-      const nodeType = figmaNode.type as string | undefined;
-      const isLeaf = nodeType === 'TEXT' || nodeType === 'VECTOR'
-        || nodeType === 'ELLIPSE' || nodeType === 'LINE'
-        || nodeType === 'STAR' || nodeType === 'POLYGON';
-
-      for (const [figmaProp, cssProp] of spacingProps) {
-        const value = figmaNode[figmaProp] as number | undefined;
-        if (value == null) continue;
-
-        // Skip irrelevant zero-value defaults
-        if (cssProp === 'counter-axis-spacing' && value === 0) continue;
-        if (cssProp === 'item-spacing' && layoutMode === 'NONE') continue;
-        if (isLeaf && cssProp.startsWith('padding-') && value === 0) continue;
-
-        const varName = this.getBoundVariableName(boundVars, figmaProp);
-        propertiesToClassify.push({
-          property: cssProp,
-          figmaVarName: varName,
-          rawValue: value,
-          category: 'spacing',
-        });
-      }
-
-      // Corner radius
-      const cornerRadius = figmaNode.cornerRadius as number | undefined;
-      if (cornerRadius != null && cornerRadius !== 0) {
-        const varName = this.getBoundVariableName(boundVars, 'cornerRadius');
-        propertiesToClassify.push({
-          property: 'border-radius',
-          figmaVarName: varName,
-          rawValue: cornerRadius,
-          category: 'radius',
-        });
-      }
-
-      // Fill colors
-      const fills = figmaNode.fills as
-        Array<Record<string, unknown>> | undefined;
-      if (fills) {
-        for (const fill of fills) {
-          const color = fill.color as Record<string, number> | undefined;
-          if (!color) continue;
-          const r = Math.round((color.r ?? 0) * 255);
-          const g = Math.round((color.g ?? 0) * 255);
-          const b = Math.round((color.b ?? 0) * 255);
-          const a = (color.a ?? 1) * ((fill.opacity as number) ?? 1);
-          const rgba = `rgba(${r}, ${g}, ${b}, ${a})`;
-
-          const fillBv = fill.boundVariables as
-            Record<string, unknown> | undefined;
-          const varName = this.getBoundVariableName(fillBv, 'color');
-          propertiesToClassify.push({
-            property: 'fill',
-            figmaVarName: varName,
-            rawValue: rgba,
-            category: 'color',
-          });
-        }
-      }
-
-      // Opacity
-      const opacity = figmaNode.opacity as number | undefined;
-      if (opacity != null && opacity !== 1) {
-        const varName = this.getBoundVariableName(boundVars, 'opacity');
-        propertiesToClassify.push({
-          property: 'opacity',
-          figmaVarName: varName,
-          rawValue: opacity,
-          category: 'opacity',
-        });
-      }
-
-      // Stroke weight
-      const strokeWeight = figmaNode.strokeWeight as number | undefined;
-      if (strokeWeight != null && strokeWeight > 0) {
-        const varName = this.getBoundVariableName(boundVars, 'strokeWeight');
-        propertiesToClassify.push({
-          property: 'border-width',
-          figmaVarName: varName,
-          rawValue: strokeWeight,
-          category: 'borderWidth',
-        });
-      }
-
-      // Stroke colors
-      const strokes = figmaNode.strokes as Array<Record<string, unknown>> | undefined;
-      if (strokes) {
-        for (const stroke of strokes) {
-          const c = stroke.color as Record<string, number> | undefined;
-          if (!c) continue;
-          const r = Math.round((c.r ?? 0) * 255);
-          const g = Math.round((c.g ?? 0) * 255);
-          const b = Math.round((c.b ?? 0) * 255);
-          const a = (c.a ?? 1) * ((stroke.opacity as number) ?? 1);
-          const strokeBv = stroke.boundVariables as Record<string, unknown> | undefined;
-          const varName = this.getBoundVariableName(strokeBv, 'color');
-          propertiesToClassify.push({
-            property: 'stroke',
-            figmaVarName: varName,
-            rawValue: `rgba(${r}, ${g}, ${b}, ${a})`,
-            category: 'color',
-          });
-        }
-      }
-
-      // Typography properties (TEXT nodes only)
-      if (nodeType === 'TEXT') {
-        const fontSize = figmaNode.fontSize as number | undefined;
-        if (fontSize != null) {
-          const varName = this.getBoundVariableName(boundVars, 'fontSize');
-          propertiesToClassify.push({
-            property: 'font-size',
-            figmaVarName: varName,
-            rawValue: fontSize,
-            category: 'fontSize',
-          });
-        }
-
-        const fontWeight = figmaNode.fontWeight as number | undefined;
-        if (fontWeight != null) {
-          const varName = this.getBoundVariableName(boundVars, 'fontWeight');
-          propertiesToClassify.push({
-            property: 'font-weight',
-            figmaVarName: varName,
-            rawValue: fontWeight,
-            category: 'fontWeight',
-          });
-        }
-
-        const lh = figmaNode.lineHeight as { value?: number; unit?: string } | undefined;
-        if (lh?.value != null && lh.unit !== 'AUTO') {
-          const varName = this.getBoundVariableName(boundVars, 'lineHeight');
-          propertiesToClassify.push({
-            property: 'line-height',
-            figmaVarName: varName,
-            rawValue: lh.value,
-            category: 'lineHeight',
-          });
-        }
-
-        const ls = figmaNode.letterSpacing as { value?: number } | undefined;
-        if (ls?.value != null && ls.value !== 0) {
-          const varName = this.getBoundVariableName(boundVars, 'letterSpacing');
-          propertiesToClassify.push({
-            property: 'letter-spacing',
-            figmaVarName: varName,
-            rawValue: ls.value,
-            category: 'letterSpacing',
-          });
-        }
-      }
-
-      // Classify each property
-      for (const { property, figmaVarName, rawValue, category } of propertiesToClassify) {
-        const result = this.translator.translate(figmaVarName, rawValue, category);
-        const tier = this.translator.classifyTokenMatch(result);
-
-        // Value-based matches → Unidentified with suggestion (only bindings earn Identified)
-        if (result.matchMethod === 'value' && tier !== 'unidentified') {
-          node.tokenClassifications.unidentified.push({
-            property,
-            rawValue: result.rawValue,
-            reason: figmaVarName ? 'unresolved-binding' : 'value-match',
-            suggestedToken: result.semantic ?? result.primitive ?? result.token,
-            boundVariableId: figmaVarName,
-          });
-        } else if (tier === 'semantic') {
-          node.tokenClassifications.semanticIdentified.push(
-            this.translator.toClassifiedToken(result, property),
-          );
-        } else if (tier === 'primitive') {
-          node.tokenClassifications.primitiveIdentified.push(
-            this.translator.toClassifiedToken(result, property),
-          );
-        } else {
-          node.tokenClassifications.unidentified.push(
-            this.translator.toUnidentifiedValue(result, property),
-          );
-        }
-      }
-    }
-
-    /**
-     * Extract a Figma variable name from a node's boundVariables for a
-     * given property.
-     *
-     * Handles both single-binding objects and array-of-bindings.
-     */
-    private getBoundVariableName(
-      boundVars: Record<string, unknown> | undefined,
-      property: string,
-    ): string | undefined {
-      if (!boundVars) return undefined;
-      const binding = boundVars[property];
-      if (!binding || typeof binding !== 'object') return undefined;
-      const bindingObj = binding as Record<string, unknown>;
-      const entry = Array.isArray(bindingObj) ? bindingObj[0] : bindingObj;
-      if (!entry || typeof entry !== 'object') return undefined;
-      const entryObj = entry as Record<string, unknown>;
-      return entryObj.id as string | undefined;
-    }
-
-    /**
-     * Extract boundVariables from a node's boundVariables object into the map.
-     */
-    private extractBoundVariables(
-      boundVars: Record<string, unknown>,
-      boundVariableMap: Map<string, string>,
-    ): void {
-      for (const [prop, binding] of Object.entries(boundVars)) {
-        if (!binding || typeof binding !== 'object') continue;
-
-        const bindingObj = binding as Record<string, unknown>;
-        const bindingEntries = Array.isArray(bindingObj) ? bindingObj : [bindingObj];
-
-        for (const entry of bindingEntries) {
-          const entryObj = entry as Record<string, unknown>;
-          const varId = entryObj.id as string | undefined;
-          if (varId && !boundVariableMap.has(prop)) {
-            boundVariableMap.set(prop, varId);
-          }
-        }
-      }
-    }
-
-    /**
-     * Recursively walk a node tree to collect all boundVariables.
-     *
-     * Collects from node-level boundVariables and fill-level boundVariables
-     * on all descendants up to maxDepth.
-     */
-    private collectBoundVariablesRecursive(
-      node: Record<string, unknown>,
-      boundVariableMap: Map<string, string>,
-      depth: number,
-      maxDepth: number,
-    ): void {
-      if (depth > maxDepth) return;
-
-      // Node-level boundVariables
-      const boundVars = node.boundVariables as Record<string, unknown> | undefined;
-      if (boundVars) {
-        this.extractBoundVariables(boundVars, boundVariableMap);
-      }
-
-      // Fill-level boundVariables (color bindings inside fills array)
-      const nodeFills = node.fills as Array<Record<string, unknown>> | undefined;
-      if (nodeFills) {
-        for (const fill of nodeFills) {
-          const fillBoundVars = fill.boundVariables as Record<string, unknown> | undefined;
-          if (fillBoundVars) {
-            this.extractBoundVariables(fillBoundVars, boundVariableMap);
-          }
-        }
-      }
-
-      // Recurse into children
-      const children = node.children as Array<Record<string, unknown>> | undefined;
-      if (children) {
-        for (const child of children) {
-          this.collectBoundVariablesRecursive(child, boundVariableMap, depth + 1, maxDepth);
-        }
-      }
-    }
-
-    // -----------------------------------------------------------------------
-    // Bound Variable Batch Resolution (Task 1.5)
-    // -----------------------------------------------------------------------
-
-    /**
-     * Walk a raw Figma node tree and collect all bound variable entries
-     * with full node context.
-     *
-     * Checks spacing properties, cornerRadius, and fill colors for
-     * boundVariables. Returns all entries (not deduplicated) — dedup
-     * happens in batchResolveBoundVariables.
-     *
-     * @param figmaNode - Raw Figma node object from API response
-     * @param depth - Current depth in the tree (root = 0)
-     * @param ancestors - Ancestor node types from root to parent
-     * @returns Array of BoundVariableEntry with full node context
-     * @requirements Req 4 (Bound Variable Batch Resolution)
-     */
-    collectBoundVariableIds(
-      figmaNode: Record<string, unknown>,
-      depth: number = 0,
-      ancestors: string[] = [],
-    ): BoundVariableEntry[] {
-      const entries: BoundVariableEntry[] = [];
-      const nodeId = String(figmaNode.id ?? '');
-      const nodeName = String(figmaNode.name ?? '');
-      const nodeType = String(figmaNode.type ?? 'FRAME');
-
-      const boundVars = figmaNode.boundVariables as
-        Record<string, unknown> | undefined;
-
-      // Spacing properties
-      const spacingProps: Array<[string, string]> = [
-        ['paddingTop', 'padding-top'],
-        ['paddingRight', 'padding-right'],
-        ['paddingBottom', 'padding-bottom'],
-        ['paddingLeft', 'padding-left'],
-        ['itemSpacing', 'item-spacing'],
-        ['counterAxisSpacing', 'counter-axis-spacing'],
-      ];
-
-      for (const [figmaProp, cssProp] of spacingProps) {
-        const value = figmaNode[figmaProp] as number | undefined;
-        if (value == null) continue;
-        const varId = this.getBoundVariableName(boundVars, figmaProp);
-        if (varId) {
-          entries.push({
-            variableId: varId,
-            property: cssProp,
-            nodeId,
-            nodeName,
-            ancestorChain: ancestors,
-            rawValue: value,
-            category: 'spacing',
-          });
-        }
-      }
-
-      // Corner radius
-      const cornerRadius = figmaNode.cornerRadius as number | undefined;
-      if (cornerRadius != null) {
-        const varId = this.getBoundVariableName(boundVars, 'cornerRadius');
-        if (varId) {
-          entries.push({
-            variableId: varId,
-            property: 'border-radius',
-            nodeId,
-            nodeName,
-            ancestorChain: ancestors,
-            rawValue: cornerRadius,
-            category: 'radius',
-          });
-        }
-      }
-
-      // Fill colors
-      const fills = figmaNode.fills as
-        Array<Record<string, unknown>> | undefined;
-      if (fills) {
-        for (const fill of fills) {
-          const color = fill.color as Record<string, number> | undefined;
-          if (!color) continue;
-          const r = Math.round((color.r ?? 0) * 255);
-          const g = Math.round((color.g ?? 0) * 255);
-          const b = Math.round((color.b ?? 0) * 255);
-          const a = (color.a ?? 1) * ((fill.opacity as number) ?? 1);
-          const rgba = `rgba(${r}, ${g}, ${b}, ${a})`;
-
-          const fillBv = fill.boundVariables as
-            Record<string, unknown> | undefined;
-          const varId = this.getBoundVariableName(fillBv, 'color');
-          if (varId) {
-            entries.push({
-              variableId: varId,
-              property: 'fill',
-              nodeId,
-              nodeName,
-              ancestorChain: ancestors,
-              rawValue: rgba,
-              category: 'color',
-            });
-          }
-        }
-      }
-
-      // Opacity
-      const opacity = figmaNode.opacity as number | undefined;
-      if (opacity != null && opacity !== 1) {
-        const varId = this.getBoundVariableName(boundVars, 'opacity');
-        if (varId) {
-          entries.push({
-            variableId: varId, property: 'opacity', nodeId, nodeName,
-            ancestorChain: ancestors, rawValue: opacity, category: 'opacity',
-          });
-        }
-      }
-
-      // Stroke weight
-      const strokeWeight = figmaNode.strokeWeight as number | undefined;
-      if (strokeWeight != null && strokeWeight > 0) {
-        const varId = this.getBoundVariableName(boundVars, 'strokeWeight');
-        if (varId) {
-          entries.push({
-            variableId: varId, property: 'border-width', nodeId, nodeName,
-            ancestorChain: ancestors, rawValue: strokeWeight, category: 'borderWidth',
-          });
-        }
-      }
-
-      // Stroke colors
-      const strokes = figmaNode.strokes as Array<Record<string, unknown>> | undefined;
-      if (strokes) {
-        for (const stroke of strokes) {
-          const sc = stroke.color as Record<string, number> | undefined;
-          if (!sc) continue;
-          const sr = Math.round((sc.r ?? 0) * 255);
-          const sg = Math.round((sc.g ?? 0) * 255);
-          const sb = Math.round((sc.b ?? 0) * 255);
-          const sa = (sc.a ?? 1) * ((stroke.opacity as number) ?? 1);
-          const strokeBv = stroke.boundVariables as Record<string, unknown> | undefined;
-          const varId = this.getBoundVariableName(strokeBv, 'color');
-          if (varId) {
-            entries.push({
-              variableId: varId, property: 'stroke', nodeId, nodeName,
-              ancestorChain: ancestors, rawValue: `rgba(${sr}, ${sg}, ${sb}, ${sa})`, category: 'color',
-            });
-          }
-        }
-      }
-
-      // Typography bindings (TEXT nodes only)
-      if (nodeType === 'TEXT') {
-        const typoProps: Array<[string, string, TokenCategory]> = [
-          ['fontSize', 'font-size', 'fontSize'],
-          ['fontWeight', 'font-weight', 'fontWeight'],
-          ['lineHeight', 'line-height', 'lineHeight'],
-          ['letterSpacing', 'letter-spacing', 'letterSpacing'],
-        ];
-        for (const [figmaProp, cssProp, cat] of typoProps) {
-          const varId = this.getBoundVariableName(boundVars, figmaProp);
-          if (varId) {
-            const raw = figmaNode[figmaProp];
-            const rawVal = typeof raw === 'object' && raw !== null
-              ? (raw as Record<string, unknown>).value ?? 0
-              : raw ?? 0;
-            entries.push({
-              variableId: varId, property: cssProp, nodeId, nodeName,
-              ancestorChain: ancestors, rawValue: rawVal as number, category: cat,
-            });
-          }
-        }
-      }
-
-      // Recurse into children
-      const children = figmaNode.children as
-        Array<Record<string, unknown>> | undefined;
-      if (children) {
-        const newAncestors = [...ancestors, nodeType];
-        for (const child of children) {
-          entries.push(
-            ...this.collectBoundVariableIds(child, depth + 1, newAncestors),
-          );
-        }
-      }
-
-      return entries;
-    }
-
-    /**
-     * Batch-resolve bound variable IDs via the Figma Plugin API.
-     *
-     * Deduplicates variable IDs, calls figma_execute to resolve names,
-     * and returns a map of resolved names plus an array of unresolved
-     * bindings with full node context.
-     *
-     * @param fileKey - The Figma file key
-     * @param entries - BoundVariableEntry[] collected from the node tree
-     * @returns Object with resolved map and unresolvedBindings array
-     * @requirements Req 4 (Bound Variable Batch Resolution)
-     */
-    async batchResolveBoundVariables(
-      fileKey: string,
-      entries: BoundVariableEntry[],
-    ): Promise<{
-      resolved: Map<string, string>;
-      unresolvedBindings: UnresolvedBinding[];
-    }> {
-      const resolved = new Map<string, string>();
-      const unresolvedBindings: UnresolvedBinding[] = [];
-
-      if (entries.length === 0) {
-        return { resolved, unresolvedBindings };
-      }
-
-      // Deduplicate variable IDs
-      const uniqueIds = [...new Set(entries.map(e => e.variableId))];
-
-      // Build Plugin API code
-      const code = `
-      const results = {};
-      const collections = {};
-      for (const id of ${JSON.stringify(uniqueIds)}) {
-        try {
-          const v = await figma.variables.getVariableByIdAsync(id);
-          if (v) {
-            let collectionName = collections[v.variableCollectionId];
-            if (!collectionName) {
-              try {
-                const c = await figma.variables.getVariableCollectionByIdAsync(v.variableCollectionId);
-                collectionName = c ? c.name : '';
-              } catch(e) { collectionName = ''; }
-              collections[v.variableCollectionId] = collectionName;
-            }
-            results[id] = { name: v.name, collection: collectionName };
-          }
-        } catch (e) {
-          // Variable not found — skip
-        }
-      }
-      return results;
-      `.trim();
-
-      try {
-        const result = await this.consoleMcp.execute(fileKey, code);
-
-        // Parse the result — may be wrapped in { result: { ... } } or { result: "..." }
-        let resolvedData: Record<string, { name: string; collection?: string }> = {};
-        if (result && typeof result === 'object') {
-          const raw = result as Record<string, unknown>;
-          let inner = raw.result ?? raw;
-          if (typeof inner === 'string') {
-            try { inner = JSON.parse(inner); } catch { /* not JSON */ }
-          }
-          if (inner && typeof inner === 'object') {
-            resolvedData = inner as typeof resolvedData;
-          }
-        }
-
-        // Populate resolved map
-        for (const [varId, info] of Object.entries(resolvedData)) {
-          if (info?.name) {
-            resolved.set(varId, info.name);
-          }
-        }
-
-        // Build unresolvedBindings for IDs that failed
-        for (const entry of entries) {
-          if (!resolved.has(entry.variableId)) {
-            unresolvedBindings.push({
-              variableId: entry.variableId,
-              property: entry.property,
-              nodeId: entry.nodeId,
-              nodeName: entry.nodeName,
-              ancestorChain: entry.ancestorChain,
-              reason: 'api-resolution-failed' as UnresolvedBindingReason,
-            });
-          }
-        }
-      } catch {
-        // API call failed entirely — all entries are unresolved
-        for (const entry of entries) {
-          unresolvedBindings.push({
-            variableId: entry.variableId,
-            property: entry.property,
-            nodeId: entry.nodeId,
-            nodeName: entry.nodeName,
-            ancestorChain: entry.ancestorChain,
-            reason: 'api-resolution-failed' as UnresolvedBindingReason,
-          });
-        }
-      }
-
-      return { resolved, unresolvedBindings };
-    }
-
-    /**
-     * Walk a NodeWithClassifications tree and reclassify unidentified values
-     * that have a boundVariableId using resolved variable names.
-     *
-     * For each unidentified value with a boundVariableId found in the
-     * resolvedMap, re-translates using the resolved name and moves
-     * successfully classified tokens from unidentified to semantic or
-     * primitive. Mutates the tree in place.
-     *
-     * @param nodeTree - Root of the classified node tree
-     * @param resolvedMap - Map of variableId → resolved variable name
-     * @requirements Req 4 (Bound Variable Batch Resolution)
-     */
-    reclassifyWithResolvedBindings(
-      nodeTree: NodeWithClassifications,
-      resolvedMap: Map<string, string>,
-    ): void {
-      const { unidentified } = nodeTree.tokenClassifications;
-      const remaining: typeof unidentified = [];
-
-      for (const entry of unidentified) {
-        if (entry.boundVariableId && resolvedMap.has(entry.boundVariableId)) {
-          const resolvedName = resolvedMap.get(entry.boundVariableId)!;
-
-          // Use translateByBinding directly — no enrichResponse promotion.
-          // The designer bound to THIS variable; honour the tier it lives at.
-          const bindingResult = this.translator.translateByBinding(resolvedName);
-          if (bindingResult.confidence === 'no-match') {
-            // Binding resolved to a name but no matching token in DTCG —
-            // likely a component-level variable that needs to be created.
-            entry.reason = 'no-token-match';
-            entry.suggestedToken = resolvedName;
-            remaining.push(entry);
-            continue;
-          }
-
-          // Determine tier from the token itself (alias = semantic, raw = primitive)
-          const tokenObj = this.translator.lookupToken(bindingResult.token);
-          const isAlias = tokenObj && typeof tokenObj.$value === 'string'
-            && tokenObj.$value.startsWith('{') && tokenObj.$value.endsWith('}');
-
-          const classified: ClassifiedToken = {
-            property: entry.property,
-            semanticToken: isAlias ? bindingResult.token : undefined,
-            primitiveToken: isAlias
-              ? (tokenObj!.$value as string).slice(1, -1)
-              : bindingResult.token,
-            rawValue: bindingResult.rawValue,
-            matchMethod: 'binding',
-            confidence: 'exact',
-          };
-
-          if (isAlias) {
-            nodeTree.tokenClassifications.semanticIdentified.push(classified);
-          } else {
-            nodeTree.tokenClassifications.primitiveIdentified.push(classified);
-          }
-        } else {
-          remaining.push(entry);
-        }
-      }
-
-      nodeTree.tokenClassifications.unidentified = remaining;
-
-      // Recurse into children
-      for (const child of nodeTree.children) {
-        this.reclassifyWithResolvedBindings(child, resolvedMap);
-      }
-    }
-
-    /**
-     * Collect fills from deep children that have boundVariables on their fills.
-     *
-     * These represent designer-intentional color assignments (variables bound
-     * to fill colors) that may differ from the parent component's fills.
-     * Returns deduplicated fills with their hex color values.
-     */
-    private collectDeepFills(
-      nodes: Array<Record<string, unknown>>,
-    ): Array<{ type: string; color?: string; opacity?: number }> {
-      const result: Array<{ type: string; color?: string; opacity?: number }> = [];
-      const seenColors = new Set<string>();
-
-      const walk = (node: Record<string, unknown>, depth: number): void => {
-        if (depth > 4) return;
-
-        const nodeFills = node.fills as Array<Record<string, unknown>> | undefined;
-        if (nodeFills) {
-          for (const fill of nodeFills) {
-            // Only collect fills that have boundVariables (designer intent)
-            const fillBv = fill.boundVariables as Record<string, unknown> | undefined;
-            if (!fillBv || Object.keys(fillBv).length === 0) continue;
-
-            const color = fill.color as Record<string, number> | undefined;
-            if (!color) continue;
-
-            const r = Math.round((color.r ?? 0) * 255);
-            const g = Math.round((color.g ?? 0) * 255);
-            const b = Math.round((color.b ?? 0) * 255);
-            const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
-
-            if (!seenColors.has(hex)) {
-              seenColors.add(hex);
-              result.push({
-                type: String(fill.type ?? 'SOLID'),
-                color: hex,
-                opacity: fill.opacity as number | undefined,
-              });
-            }
-          }
-        }
-
-        const children = node.children as Array<Record<string, unknown>> | undefined;
-        if (children) {
-          for (const child of children) {
-            walk(child, depth + 1);
-          }
-        }
-      };
-
-      for (const node of nodes) {
-        walk(node, 0);
-      }
-
-      return result;
-    }
-
-
-
-
-  // -------------------------------------------------------------------------
-  // Design context parsing helpers
-  // -------------------------------------------------------------------------
-
-  /** Extract component name from generated code. */
-  private extractComponentName(code: string): string {
-    // Match class/component name patterns
-    const classMatch = code.match(/class\s+(\w+)/);
-    if (classMatch) return classMatch[1];
-
-    const componentMatch = code.match(/(?:export\s+)?(?:default\s+)?(?:function|const)\s+(\w+)/);
-    if (componentMatch) return componentMatch[1];
-
-    // Try HTML custom element tag
-    const tagMatch = code.match(/<([a-z][\w-]*)/);
-    if (tagMatch) return tagMatch[1];
-
-    return '';
-  }
-
-  /** Extract description from code comments or JSDoc. */
-  private extractDescription(code: string): string {
-    const jsdocMatch = code.match(/\/\*\*\s*\n?\s*\*?\s*(.+?)(?:\n|\*\/)/);
-    if (jsdocMatch) return jsdocMatch[1].trim();
-
-    const commentMatch = code.match(/\/\/\s*(.+)/);
-    if (commentMatch) return commentMatch[1].trim();
-
-    return '';
-  }
-
-  /** Extract variant definitions from code. */
-  private extractVariants(code: string): VariantDefinition[] {
-    const variants: VariantDefinition[] = [];
-
-    // Match variant property patterns (e.g. variant="primary", size="large")
-    const variantPattern = /(?:variant|type|size|state)\s*[=:]\s*["'](\w+)["']/gi;
-    const seen = new Set<string>();
-    let match: RegExpExecArray | null;
-
-    while ((match = variantPattern.exec(code)) !== null) {
-      const propName = match[0].split(/[=:]/)[0].trim().toLowerCase();
-      const value = match[1];
-      const key = `${propName}=${value}`;
-      if (!seen.has(key)) {
-        seen.add(key);
-        variants.push({ name: key, properties: { [propName]: value } });
-      }
-    }
-
-    return variants;
-  }
-
-  /** Extract visual states from code (hover, focus, disabled, pressed). */
-  private extractStates(code: string): StateDefinition[] {
-    const stateKeywords = ['hover', 'focus', 'disabled', 'pressed', 'active', 'selected'];
-    const states: StateDefinition[] = [];
-    const codeLower = code.toLowerCase();
-
-    for (const keyword of stateKeywords) {
-      if (codeLower.includes(keyword)) {
-        states.push({ name: keyword });
-      }
-    }
-
-    return states;
-  }
-
-  /** Extract component properties from code. */
-  private extractProperties(code: string): PropertyDefinition[] {
-    const properties: PropertyDefinition[] = [];
-
-    // Match TypeScript interface/type property patterns
-    const propPattern = /(\w+)\s*[?]?\s*:\s*(string|number|boolean|'[^']*'(?:\s*\|\s*'[^']*')*)/g;
-    const seen = new Set<string>();
-    let match: RegExpExecArray | null;
-
-    while ((match = propPattern.exec(code)) !== null) {
-      const name = match[1];
-      const type = match[2];
-      if (!seen.has(name)) {
-        seen.add(name);
-        properties.push({ name, type });
-      }
-    }
-
-    return properties;
-  }
-
-  /** Extract layout information from code. */
-  private extractLayout(code: string): ExtractedLayout {
-    const codeLower = code.toLowerCase();
-
-    let mode: ExtractedLayout['mode'] = 'none';
-    if (codeLower.includes('flex-direction: row') || codeLower.includes('flexdirection: row') || codeLower.includes('display: flex')) {
-      mode = 'horizontal';
-    }
-    if (codeLower.includes('flex-direction: column') || codeLower.includes('flexdirection: column')) {
-      mode = 'vertical';
-    }
-
-    const layout: ExtractedLayout = { mode };
-
-    // Extract gap/spacing
-    const gapMatch = code.match(/gap:\s*(\d+)/);
-    if (gapMatch) {
-      layout.itemSpacing = parseInt(gapMatch[1], 10);
-    }
-
-    // Extract padding
-    const paddingMatch = code.match(/padding:\s*(\d+)(?:px)?(?:\s+(\d+)(?:px)?)?(?:\s+(\d+)(?:px)?)?(?:\s+(\d+)(?:px)?)?/);
-    if (paddingMatch) {
-      const values = [paddingMatch[1], paddingMatch[2], paddingMatch[3], paddingMatch[4]]
-        .filter(Boolean)
-        .map(Number);
-
-      if (values.length === 1) {
-        layout.padding = { top: values[0], right: values[0], bottom: values[0], left: values[0] };
-      } else if (values.length === 2) {
-        layout.padding = { top: values[0], right: values[1], bottom: values[0], left: values[1] };
-      } else if (values.length === 4) {
-        layout.padding = { top: values[0], right: values[1], bottom: values[2], left: values[3] };
-      }
-    }
-
-    return layout;
-  }
-
-  /** Extract states from metadata XML. */
-  private extractStatesFromMetadata(xml: string): StateDefinition[] {
-    const stateKeywords = ['hover', 'focus', 'disabled', 'pressed', 'active', 'selected'];
-    const states: StateDefinition[] = [];
-    const xmlLower = xml.toLowerCase();
-
-    for (const keyword of stateKeywords) {
-      if (xmlLower.includes(keyword)) {
-        states.push({ name: keyword });
-      }
-    }
-
-    return states;
-  }
-
-  // -------------------------------------------------------------------------
-  // readTokenBindings (Task 3.3)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Read all token bindings (Figma variables) from a file.
-   *
-   * Uses figma-console-mcp via `consoleMcp.getVariables()` which calls
-   * `figma_get_token_values`. Maps results to `TokenBinding[]` with alias
-   * detection based on `valuesByMode` containing `{ aliasOf: string }`.
-   *
-   * @param fileKey - The Figma file key.
-   * @returns Array of token bindings with alias relationships detected.
-   */
-  async readTokenBindings(fileKey: string): Promise<TokenBinding[]> {
-    const variables = await this.consoleMcp.getVariables(fileKey);
-
-    if (!variables || variables.length === 0) {
-      return [];
-    }
-
-    // Build a lookup of variable names for alias target resolution
-    const nameById = new Map<string, string>();
-    for (const v of variables) {
-      if (v.id) {
-        nameById.set(v.id, v.name);
-      }
-    }
-
-    return variables.map((v) => {
-      // Detect alias: valuesByMode values shaped { aliasOf: string }
-      const { isAlias, aliasTarget } = this.detectAlias(v.valuesByMode, nameById);
-
-      // collectionName is available at runtime from figma_get_token_values
-      // even though the FigmaVariable type doesn't declare it
-      const raw = v as unknown as Record<string, unknown>;
-      const collectionName = typeof raw.collectionName === 'string'
-        ? raw.collectionName
-        : this.inferCollectionFromName(v.name, isAlias);
-
-      return {
-        variableName: v.name,
-        variableId: v.id ?? '',
-        collectionName,
-        resolvedType: v.resolvedType,
-        valuesByMode: v.valuesByMode,
-        isAlias,
-        aliasTarget,
-      };
-    });
-  }
-
-  /**
-   * Detect whether a variable is an alias by inspecting its mode values.
-   *
-   * Figma aliases are represented as `{ aliasOf: string }` in valuesByMode.
-   * Returns the first alias target found (semantic tokens typically alias
-   * the same primitive across all modes).
-   */
-  private detectAlias(
-    valuesByMode: Record<string, unknown>,
-    nameById: Map<string, string>,
-  ): { isAlias: boolean; aliasTarget?: string } {
-    for (const modeValue of Object.values(valuesByMode)) {
-      if (
-        modeValue &&
-        typeof modeValue === 'object' &&
-        'aliasOf' in (modeValue as Record<string, unknown>)
-      ) {
-        const aliasRef = (modeValue as { aliasOf: string }).aliasOf;
-        // aliasOf may be a variable name or an ID — resolve via lookup
-        const resolved = nameById.get(aliasRef) ?? aliasRef;
-        return { isAlias: true, aliasTarget: resolved };
-      }
-    }
-    return { isAlias: false };
-  }
-
-  /**
-   * Infer collection name from variable name when not provided by MCP.
-   *
-   * Heuristic: variables with dot-separated semantic paths (e.g.
-   * "color.primary", "color.feedback.success.text") are Semantics;
-   * simple group/value names (e.g. "space/100", "color/purple/300")
-   * are Primitives.
-   */
-  private inferCollectionFromName(name: string, isAlias: boolean): string {
-    if (isAlias) return 'Semantics';
-    // Semantic tokens use dot notation in their Figma names (pushed via 054a)
-    // e.g. "color.primary", "color.feedback.success.text"
-    if (name.includes('.')) return 'Semantics';
-    // Primitive tokens use slash notation: "space/100", "color/purple/300"
-    return 'Primitives';
-  }
-
-  /**
-   * Read Figma styles (effect and text) from a file via figma-console-mcp.
-   *
-   * Calls `consoleMcp.getStyles(fileKey)` which invokes `figma_get_styles`,
-   * then maps results to `FigmaStyle[]`. Effect styles represent shadows/blurs;
-   * text styles represent typography.
-   *
-   * @param fileKey - The Figma file key.
-   * @returns Array of FigmaStyle objects separated by type.
-   * @requirements Req 3 (Composite Token Reconstruction)
-   */
-  async readStyles(fileKey: string): Promise<FigmaStyle[]> {
-    const rawStyles = await this.consoleMcp.getStyles(fileKey);
-
-    if (!rawStyles || rawStyles.length === 0) {
-      return [];
-    }
-
-    return rawStyles.map((s) => ({
-      name: s.name,
-      type: s.type,
-      properties: s.properties,
-    }));
-  }
-
-  // -------------------------------------------------------------------------
-  // queryContext (Task 3.5)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Determine the component family from a component name and query
-   * DesignerPunk MCP for family pattern and existing component status.
-   *
-   * Family extraction uses PascalCase heuristics:
-   *   "ButtonCTA"       → "Button"
-   *   "InputTextBase"   → "Input"
-   *   "IconBase"        → "Icon"
-   *   "ContainerBase"   → "Container"
-   *
-   * Delegates to VariantAnalyzer's `queryFamilyPattern()` and
-   * `queryExistingComponents()` for the actual MCP queries.
-   *
-   * @param componentName - The Figma component name (e.g. "ButtonCTA").
-   * @returns ExtractionContext with family pattern and existing components.
-   * @requirements Req 1 (DesignExtractor), Req 4 (Context-Aware Variant Mapping)
-   */
-  async queryContext(componentName: string): Promise<ExtractionContext> {
-    const familyName = this.extractFamilyName(componentName);
-
-    const [familyPattern, existingComponents] = await Promise.all([
-      this.analyzer.queryFamilyPattern(familyName),
-      this.analyzer.queryExistingComponents(familyName),
-    ]);
-
-    return { familyPattern, existingComponents };
-  }
-
-  /**
-   * Extract the family name from a PascalCase component name.
-   *
-   * Splits on uppercase boundaries and returns the first segment.
-   * Handles common suffixes like "Base", "CTA", etc.
-   *
-   * Examples:
-   *   "ButtonCTA"       → "Button"
-   *   "InputTextBase"   → "Input"
-   *   "IconBase"        → "Icon"
-   *   "container-base"  → "Container" (kebab-case fallback)
-   *   "Button"          → "Button"
-   */
-  private extractFamilyName(componentName: string): string {
-    // Handle kebab-case (e.g. "button-cta", "input-text-base")
-    if (componentName.includes('-')) {
-      const first = componentName.split('-')[0];
-      return first.charAt(0).toUpperCase() + first.slice(1).toLowerCase();
-    }
-
-    // PascalCase: split on uppercase boundaries
-    const segments = componentName.replace(/([a-z])([A-Z])/g, '$1 $2').split(' ');
-    return segments[0];
-  }
-
-  // -------------------------------------------------------------------------
-  // translateTokens (Task 3.6)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Translate all component properties to DesignerPunk token references.
-   *
-   * Builds a binding lookup map from the token bindings, then iterates
-   * over the component's layout, color, typography, radius, and shadow
-   * properties. For each property, checks if a variable binding exists
-   * and delegates to `translator.translate()` with binding-first strategy.
-   *
-   * Tracks no-match values for pause reporting in the extraction confidence.
-   *
-   * @param component - The extracted Figma component with layout and raw data.
-   * @param bindings - Token bindings read from figma-console-mcp.
-   * @returns Aggregated TokenUsage with all translated references.
-   * @requirements Req 2 (TokenTranslator Implementation)
-   */
-  translateTokens(
-    component: ExtractedComponent,
-    bindings: TokenBinding[],
-  ): TokenUsage {
-    // Build binding lookup: variableName → TokenBinding
-    const bindingMap = new Map<string, TokenBinding>();
-    for (const binding of bindings) {
-      bindingMap.set(binding.variableName, binding);
-    }
-
-    // Build variable ID → variable name lookup for resolving boundVariables
-    const nameById = new Map<string, string>();
-    for (const binding of bindings) {
-      if (binding.variableId) {
-        nameById.set(binding.variableId, binding.variableName);
-      }
-    }
-
-    const usage: TokenUsage = {
-      spacing: [],
-      colors: [],
-      typography: [],
-      radius: [],
-      shadows: [],
-    };
-
-    // --- Direct boundVariable translation (highest confidence path) ---
-    // When Console MCP provides boundVariables from component children,
-    // we can resolve variable IDs directly to token names without value scanning.
-    const bvMap = component.boundVariableMap;
-    // Track which layout properties were resolved via boundVariables so we
-    // can fall through to value-based matching for the rest.
-    const resolvedByBinding = new Set<string>();
-
-    if (bvMap && bvMap.size > 0) {
-      // Mapping of Figma boundVariable property names to our categories
-      const spacingProps: Record<string, string> = {
-        paddingLeft: 'padding-left',
-        paddingRight: 'padding-right',
-        paddingTop: 'padding-top',
-        paddingBottom: 'padding-bottom',
-        itemSpacing: 'item-spacing',
-      };
-      const radiusProps: Record<string, string> = {
-        topLeftRadius: 'border-radius-top-left',
-        topRightRadius: 'border-radius-top-right',
-        bottomLeftRadius: 'border-radius-bottom-left',
-        bottomRightRadius: 'border-radius-bottom-right',
-        cornerRadius: 'border-radius',
-      };
-      const colorProps: Record<string, string> = {
-        color: 'fill',
-      };
-
-      for (const [figmaProp, varId] of bvMap) {
-        const varName = nameById.get(varId);
-        if (!varName) continue; // Variable ID not found in bindings
-
-        const cssProperty = spacingProps[figmaProp] ?? radiusProps[figmaProp] ?? colorProps[figmaProp];
-        if (!cssProperty) continue; // Unknown property — skip
-
-        let category: TokenCategory;
-        if (spacingProps[figmaProp]) category = 'spacing';
-        else if (radiusProps[figmaProp]) category = 'radius';
-        else category = 'color';
-
-        const result = this.translator.translate(varName, 0, category);
-
-        const ref: TokenReference = {
-          property: cssProperty,
-          token: result.token,
-          confidence: result.confidence,
-          matchMethod: 'binding',
-          primitive: result.primitive,
-          semantic: result.semantic,
-          delta: result.delta,
-          rawValue: result.rawValue,
-          suggestion: result.suggestion,
-        };
-
-        if (category === 'spacing') {
-          usage.spacing.push(ref);
-          resolvedByBinding.add(cssProperty);
-        } else if (category === 'radius') {
-          usage.radius.push(ref);
-          resolvedByBinding.add(cssProperty);
-        } else {
-          usage.colors.push(ref);
-        }
-      }
-    }
-
-    // --- Layout-based spacing (fills gaps not covered by boundVariables) ---
-    // Always attempt layout-based translation for properties that weren't
-    // resolved via direct boundVariable binding above.
-    {
-      const layout = component.layout;
-
-      if (layout.itemSpacing != null && !resolvedByBinding.has('item-spacing')) {
-        const ref = this.translateProperty(
-          'item-spacing', layout.itemSpacing, 'spacing', bindingMap,
-        );
-        usage.spacing.push(ref);
-      }
-
-      if (layout.padding) {
-        const sides: Array<[string, number | undefined]> = [
-          ['padding-top', layout.padding.top],
-          ['padding-right', layout.padding.right],
-          ['padding-bottom', layout.padding.bottom],
-          ['padding-left', layout.padding.left],
-        ];
-        for (const [prop, value] of sides) {
-          if (value != null && !resolvedByBinding.has(prop)) {
-            usage.spacing.push(
-              this.translateProperty(prop, value, 'spacing', bindingMap),
-            );
-          }
-        }
-      }
-
-      // Corner radius from structured data (when not resolved via boundVariable)
-      if (component.cornerRadius != null && usage.radius.length === 0) {
-        usage.radius.push(
-          this.translateProperty('border-radius', component.cornerRadius, 'radius', bindingMap),
-        );
-      }
-    }
-
-    // --- Fills from structured data (when no rawDesignContext) ---
-    if (component.fills && component.fills.length > 0 && !component.rawDesignContext) {
-      for (const fill of component.fills) {
-        if (fill.color) {
-          usage.colors.push(
-            this.translateProperty('fill', fill.color, 'color', bindingMap),
-          );
-        }
-      }
-    }
-
-    // --- Parse raw design context for colors, typography, radius, shadows ---
-    const raw = component.rawDesignContext ?? '';
-
-    // Colors: match CSS color properties
-    const colorPatterns = [
-      { pattern: /(?:background|background-color)\s*:\s*([^;}\n]+)/gi, prop: 'background' },
-      { pattern: /(?:^|[^-])color\s*:\s*([^;}\n]+)/gim, prop: 'color' },
-      { pattern: /border-color\s*:\s*([^;}\n]+)/gi, prop: 'border-color' },
-      { pattern: /fill\s*:\s*([^;}\n]+)/gi, prop: 'fill' },
-      { pattern: /stroke\s*:\s*([^;}\n]+)/gi, prop: 'stroke' },
-    ];
-    for (const { pattern, prop } of colorPatterns) {
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(raw)) !== null) {
-        const value = match[1].trim();
-        if (this.isColorValue(value)) {
-          usage.colors.push(
-            this.translateProperty(prop, value, 'color', bindingMap),
-          );
-        }
-      }
-    }
-
-    // Typography: font-size, font-family, font-weight, line-height
-    const typographyPatterns = [
-      { pattern: /font-size\s*:\s*([^;}\n]+)/gi, prop: 'font-size' },
-      { pattern: /font-weight\s*:\s*([^;}\n]+)/gi, prop: 'font-weight' },
-      { pattern: /line-height\s*:\s*([^;}\n]+)/gi, prop: 'line-height' },
-    ];
-    for (const { pattern, prop } of typographyPatterns) {
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(raw)) !== null) {
-        const value = match[1].trim();
-        usage.typography.push(
-          this.translateProperty(prop, value, 'typography', bindingMap),
-        );
-      }
-    }
-
-    // Radius: border-radius
-    const radiusPattern = /border-radius\s*:\s*([^;}\n]+)/gi;
-    let radiusMatch: RegExpExecArray | null;
-    while ((radiusMatch = radiusPattern.exec(raw)) !== null) {
-      const value = radiusMatch[1].trim();
-      usage.radius.push(
-        this.translateProperty('border-radius', value, 'radius', bindingMap),
-      );
-    }
-
-    // Shadows: box-shadow
-    const shadowPattern = /box-shadow\s*:\s*([^;}\n]+)/gi;
-    let shadowMatch: RegExpExecArray | null;
-    while ((shadowMatch = shadowPattern.exec(raw)) !== null) {
-      const value = shadowMatch[1].trim();
-      usage.shadows.push(
-        this.translateProperty('box-shadow', value, 'shadow', bindingMap),
-      );
-    }
-
-    return usage;
-  }
-
-  /**
-   * Translate a single property value to a token reference.
-   *
-   * Checks the binding map for a variable whose resolved value matches
-   * the raw value, then delegates to `translator.translate()`.
-   */
-  private translateProperty(
-    property: string,
-    rawValue: number | string,
-    category: TokenCategory,
-    bindingMap: Map<string, TokenBinding>,
-  ): TokenReference {
-    // Try to find a binding whose value matches this raw value
-    const bindingName = this.findBindingForValue(rawValue, category, bindingMap);
-
-    const result: TranslationResult = this.translator.translate(
-      bindingName, rawValue, category,
-    );
-
-    return {
-      property,
-      token: result.token,
-      confidence: result.confidence,
-      matchMethod: result.matchMethod,
-      primitive: result.primitive,
-      semantic: result.semantic,
-      delta: result.delta,
-      rawValue: result.rawValue,
-      suggestion: result.suggestion,
-    };
-  }
-
-  /**
-   * Find a binding variable name whose resolved value matches the given raw value.
-   *
-   * Searches the binding map for a variable of the matching type whose
-   * first mode value equals the raw value. Returns the variable name
-   * (for binding-first translation) or undefined if no binding found.
-   */
-  private findBindingForValue(
-    rawValue: number | string,
-    category: TokenCategory,
-    bindingMap: Map<string, TokenBinding>,
-  ): string | undefined {
-    const expectedType = category === 'color' ? 'COLOR' : 'FLOAT';
-
-    for (const [name, binding] of bindingMap) {
-      if (binding.resolvedType !== expectedType) continue;
-
-      // Check first mode value
-      const modeValues = Object.values(binding.valuesByMode);
-      if (modeValues.length === 0) continue;
-
-      const firstValue = modeValues[0];
-
-      // Skip alias objects — they don't carry resolved values
-      if (firstValue != null && typeof firstValue === 'object') continue;
-
-      if (typeof rawValue === 'number' && firstValue === rawValue) {
-        return name;
-      }
-      if (String(rawValue) === String(firstValue)) {
-        return name;
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Check if a CSS value looks like a color (hex, rgb, rgba, hsl, named).
-   */
-  /**
-     * Check if a CSS value looks like a color (hex, rgb, rgba, hsl, named).
-     */
-    private isColorValue(value: string): boolean {
-      const v = value.toLowerCase().trim();
-
-      // Exclude CSS keywords and non-color values
-      const nonColorKeywords = new Set([
-        'inherit', 'initial', 'unset', 'revert', 'none', 'transparent',
-        'currentcolor', 'auto', 'normal',
-      ]);
-      if (nonColorKeywords.has(v)) return false;
-
-      // Exclude url(), var() (non-color), calc(), etc.
-      if (v.startsWith('url(') || v.startsWith('calc(')) return false;
-
-      return (
-        v.startsWith('#') ||
-        v.startsWith('rgb') ||
-        v.startsWith('hsl') ||
-        v.startsWith('var(--color')
-      );
-    }
-
-  // -------------------------------------------------------------------------
-  // reconstructCompositeTokens (Task 3.7)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Reconstruct composite token references from Figma styles.
-   *
-   * Primary path: match style names directly to DTCG composite tokens
-   * (names match because 054a pushed them with known names).
-   *
-   * Fallback path: if style name doesn't match, attempt property-by-property
-   * reconstruction by searching the DTCG token tree for tokens whose
-   * composite sub-values match the style's raw properties.
-   *
-   * Unmatched composites are flagged with ⚠️ confidence for Ada's review.
-   *
-   * @param styles - Figma styles read via figma-console-mcp.
-   * @param dtcgTokens - The loaded DTCG token file for lookup.
-   * @returns TokenReference[] with matched composite tokens.
-   * @requirements Req 3 (Composite Token Reconstruction)
-   */
-  reconstructCompositeTokens(
-    styles: FigmaStyle[],
-    dtcgTokens: DTCGTokenFile,
-  ): TokenReference[] {
-    const results: TokenReference[] = [];
-
-    for (const style of styles) {
-      const category = style.type === 'EFFECT' ? 'shadow' : 'typography';
-
-      // Primary path: direct name match against DTCG token tree
-      const directMatch = this.lookupCompositeToken(style.name, category, dtcgTokens);
-      if (directMatch) {
-        results.push({
-          property: category,
-          token: directMatch.path,
-          confidence: 'exact',
-          matchMethod: 'binding',
-          primitive: directMatch.path,
-        });
-        continue;
-      }
-
-      // Fallback path: property-by-property reconstruction
-      const reconstructed = this.reconstructFromProperties(style, category, dtcgTokens);
-      if (reconstructed) {
-        results.push(reconstructed);
-        continue;
-      }
-
-      // No match — flag for Ada's review
-      results.push({
-        property: category,
-        token: '',
-        confidence: 'no-match',
-        matchMethod: 'value',
-        delta: `Unmatched ${category} style "${style.name}" — requires Ada review`,
-      });
-    }
-
-    return results;
-  }
-
-  /**
-   * Look up a composite token by name in the DTCG token tree.
-   *
-   * Tries multiple name resolution strategies:
-   * 1. Direct path: `{category}.{styleName}` (e.g. `shadow.elevation200`)
-   * 2. Full style name as path (e.g. `shadow.elevation200` already dot-separated)
-   * 3. Style name with dots converted from slashes
-   *
-   * @returns The token path and token object if found, or null.
-   */
-  private lookupCompositeToken(
-    styleName: string,
-    category: 'shadow' | 'typography',
-    dtcgTokens: DTCGTokenFile,
-  ): { path: string; token: object } | null {
-    // Strategy 1: style name already includes category prefix (e.g. "shadow.elevation200")
-    if (styleName.startsWith(`${category}.`)) {
-      const token = this.resolveTokenPath(styleName, dtcgTokens);
-      if (token) return { path: styleName, token };
-    }
-
-    // Strategy 2: prepend category (e.g. "elevation200" → "shadow.elevation200")
-    const prefixedPath = `${category}.${styleName}`;
-    const prefixedToken = this.resolveTokenPath(prefixedPath, dtcgTokens);
-    if (prefixedToken) return { path: prefixedPath, token: prefixedToken };
-
-    // Strategy 3: convert slashes to dots and try both with and without prefix
-    const dotName = styleName.replace(/\//g, '.');
-    if (dotName !== styleName) {
-      if (dotName.startsWith(`${category}.`)) {
-        const token = this.resolveTokenPath(dotName, dtcgTokens);
-        if (token) return { path: dotName, token };
-      }
-      const prefixedDot = `${category}.${dotName}`;
-      const token = this.resolveTokenPath(prefixedDot, dtcgTokens);
-      if (token) return { path: prefixedDot, token };
-    }
-
-    return null;
-  }
-
-  /**
-   * Resolve a dot-separated token path in the DTCG token tree.
-   *
-   * Walks the tree following each path segment and returns the node
-   * if it has a `$value` (i.e. is a token, not just a group).
-   */
-  private resolveTokenPath(
-    path: string,
-    dtcgTokens: DTCGTokenFile,
-  ): object | null {
-    const parts = path.split('.');
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let current: any = dtcgTokens;
-
-    for (const part of parts) {
-      if (current == null || typeof current !== 'object') return null;
-      current = current[part];
-    }
-
-    if (current != null && typeof current === 'object' && '$value' in current) {
-      return current;
-    }
-
-    return null;
-  }
-
-  /**
-   * Attempt to reconstruct a composite token from raw style properties.
-   *
-   * For shadow styles: compares offsetX, offsetY, blur, spread, color
-   * against all shadow tokens in the DTCG tree.
-   *
-   * For typography styles: compares fontFamily, fontSize, fontWeight,
-   * lineHeight against all typography tokens in the DTCG tree.
-   *
-   * Returns an approximate-confidence match if a token's sub-values
-   * match the style properties, or null if no reconstruction possible.
-   */
-  private reconstructFromProperties(
-    style: FigmaStyle,
-    category: 'shadow' | 'typography',
-    dtcgTokens: DTCGTokenFile,
-  ): TokenReference | null {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const group = (dtcgTokens as any)[category];
-    if (!group || typeof group !== 'object') return null;
-
-    const props = style.properties;
-    let bestMatch: { path: string; score: number } | null = null;
-
-    for (const [key, entry] of Object.entries(group)) {
-      if (key.startsWith('$')) continue;
-      if (entry == null || typeof entry !== 'object' || !('$value' in entry)) continue;
-
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const tokenValue = (entry as any).$value;
-      if (tokenValue == null || typeof tokenValue !== 'object') continue;
-
-      const score = category === 'shadow'
-        ? this.scoreShadowMatch(props, tokenValue)
-        : this.scoreTypographyMatch(props, tokenValue);
-
-      if (score > 0 && (bestMatch === null || score > bestMatch.score)) {
-        bestMatch = { path: `${category}.${key}`, score };
-      }
-    }
-
-    if (bestMatch) {
-      return {
-        property: category,
-        token: bestMatch.path,
-        confidence: 'approximate',
-        matchMethod: 'value',
-        primitive: bestMatch.path,
-        delta: `Reconstructed from properties (score: ${bestMatch.score}/4)`,
-      };
-    }
-
-    return null;
-  }
-
-  /**
-   * Score how well a Figma effect style's properties match a DTCG shadow token value.
-   *
-   * Compares offsetX, offsetY, blur, and spread. Each matching property
-   * adds 1 to the score (max 4). Returns 0 if no properties match.
-   */
-  private scoreShadowMatch(
-    styleProps: Record<string, unknown>,
-    tokenValue: Record<string, unknown>,
-  ): number {
-    let score = 0;
-    const fields = ['offsetX', 'offsetY', 'blur', 'spread'];
-
-    for (const field of fields) {
-      const styleProp = styleProps[field];
-      const tokenProp = tokenValue[field];
-      if (styleProp == null || tokenProp == null) continue;
-      if (this.dimensionValuesMatch(styleProp, tokenProp)) score++;
-    }
-
-    return score;
-  }
-
-  /**
-   * Score how well a Figma text style's properties match a DTCG typography token value.
-   *
-   * Compares fontFamily, fontSize, fontWeight, and lineHeight. Each matching
-   * property adds 1 to the score (max 4). Returns 0 if no properties match.
-   */
-  private scoreTypographyMatch(
-    styleProps: Record<string, unknown>,
-    tokenValue: Record<string, unknown>,
-  ): number {
-    let score = 0;
-
-    // fontFamily: string comparison
-    if (styleProps.fontFamily != null && tokenValue.fontFamily != null) {
-      if (String(styleProps.fontFamily) === String(tokenValue.fontFamily)) score++;
-    }
-
-    // fontSize: dimension comparison
-    if (styleProps.fontSize != null && tokenValue.fontSize != null) {
-      if (this.dimensionValuesMatch(styleProps.fontSize, tokenValue.fontSize)) score++;
-    }
-
-    // fontWeight: numeric comparison
-    if (styleProps.fontWeight != null && tokenValue.fontWeight != null) {
-      if (Number(styleProps.fontWeight) === Number(tokenValue.fontWeight)) score++;
-    }
-
-    // lineHeight: numeric comparison (may be unitless ratio or px)
-    if (styleProps.lineHeight != null && tokenValue.lineHeight != null) {
-      if (this.dimensionValuesMatch(styleProps.lineHeight, tokenValue.lineHeight)) score++;
-    }
-
-    return score;
-  }
-
-  /**
-   * Compare two dimension values that may be numbers or strings with units.
-   *
-   * Handles: `24` vs `"24px"`, `"16px"` vs `"16px"`, `1.5` vs `1.5`.
-   */
-  private dimensionValuesMatch(a: unknown, b: unknown): boolean {
-    // Both numeric
-    const numA = typeof a === 'number' ? a : parseFloat(String(a));
-    const numB = typeof b === 'number' ? b : parseFloat(String(b));
-
-    if (!isNaN(numA) && !isNaN(numB)) {
-      return numA === numB;
-    }
-
-    // String comparison as fallback
-    return String(a) === String(b);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Behavioral contract detection (Task 3.8)
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Keywords that indicate an interactive component requiring behavioral contracts.
-   * Matched case-insensitively against the component name.
-   */
-  private static readonly INTERACTIVE_KEYWORDS = [
-    'button', 'input', 'toggle', 'switch', 'checkbox', 'radio',
-    'select', 'dropdown', 'slider', 'tab', 'link', 'menu',
-    'dialog', 'modal', 'tooltip', 'popover', 'accordion',
-  ];
-
-  /**
-   * Keywords that indicate a static (non-interactive) component.
-   * Matched case-insensitively against the component name.
-   */
-  private static readonly STATIC_KEYWORDS = [
-    'badge', 'divider', 'icon', 'avatar', 'label', 'tag',
-    'separator', 'spacer', 'image', 'logo', 'progress',
-  ];
-
-  /**
-   * Classify a component as interactive or static based on keyword heuristics.
-   *
-   * Checks the component name against known interactive and static keywords.
-   * If both match (unlikely but possible), interactive takes precedence because
-   * missing behavioral contracts on an interactive component is a higher risk
-   * than unnecessary contracts on a static one.
-   *
-   * @param componentName - The Figma component name.
-   * @returns 'interactive' or 'static'.
-   */
-  private classifyComponent(componentName: string): 'interactive' | 'static' {
-    const lower = componentName.toLowerCase();
-
-    const isInteractive = DesignExtractor.INTERACTIVE_KEYWORDS.some(
-      (kw) => lower.includes(kw),
-    );
-    if (isInteractive) return 'interactive';
-
-    const isStatic = DesignExtractor.STATIC_KEYWORDS.some(
-      (kw) => lower.includes(kw),
-    );
-    if (isStatic) return 'static';
-
-    // Default: treat unknown components as interactive (safer — forces review)
-    return 'interactive';
-  }
-
-  /**
-   * Extract visual state names from a component's detected states.
-   *
-   * Filters for well-known interaction states: hover, focus, disabled, pressed,
-   * active, selected, error, loading.
-   */
-  private extractVisualStates(states: StateDefinition[]): string[] {
-    const knownStates = new Set([
-      'hover', 'focus', 'disabled', 'pressed',
-      'active', 'selected', 'error', 'loading',
-      'long-press',
-    ]);
-    return states
-      .map((s) => s.name.toLowerCase())
-      .filter((name) => knownStates.has(name));
-  }
-
-  /**
-   * Detect behavioral contract status for a component.
-   *
-   * Classifies the component as interactive or static using keyword heuristics,
-   * extracts visual states from the Figma component, and flags missing
-   * behavioral contracts for interactive components.
-   *
-   * For static components, auto-generates a "no interaction" contract.
-   *
-   * @param component - The extracted Figma component.
-   * @returns BehavioralContractStatus with classification, states, and confidence.
-   */
-  detectBehavioralContracts(component: ExtractedComponent): BehavioralContractStatus {
-    const classification = this.classifyComponent(component.name);
-    const detectedStates = this.extractVisualStates(component.states);
-
-    if (classification === 'static') {
-      return {
-        classification: 'static',
-        detectedStates,
-        contractsDefined: true,
-        autoContract: 'No interaction — static display component',
-        confidence: '✅',
-      };
-    }
-
-    // Interactive component: flag missing behavioral contracts
-    // Behavioral contracts are considered missing because Figma designs
-    // don't encode interaction behavior — only visual states.
-    // The actual contracts must be defined during spec review.
-    const hasStates = detectedStates.length > 0;
-
-    return {
-      classification: 'interactive',
-      detectedStates,
-      contractsDefined: false,
-      confidence: '❌',
-    };
-  }
-
-  // -------------------------------------------------------------------------
-  // detectPlatformParity (Task 3.9)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Detect platform-specific interactions and flag parity concerns.
-   *
-   * Applies heuristics to classify each detected visual state by platform
-   * support (hover = web-only, focus = all platforms, long-press = mobile).
-   * Optionally queries platform-implementation-guidelines.md via
-   * DesignerPunk MCP for cross-reference validation.
-   *
-   * Provides decision options for platform-specific interactions:
-   * omit on unsupported platform, map to alternative interaction, or
-   * defer to human review.
-   *
-   * @param component - The extracted Figma component.
-   * @returns PlatformParityCheck with interactions and concern status.
-   * @requirements Req 7 (Platform Parity Detection)
-   */
-  async detectPlatformParity(component: ExtractedComponent): Promise<PlatformParityCheck> {
-    const detectedStates = this.extractVisualStates(component.states);
-
-    // Query platform guidelines for cross-reference (best-effort)
-    let guidelinesContent: string | null = null;
-    if (this.mcpDocs) {
-      try {
-        guidelinesContent = await this.mcpDocs.getSection(
-          'governance/platform-implementation-guidelines.md',
-          'State Management Consistency',
-        );
-      } catch {
-        // MCP unavailable — proceed with heuristics only
-      }
-    }
-
-    const interactions: PlatformInteraction[] = [];
-
-    for (const state of detectedStates) {
-      const platforms = DesignExtractor.PLATFORM_HEURISTICS[state];
-      if (!platforms) continue;
-
-      const allPlatforms: ('web' | 'ios' | 'android')[] = ['web', 'ios', 'android'];
-      const missingPlatforms = allPlatforms.filter((p) => !platforms.includes(p));
-
-      // Only flag interactions that are NOT available on all platforms
-      if (missingPlatforms.length === 0) continue;
-
-      const recommendation = this.buildPlatformRecommendation(
-        state,
-        platforms,
-        missingPlatforms,
-        guidelinesContent,
-      );
-
-      interactions.push({
-        interaction: state,
-        platforms,
-        recommendation,
-      });
-    }
-
-    return {
-      interactions,
-      hasConcerns: interactions.length > 0,
-    };
-  }
-
-  /**
-   * Build a recommendation string for a platform-specific interaction.
-   *
-   * Includes decision options for the human reviewer: omit on unsupported
-   * platforms, map to an alternative interaction, or provide a custom
-   * approach.
-   */
-  private buildPlatformRecommendation(
-    state: string,
-    supportedPlatforms: ('web' | 'ios' | 'android')[],
-    missingPlatforms: ('web' | 'ios' | 'android')[],
-    guidelinesContent: string | null,
-  ): string {
-    const supported = supportedPlatforms.join(', ');
-    const missing = missingPlatforms.join(', ');
-
-    // State-specific recommendations
-    if (state === 'hover') {
-      return (
-        `"${state}" is ${supported}-only (not available on ${missing}). ` +
-        'Decision options: (a) omit hover feedback on mobile, ' +
-        '(b) map to press/active state on mobile, ' +
-        '(c) provide alternative visual feedback.' +
-        (guidelinesContent ? ' Cross-referenced with platform-implementation-guidelines.md.' : '')
-      );
-    }
-
-    if (state === 'long-press') {
-      return (
-        `"${state}" is ${supported}-only (not available on ${missing}). ` +
-        'Decision options: (a) omit on web, ' +
-        '(b) map to right-click/context menu on web, ' +
-        '(c) provide alternative trigger.' +
-        (guidelinesContent ? ' Cross-referenced with platform-implementation-guidelines.md.' : '')
-      );
-    }
-
-    // Generic recommendation for other platform-limited states
-    return (
-      `"${state}" is available on ${supported} but not on ${missing}. ` +
-      `Decision options: (a) omit on ${missing}, ` +
-      '(b) map to equivalent interaction, ' +
-      '(c) defer to human review.' +
-      (guidelinesContent ? ' Cross-referenced with platform-implementation-guidelines.md.' : '')
-    );
-  }
-
-
-  // -------------------------------------------------------------------------
-  // detectComponentTokenDecisions (Task 3.10)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Detect repeated primitive token usage and surface component token
-   * decision points for Ada's review.
-   *
-   * Scans all token categories in the usage map, groups references by
-   * their resolved primitive token, and generates illustrative component
-   * token suggestions for any primitive used two or more times.
-   *
-   * All suggestions are explicitly labeled as pending human review —
-   * no autonomous token creation per governance.
-   *
-   * @param tokenUsage - Aggregated token usage from translateTokens().
-   * @param componentName - Component name for illustrative naming.
-   * @returns Array of decision points for Ada's review.
-   */
-  detectComponentTokenDecisions(
-    tokenUsage: TokenUsage,
-    componentName: string = 'component',
-  ): ComponentTokenDecision[] {
-    // Build a map of primitiveToken → list of property locations
-    const usageMap = new Map<string, string[]>();
-
-    const categories: Array<[keyof TokenUsage, string]> = [
-      ['spacing', 'spacing'],
-      ['colors', 'color'],
-      ['typography', 'typography'],
-      ['radius', 'radius'],
-      ['shadows', 'shadow'],
-    ];
-
-    for (const [category] of categories) {
-      const refs = tokenUsage[category];
-      for (const ref of refs) {
-        // Only consider matched tokens (not no-match)
-        if (ref.confidence === 'no-match') continue;
-
-        // Use the primitive token if available, otherwise the main token
-        const primitiveKey = ref.primitive ?? ref.token;
-        if (!primitiveKey) continue;
-
-        const location = ref.property;
-        const existing = usageMap.get(primitiveKey) ?? [];
-        existing.push(location);
-        usageMap.set(primitiveKey, existing);
-      }
-    }
-
-    // Generate decisions for tokens used 2+ times
-    const decisions: ComponentTokenDecision[] = [];
-    const baseName = this.extractComponentBaseName(componentName);
-
-    for (const [primitiveToken, locations] of usageMap) {
-      if (locations.length < 2) continue;
-
-      const propertyGroup = this.inferPropertyGroup(locations);
-      const suggestion = `${baseName}.${propertyGroup} = ${primitiveToken}`;
-
-      decisions.push({
-        primitiveToken,
-        usageCount: locations.length,
-        locations,
-        illustrativeSuggestion: suggestion,
-        rationale:
-          `${primitiveToken} is used across ${locations.length} properties ` +
-          `(${locations.join(', ')}). Consistent usage suggests semantic ` +
-          `intent that could be encoded as a component token.`,
-      });
-    }
-
-    // Sort by usage count descending for prioritized review
-    decisions.sort((a, b) => b.usageCount - a.usageCount);
-
-    return decisions;
-  }
-
-  /**
-   * Extract a short base name from a component name for illustrative
-   * token naming.
-   *
-   * "ButtonCTA" → "button", "InputTextBase" → "input", "ContainerBase" → "container"
-   */
-  private extractComponentBaseName(componentName: string): string {
-    // Split PascalCase into words, take the first word, lowercase it
-    const words = componentName.replace(/([a-z])([A-Z])/g, '$1 $2').split(/[\s_-]+/);
-    return (words[0] ?? 'component').toLowerCase();
-  }
-
-  /**
-   * Infer a property group name from a list of CSS property locations.
-   *
-   * Groups related properties into semantic names:
-   * - padding-left, padding-right → "padding.horizontal"
-   * - padding-top, padding-bottom → "padding.vertical"
-   * - mixed padding → "padding"
-   * - color, fill, background → "fill"
-   * - border-radius → "radius"
-   * - Otherwise uses the first property name.
-   */
-  private inferPropertyGroup(locations: string[]): string {
-    const normalized = locations.map(l => l.toLowerCase());
-
-    // Check for padding patterns
-    const hasPaddingLeft = normalized.some(l => l.includes('padding-left') || l.includes('padding-inline-start'));
-    const hasPaddingRight = normalized.some(l => l.includes('padding-right') || l.includes('padding-inline-end'));
-    const hasPaddingTop = normalized.some(l => l.includes('padding-top') || l.includes('padding-block-start'));
-    const hasPaddingBottom = normalized.some(l => l.includes('padding-bottom') || l.includes('padding-block-end'));
-    const allPadding = normalized.every(l => l.includes('padding'));
-
-    if (allPadding) {
-      if ((hasPaddingLeft || hasPaddingRight) && !hasPaddingTop && !hasPaddingBottom) {
-        return 'padding.horizontal';
-      }
-      if ((hasPaddingTop || hasPaddingBottom) && !hasPaddingLeft && !hasPaddingRight) {
-        return 'padding.vertical';
-      }
-      return 'padding';
-    }
-
-    // Check for spacing patterns (item-spacing, gap, margin)
-    if (normalized.every(l => l.includes('spacing') || l.includes('gap') || l.includes('margin'))) {
-      return 'spacing';
-    }
-
-    // Check for color patterns
-    if (normalized.every(l =>
-      l.includes('color') || l.includes('fill') || l.includes('background') || l.includes('stroke'),
-    )) {
-      return 'fill';
-    }
-
-    // Check for radius
-    if (normalized.every(l => l.includes('radius'))) {
-      return 'radius';
-    }
-
-    // Check for shadow
-    if (normalized.every(l => l.includes('shadow'))) {
-      return 'shadow';
-    }
-
-    // Check for typography
-    if (normalized.every(l =>
-      l.includes('font') || l.includes('line-height') || l.includes('letter-spacing'),
-    )) {
-      return 'typography';
-    }
-
-    // Fallback: use the first property, cleaned up
-    return normalized[0]?.replace(/[^a-z0-9.]/g, '-') ?? 'token';
-  }
-
-  /**
-   * Validate mode consistency across token bindings.
-   *
-   * For each binding with multiple mode values, checks whether light and
-   * dark mode values are identical. Discrepancies are categorized:
-   *
-   * - **expected**: Color tokens differ by mode (light/dark theme variations).
-   * - **unexpected**: Spacing, radius, or typography tokens differ by mode
-   *   (structural tokens should be mode-agnostic).
-   *
-   * @param bindings - Token bindings read from Figma.
-   * @returns ModeValidationResult with discrepancies and a flag for unexpected ones.
-   * @requirements Req 9 (Mode Consistency Validation)
-   */
-  validateModes(bindings: TokenBinding[]): ModeValidationResult {
-    const discrepancies: ModeDiscrepancy[] = [];
-
-    for (const binding of bindings) {
-      const modeEntries = Object.entries(binding.valuesByMode);
-
-      // Need at least two modes to compare
-      if (modeEntries.length < 2) continue;
-
-      // Identify light and dark mode entries by key name heuristic
-      const lightKey = modeEntries.find(([k]) => /light/i.test(k));
-      const darkKey = modeEntries.find(([k]) => /dark/i.test(k));
-
-      // If we can't identify light/dark by name, compare first two modes
-      const [modeA, modeB] = lightKey && darkKey
-        ? [lightKey, darkKey]
-        : [modeEntries[0], modeEntries[1]];
-
-      const valueA = modeA[1];
-      const valueB = modeB[1];
-
-      // Skip alias objects — they reference other variables, not resolved values
-      if (this.isAliasValue(valueA) || this.isAliasValue(valueB)) continue;
-
-      // Compare values — use JSON.stringify for deep equality of objects
-      if (this.modeValuesEqual(valueA, valueB)) continue;
-
-      // Values differ — categorize the discrepancy
-      const category = binding.resolvedType === 'COLOR' ? 'expected' : 'unexpected';
-
-      discrepancies.push({
-        variableName: binding.variableName,
-        lightValue: valueA,
-        darkValue: valueB,
-        category,
-      });
-    }
-
-    return {
-      discrepancies,
-      hasUnexpectedDiscrepancies: discrepancies.some(d => d.category === 'unexpected'),
-    };
-  }
-
-  /**
-   * Resolve variable IDs from boundVariableMap that aren't in the bindings.
-   *
-   * When `figma_get_token_values` (limit: 500) doesn't return all variables,
-   * some boundVariable IDs from the component tree won't resolve in the
-   * `nameById` lookup during `translateTokens`. This method uses
-   * `figma_execute` with Plugin API to batch-resolve those missing IDs,
-   * returning synthetic TokenBinding entries that can be appended to the
-   * bindings array.
-   *
-   * @param fileKey - The Figma file key.
-   * @param boundVariableMap - Property→variableId map from component extraction.
-   * @param existingBindings - Bindings already loaded from figma_get_token_values.
-   * @returns Additional TokenBinding entries for previously unresolved IDs.
-   */
-  async resolveUnknownVariableIds(
-    fileKey: string,
-    boundVariableMap: Map<string, string>,
-    existingBindings: TokenBinding[],
-  ): Promise<TokenBinding[]> {
-    if (!boundVariableMap || boundVariableMap.size === 0) return [];
-
-    // Build set of known variable IDs
-    const knownIds = new Set<string>();
-    for (const binding of existingBindings) {
-      if (binding.variableId) knownIds.add(binding.variableId);
-    }
-
-    // Collect unresolved IDs (deduplicated)
-    const unresolvedIds = new Set<string>();
-    for (const varId of boundVariableMap.values()) {
-      if (!knownIds.has(varId)) unresolvedIds.add(varId);
-    }
-
-    if (unresolvedIds.size === 0) return [];
-
-    // Batch-resolve via Plugin API
-    const idsArray = [...unresolvedIds];
-    const code = `
-      const results = {};
-      for (const id of ${JSON.stringify(idsArray)}) {
-        try {
-          const v = figma.variables.getVariableById(id);
-          if (v) {
-            results[id] = {
-              name: v.name,
-              resolvedType: v.resolvedType,
-              id: v.id,
-            };
-          }
-        } catch (e) {
-          // Variable not found — skip
-        }
-      }
-      return results;
-    `.trim();
-
-    try {
-      const result = await this.consoleMcp.execute(fileKey, code);
-
-      // Parse the result — may be wrapped in various formats
-      let resolved: Record<string, { name: string; resolvedType: string; id: string }> = {};
-      if (result && typeof result === 'object') {
-        // Handle { result: { ... } } wrapper from figma_execute
-        const raw = result as Record<string, unknown>;
-        const inner = raw.result ?? raw;
-        if (inner && typeof inner === 'object') {
-          resolved = inner as typeof resolved;
-        }
-      }
-
-      const additionalBindings: TokenBinding[] = [];
-      for (const [varId, info] of Object.entries(resolved)) {
-        if (!info?.name) continue;
-        additionalBindings.push({
-          variableName: info.name,
-          variableId: varId,
-          collectionName: this.inferCollectionFromName(info.name, false),
-          resolvedType: (info.resolvedType ?? 'FLOAT') as TokenBinding['resolvedType'],
-          valuesByMode: {},
-          isAlias: false,
-        });
-      }
-
-      return additionalBindings;
-    } catch {
-      // Plugin API resolution failed — return empty (value-based fallback still works)
-      return [];
-    }
-  }
-
-
-
-  /**
-   * Check whether a mode value is an alias reference (not a resolved value).
-   */
-  private isAliasValue(value: unknown): boolean {
-    return (
-      value != null &&
-      typeof value === 'object' &&
-      'aliasOf' in (value as Record<string, unknown>)
-    );
-  }
-
-  /**
-   * Compare two mode values for equality.
-   *
-   * Handles primitives (number, string) directly and falls back to
-   * JSON.stringify for object values (e.g. color objects).
-   */
-  private modeValuesEqual(a: unknown, b: unknown): boolean {
-    if (a === b) return true;
-    if (typeof a !== typeof b) return false;
-    if (typeof a === 'object' && a !== null && b !== null) {
-      return JSON.stringify(a) === JSON.stringify(b);
-    }
-    return false;
-  }
-
-
-  /**
-   * Extract a Figma component and produce a ComponentAnalysis.
-   *
-   * Orchestrates: read component → build node tree → collect/resolve
-   * bound variables → reclassify → detect composition patterns →
-   * capture screenshot → gather recommendations.
-   */
-  async extractComponentAnalysis(
-    fileKey: string,
-    nodeId: string,
-    outputDir: string,
-    fileUrl?: string,
-  ): Promise<ComponentAnalysis> {
-    // 1. Read component structure, token bindings, and styles in parallel
-    const [component, bindings, styles] = await Promise.all([
-      this.readFigmaComponent(fileKey, nodeId),
-      this.readTokenBindings(fileKey),
-      this.readStyles(fileKey),
-    ]);
-
-    // 2. Resolve unknown variable IDs
-    if (component.boundVariableMap && component.boundVariableMap.size > 0) {
-      const additional = await this.resolveUnknownVariableIds(
-        fileKey, component.boundVariableMap, bindings,
-      );
-      if (additional.length > 0) bindings.push(...additional);
-    }
-
-    // 3. Get raw component data for node tree building
-    const rawComponent = await this.consoleMcp.getComponent(fileKey, nodeId);
-
-    // 4. Build hierarchical node tree with per-node classification
-    const nodeTree = this.buildNodeTree(rawComponent as Record<string, unknown>);
-
-    // 5. Collect and resolve bound variable IDs
-    const boundEntries = this.collectBoundVariableIds(rawComponent as Record<string, unknown>);
-    const { resolved, unresolvedBindings } = await this.batchResolveBoundVariables(fileKey, boundEntries);
-
-    // 6. Reclassify unidentified values using resolved bindings
-    this.reclassifyWithResolvedBindings(nodeTree, resolved);
-
-    // 7. Aggregate classification counts
-    const classificationSummary = this.aggregateClassifications(nodeTree);
-
-    // 8. Detect composition patterns
-    const compositionPatterns = this.detectCompositionPatterns(nodeTree);
-
-    // 9. Capture screenshots (variants for COMPONENT_SET, single for others)
-    const screenshots: ScreenshotMetadata[] = [];
-    const screenshotUrl = fileUrl ?? `https://www.figma.com/design/${fileKey}`;
-    if (nodeTree.type === 'COMPONENT_SET' && nodeTree.children.length > 0) {
-      for (const child of nodeTree.children) {
-        const shot = await this.captureComponentScreenshot(
-          screenshotUrl, child.id, outputDir, component.name, child.name,
-        );
-        if (shot) screenshots.push(shot);
-      }
-    } else {
-      const shot = await this.captureComponentScreenshot(
-        screenshotUrl, nodeId, outputDir, component.name,
-      );
-      if (shot) screenshots.push(shot);
-    }
-
-    // 10. Gather recommendations (reuse existing methods)
-    const tokenUsage = this.translateTokens(component, bindings);
-    const compositeTokens = this.reconstructCompositeTokens(styles, this.translator.getDtcgTokens());
-    for (const ref of compositeTokens) {
-      if (ref.property === 'shadow') tokenUsage.shadows.push(ref);
-      else if (ref.property === 'typography') tokenUsage.typography.push(ref);
-    }
-    const context = await this.queryContext(component.name);
-    const analyzerComponent = {
-      name: component.name,
-      description: component.description,
-      variants: component.variants.map(v => ({ name: v.name, properties: v.properties })),
-      states: component.states.map(s => s.name),
-    };
-    const variantMapping = await this.analyzer.analyzeVariants(analyzerComponent, context);
-    const componentTokens = this.detectComponentTokenDecisions(tokenUsage, component.name);
-    const modeValidation = this.validateModes(bindings);
-    const platformParity = await this.detectPlatformParity(component);
-
-    // 11. Build variant definitions from raw response
-    const variantDefinitions = this.buildVariantDefinitions(rawComponent);
-
-    // 12. Determine component type
-    const componentType = this.resolveComponentType(rawComponent);
-
-    return {
-      componentName: component.name,
-      componentType,
-      figmaId: nodeId,
-      fileKey,
-      variantDefinitions: Object.keys(variantDefinitions).length > 0 ? variantDefinitions : undefined,
-      nodeTree,
-      classificationSummary,
-      compositionPatterns,
-      unresolvedBindings,
-      recommendations: {
-        variantMapping: variantMapping.recommendations.length > 0 || variantMapping.conflicts.length > 0 ? variantMapping : undefined,
-        componentTokens: componentTokens.length > 0 ? componentTokens : undefined,
-        modeValidation: modeValidation.hasUnexpectedDiscrepancies ? modeValidation : undefined,
-        platformParity: platformParity.hasConcerns ? platformParity : undefined,
-      },
-      screenshots,
-      extractedAt: new Date().toISOString(),
-      extractorVersion: '6.3.0',
-    };
-  }
-
-  /** Aggregate classification counts across all nodes in a tree. */
-  private aggregateClassifications(node: NodeWithClassifications): {
-    semanticIdentified: number;
-    primitiveIdentified: number;
-    unidentified: number;
-  } {
-    let semantic = node.tokenClassifications.semanticIdentified.length;
-    let primitive = node.tokenClassifications.primitiveIdentified.length;
-    let unidentified = node.tokenClassifications.unidentified.length;
-    for (const child of node.children) {
-      const c = this.aggregateClassifications(child);
-      semantic += c.semanticIdentified;
-      primitive += c.primitiveIdentified;
-      unidentified += c.unidentified;
-    }
-    return { semanticIdentified: semantic, primitiveIdentified: primitive, unidentified };
-  }
-
-  /** Build variantDefinitions from raw Figma component response. */
-  private buildVariantDefinitions(raw: Record<string, unknown>): Record<string, {
-    type: 'VARIANT' | 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP';
-    defaultValue: unknown;
-    variantOptions?: string[];
-  }> {
-    const defs: Record<string, { type: 'VARIANT' | 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP'; defaultValue: unknown; variantOptions?: string[] }> = {};
-    const vp = raw.variantProperties as Record<string, string[]> | undefined;
-    if (vp) {
-      for (const [name, options] of Object.entries(vp)) {
-        defs[name] = { type: 'VARIANT', defaultValue: options[0] ?? '', variantOptions: options };
-      }
-    }
-    return defs;
-  }
-
-  /** Resolve component type from raw Figma response. */
-  private resolveComponentType(raw: Record<string, unknown>): 'COMPONENT_SET' | 'COMPONENT' | 'INSTANCE' {
-    const t = raw.type as string | undefined;
-    if (t === 'COMPONENT_SET' || t === 'COMPONENT' || t === 'INSTANCE') return t;
-    // If it has variantProperties, it's a COMPONENT_SET
-    if (raw.variantProperties) return 'COMPONENT_SET';
-    return 'COMPONENT';
-  }
-
-}