@sarjallab09/figma-intelligence 1.0.1 → 1.2.0

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

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

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

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

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

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