@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,58 @@
+/**
+ * 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

@@ -0,0 +1,79 @@
+/**
+ * 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

@@ -0,0 +1,50 @@
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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

@@ -0,0 +1,55 @@
+/**
+ * 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

@@ -0,0 +1,73 @@
+/**
+ * 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

@@ -0,0 +1,81 @@
+/**
+ * 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 },
+  };
+}