@3fn/core 13.0.0

package/dist/figma/DesignExtractor.d.ts

@@ -0,0 +1,971 @@
+/**
+ * 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, TokenCategory } from './TokenTranslator';
+import type { VariantAnalyzer, ExtractionContext, MCPDocClient } from './VariantAnalyzer';
+import type { DTCGTokenFile } from '../generators/types/DTCGTypes';
+import type { NodeWithClassifications, CompositionPattern, UnresolvedBinding, ScreenshotMetadata, ComponentAnalysis } from './ComponentAnalysis';
+/**
+ * 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>;
+}
+/**
+ * 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;
+    }>;
+}
+/** 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[];
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare class DesignExtractor {
+    private readonly consoleMcp;
+    private readonly translator;
+    private readonly analyzer;
+    private readonly kiroPower?;
+    private readonly mcpDocs?;
+    /** Platform-interaction heuristics: interaction → supported platforms. */
+    private static readonly PLATFORM_HEURISTICS;
+    constructor(consoleMcp: ConsoleMCPClient, translator: TokenTranslator, analyzer: VariantAnalyzer, kiroPower?: KiroFigmaPowerClient | undefined, mcpDocs?: MCPDocClient | undefined);
+    /**
+     * 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.
+     */
+    readFigmaComponent(fileKey: string, nodeId: string): Promise<ExtractedComponent>;
+    /**
+     * 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;
+    /**
+     * 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 readFigmaComponentFallback;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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, ancestors?: string[]): NodeWithClassifications;
+    /**
+     * 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[];
+    /**
+     * Detect composition patterns at a single level and recurse into children.
+     */
+    private detectPatternsAtLevel;
+    /**
+     * Find properties shared across all instances in a group.
+     *
+     * A property is "shared" when every instance has the same value for it.
+     */
+    private findSharedProperties;
+    /**
+     * Group instances by their non-shared property combinations.
+     *
+     * Returns distinct property value combinations with counts.
+     */
+    private groupByPropertyVariations;
+    /**
+     * 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)
+     */
+    captureComponentScreenshot(fileUrl: string, nodeId: string, outputDir: string, componentName: string, variant?: string): Promise<ScreenshotMetadata | null>;
+    /** Download a file from a URL to a local path. */
+    private downloadFile;
+    /**
+     * Deep equality check for property values.
+     */
+    private valuesEqual;
+    /**
+     * 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;
+    /**
+     * Extract text style properties from a TEXT node.
+     */
+    private extractTextStyle;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Extract boundVariables from a node's boundVariables object into the map.
+     */
+    private extractBoundVariables;
+    /**
+     * 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;
+    /**
+     * 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, ancestors?: string[]): BoundVariableEntry[];
+    /**
+     * 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)
+     */
+    batchResolveBoundVariables(fileKey: string, entries: BoundVariableEntry[]): Promise<{
+        resolved: Map<string, string>;
+        unresolvedBindings: UnresolvedBinding[];
+    }>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Extract component name from generated code. */
+    private extractComponentName;
+    /** Extract description from code comments or JSDoc. */
+    private extractDescription;
+    /** Extract variant definitions from code. */
+    private extractVariants;
+    /** Extract visual states from code (hover, focus, disabled, pressed). */
+    private extractStates;
+    /** Extract component properties from code. */
+    private extractProperties;
+    /** Extract layout information from code. */
+    private extractLayout;
+    /** Extract states from metadata XML. */
+    private extractStatesFromMetadata;
+    /**
+     * 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.
+     */
+    readTokenBindings(fileKey: string): Promise<TokenBinding[]>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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)
+     */
+    readStyles(fileKey: string): Promise<FigmaStyle[]>;
+    /**
+     * 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)
+     */
+    queryContext(componentName: string): Promise<ExtractionContext>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Keywords that indicate an interactive component requiring behavioral contracts.
+     * Matched case-insensitively against the component name.
+     */
+    private static readonly INTERACTIVE_KEYWORDS;
+    /**
+     * Keywords that indicate a static (non-interactive) component.
+     * Matched case-insensitively against the component name.
+     */
+    private static readonly STATIC_KEYWORDS;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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)
+     */
+    detectPlatformParity(component: ExtractedComponent): Promise<PlatformParityCheck>;
+    /**
+     * 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;
+    /**
+     * 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): ComponentTokenDecision[];
+    /**
+     * Extract a short base name from a component name for illustrative
+     * token naming.
+     *
+     * "ButtonCTA" → "button", "InputTextBase" → "input", "ContainerBase" → "container"
+     */
+    private extractComponentBaseName;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    resolveUnknownVariableIds(fileKey: string, boundVariableMap: Map<string, string>, existingBindings: TokenBinding[]): Promise<TokenBinding[]>;
+    /**
+     * Check whether a mode value is an alias reference (not a resolved value).
+     */
+    private isAliasValue;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    extractComponentAnalysis(fileKey: string, nodeId: string, outputDir: string, fileUrl?: string): Promise<ComponentAnalysis>;
+    /** Aggregate classification counts across all nodes in a tree. */
+    private aggregateClassifications;
+    /** Build variantDefinitions from raw Figma component response. */
+    private buildVariantDefinitions;
+    /** Resolve component type from raw Figma response. */
+    private resolveComponentType;
+}
+//# sourceMappingURL=DesignExtractor.d.ts.map