@sarjallab09/figma-intelligence 1.0.1 → 1.2.0

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/spacing-structure.ts

@@ -1,58 +0,0 @@
-/**
- * Spacing & Structure section — layout info, dimensions, padding, gaps
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildSpacingSection(data: ExtractionResult): SpecSectionOutput {
-  const { spacing, snapshot } = data;
-  const blocks: SpecSectionContent[] = [];
-
-  // Root component structure
-  blocks.push({
-    kind: "key-value",
-    entries: [
-      { label: "Root layout", value: snapshot.layoutMode === "NONE" ? "Absolute (no auto layout)" : `${snapshot.layoutMode} auto layout` },
-      { label: "Dimensions", value: `${Math.round(snapshot.width)} × ${Math.round(snapshot.height)} px` },
-      { label: "Padding", value: `${snapshot.paddingTop} / ${snapshot.paddingRight} / ${snapshot.paddingBottom} / ${snapshot.paddingLeft} (T/R/B/L)` },
-      { label: "Item spacing", value: `${snapshot.itemSpacing}px` },
-    ],
-  });
-
-  // Child spacing table
-  if (spacing.length > 0) {
-    blocks.push({
-      kind: "table",
-      headers: ["Element", "Layout", "W × H", "Padding (T/R/B/L)", "Gap", "Sizing (H/V)"],
-      rows: spacing.slice(0, 20).map((entry) => [
-        entry.element,
-        entry.layoutMode,
-        `${entry.width} × ${entry.height}`,
-        `${entry.paddingTop}/${entry.paddingRight}/${entry.paddingBottom}/${entry.paddingLeft}`,
-        `${entry.itemSpacing}px`,
-        `${entry.layoutSizingH} / ${entry.layoutSizingV}`,
-      ]),
-    });
-  }
-
-  // Layout guidance
-  if (snapshot.layoutMode === "NONE") {
-    blocks.push({
-      kind: "paragraph",
-      text: "This component uses absolute positioning instead of auto layout. Consider converting to auto layout for responsive behavior, consistent spacing, and easier maintenance.",
-    });
-  }
-
-  // Knowledge-based structure rules
-  if (data.knowledge?.structureRules && data.knowledge.structureRules.length > 0) {
-    blocks.push({
-      kind: "rules",
-      items: data.knowledge.structureRules,
-    });
-  }
-
-  return {
-    id: "spacing",
-    title: "Structure & Layout",
-    content: blocks.length === 1 ? blocks[0] : { kind: "mixed", blocks },
-  };
-}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/state-specs.ts

@@ -1,79 +0,0 @@
-/**
- * State Specifications section — rich state descriptions merged from knowledge
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildStateSpecsSection(data: ExtractionResult): SpecSectionOutput | null {
-  const { states, knowledge } = data;
-  if (!knowledge || knowledge.stateSpecifications.length === 0) return null;
-
-  const blocks: SpecSectionContent[] = [];
-
-  // Build a lookup from knowledge state entries
-  const knowledgeLookup = new Map(
-    knowledge.stateSpecifications.map((s) => [s.state.toLowerCase(), s])
-  );
-
-  // If we have detected Figma states, merge with knowledge
-  if (states.states.length > 0) {
-    const detectedNames = states.states.map((s) => s.name);
-    const rows: Record<string, string>[] = [];
-
-    for (const name of detectedNames) {
-      const kEntry = knowledgeLookup.get(name.toLowerCase());
-      rows.push({
-        state: name,
-        visualChange: kEntry?.visualChange ?? "See component definition",
-        opacity: kEntry?.opacity ?? "100% (1.0)",
-        cursorWeb: kEntry?.cursorWeb ?? "default",
-        usage: kEntry?.usage ?? "",
-      });
-    }
-
-    // Add knowledge-only states that were expected but not detected
-    for (const kState of knowledge.stateSpecifications) {
-      const alreadyIncluded = detectedNames.some(
-        (n) => n.toLowerCase() === kState.state.toLowerCase()
-      );
-      if (!alreadyIncluded) {
-        rows.push({
-          state: `${kState.state} (expected)`,
-          visualChange: kState.visualChange,
-          opacity: kState.opacity,
-          cursorWeb: kState.cursorWeb,
-          usage: kState.usage,
-        });
-      }
-    }
-
-    blocks.push({
-      kind: "structured-data",
-      columns: ["state", "visualChange", "opacity", "cursorWeb", "usage"],
-      rows,
-    });
-  } else {
-    // No Figma states detected — output full knowledge as recommended spec
-    blocks.push({
-      kind: "structured-data",
-      columns: ["state", "visualChange", "opacity", "cursorWeb", "usage"],
-      rows: knowledge.stateSpecifications.map((s) => ({
-        state: `${s.state} (recommended)`,
-        visualChange: s.visualChange,
-        opacity: s.opacity,
-        cursorWeb: s.cursorWeb,
-        usage: s.usage,
-      })),
-    });
-
-    blocks.push({
-      kind: "paragraph",
-      text: "No explicit state variants detected in the Figma component. The states listed above are recommended for this component type.",
-    });
-  }
-
-  return {
-    id: "state-specs",
-    title: "State Specifications",
-    content: blocks.length === 1 ? blocks[0] : { kind: "mixed", blocks },
-  };
-}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/states.ts

@@ -1,50 +0,0 @@
-/**
- * States section — detected interaction states
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildStatesSection(data: ExtractionResult): SpecSectionOutput {
-  const { states, snapshot } = data;
-  const blocks: SpecSectionContent[] = [];
-
-  if (states.states.length > 0) {
-    blocks.push({
-      kind: "table",
-      headers: ["State", "Source", "Axis / Property"],
-      rows: states.states.map((s) => [s.name, s.source, s.axisName || "—"]),
-    });
-  }
-
-  // Generate expected states based on component type
-  const isInteractive = /button|btn|input|field|toggle|switch|checkbox|radio|tab|link|select|slider/i.test(snapshot.name);
-  if (isInteractive) {
-    const expectedStates = ["Default", "Hover", "Pressed", "Focused", "Disabled"];
-    const detectedNames = states.states.map((s) => s.name.toLowerCase());
-    const missing = expectedStates.filter((s) => !detectedNames.some((d) => d.includes(s.toLowerCase())));
-
-    if (missing.length > 0 && states.states.length > 0) {
-      blocks.push({
-        kind: "paragraph",
-        text: `Potentially missing states for an interactive component: ${missing.join(", ")}. Review whether these states are needed for this component.`,
-      });
-    }
-
-    if (states.states.length === 0) {
-      blocks.push({
-        kind: "paragraph",
-        text: `This appears to be an interactive component but no explicit state variants were detected. Expected states for interactive components include: ${expectedStates.join(", ")}. Consider adding a "State" variant axis to support these interaction states.`,
-      });
-    }
-  } else if (states.states.length === 0) {
-    blocks.push({
-      kind: "paragraph",
-      text: "No explicit interaction states detected. This component appears to be a static/presentational element. If it needs interaction states, add a variant axis named \"State\" with values like Default, Hover, Pressed, Focused, Disabled.",
-    });
-  }
-
-  return {
-    id: "states",
-    title: "States",
-    content: blocks.length === 1 ? blocks[0] : { kind: "mixed", blocks },
-  };
-}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/type-hierarchy.ts

@@ -1,33 +0,0 @@
-/**
- * Type Hierarchy & Emphasis section — typography rules from knowledge + extracted data
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildTypeHierarchySection(data: ExtractionResult): SpecSectionOutput | null {
-  const { knowledge, typography } = data;
-  if (!knowledge || knowledge.typeHierarchyRules.length === 0) return null;
-
-  const blocks: SpecSectionContent[] = [];
-
-  blocks.push({
-    kind: "rules",
-    items: knowledge.typeHierarchyRules,
-  });
-
-  // Add observed typography summary if available
-  if (typography.length > 0) {
-    const fontFamilies = [...new Set(typography.map((t) => `${t.fontFamily} ${t.fontStyle}`))];
-    const fontSizes = [...new Set(typography.map((t) => t.fontSize))].sort((a, b) => a - b);
-
-    blocks.push({
-      kind: "paragraph",
-      text: `Observed in component: ${fontFamilies.join(", ")}. Size range: ${fontSizes[0]}px–${fontSizes[fontSizes.length - 1]}px.`,
-    });
-  }
-
-  return {
-    id: "type-hierarchy",
-    title: "Type Hierarchy & Emphasis",
-    content: blocks.length === 1 ? blocks[0] : { kind: "mixed", blocks },
-  };
-}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/typography.ts

@@ -1,55 +0,0 @@
-/**
- * Typography section — text style specifications with guidance
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildTypographySection(data: ExtractionResult): SpecSectionOutput {
-  const { typography, snapshot } = data;
-  const blocks: SpecSectionContent[] = [];
-
-  if (typography.length > 0) {
-    blocks.push({
-      kind: "table",
-      headers: ["Element", "Content", "Font", "Size", "Line Height", "Token"],
-      rows: typography.map((entry) => [
-        entry.element,
-        entry.characters.length > 40 ? entry.characters.slice(0, 37) + "…" : entry.characters || "—",
-        `${entry.fontFamily} ${entry.fontStyle}`,
-        `${entry.fontSize}px`,
-        entry.lineHeightPx ? `${Math.round(entry.lineHeightPx)}px` : "Auto",
-        entry.tokenName || "—",
-      ]),
-    });
-
-    // Font summary
-    const fonts = [...new Set(typography.map((t) => `${t.fontFamily} ${t.fontStyle}`))];
-    const sizes = [...new Set(typography.map((t) => t.fontSize))].sort((a, b) => a - b);
-    blocks.push({
-      kind: "paragraph",
-      text: `Font families used: ${fonts.join(", ")}. Size range: ${sizes[0]}px–${sizes[sizes.length - 1]}px across ${typography.length} text layer(s).`,
-    });
-  } else if (snapshot.textLayers.length > 0) {
-    // Use snapshot text layers as fallback
-    blocks.push({
-      kind: "table",
-      headers: ["Layer", "Content", "Font", "Size"],
-      rows: snapshot.textLayers.map((t) => [
-        t.name,
-        t.characters.length > 40 ? t.characters.slice(0, 37) + "…" : t.characters || "—",
-        `${t.fontFamily} ${t.fontStyle}`,
-        `${t.fontSize}px`,
-      ]),
-    });
-  } else {
-    blocks.push({
-      kind: "paragraph",
-      text: `No text layers detected in "${snapshot.name}". This component is either icon-only, purely structural, or all text is inside nested sub-components.`,
-    });
-  }
-
-  return {
-    id: "typography",
-    title: "Typography",
-    content: blocks.length === 1 ? blocks[0] : { kind: "mixed", blocks },
-  };
-}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/usage-guidelines.ts

@@ -1,73 +0,0 @@
-/**
- * Usage Guidelines section — do's and don'ts derived from component structure
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildUsageSection(data: ExtractionResult): SpecSectionOutput {
-  const { snapshot, properties, anatomy, states, colorTokens, knowledge } = data;
-
-  // If knowledge provides curated dos/donts, use those as the base
-  const dos: string[] = knowledge?.dos ? [...knowledge.dos] : [];
-  const donts: string[] = knowledge?.donts ? [...knowledge.donts] : [];
-
-  // Only add generated guidance when knowledge doesn't provide curated content
-  if (!knowledge?.dos || knowledge.dos.length === 0) {
-    // Token-based guidance
-    const hasTokens = colorTokens.some((t) => t.tokenName);
-    if (hasTokens) {
-      dos.push("Use the bound design tokens for all colors — never hardcode hex values.");
-    } else if (colorTokens.length > 0) {
-      donts.push("Hardcoded colors detected — bind all fills and strokes to design tokens before publishing.");
-    }
-
-    // Variant-based guidance
-    if (properties.variantAxes.length > 0) {
-      dos.push(`Use the variant properties (${properties.variantAxes.map((a) => a.name).join(", ")}) to configure the component. Don't detach instances to create custom variations.`);
-    }
-
-    // Boolean toggle guidance
-    if (properties.booleanToggles.length > 0) {
-      dos.push(`Use boolean toggles (${properties.booleanToggles.map((t) => t.name).join(", ")}) to show/hide optional elements instead of deleting layers.`);
-    }
-
-    // Anatomy-based guidance
-    const requiredElements = anatomy.elements.filter((e) => e.role === "content-element");
-    if (requiredElements.length > 0) {
-      dos.push(`Keep required elements intact: ${requiredElements.map((e) => e.name).join(", ")}.`);
-      donts.push("Don't remove or hide required child elements — this breaks the component's semantic structure.");
-    }
-
-    const optionalSlots = anatomy.elements.filter((e) => e.role === "optional-slot");
-    if (optionalSlots.length > 0) {
-      dos.push(`Toggle optional elements (${optionalSlots.map((e) => e.name).join(", ")}) via boolean properties instead of deleting them.`);
-    }
-
-    // State-based guidance
-    if (states.states.length > 0) {
-      dos.push(`Support all defined states (${states.states.map((s) => s.name).join(", ")}) in your implementation.`);
-      donts.push("Don't create undocumented state variations — extend the variant set formally if new states are needed.");
-    }
-
-    // Layout-based guidance
-    if (snapshot.layoutMode !== "NONE") {
-      dos.push("Preserve auto layout settings when overriding content — don't switch to absolute positioning.");
-      dos.push(`Maintain the ${snapshot.itemSpacing}px gap between child elements.`);
-    }
-
-    // Instance swap guidance
-    if (properties.instanceSwaps.length > 0) {
-      dos.push(`Use instance swap properties for ${properties.instanceSwaps.map((s) => s.name).join(", ")} — only swap in compatible component types.`);
-      donts.push("Don't replace swap slots with unrelated components that break the visual or semantic contract.");
-    }
-
-    // General best practices
-    dos.push("Test the component in both light and dark themes before publishing.");
-    donts.push("Don't override internal padding or spacing values — use the component's built-in sizing properties.");
-  }
-
-  return {
-    id: "usage",
-    title: "Usage Guidelines",
-    content: { kind: "do-dont", dos, donts },
-  };
-}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/sections/variants.ts

@@ -1,81 +0,0 @@
-/**
- * Variants section — variant axes, boolean toggles, instance swaps, variant matrix
- */
-import type { ExtractionResult, SpecSectionOutput, SpecSectionContent } from "../types.js";
-
-export function buildVariantsSection(data: ExtractionResult): SpecSectionOutput | null {
-  const { properties, snapshot } = data;
-  const blocks: SpecSectionContent[] = [];
-
-  // Variant axes table
-  if (properties.variantAxes.length > 0) {
-    blocks.push({
-      kind: "table",
-      headers: ["Axis", "Values", "Default", "Count"],
-      rows: properties.variantAxes.map((axis) => [
-        axis.name,
-        axis.values.join(", "),
-        axis.defaultValue || axis.values[0] || "—",
-        String(axis.values.length),
-      ]),
-    });
-  }
-
-  // Boolean toggles
-  if (properties.booleanToggles.length > 0) {
-    blocks.push({
-      kind: "table",
-      headers: ["Toggle", "Default", "Controls Element"],
-      rows: properties.booleanToggles.map((t) => [
-        t.name,
-        t.defaultValue ? "true" : "false",
-        t.controlsElement || "—",
-      ]),
-    });
-  }
-
-  // Instance swaps
-  if (properties.instanceSwaps.length > 0) {
-    blocks.push({
-      kind: "table",
-      headers: ["Swap Slot", "Current Component"],
-      rows: properties.instanceSwaps.map((s) => [s.name, s.currentComponentName || "—"]),
-    });
-  }
-
-  // Variant combination summary
-  if (properties.variantAxes.length > 0) {
-    const totalCombinations = properties.variantAxes.reduce((acc, a) => acc * a.values.length, 1);
-    const boolMultiplier = properties.booleanToggles.length > 0 ? Math.pow(2, properties.booleanToggles.length) : 1;
-    blocks.push({
-      kind: "paragraph",
-      text: `Total possible configurations: ${totalCombinations * boolMultiplier} (${properties.variantAxes.length} variant axes × ${properties.booleanToggles.length} boolean toggles). Defined variants in file: ${snapshot.variants.length}.`,
-    });
-  }
-
-  // Variant list (first few names)
-  if (snapshot.variants.length > 0 && snapshot.variants.length <= 20) {
-    blocks.push({
-      kind: "list",
-      items: snapshot.variants.map((v) => v.name),
-    });
-  } else if (snapshot.variants.length > 20) {
-    const items = snapshot.variants.slice(0, 15).map((v) => v.name);
-    items.push(`... and ${snapshot.variants.length - 15} more variants`);
-    blocks.push({ kind: "list", items });
-  }
-
-  if (blocks.length === 0) {
-    // Always produce content
-    blocks.push({
-      kind: "paragraph",
-      text: "This component has no variant axes, boolean toggles, or instance swap slots defined. It is a single-configuration component. Consider adding variant properties (e.g., Size, State, Style) if this component needs multiple configurations for different use cases.",
-    });
-  }
-
-  return {
-    id: "variants",
-    title: "Variants",
-    content: blocks.length === 1 ? blocks[0] : { kind: "mixed", blocks },
-  };
-}