@sarjallab09/figma-intelligence 1.0.0

package/figma-bridge-plugin/spec-helpers/build-table.js

@@ -0,0 +1,269 @@
+/**
+ * build-table.js
+ * 
+ * Generates Figma MCP commands to create structured data tables.
+ * Used by all spec types for rendering property tables, attribute tables,
+ * token mapping tables, etc.
+ * 
+ * Design tokens:
+ * - Header background: #F3F4F6
+ * - Alternate row background: #FAFAFA  
+ * - Border color: #E5E5E5
+ * - Header text: 13px bold, #1A1A1A
+ * - Body text: 13px regular, #1A1A1A
+ * - Cell padding: 8px horizontal, 6px vertical
+ */
+
+const TABLE_STYLES = {
+  headerBg: '#F3F4F6',
+  altRowBg: '#FAFAFA',
+  borderColor: '#E5E5E5',
+  textColor: '#1A1A1A',
+  headerFontSize: 13,
+  bodyFontSize: 13,
+  cellPaddingH: 8,
+  cellPaddingV: 6,
+  borderWeight: 1,
+  rowHeight: 36,
+  headerRowHeight: 40
+};
+
+/**
+ * Build a table specification object.
+ * 
+ * @param {Object} config
+ * @param {Array<Object>} config.columns - [{ key, label, width }]
+ * @param {Array<Object>} config.rows - [{ [key]: value, ... }]
+ * @param {number} config.x - X position
+ * @param {number} config.y - Y position
+ * @param {string} config.name - Frame name for the table
+ * @returns {Object} Table spec with dimensions and commands
+ */
+function buildTable(config) {
+  const { columns, rows, x = 0, y = 0, name = 'Table' } = config;
+  
+  const totalWidth = columns.reduce((sum, col) => sum + col.width, 0);
+  const totalHeight = TABLE_STYLES.headerRowHeight + (rows.length * TABLE_STYLES.rowHeight);
+  
+  const commands = [];
+  
+  // Table container frame
+  commands.push({
+    tool: 'create_frame',
+    params: {
+      x, y,
+      width: totalWidth,
+      height: totalHeight,
+      name,
+      fills: [{ type: 'SOLID', color: '#FFFFFF' }],
+      stroke: { color: TABLE_STYLES.borderColor, weight: TABLE_STYLES.borderWeight }
+    }
+  });
+  
+  // Header row
+  let colX = 0;
+  for (const col of columns) {
+    commands.push({
+      tool: 'create_frame',
+      params: {
+        x: colX, y: 0,
+        width: col.width,
+        height: TABLE_STYLES.headerRowHeight,
+        name: `Header: ${col.label}`,
+        fills: [{ type: 'SOLID', color: TABLE_STYLES.headerBg }]
+      }
+    });
+    
+    commands.push({
+      tool: 'create_text',
+      params: {
+        x: colX + TABLE_STYLES.cellPaddingH,
+        y: TABLE_STYLES.cellPaddingV + 4,
+        content: col.label,
+        font_size: TABLE_STYLES.headerFontSize,
+        font_weight: 'Bold',
+        color: TABLE_STYLES.textColor,
+        width: col.width - (TABLE_STYLES.cellPaddingH * 2)
+      }
+    });
+    
+    colX += col.width;
+  }
+  
+  // Body rows
+  for (let rowIdx = 0; rowIdx < rows.length; rowIdx++) {
+    const row = rows[rowIdx];
+    const rowY = TABLE_STYLES.headerRowHeight + (rowIdx * TABLE_STYLES.rowHeight);
+    const isAlt = rowIdx % 2 === 1;
+    
+    colX = 0;
+    for (const col of columns) {
+      const cellValue = String(row[col.key] || '');
+      
+      // Cell background (alternating)
+      if (isAlt) {
+        commands.push({
+          tool: 'create_frame',
+          params: {
+            x: colX, y: rowY,
+            width: col.width,
+            height: TABLE_STYLES.rowHeight,
+            name: `Cell ${rowIdx}:${col.key}`,
+            fills: [{ type: 'SOLID', color: TABLE_STYLES.altRowBg }]
+          }
+        });
+      }
+      
+      // Cell text
+      commands.push({
+        tool: 'create_text',
+        params: {
+          x: colX + TABLE_STYLES.cellPaddingH,
+          y: rowY + TABLE_STYLES.cellPaddingV + 2,
+          content: cellValue,
+          font_size: TABLE_STYLES.bodyFontSize,
+          font_weight: row._bold && row._bold.includes(col.key) ? 'Bold' : 'Regular',
+          color: TABLE_STYLES.textColor,
+          width: col.width - (TABLE_STYLES.cellPaddingH * 2)
+        }
+      });
+      
+      // Cell border (bottom)
+      commands.push({
+        tool: 'create_line',
+        params: {
+          start_x: colX,
+          start_y: rowY + TABLE_STYLES.rowHeight,
+          end_x: colX + col.width,
+          end_y: rowY + TABLE_STYLES.rowHeight,
+          stroke_color: TABLE_STYLES.borderColor,
+          stroke_weight: TABLE_STYLES.borderWeight
+        }
+      });
+      
+      colX += col.width;
+    }
+  }
+  
+  return {
+    commands,
+    width: totalWidth,
+    height: totalHeight
+  };
+}
+
+/**
+ * Build an anatomy attribute table.
+ */
+function buildAnatomyTable(elements, x, y) {
+  const columns = [
+    { key: 'number', label: '#', width: 48 },
+    { key: 'type', label: 'Type', width: 48 },
+    { key: 'name', label: 'Element', width: 200 },
+    { key: 'notes', label: 'Notes', width: 544 }
+  ];
+  
+  const rows = elements.map((el, i) => ({
+    number: String(i + 1),
+    type: el.typeIcon || '🔲',
+    name: el.displayName + (el.hidden ? ' (hidden)' : ''),
+    notes: el.semanticNotes || ''
+  }));
+  
+  return buildTable({ columns, rows, x, y, name: 'Attribute Table' });
+}
+
+/**
+ * Build an API property table.
+ */
+function buildApiTable(properties, x, y) {
+  const columns = [
+    { key: 'name', label: 'Property', width: 160 },
+    { key: 'type', label: 'Type', width: 100 },
+    { key: 'values', label: 'Values', width: 200 },
+    { key: 'default', label: 'Default', width: 120 },
+    { key: 'required', label: 'Required', width: 80 },
+    { key: 'notes', label: 'Notes', width: 380 }
+  ];
+  
+  const rows = properties.map(prop => ({
+    name: prop.name,
+    type: prop.type,
+    values: Array.isArray(prop.values) ? prop.values.join(' | ') : prop.values,
+    default: prop.default || '—',
+    required: prop.required ? '✓' : '—',
+    notes: prop.notes || '',
+    _bold: ['default']
+  }));
+  
+  return buildTable({ columns, rows, x, y, name: 'API Property Table' });
+}
+
+/**
+ * Build a color token mapping table.
+ */
+function buildColorTable(tokenMappings, states, x, y) {
+  const stateColumns = states.map(state => ({
+    key: state.toLowerCase(),
+    label: state,
+    width: Math.max(160, Math.floor(640 / states.length))
+  }));
+  
+  const columns = [
+    { key: 'element', label: 'Element', width: 140 },
+    { key: 'property', label: 'Property', width: 80 },
+    ...stateColumns
+  ];
+  
+  const rows = tokenMappings.map(mapping => {
+    const row = {
+      element: mapping.element,
+      property: mapping.property
+    };
+    for (const state of states) {
+      const stateKey = state.toLowerCase();
+      const token = mapping.states[stateKey];
+      row[stateKey] = token ? `${token.name}\n${token.hex}` : '—';
+    }
+    return row;
+  });
+  
+  return buildTable({ columns, rows, x, y, name: 'Color Token Table' });
+}
+
+/**
+ * Build a structure dimensions table.
+ */
+function buildStructureTable(measurements, variants, x, y, sectionName) {
+  const variantColumns = variants.map(v => ({
+    key: v.toLowerCase().replace(/\s/g, '_'),
+    label: v,
+    width: Math.max(120, Math.floor(720 / variants.length))
+  }));
+  
+  const columns = [
+    { key: 'property', label: 'Property', width: 200 },
+    ...variantColumns
+  ];
+  
+  const rows = measurements.map(m => {
+    const row = { property: m.property };
+    for (const v of variants) {
+      const vKey = v.toLowerCase().replace(/\s/g, '_');
+      const val = m.values[vKey];
+      row[vKey] = val ? (val.token ? `${val.token} (${val.px})` : String(val.px)) : '—';
+    }
+    return row;
+  });
+  
+  return buildTable({ columns, rows, x, y, name: `Structure: ${sectionName}` });
+}
+
+module.exports = {
+  buildTable,
+  buildAnatomyTable,
+  buildApiTable,
+  buildColorTable,
+  buildStructureTable,
+  TABLE_STYLES
+};

package/figma-bridge-plugin/spec-helpers/classify-elements.js

@@ -0,0 +1,189 @@
+/**
+ * classify-elements.js
+ * 
+ * Deterministic classification rules for component child elements.
+ * Used by anatomy and color spec generation to filter and categorize elements.
+ * 
+ * Usage: Import and call classifyElement(node) for each child layer.
+ */
+
+// Utility sub-components that should be skipped in anatomy per-child sections
+const UTILITY_COMPONENTS = [
+  'spacer', 'divider', 'separator', 'gap', 'padding',
+  'spacing', 'gutter', 'rule', 'hairline'
+];
+
+// Structural frame names that indicate auto-layout wrappers (not meaningful elements)
+const STRUCTURAL_PATTERNS = [
+  /^frame\s*\d*$/i,
+  /^group\s*\d*$/i,
+  /^auto[-\s]?layout/i,
+  /^wrapper/i,
+  /^container$/i,  // generic "Container" (but "Input Container" is meaningful)
+  /^content$/i,
+  /^layout/i,
+  /^stack/i
+];
+
+// Decorative element patterns
+const DECORATIVE_PATTERNS = [
+  /^background$/i,
+  /^bg$/i,
+  /^shadow$/i,
+  /^overlay$/i,
+  /^backdrop$/i,
+  /^\./, // Figma convention: layers starting with "." are private/decorative
+  /^_/   // Underscore prefix also common for internal layers
+];
+
+/**
+ * Classify a Figma node into a documentation role.
+ * 
+ * @param {Object} node - Figma node data
+ * @param {string} node.name - Layer name
+ * @param {string} node.type - Node type (INSTANCE, TEXT, FRAME, etc.)
+ * @param {boolean} node.visible - Whether the node is visible
+ * @param {Object} node.componentPropertyReferences - Boolean property bindings
+ * @param {number} node.childCount - Number of meaningful children (for instances)
+ * @param {string} node.componentName - Resolved component name (for instances)
+ * 
+ * @returns {Object} { role, skip, reason }
+ *   role: 'content-element' | 'optional-slot' | 'fixed-sub-component' | 'structural' | 'decorative'
+ *   skip: boolean - whether to omit from documentation tables
+ *   reason: string - human-readable explanation
+ */
+function classifyElement(node) {
+  const name = (node.name || '').trim();
+  const type = (node.type || '').toUpperCase();
+  
+  // 1. Check if controlled by a boolean property → optional-slot
+  if (node.componentPropertyReferences && 
+      Object.keys(node.componentPropertyReferences).some(
+        key => key === 'visible' || key === 'mainComponent'
+      )) {
+    return {
+      role: 'optional-slot',
+      skip: false,
+      reason: `Controlled by boolean toggle`
+    };
+  }
+
+  // 2. Check decorative patterns
+  for (const pattern of DECORATIVE_PATTERNS) {
+    if (pattern.test(name)) {
+      return {
+        role: 'decorative',
+        skip: true,
+        reason: `Name matches decorative pattern: ${pattern}`
+      };
+    }
+  }
+
+  // 3. Check utility sub-components (for INSTANCE types)
+  if (type === 'INSTANCE' && node.componentName) {
+    const compNameLower = node.componentName.toLowerCase();
+    for (const util of UTILITY_COMPONENTS) {
+      if (compNameLower.includes(util)) {
+        return {
+          role: 'structural',
+          skip: true,
+          reason: `Utility sub-component: ${node.componentName}`
+        };
+      }
+    }
+  }
+
+  // 4. Check structural frame patterns
+  if ((type === 'FRAME' || type === 'GROUP') && !node.hasContentChildren) {
+    for (const pattern of STRUCTURAL_PATTERNS) {
+      if (pattern.test(name)) {
+        return {
+          role: 'structural',
+          skip: true,
+          reason: `Structural wrapper matching: ${pattern}`
+        };
+      }
+    }
+  }
+
+  // 5. INSTANCE with meaningful children → fixed-sub-component
+  if (type === 'INSTANCE' && node.childCount >= 2) {
+    return {
+      role: 'fixed-sub-component',
+      skip: false,
+      reason: `Instance with ${node.childCount} children — candidate for per-child section`
+    };
+  }
+
+  // 6. Everything else → content-element
+  return {
+    role: 'content-element',
+    skip: false,
+    reason: `Content element of type ${type}`
+  };
+}
+
+/**
+ * Check if a component instance qualifies for a per-child anatomy section.
+ * 
+ * @param {Object} node - Figma instance node
+ * @returns {boolean}
+ */
+function qualifiesForPerChildSection(node) {
+  if (node.type !== 'INSTANCE') return false;
+  
+  // Skip utility components
+  const compNameLower = (node.componentName || '').toLowerCase();
+  for (const util of UTILITY_COMPONENTS) {
+    if (compNameLower.includes(util)) return false;
+  }
+  
+  // Must have ≥3 internal child layers
+  if ((node.childCount || 0) < 3) return false;
+  
+  // Must have its own configurable properties
+  if (node.hasOwnProperties) return true;
+  
+  // Or must have enough structural complexity
+  return (node.childCount || 0) >= 3;
+}
+
+/**
+ * Collapse consecutive identical siblings.
+ * e.g., [Star, Star, Star, Star, Star] → [{ ...Star, count: 5, label: "Star (x5)" }]
+ */
+function collapseIdenticalSiblings(elements) {
+  const collapsed = [];
+  let i = 0;
+  
+  while (i < elements.length) {
+    let count = 1;
+    const current = elements[i];
+    
+    // Count consecutive elements with the same component ID
+    while (i + count < elements.length && 
+           elements[i + count].componentId === current.componentId &&
+           current.componentId != null) {
+      count++;
+    }
+    
+    collapsed.push({
+      ...current,
+      count,
+      displayName: count > 1 ? `${current.name} (x${count})` : current.name
+    });
+    
+    i += count;
+  }
+  
+  return collapsed;
+}
+
+module.exports = {
+  classifyElement,
+  qualifiesForPerChildSection,
+  collapseIdenticalSiblings,
+  UTILITY_COMPONENTS,
+  STRUCTURAL_PATTERNS,
+  DECORATIVE_PATTERNS
+};

package/figma-bridge-plugin/spec-helpers/index.js

@@ -0,0 +1,35 @@
+/**
+ * spec-helpers/index.js — Barrel export for spec helper modules.
+ */
+
+const { classifyElement, qualifiesForPerChildSection, collapseIdenticalSiblings, UTILITY_COMPONENTS, STRUCTURAL_PATTERNS, DECORATIVE_PATTERNS } = require('./classify-elements');
+const { buildTable, buildAnatomyTable, buildApiTable, buildColorTable, buildStructureTable, TABLE_STYLES } = require('./build-table');
+const { calculateMarkerPositions, generateMarkerCommands, MARKER_DIAMETER, MARKER_COLOR, CONNECTOR_STROKE, MIN_MARKER_GAP, MARKER_OFFSET } = require('./position-markers');
+const { parseFigmaLink } = require('./parse-figma-link');
+
+module.exports = {
+  // classify-elements
+  classifyElement,
+  qualifiesForPerChildSection,
+  collapseIdenticalSiblings,
+  UTILITY_COMPONENTS,
+  STRUCTURAL_PATTERNS,
+  DECORATIVE_PATTERNS,
+  // build-table
+  buildTable,
+  buildAnatomyTable,
+  buildApiTable,
+  buildColorTable,
+  buildStructureTable,
+  TABLE_STYLES,
+  // position-markers
+  calculateMarkerPositions,
+  generateMarkerCommands,
+  MARKER_DIAMETER,
+  MARKER_COLOR,
+  CONNECTOR_STROKE,
+  MIN_MARKER_GAP,
+  MARKER_OFFSET,
+  // parse-figma-link
+  parseFigmaLink,
+};

package/figma-bridge-plugin/spec-helpers/parse-figma-link.js

@@ -0,0 +1,49 @@
+/**
+ * parse-figma-link.js
+ * 
+ * Parses a Figma URL into its component parts: file_key and node_id.
+ * 
+ * Usage:
+ *   node parse-figma-link.js "https://www.figma.com/design/abc123/File-Name?node-id=100:200"
+ * 
+ * Output (JSON):
+ *   { "file_key": "abc123", "node_id": "100:200", "node_id_encoded": "100-200" }
+ */
+
+function parseFigmaLink(url) {
+  // Handle both /design/ and /file/ URL formats
+  const fileMatch = url.match(/figma\.com\/(?:design|file)\/([a-zA-Z0-9]+)/);
+  if (!fileMatch) {
+    throw new Error(`Invalid Figma URL: could not extract file key from "${url}"`);
+  }
+  const file_key = fileMatch[1];
+
+  // Extract node-id from query params
+  const nodeMatch = url.match(/node-id=([^&]+)/);
+  if (!nodeMatch) {
+    throw new Error(`Invalid Figma URL: could not extract node-id from "${url}"`);
+  }
+  
+  // node-id in URLs uses "-" separator, but Figma API uses ":"
+  const node_id_encoded = nodeMatch[1];
+  const node_id = node_id_encoded.replace(/-/g, ':');
+
+  return {
+    file_key,
+    node_id,
+    node_id_encoded
+  };
+}
+
+// CLI usage
+if (typeof process !== 'undefined' && process.argv.length > 2) {
+  try {
+    const result = parseFigmaLink(process.argv[2]);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { parseFigmaLink };

package/figma-bridge-plugin/spec-helpers/position-markers.js

@@ -0,0 +1,158 @@
+/**
+ * position-markers.js
+ * 
+ * Calculate marker positions for anatomy and color annotations.
+ * Places numbered markers outside the component artwork with
+ * non-overlapping leader lines to each target element.
+ * 
+ * Used by anatomy and color spec rendering phases.
+ */
+
+const MARKER_DIAMETER = 24;
+const MARKER_COLOR = '#D946EF';  // Pink/magenta
+const CONNECTOR_STROKE = 1;
+const MIN_MARKER_GAP = 8;
+const MARKER_OFFSET = 40;  // Distance from artwork edge to marker center
+
+/**
+ * Calculate marker positions for a list of target elements.
+ * 
+ * Strategy: Place markers in a column to the LEFT of the artwork,
+ * distributed evenly. If too many markers, use both left and right sides.
+ * 
+ * @param {Object} artworkBounds - { x, y, width, height } of the component artwork
+ * @param {Array} targets - Array of { id, name, bounds: { x, y, width, height } }
+ * @returns {Array} Array of { targetId, markerX, markerY, lineStartX, lineStartY, lineEndX, lineEndY }
+ */
+function calculateMarkerPositions(artworkBounds, targets) {
+  const positions = [];
+  const count = targets.length;
+  
+  if (count === 0) return positions;
+  
+  // Determine available height for markers
+  const availableHeight = artworkBounds.height;
+  const markerSpacing = Math.max(
+    MARKER_DIAMETER + MIN_MARKER_GAP,
+    availableHeight / count
+  );
+  
+  // If all markers fit on the left side
+  const maxLeftSide = Math.floor(availableHeight / (MARKER_DIAMETER + MIN_MARKER_GAP));
+  const useRightSide = count > maxLeftSide;
+  
+  const leftCount = useRightSide ? Math.ceil(count / 2) : count;
+  const rightCount = useRightSide ? count - leftCount : 0;
+  
+  // Place left-side markers
+  for (let i = 0; i < leftCount; i++) {
+    const target = targets[i];
+    const markerX = artworkBounds.x - MARKER_OFFSET;
+    const markerY = artworkBounds.y + (i * (availableHeight / leftCount)) + MARKER_DIAMETER;
+    
+    // Connector line: from marker right edge to target left edge
+    const targetCenterY = target.bounds.y + target.bounds.height / 2;
+    
+    positions.push({
+      targetId: target.id,
+      number: i + 1,
+      markerX,
+      markerY,
+      lineStartX: markerX + MARKER_DIAMETER / 2,
+      lineStartY: markerY,
+      lineEndX: target.bounds.x,
+      lineEndY: targetCenterY
+    });
+  }
+  
+  // Place right-side markers (if needed)
+  for (let i = 0; i < rightCount; i++) {
+    const target = targets[leftCount + i];
+    const markerX = artworkBounds.x + artworkBounds.width + MARKER_OFFSET;
+    const markerY = artworkBounds.y + (i * (availableHeight / rightCount)) + MARKER_DIAMETER;
+    
+    const targetCenterY = target.bounds.y + target.bounds.height / 2;
+    
+    positions.push({
+      targetId: target.id,
+      number: leftCount + i + 1,
+      markerX,
+      markerY,
+      lineStartX: markerX - MARKER_DIAMETER / 2,
+      lineStartY: markerY,
+      lineEndX: target.bounds.x + target.bounds.width,
+      lineEndY: targetCenterY
+    });
+  }
+  
+  return positions;
+}
+
+/**
+ * Generate Figma MCP commands to render markers and connector lines.
+ * 
+ * @param {string} parentFrameId - The frame to place markers in
+ * @param {Array} markerPositions - Output from calculateMarkerPositions
+ * @returns {Array} Array of MCP command objects
+ */
+function generateMarkerCommands(parentFrameId, markerPositions) {
+  const commands = [];
+  
+  for (const pos of markerPositions) {
+    // Create marker circle
+    commands.push({
+      tool: 'create_ellipse',
+      params: {
+        parent_id: parentFrameId,
+        x: pos.markerX - MARKER_DIAMETER / 2,
+        y: pos.markerY - MARKER_DIAMETER / 2,
+        width: MARKER_DIAMETER,
+        height: MARKER_DIAMETER,
+        fill: MARKER_COLOR,
+        name: `Marker ${pos.number}`
+      }
+    });
+    
+    // Create number text inside marker
+    commands.push({
+      tool: 'create_text',
+      params: {
+        parent_id: parentFrameId,
+        x: pos.markerX - (pos.number >= 10 ? 7 : 4),
+        y: pos.markerY - 7,
+        content: String(pos.number),
+        font_size: 13,
+        font_weight: 'Bold',
+        color: '#FFFFFF',
+        name: `Marker ${pos.number} Label`
+      }
+    });
+    
+    // Create connector line
+    commands.push({
+      tool: 'create_line',
+      params: {
+        parent_id: parentFrameId,
+        start_x: pos.lineStartX,
+        start_y: pos.lineStartY,
+        end_x: pos.lineEndX,
+        end_y: pos.lineEndY,
+        stroke_color: MARKER_COLOR,
+        stroke_weight: CONNECTOR_STROKE,
+        name: `Connector ${pos.number}`
+      }
+    });
+  }
+  
+  return commands;
+}
+
+module.exports = {
+  calculateMarkerPositions,
+  generateMarkerCommands,
+  MARKER_DIAMETER,
+  MARKER_COLOR,
+  CONNECTOR_STROKE,
+  MIN_MARKER_GAP,
+  MARKER_OFFSET
+};