@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/tests/spec-generator.test.ts

@@ -0,0 +1,127 @@
+import {
+  buildAccessibilityAnnotationDocument,
+  formatDocumentReport,
+  formatSpecDescription,
+  type DesignSpec,
+  type NodeSnapshot,
+} from "../src/tools/phase5-governance/spec-generator/index";
+
+describe("figma_generate_spec handoff formatting", () => {
+  test("formats a compact dev handoff description", () => {
+    const spec: DesignSpec = {
+      target: {
+        nodeId: "100:200",
+        name: "What We Do Clone",
+        type: "FRAME",
+        description: "",
+      },
+      overview: {
+        summary: "A structured marketing section with a header band and four-column grid.",
+        size: "1600 × 860 px",
+        layout: "Vertical auto layout",
+        childCount: 2,
+      },
+      anatomy: ["Header", "Disciplines Grid"],
+      variants: [],
+      states: [],
+      contentGuidance: ["Primary text layer: \"WHAT WE DO\"."],
+      styling: {
+        fills: ["rgb(251, 251, 251)"],
+        strokes: ["rgb(20, 20, 20)"],
+        effects: [],
+        tokenReferences: [],
+      },
+      accessibility: {
+        typography: ["WHAT WE DO: Libre Franklin SemiBold 72px / 74px"],
+        considerations: ["No variable aliases were detected on the target subtree."],
+      },
+      implementationNotes: ["Uses vertical auto layout with 0px item spacing."],
+      documentationGaps: ["No token aliases were found in the scanned subtree, so token documentation is likely incomplete."],
+    };
+
+    const result = formatSpecDescription(spec);
+
+    expect(result).toContain("# Dev Handoff");
+    expect(result).toContain("`1600 x 860 px`");
+    expect(result).toContain("## Engineering Notes");
+    expect(result).toContain("No token aliases detected on this subtree.");
+  });
+
+  test("builds a screen accessibility annotation with keyboard and screen reader order", () => {
+    const spec: DesignSpec = {
+      target: {
+        nodeId: "100:200",
+        name: "Checkout Payment",
+        type: "FRAME",
+        description: "",
+      },
+      overview: {
+        summary: "A payment step with address fields and a submit action.",
+        size: "1440 × 1024 px",
+        layout: "Vertical auto layout",
+        childCount: 2,
+      },
+      anatomy: ["Payment form", "Order summary"],
+      variants: [],
+      states: ["Default"],
+      contentGuidance: ["Primary text layer: \"Payment details\"."],
+      styling: {
+        fills: ["rgb(255, 255, 255)"],
+        strokes: [],
+        effects: [],
+        tokenReferences: [],
+      },
+      accessibility: {
+        typography: ["Payment details: Geist Medium 24px / 32px"],
+        considerations: ["Run contrast and focus-state checks before publishing this component spec."],
+      },
+      implementationNotes: ["Uses vertical auto layout with 24px item spacing."],
+      documentationGaps: [],
+    };
+
+    const snapshot: NodeSnapshot = {
+      id: "100:200",
+      name: "Checkout Payment",
+      type: "FRAME",
+      description: "",
+      width: 1440,
+      height: 1024,
+      layoutMode: "VERTICAL",
+      itemSpacing: 24,
+      paddingTop: 0,
+      paddingRight: 0,
+      paddingBottom: 0,
+      paddingLeft: 0,
+      childCount: 2,
+      childNames: ["Payment form", "Order summary"],
+      textLayers: [],
+      fills: [],
+      strokes: [],
+      effects: [],
+      tokenAliases: [],
+      componentProperties: [],
+      variantProperties: {},
+      variantGroupProperties: {},
+      variants: [],
+      scanNodes: [
+        { id: "100:200", parentId: null, parentName: null, name: "Checkout Payment", type: "FRAME", depth: 0, visible: true, childCount: 2, layoutMode: "VERTICAL", text: "", componentPropertyNames: [], variantPropertyKeys: [], variantPropertyValues: [] },
+        { id: "100:201", parentId: "100:200", parentName: "Checkout Payment", name: "Payment form", type: "FRAME", depth: 1, visible: true, childCount: 4, layoutMode: "VERTICAL", text: "", componentPropertyNames: [], variantPropertyKeys: [], variantPropertyValues: [] },
+        { id: "100:202", parentId: "100:201", parentName: "Payment form", name: "Heading", type: "TEXT", depth: 2, visible: true, childCount: 0, layoutMode: "NONE", text: "Payment details", componentPropertyNames: [], variantPropertyKeys: [], variantPropertyValues: [] },
+        { id: "100:203", parentId: "100:201", parentName: "Payment form", name: "Email field", type: "INSTANCE", depth: 2, visible: true, childCount: 0, layoutMode: "NONE", text: "Email address", componentPropertyNames: ["state"], variantPropertyKeys: [], variantPropertyValues: ["required"] },
+        { id: "100:204", parentId: "100:201", parentName: "Payment form", name: "Country dropdown", type: "INSTANCE", depth: 2, visible: true, childCount: 0, layoutMode: "NONE", text: "Country", componentPropertyNames: ["state"], variantPropertyKeys: [], variantPropertyValues: [] },
+        { id: "100:205", parentId: "100:201", parentName: "Payment form", name: "Continue button", type: "INSTANCE", depth: 2, visible: true, childCount: 0, layoutMode: "NONE", text: "Continue to review", componentPropertyNames: ["state"], variantPropertyKeys: [], variantPropertyValues: [] },
+      ],
+    };
+
+    const document = buildAccessibilityAnnotationDocument(snapshot, spec);
+    const report = formatDocumentReport(document);
+
+    expect(document.title).toContain("Accessibility Annotation");
+    expect(report).toContain("Keyboard Tab Order");
+    expect(report).toContain("1. Email address - Text field (required)");
+    expect(report).toContain("Country - Select");
+    expect(report).toContain("Continue to review - Button");
+    expect(report).toContain("Screen Reader Reading Order");
+    expect(report).toContain("Heading: Payment details");
+  });
+});

package/figma-intelligence-layer/tests/token-migrate.test.ts

@@ -0,0 +1,21 @@
+import { translateCanonicalName } from "../src/tools/phase5-governance/token-migrate";
+
+describe("token migrate planner", () => {
+  test("translates expanded primitives into compact schema", () => {
+    const result = translateCanonicalName("color/primitive/brand/500", "compact");
+
+    expect(result.suggestedName).toBe("color/brand/500");
+  });
+
+  test("translates compact typography names into expanded schema", () => {
+    const result = translateCanonicalName("typography/font-size/md", "expanded");
+
+    expect(result.suggestedName).toBe("typography/size/md");
+  });
+
+  test("keeps typo cleanup and singular component prefix", () => {
+    const result = translateCanonicalName("Components/typogrpahy/label/md", "compact");
+
+    expect(result.suggestedName).toBe("component/typography/label/md");
+  });
+});

package/figma-intelligence-layer/tests/token-naming.test.ts

@@ -0,0 +1,30 @@
+import { analyzeTokenName, analyzeTokenNames } from "../src/shared/token-naming";
+
+describe("token naming convention", () => {
+  test("accepts a well-formed primitive token", () => {
+    const analysis = analyzeTokenName("color/brand/500");
+
+    expect(analysis.isValid).toBe(true);
+    expect(analysis.domain).toBe("primitive");
+    expect(analysis.suggestedName).toBeNull();
+  });
+
+  test("suggests fixes for typos and plural component prefixes", () => {
+    const analyses = analyzeTokenNames([
+      "typogrpahy/font-size/md",
+      "components/button/primary/background/default",
+      "Text/Primary",
+    ]);
+
+    expect(analyses[0].suggestedName).toBe("typography/font-size/md");
+    expect(analyses[1].suggestedName).toBe("component/button/primary/background/default");
+    expect(analyses[2].suggestedName).toBe("semantic/text/primary");
+  });
+
+  test("flags invalid characters as errors", () => {
+    const analysis = analyzeTokenName("color/brand/@500");
+
+    expect(analysis.isValid).toBe(false);
+    expect(analysis.issues.some((issue) => issue.code === "invalid-characters")).toBe(true);
+  });
+});

package/figma-intelligence-layer/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sarjallab09/figma-intelligence",
+  "version": "1.0.0",
+  "description": "88 AI-powered design tools for Figma. Works with your Claude, OpenAI Codex, or Gemini CLI subscription. One command to set up.",
+  "author": "Figma Intelligence Contributors",
+  "license": "CC-BY-NC-ND-4.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Josedesign006/figma-intelligence.git"
+  },
+  "bin": {
+    "figma-intelligence": "./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "setup": "node bin/cli.js setup",
+    "start": "node bin/cli.js start",
+    "stop": "node bin/cli.js stop",
+    "status": "node bin/cli.js status",
+    "doctor": "node bin/cli.js doctor",
+    "register:codex-mcp": "node scripts/register-codex-mcp.js",
+    "connect": "node scripts/connect-ai-tool.js"
+  },
+  "files": [
+    "bin/",
+    "figma-bridge-plugin/",
+    "figma-intelligence-layer/",
+    "design-bridge/",
+    "scripts/",
+    "README.md"
+  ],
+  "keywords": ["figma", "mcp", "claude", "openai", "codex", "gemini", "ai", "design", "design-system", "figma-plugin"]
+}

package/scripts/clean-existing-chunks.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * clean-existing-chunks.js — Clean up existing .chunks.json files
+ *
+ * Applies text cleaning (OCR artifact removal, page number stripping)
+ * and re-extracts keywords with bigram support.
+ *
+ * Usage: node scripts/clean-existing-chunks.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const HUB_DIR = path.resolve(__dirname, "..", "figma-bridge-plugin", "knowledge-hub");
+
+// ── Text Cleaning ──────────────────────────────────────────────────────────
+
+function cleanChunkText(text) {
+  return text
+    // Remove OCR garbage patterns like "12ChapterC 20Ct.Ipnoddu"
+    .replace(/\b\d+[A-Z][a-z]+[A-Z]\s+\d+[A-Z][a-z]+\.\w+\b/g, "")
+    // Remove standalone page numbers
+    .replace(/^\s*\d{1,4}\s*$/gm, "")
+    // Remove tab-heavy lines (TOC remnants)
+    .replace(/^[^\n]*\t{2,}[^\n]*$/gm, "")
+    // Remove very short noise lines (1-3 chars)
+    .replace(/^.{1,3}$/gm, "")
+    // Clean up leading line numbers like "3\t" or "142\t"
+    .replace(/^\d{1,4}\t/gm, "")
+    // Collapse multiple blank lines
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function cleanHeading(heading) {
+  return heading
+    // Remove tab-separated content (TOC-style headings like "Chapter 07. \tAppendix \t142")
+    .replace(/\t.*/g, "")
+    // Remove trailing page numbers
+    .replace(/\s+\d{1,4}\s*$/, "")
+    // Remove "(part N)" suffix for re-detection
+    // Keep it — it's useful for navigation
+    .replace(/^\d{1,4}\t/, "")
+    .trim();
+}
+
+// ── Keyword Extraction ─────────────────────────────────────────────────────
+
+const STOP_WORDS = new Set([
+  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "shall", "can", "need", "must",
+  "i", "me", "my", "we", "our", "you", "your", "he", "she", "it",
+  "they", "them", "their", "this", "that", "these", "those",
+  "what", "which", "who", "whom", "how", "when", "where", "why",
+  "and", "or", "but", "not", "no", "nor", "so", "if", "then",
+  "of", "in", "on", "at", "to", "for", "with", "by", "from",
+  "about", "into", "through", "during", "before", "after",
+  "above", "below", "between", "under", "over",
+  "just", "also", "very", "too", "more", "most", "some", "any",
+  "all", "each", "every", "both", "few", "many", "much",
+  "such", "only", "other", "new", "like", "than", "even",
+  "one", "two", "three", "first", "second", "well", "way",
+  "use", "used", "using", "make", "made", "see", "get", "take",
+  "work", "part", "page", "chapter", "figure", "table",
+]);
+
+function extractChunkKeywords(text, maxKeywords = 15) {
+  const words = text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => {
+      if (w.length < 3) return false;
+      if (STOP_WORDS.has(w)) return false;
+      // Filter OCR garbage
+      if (/\d/.test(w) && /[a-z]/i.test(w) && w.length > 6) return false;
+      return true;
+    });
+
+  const freq = {};
+  for (const w of words) {
+    freq[w] = (freq[w] || 0) + 1;
+  }
+
+  // Bigrams
+  const bigramFreq = {};
+  for (let i = 0; i < words.length - 1; i++) {
+    const bigram = words[i] + " " + words[i + 1];
+    if ((freq[words[i]] || 0) >= 2 && (freq[words[i + 1]] || 0) >= 2) {
+      bigramFreq[bigram] = (bigramFreq[bigram] || 0) + 1;
+    }
+  }
+
+  const allTerms = [
+    ...Object.entries(bigramFreq).filter(([, c]) => c >= 2).map(([term, count]) => ({ term, score: count * 3 })),
+    ...Object.entries(freq).map(([term, count]) => ({ term, score: count })),
+  ];
+
+  allTerms.sort((a, b) => b.score - a.score);
+  const seen = new Set();
+  const keywords = [];
+  for (const { term } of allTerms) {
+    if (keywords.length >= maxKeywords) break;
+    if (seen.has(term)) continue;
+    seen.add(term);
+    if (!term.includes(" ") && keywords.some((k) => k.includes(" ") && k.includes(term))) continue;
+    keywords.push(term);
+  }
+
+  return keywords;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log("Cleaning existing chunk files...\n");
+
+  if (!fs.existsSync(HUB_DIR)) {
+    console.error(`Knowledge hub directory not found: ${HUB_DIR}`);
+    process.exit(1);
+  }
+
+  const chunkFiles = fs.readdirSync(HUB_DIR).filter((f) => f.endsWith(".chunks.json"));
+
+  if (chunkFiles.length === 0) {
+    console.log("No .chunks.json files found.");
+    process.exit(0);
+  }
+
+  for (const file of chunkFiles) {
+    const filePath = path.join(HUB_DIR, file);
+    console.log(`Processing ${file}...`);
+
+    const data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+
+    let cleanedChunks = 0;
+    let keywordsUpdated = 0;
+
+    for (const chunk of data.chunks) {
+      // Clean text
+      const originalLen = chunk.text.length;
+      chunk.text = cleanChunkText(chunk.text);
+      chunk.chars = chunk.text.length;
+      if (chunk.text.length !== originalLen) cleanedChunks++;
+
+      // Clean heading
+      chunk.heading = cleanHeading(chunk.heading);
+
+      // Re-extract keywords
+      const oldKeywords = chunk.keywords || [];
+      chunk.keywords = extractChunkKeywords(chunk.text);
+      if (JSON.stringify(oldKeywords) !== JSON.stringify(chunk.keywords)) keywordsUpdated++;
+    }
+
+    // Remove empty chunks
+    const before = data.chunks.length;
+    data.chunks = data.chunks.filter((c) => c.text.length > 50);
+    const removed = before - data.chunks.length;
+
+    // Re-index chunk IDs
+    data.chunks.forEach((c, i) => {
+      c.id = `ch-${String(i + 1).padStart(3, "0")}`;
+    });
+
+    // Recalculate totalChars
+    data.totalChars = data.chunks.reduce((s, c) => s + c.chars, 0);
+
+    // Write back
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+
+    console.log(`  ${cleanedChunks} chunks cleaned, ${keywordsUpdated} keywords updated, ${removed} empty chunks removed`);
+    console.log(`  ${data.chunks.length} chunks remaining (${(data.totalChars / 1000).toFixed(0)}K chars)\n`);
+  }
+
+  console.log("Done.");
+}
+
+main();