@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,409 @@
+/**
+ * component-spec/types.ts — All interfaces for the unified component spec tool
+ */
+
+// ─── Spec Sections ──────────────────────────────────────────────────────────
+
+export type SpecSection =
+  | "overview"
+  | "anatomy"
+  | "variants"
+  | "states"
+  | "properties"
+  | "spacing"
+  | "color-tokens"
+  | "typography"
+  | "accessibility"
+  | "usage"
+  | "related"
+  | "size-specs"
+  | "state-specs"
+  | "design-tokens"
+  | "interaction-rules"
+  | "content-guidance"
+  | "responsive"
+  | "qa-criteria"
+  | "type-hierarchy";
+
+export const ALL_SECTIONS: SpecSection[] = [
+  "overview",
+  "variants",
+  "anatomy",
+  "states",
+  "state-specs",
+  "properties",
+  "size-specs",
+  "spacing",
+  "color-tokens",
+  "design-tokens",
+  "typography",
+  "type-hierarchy",
+  "interaction-rules",
+  "content-guidance",
+  "responsive",
+  "accessibility",
+  "qa-criteria",
+  "usage",
+  "related",
+];
+
+// ─── Tool Input/Output ──────────────────────────────────────────────────────
+
+export interface ComponentSpecArgs {
+  nodeId?: string;
+  outputFormat: "json" | "markdown" | "figma-page" | "all";
+  sections?: SpecSection[];
+  pageName?: string;
+}
+
+export interface ComponentSpecResult {
+  spec: ComponentSpec;
+  markdown?: string;
+  figmaPageId?: string;
+  logEntryId: string;
+  warnings?: string[];
+}
+
+// ─── Node Snapshot (from Figma Plugin API) ──────────────────────────────────
+
+export interface NodeSnapshot {
+  id: string;
+  name: string;
+  type: string;
+  description: string;
+  width: number;
+  height: number;
+  layoutMode: string;
+  itemSpacing: number;
+  paddingTop: number;
+  paddingRight: number;
+  paddingBottom: number;
+  paddingLeft: number;
+  childCount: number;
+  childNames: string[];
+  textLayers: Array<{
+    name: string;
+    characters: string;
+    fontFamily: string;
+    fontStyle: string;
+    fontSize: number;
+    lineHeightPx: number | null;
+  }>;
+  fills: Array<{ type: string; label: string }>;
+  strokes: Array<{ type: string; label: string }>;
+  effects: Array<{ type: string; radius?: number; visible?: boolean }>;
+  tokenAliases: string[];
+  componentProperties: Array<{
+    name: string;
+    type: string;
+    value: string;
+    options: string[];
+  }>;
+  variantProperties: Record<string, string>;
+  variantGroupProperties: Record<string, string[]>;
+  variants: Array<{
+    id: string;
+    name: string;
+    description: string;
+    properties: Record<string, string>;
+  }>;
+  scanNodes?: SnapshotNode[];
+}
+
+export interface SnapshotNode {
+  id: string;
+  parentId: string | null;
+  parentName: string | null;
+  name: string;
+  type: string;
+  depth: number;
+  visible: boolean;
+  childCount: number;
+  layoutMode: string;
+  text: string;
+  componentPropertyNames: string[];
+  variantPropertyKeys: string[];
+  variantPropertyValues: string[];
+}
+
+// ─── Anatomy Extraction ─────────────────────────────────────────────────────
+
+export type ElementRole =
+  | "content-element"
+  | "optional-slot"
+  | "fixed-sub-component"
+  | "structural"
+  | "decorative";
+
+export interface ClassifiedElement {
+  index: number;
+  name: string;
+  nodeType: string;
+  role: ElementRole;
+  visible: boolean;
+  controlledByBoolean?: string;
+  depth?: number;
+  position: { x: number; y: number; w: number; h: number };
+  absolutePosition?: { x: number; y: number; w: number; h: number };
+
+  // TEXT nodes
+  fontFamily?: string;
+  fontStyle?: string;
+  fontSize?: number;
+  lineHeightPx?: number;
+  tokenName?: string;
+  characters?: string;
+
+  // INSTANCE nodes
+  componentName?: string;
+  instanceOf?: string;
+  variantProperties?: Record<string, string>;
+
+  // FRAME/COMPONENT nodes
+  layoutMode?: string;
+  itemSpacing?: number;
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  layoutSizingH?: string;
+  layoutSizingV?: string;
+
+  // All nodes
+  fills?: string[];
+  strokes?: string[];
+  cornerRadius?: number;
+}
+
+export interface AnatomyExtraction {
+  elements: ClassifiedElement[];
+  componentBounds?: { x: number; y: number; w: number; h: number };
+}
+
+// ─── Properties Extraction ──────────────────────────────────────────────────
+
+export interface VariantAxis {
+  name: string;
+  values: string[];
+  defaultValue: string;
+}
+
+export interface BooleanToggle {
+  name: string;
+  defaultValue: boolean;
+  controlsElement?: string;
+}
+
+export interface InstanceSwap {
+  name: string;
+  currentComponentName: string;
+}
+
+export interface PropertyExtraction {
+  variantAxes: VariantAxis[];
+  booleanToggles: BooleanToggle[];
+  instanceSwaps: InstanceSwap[];
+  textProperties: Array<{ name: string; value: string }>;
+}
+
+// ─── States Extraction ──────────────────────────────────────────────────────
+
+export interface DetectedState {
+  name: string;
+  source: "variant-axis" | "component-property";
+  axisName: string;
+}
+
+export interface StatesExtraction {
+  states: DetectedState[];
+  stateAxisName: string | null;
+}
+
+// ─── Spacing Extraction ─────────────────────────────────────────────────────
+
+export interface SpacingChildEntry {
+  name: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface SpacingEntry {
+  element: string;
+  paddingTop: number;
+  paddingRight: number;
+  paddingBottom: number;
+  paddingLeft: number;
+  itemSpacing: number;
+  width: number;
+  height: number;
+  layoutMode: string;
+  layoutSizingH: string;
+  layoutSizingV: string;
+  children?: SpacingChildEntry[];
+}
+
+// ─── Color Token Extraction ─────────────────────────────────────────────────
+
+export interface ColorTokenEntry {
+  element: string;
+  property: "fill" | "stroke";
+  colorHex: string;
+  tokenName: string;
+  tokenId: string;
+}
+
+// ─── Typography Extraction ──────────────────────────────────────────────────
+
+export interface TypographyEntry {
+  element: string;
+  characters: string;
+  fontFamily: string;
+  fontStyle: string;
+  fontSize: number;
+  lineHeightPx: number | null;
+  letterSpacing: number;
+  tokenName: string;
+}
+
+// ─── Extraction Result (all data combined) ──────────────────────────────────
+
+export interface ExtractionResult {
+  snapshot: NodeSnapshot;
+  anatomy: AnatomyExtraction;
+  properties: PropertyExtraction;
+  states: StatesExtraction;
+  spacing: SpacingEntry[];
+  colorTokens: ColorTokenEntry[];
+  typography: TypographyEntry[];
+  componentType?: string;
+  typeGuidance?: ComponentTypeGuidance;
+  knowledge?: ComponentKnowledge;
+}
+
+// ─── Component Knowledge (design intelligence) ────────────────────────────
+
+export interface ComponentKnowledge {
+  description: string;
+
+  stateSpecifications: Array<{
+    state: string;
+    visualChange: string;
+    opacity: string;
+    cursorWeb: string;
+    usage: string;
+  }>;
+
+  propertyDescriptions: Record<string, string>;
+
+  sizeSpecifications: Array<{
+    size: string;
+    height: string;
+    paddingLR: string;
+    fontSize: string;
+    iconSize: string;
+    borderRadius: string;
+  }>;
+
+  designTokenBindings: Array<{
+    property: string;
+    tokenName: string;
+    role: string;
+    fallback: string;
+  }>;
+
+  structureRules: string[];
+  typeHierarchyRules: string[];
+
+  interactionRules: Array<{
+    event: string;
+    trigger: string;
+    action: string;
+  }>;
+
+  contentGuidance: string[];
+
+  responsiveBehaviour: Array<{
+    breakpoint: string;
+    behavior: string;
+  }>;
+
+  accessibilitySpec: {
+    intro: string;
+    requirements: Array<{
+      requirement: string;
+      level: "A" | "AA" | "AAA";
+      notes: string;
+    }>;
+    outro: string[];
+  };
+
+  qaAcceptanceCriteria: Array<{
+    check: string;
+    platform: string;
+    expectedResult: string;
+  }>;
+
+  dos: string[];
+  donts: string[];
+}
+
+// ─── Component Type Guidance ────────────────────────────────────────────────
+
+export interface ComponentTypeGuidance {
+  expectedElements: string[];
+  expectedVariantAxes: string[];
+  expectedStates: string[];
+  semanticRole: string;
+  wcagPattern: string;
+  minTouchTarget: number;
+  contrastRequirement: string;
+}
+
+// ─── Section Output ─────────────────────────────────────────────────────────
+
+export interface SpecSectionOutput {
+  id: SpecSection;
+  title: string;
+  content: SpecSectionContent;
+}
+
+export type SpecSectionContent =
+  | { kind: "key-value"; entries: Array<{ label: string; value: string }> }
+  | { kind: "table"; headers: string[]; rows: string[][] }
+  | { kind: "list"; items: string[] }
+  | { kind: "do-dont"; dos: string[]; donts: string[] }
+  | { kind: "paragraph"; text: string }
+  | { kind: "mixed"; blocks: SpecSectionContent[] }
+  | { kind: "structured-data"; columns: string[]; rows: Record<string, string>[] }
+  | { kind: "rules"; items: string[] };
+
+// ─── Full Component Spec ────────────────────────────────────────────────────
+
+export interface ComponentSpec {
+  componentName: string;
+  description?: string;
+  nodeId: string;
+  nodeType: string;
+  componentType?: string;
+  sections: SpecSectionOutput[];
+  extraction: ExtractionResult;
+}
+
+// ─── Legacy re-exports needed by apg-doc ────────────────────────────────────
+
+export type DocumentationSectionStyle = "bullets" | "paragraph" | "checklist";
+
+export interface GeneratedDocumentSection {
+  title: string;
+  style: DocumentationSectionStyle;
+  items: string[];
+}
+
+export interface GeneratedDocument {
+  type: "anatomy-usage" | "accessibility" | "accessibility-annotation";
+  title: string;
+  summary: string;
+  sections: GeneratedDocumentSection[];
+}

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec-sheet/index.ts

@@ -0,0 +1,198 @@
+/**
+ * component-spec-sheet/index.ts
+ *
+ * Visual spec sheet generator — creates an on-canvas anatomy + properties
+ * + spacing spec sheet in 3-5 seconds, similar to EightShapes Specs plugin.
+ *
+ * Pipeline: Extract (parallel) → Plan (CPU) → Render (1 execute call)
+ */
+import { getBridge } from "../../../shared/figma-bridge.js";
+import { resolveTargetNodeId, captureSnapshot } from "../component-spec/extractors/snapshot.js";
+import { extractAnatomy } from "../component-spec/extractors/anatomy.js";
+import { extractSpacing } from "../component-spec/extractors/spacing.js";
+import { computeMarkerPositions } from "../component-spec/renderers/anatomy-diagram.js";
+import { buildSpecSheetScript } from "./renderer.js";
+import type {
+  SpecSheetArgs,
+  SpecSheetResult,
+  SpecSheetPlan,
+  SpecSheetSection,
+  PropertyAxisPlan,
+  BooleanTogglePlan,
+} from "./types.js";
+import type { NodeSnapshot, AnatomyExtraction, SpacingEntry } from "../component-spec/types.js";
+
+const DEFAULT_SECTIONS: SpecSheetSection[] = ["header", "anatomy", "properties", "spacing"];
+const MAX_VARIANTS_DEFAULT = 6;
+const MARKER_MARGIN = 60;
+
+// ── Main handler ────────────────────────────────────────────────────────
+
+export async function componentSpecSheetHandler(
+  args: SpecSheetArgs,
+): Promise<SpecSheetResult> {
+  const bridge = await getBridge();
+
+  // Phase 1: Extract (parallel)
+  const nodeId = await resolveTargetNodeId(args);
+
+  const [snapshot, anatomy, spacing] = await Promise.all([
+    captureSnapshot(nodeId),
+    extractAnatomy(nodeId),
+    extractSpacing(nodeId),
+  ]);
+
+  // Phase 2: Plan
+  const plan = buildPlan(nodeId, snapshot, anatomy, spacing, args);
+
+  // Phase 3: Render
+  const script = buildSpecSheetScript(plan);
+  const result = await bridge.execute(script);
+
+  if (!result.success) {
+    throw new Error(`Spec sheet render failed: ${result.error}`);
+  }
+
+  const frameId = (result.result as { frameId: string })?.frameId || "";
+
+  return {
+    frameId,
+    componentName: plan.componentName,
+    sections: plan.sections,
+    variantCount: plan.propertyAxes.reduce((sum, ax) => sum + ax.samples.length, 0),
+    anatomyElementCount: plan.markers.length,
+  };
+}
+
+// ── Plan builder ────────────────────────────────────────────────────────
+
+function buildPlan(
+  nodeId: string,
+  snapshot: NodeSnapshot,
+  anatomy: AnatomyExtraction,
+  spacing: SpacingEntry[],
+  args: SpecSheetArgs,
+): SpecSheetPlan {
+  const sections = args.sections ?? DEFAULT_SECTIONS;
+  const maxVariants = args.maxVariantsPerAxis ?? MAX_VARIANTS_DEFAULT;
+  const placement = args.placement ?? "right";
+
+  const compW = anatomy.componentBounds?.w || snapshot.width || 200;
+  const compH = anatomy.componentBounds?.h || snapshot.height || 60;
+
+  // Variant label for header
+  const variantLabel = Object.entries(snapshot.variantProperties || {})
+    .map(([k, v]) => `${k}=${v}`)
+    .join(", ");
+
+  // Anatomy: scale up small components (cap at 3x to avoid oversized previews)
+  const MIN_DISPLAY = 120;
+  const scale = Math.min(3, Math.max(1, MIN_DISPLAY / Math.min(compW, compH)));
+  const displayW = Math.round(compW * scale);
+  const displayH = Math.round(compH * scale);
+
+  // Filter anatomy to direct children only (depth 1) for clean spec sheet
+  const directChildren = anatomy.elements.filter(
+    el => el.visible && el.position.w > 0 && el.position.h > 0 && (el.depth === undefined || el.depth === 1),
+  );
+
+  // Compute marker positions using scaled element positions
+  const scaledElements = directChildren.map(el => ({
+    ...el,
+    position: {
+      x: Math.round(el.position.x * scale),
+      y: Math.round(el.position.y * scale),
+      w: Math.round(el.position.w * scale),
+      h: Math.round(el.position.h * scale),
+    },
+  }));
+
+  // For the spec sheet, markers are placed OUTSIDE the component with leader lines.
+  // Pass MARKER_MARGIN as offset so markers sit in the margin area around the clone.
+  const markers = computeMarkerPositions(displayW, displayH, MARKER_MARGIN, MARKER_MARGIN, scaledElements);
+
+  // Property axes from variantGroupProperties
+  const propertyAxes: PropertyAxisPlan[] = [];
+  const variantGroupProps = snapshot.variantGroupProperties || {};
+  const defaultProps = snapshot.variants?.[0]?.properties || {};
+
+  for (const [axisName, values] of Object.entries(variantGroupProps)) {
+    const capped = values.slice(0, maxVariants);
+    const samples = capped.map(val => {
+      // Find the variant that matches this value (use defaults for other axes)
+      const props = { ...defaultProps, [axisName]: val };
+      const matchedVariant = snapshot.variants.find(v => {
+        for (const [pk, pv] of Object.entries(props)) {
+          if (v.properties[pk] !== pv) return false;
+        }
+        return true;
+      });
+      return {
+        variantId: matchedVariant?.id || "",
+        label: val,
+        props,
+      };
+    });
+    propertyAxes.push({ axisName, samples });
+  }
+
+  // Boolean toggles from componentProperties
+  const booleanToggles: BooleanTogglePlan[] = [];
+  for (const cp of snapshot.componentProperties || []) {
+    if (cp.type === "BOOLEAN") {
+      const cleanName = cp.name.replace(/#.*$/, "").trim();
+      booleanToggles.push({
+        name: cleanName,
+        trueVariantId: null,
+        falseVariantId: null,
+      });
+    }
+  }
+
+  // Placement coordinates
+  const placementCoords = computePlacement(
+    placement,
+    snapshot.width || 200,
+    snapshot.height || 200,
+  );
+
+  return {
+    componentName: snapshot.name,
+    variantLabel,
+    sourceNodeId: nodeId,
+    sourceType: snapshot.type,
+    placement: placementCoords,
+    componentBounds: { w: compW, h: compH },
+    sections,
+    anatomyElements: anatomy.elements,
+    markers: markers.map(m => ({
+      letter: m.letter,
+      markerX: m.markerX,
+      markerY: m.markerY,
+      targetX: m.targetX,
+      targetY: m.targetY,
+      name: m.name,
+      role: m.role,
+    })),
+    anatomyScale: scale,
+    anatomyDisplayW: displayW,
+    anatomyDisplayH: displayH,
+    propertyAxes,
+    booleanToggles,
+    spacingEntries: spacing,
+  };
+}
+
+function computePlacement(
+  placement: string,
+  sourceW: number,
+  sourceH: number,
+): { x: number; y: number } {
+  switch (placement) {
+    case "below":
+      return { x: 0, y: sourceH + 100 };
+    case "right":
+    default:
+      return { x: sourceW + 200, y: 0 };
+  }
+}