@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase2-accuracy/intent-translator/index.ts

@@ -0,0 +1,356 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Intent Translator
+// Parses a natural-language prompt into a structured IntentManifest by
+// performing NLP decomposition with Claude, then fuzzy-matching the extracted
+// component names against the live Design-System component sets in Figma.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import Fuse from "fuse.js";
+import { getBridge } from "../../../shared/figma-bridge.js";
+import { decisionLog } from "../../../shared/decision-log.js";
+import { resolveTokenRefsForComponent } from "../../../shared/token-binder.js";
+import { ComponentSet, Token } from "../../../shared/types.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface IntentTranslatorArgs {
+  prompt: string;
+  context?: string;
+  strictMode?: boolean;
+}
+
+export interface MatchedComponent {
+  dsNodeId: string;
+  dsName: string;
+  score: number;                       // 0–1, higher = better
+  variantHints: Record<string, string>;
+  tokenRefs: string[];
+}
+
+export interface ClarifyingQuestion {
+  question: string;
+  candidates: Array<{ dsNodeId: string; dsName: string; score: number }>;
+}
+
+export type IntentManifestStatus =
+  | "resolved"        // confidence ≥ 0.75 — safe to proceed
+  | "ambiguous"       // 0.50 ≤ confidence < 0.75 — needs clarification
+  | "low-confidence"; // confidence < 0.50 — list top-3 matches
+
+export interface IntentManifest {
+  status: IntentManifestStatus;
+  confidence: number;
+  parsedIntent: {
+    componentTypes: string[];
+    variants: Record<string, string>;
+    tokens: string[];
+    layout?: string;
+    textContent?: string;
+  };
+  matches: MatchedComponent[];
+  clarifyingQuestion?: ClarifyingQuestion;
+  logEntryId: string;
+}
+
+// ─── NLP prompt sent to Claude ────────────────────────────────────────────────
+
+const PARSE_SYSTEM_PROMPT = `You are a design-system intent parser.
+Given a natural-language UI description, extract structured information.
+Return ONLY valid JSON — no markdown fences, no explanation — matching this schema:
+{
+  "componentTypes": ["string"],   // e.g. ["Button","Card","Avatar"]
+  "variants": {                   // known variant keys and their values
+    "size": "md",
+    "state": "default",
+    "theme": "light"
+  },
+  "tokens": ["string"],           // CSS custom-property names if mentioned
+  "layout": "string | null",      // e.g. "horizontal", "grid"
+  "textContent": "string | null"  // visible text if specified
+}`;
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+interface NLPParseResult {
+  componentTypes: string[];
+  variants: Record<string, string>;
+  tokens: string[];
+  layout?: string;
+  textContent?: string;
+}
+
+function parseFromKeywords(
+  prompt: string,
+  context?: string
+): NLPParseResult {
+  const lower = ((context ? context + " " : "") + prompt).toLowerCase();
+
+  const componentPatterns: Record<string, string[]> = {
+    Button: ["button", "btn", "cta", "submit", "action button"],
+    TextInput: ["input", "text field", "textbox", "search bar", "form field", "text input"],
+    Card: ["card", "tile", "panel"],
+    Avatar: ["avatar", "profile picture", "user icon"],
+    Badge: ["badge", "chip", "tag", "pill"],
+    Modal: ["modal", "dialog", "popup", "overlay"],
+    Heading: ["heading", "title", "header text", "h1", "h2"],
+    Navigation: ["nav", "navigation", "sidebar", "menu", "breadcrumb", "tabs"],
+    Image: ["image", "photo", "illustration", "hero image", "banner"],
+    Toggle: ["toggle", "switch", "checkbox"],
+    Select: ["select", "dropdown", "picker", "combobox"],
+    Toast: ["toast", "snackbar", "notification", "alert"],
+    Tooltip: ["tooltip", "popover"],
+    Table: ["table", "data grid", "list view"],
+    Link: ["link", "anchor", "hyperlink"],
+  };
+
+  const componentTypes: string[] = [];
+  for (const [component, keywords] of Object.entries(componentPatterns)) {
+    if (keywords.some((kw) => lower.includes(kw))) {
+      componentTypes.push(component);
+    }
+  }
+
+  if (componentTypes.length === 0) {
+    componentTypes.push(prompt.split(" ").slice(0, 3).join(" "));
+  }
+
+  const variants: Record<string, string> = {};
+  const sizeMatch = lower.match(/\b(small|sm|medium|md|large|lg|xl|xs)\b/);
+  if (sizeMatch) variants.size = sizeMatch[1];
+  const stateMatch = lower.match(/\b(default|hover|active|disabled|focused|pressed|loading)\b/);
+  if (stateMatch) variants.state = stateMatch[1];
+  const themeMatch = lower.match(/\b(light|dark|brand|outline|ghost|solid)\b/);
+  if (themeMatch) variants.theme = themeMatch[1];
+
+  const tokenMatches = lower.match(/--[\w-]+/g) ?? [];
+
+  return {
+    componentTypes,
+    variants,
+    tokens: tokenMatches,
+    layout: lower.includes("horizontal") ? "horizontal" : lower.includes("grid") ? "grid" : undefined,
+    textContent: undefined,
+  };
+}
+
+interface FuseMatch {
+  dsNodeId: string;
+  dsName: string;
+  score: number;
+  variantHints: Record<string, string>;
+  tokenRefs: string[];
+}
+
+function buildFuseIndex(
+  componentSets: ComponentSet[]
+): Fuse<{ id: string; name: string; tokens: string[]; variantKeys: string[] }> {
+  const docs = componentSets.map((cs) => ({
+    id: cs.id,
+    name: cs.name,
+    tokens: [] as string[],
+    variantKeys: Object.keys(cs.variantGroupProperties ?? {}),
+  }));
+
+  return new Fuse(docs, {
+    keys: ["name", "variantKeys"],
+    threshold: 0.6,          // generous threshold; we filter by score later
+    includeScore: true,
+    minMatchCharLength: 2,
+  });
+}
+
+function fuseScoreToConfidence(fuseScore: number | undefined): number {
+  // Fuse score is 0 (perfect) → 1 (worst); invert to get confidence
+  return 1 - (fuseScore ?? 1);
+}
+
+function extractVariantHints(
+  componentSet: ComponentSet,
+  parsedVariants: Record<string, string>
+): Record<string, string> {
+  const hints: Record<string, string> = {};
+  const groupProps = componentSet.variantGroupProperties ?? {};
+
+  for (const [key, { values }] of Object.entries(groupProps)) {
+    const normalizedKey = key.toLowerCase();
+    // Direct match from parsed variants
+    if (parsedVariants[normalizedKey]) {
+      const requested = parsedVariants[normalizedKey].toLowerCase();
+      const matched = values.find((v) => v.toLowerCase() === requested);
+      if (matched) hints[key] = matched;
+    }
+    // Default: first value
+    if (!hints[key] && values.length > 0) {
+      hints[key] = values[0];
+    }
+  }
+
+  return hints;
+}
+
+function matchComponents(
+  componentTypes: string[],
+  componentSets: ComponentSet[],
+  parsedVariants: Record<string, string>
+): FuseMatch[] {
+  const index = buildFuseIndex(componentSets);
+  const seen = new Set<string>();
+  const results: FuseMatch[] = [];
+
+  for (const typeName of componentTypes) {
+    const hits = index.search(typeName);
+
+    for (const hit of hits) {
+      if (seen.has(hit.item.id)) continue;
+      seen.add(hit.item.id);
+
+      const cs = componentSets.find((c) => c.id === hit.item.id);
+      if (!cs) continue;
+
+      const confidence = fuseScoreToConfidence(hit.score);
+      results.push({
+        dsNodeId: cs.id,
+        dsName: cs.name,
+        score: confidence,
+        variantHints: extractVariantHints(cs, parsedVariants),
+        tokenRefs: [], // populated below if needed
+      });
+    }
+  }
+
+  // Sort descending by score
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
+// ─── Main handler ─────────────────────────────────────────────────────────────
+
+export async function intentTranslatorHandler(
+  args: IntentTranslatorArgs
+): Promise<IntentManifest> {
+  const { prompt, context, strictMode = false } = args;
+
+  if (!prompt || prompt.trim().length === 0) {
+    throw new Error("intentTranslator: `prompt` must be a non-empty string.");
+  }
+
+  // 1. Parse the prompt into components using keyword matching
+  const parsedIntent = parseFromKeywords(prompt, context);
+
+  // 2. Fetch DS component sets and tokens via the bridge (graceful fallback on timeout)
+  const bridge = await getBridge();
+  let componentSets: ComponentSet[] = [];
+  let tokens: Token[] = [];
+  try {
+    componentSets = await bridge.getComponentSets();
+  } catch {
+    // If scanning times out, continue with keyword-only results
+  }
+  // DS tokens are authoritative when a design system is selected
+  const dsId = bridge.getActiveDesignSystemId();
+  if (dsId) {
+    try {
+      const { getDesignSystemTokens } = await import("../../../shared/design-system-tokens.js");
+      tokens = getDesignSystemTokens(dsId);
+    } catch {}
+  } else {
+    try {
+      tokens = await bridge.getTokens();
+    } catch {
+      // If token fetch fails, tokenRefs will remain empty
+    }
+  }
+
+  // 3. Fuzzy match parsed component names against DS sets
+  const allMatches = matchComponents(
+    parsedIntent.componentTypes,
+    componentSets,
+    parsedIntent.variants
+  );
+
+  // 3b. Populate tokenRefs for each match by resolving semantic token mappings
+  if (tokens.length > 0) {
+    for (const match of allMatches) {
+      // Use the DS component name to infer which tokens are relevant
+      const componentType = match.dsName.split("/").pop()?.trim() ?? match.dsName;
+      match.tokenRefs = resolveTokenRefsForComponent(componentType, tokens);
+    }
+  }
+
+  // 4. Determine overall confidence from the best match
+  const bestScore = allMatches.length > 0 ? allMatches[0].score : 0;
+
+  // In strictMode any ambiguity below 0.75 is treated as low-confidence
+  const effectiveScore = strictMode && bestScore < 0.75 ? bestScore * 0.8 : bestScore;
+
+  let status: IntentManifestStatus;
+  let selectedMatches: MatchedComponent[];
+  let clarifyingQuestion: ClarifyingQuestion | undefined;
+
+  if (effectiveScore >= 0.75) {
+    // High confidence — return the single best match
+    status = "resolved";
+    selectedMatches = allMatches.slice(0, 1).map((m) => ({
+      dsNodeId: m.dsNodeId,
+      dsName: m.dsName,
+      score: m.score,
+      variantHints: m.variantHints,
+      tokenRefs: m.tokenRefs,
+    }));
+  } else if (effectiveScore >= 0.5) {
+    // Medium confidence — ask a clarifying question
+    status = "ambiguous";
+    const topThree = allMatches.slice(0, 3);
+    selectedMatches = topThree.map((m) => ({
+      dsNodeId: m.dsNodeId,
+      dsName: m.dsName,
+      score: m.score,
+      variantHints: m.variantHints,
+      tokenRefs: m.tokenRefs,
+    }));
+    clarifyingQuestion = {
+      question: `I found multiple components that could match "${prompt}". Which did you mean?`,
+      candidates: topThree.map((m) => ({
+        dsNodeId: m.dsNodeId,
+        dsName: m.dsName,
+        score: m.score,
+      })),
+    };
+  } else {
+    // Low confidence — list the 3 closest matches for user inspection
+    status = "low-confidence";
+    selectedMatches = allMatches.slice(0, 3).map((m) => ({
+      dsNodeId: m.dsNodeId,
+      dsName: m.dsName,
+      score: m.score,
+      variantHints: m.variantHints,
+      tokenRefs: m.tokenRefs,
+    }));
+  }
+
+  // 5. Log the decision
+  const logEntry = await decisionLog.log({
+    tool: "intent-translator",
+    nodeIds: selectedMatches.map((m) => m.dsNodeId),
+    rationale: `Parsed prompt "${prompt}" → components: [${parsedIntent.componentTypes.join(", ")}]. Status: ${status}. Best confidence: ${effectiveScore.toFixed(2)}.`,
+    tokens: parsedIntent.tokens,
+    reversible: false,
+    metadata: {
+      prompt,
+      context,
+      strictMode,
+      parsedIntent,
+      status,
+      matchCount: allMatches.length,
+    },
+  });
+
+  return {
+    status,
+    confidence: effectiveScore,
+    parsedIntent,
+    matches: selectedMatches,
+    clarifyingQuestion,
+    logEntryId: logEntry.id,
+  };
+}

package/figma-intelligence-layer/src/tools/phase2-accuracy/layout-intelligence/container-patterns.ts

@@ -0,0 +1,123 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Container Patterns
+// Lookup table that maps detected container kinds to optimal Auto Layout
+// configuration and spacing tokens.  Used by layout-intelligence.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ContainerKind =
+  | "navigation bar"
+  | "card"
+  | "form"
+  | "button"
+  | "grid"
+  | "list item"
+  | "modal"
+  | "section";
+
+export interface AutoLayoutSpec {
+  direction: "HORIZONTAL" | "VERTICAL" | "WRAP";
+  primaryAxisSizingMode: "FIXED" | "AUTO";
+  counterAxisSizingMode: "FIXED" | "AUTO";
+  paddingToken: string;
+  gapToken: string;
+  paddingValue: number;
+  gapValue: number;
+}
+
+/** Spacing token name → px */
+export const SPACE: Record<string, number> = {
+  "--space-xs":  4,
+  "--space-sm":  8,
+  "--space-md":  16,
+  "--space-lg":  24,
+  "--space-xl":  32,
+  "--space-2xl": 48,
+};
+
+/**
+ * Container type → recommended Auto Layout + token settings.
+ *
+ * From the plan:
+ *   Navigation bar  → Horizontal, Fill W / Hug H, --space-md
+ *   Card            → Vertical,   Fill W / Hug H, --space-lg
+ *   Form            → Vertical,   Fill W / Hug H, --space-md gap
+ *   Button          → Horizontal, Hug W / Hug H,  --space-sm × --space-md
+ *   Grid container  → Wrap,       Fill W / Hug H, --space-md gap
+ *   List item       → Horizontal, Fill W / Hug H, --space-sm gap
+ *   Modal           → Vertical,   Fixed W / Hug H, --space-xl padding
+ *   Page section    → Vertical,   Fill W / Hug H, --space-2xl padding
+ */
+export const CONTAINER_SPECS: Record<ContainerKind, AutoLayoutSpec> = {
+  "navigation bar": {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-md",
+    gapToken: "--space-md",
+    paddingValue: SPACE["--space-md"],
+    gapValue: SPACE["--space-md"],
+  },
+  card: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-lg",
+    gapToken: "--space-lg",
+    paddingValue: SPACE["--space-lg"],
+    gapValue: SPACE["--space-lg"],
+  },
+  form: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-md",
+    gapToken: "--space-md",
+    paddingValue: SPACE["--space-md"],
+    gapValue: SPACE["--space-md"],
+  },
+  button: {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-sm",
+    gapToken: "--space-sm",
+    paddingValue: SPACE["--space-sm"],
+    gapValue: SPACE["--space-sm"],
+  },
+  grid: {
+    direction: "WRAP",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-md",
+    gapToken: "--space-md",
+    paddingValue: SPACE["--space-md"],
+    gapValue: SPACE["--space-md"],
+  },
+  "list item": {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-sm",
+    gapToken: "--space-sm",
+    paddingValue: SPACE["--space-sm"],
+    gapValue: SPACE["--space-sm"],
+  },
+  modal: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "FIXED",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xl",
+    gapToken: "--space-xl",
+    paddingValue: SPACE["--space-xl"],
+    gapValue: SPACE["--space-xl"],
+  },
+  section: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-2xl",
+    gapToken: "--space-2xl",
+    paddingValue: SPACE["--space-2xl"],
+    gapValue: SPACE["--space-2xl"],
+  },
+};