inkbridge 0.1.0-beta.1

package/manifest.json

@@ -0,0 +1,30 @@
+{
+  "name": "Inkbridge",
+  "id": "inkbridge-tokens-plugin",
+  "api": "1.0.0",
+  "main": "code.js",
+  "ui": "ui.html",
+  "capabilities": ["codegen"],
+  "codegenLanguages": [
+    { "label": "Tailwind CSS", "value": "PLAINTEXT" }
+  ],
+  "editorType": ["figma", "dev"],
+  "networkAccess": {
+    "allowedDomains": [
+      "https://api.github.com"
+    ],
+    "devAllowedDomains": [
+      "http://localhost:4000",
+      "http://localhost:3000",
+      "http://localhost:5173"
+    ],
+    "reasoning": "Fetches component definitions from local dev server for Design System generation, and uses GitHub API to create PRs for design token syncing."
+  },
+  "menu": [
+    { "name": "Push to Code", "command": "push" },
+    { "name": "Settings", "command": "settings" },
+    { "separator": true },
+    { "name": "Generate Design System Page", "command": "generate" },
+    { "name": "Debug Selection (Console)", "command": "debug-selection" }
+  ]
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "inkbridge",
+  "version": "0.1.0-beta.1",
+  "description": "Figma plugin that generates a pixel-accurate design system from your Tailwind React components.",
+  "type": "module",
+  "bin": {
+    "inkbridge": "./bin/inkbridge.mjs"
+  },
+  "files": [
+    "bin/",
+    "scanner/",
+    "src/",
+    "templates/",
+    "code.js",
+    "ui.html",
+    "manifest.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node build.mjs --watch",
+    "doctor": "cd ../.. && node scripts/figma-doctor.mjs",
+    "scan": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/cli.ts",
+    "test:blob": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/blob-placement-regression.ts",
+    "test:tokens": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/css-token-reader-regression.ts",
+    "test:font": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/font-style-resolver-regression.ts",
+    "test:radial": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/radial-gradient-regression.ts",
+    "test:transform": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/transform-math-regression.ts",
+    "test:csspatch": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/css-patch-regression.ts",
+    "verify": "pnpm run scan && pnpm run test:blob && pnpm run test:tokens && pnpm run test:font && pnpm run test:radial && pnpm run test:transform && pnpm run test:csspatch && pnpm run build",
+    "postinstall": "node ./bin/inkbridge.mjs postinstall",
+    "prepublishOnly": "node build.mjs"
+  },
+  "keywords": ["figma", "plugin", "tailwind", "design-tokens", "storybook"],
+  "license": "MIT",
+  "homepage": "https://inkbridge.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/inkn9ne/inkbridge.git",
+    "directory": "tools/figma-plugin-tailwind-tokens"
+  }
+}

package/scanner/blob-placement-regression.ts

@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import { resolveBlobDimensions, resolveBlobPlacement } from '../src/blob-placement';
+import { getClassesForBreakpoint } from '../src/responsive-analyzer';
+
+type CaseDef = {
+  name: string;
+  classes: string[];
+  breakpoint: 'base' | 'sm';
+  containerWidth: number;
+  expected: {
+    width: number;
+    height: number;
+    layoutLeft: number;
+    centerX: number;
+    rotateDeg: number;
+    topOffset: number;
+  };
+};
+
+const BLOB1_CLASSES = [
+  'relative',
+  'left-[calc(50%-11rem)]',
+  'aspect-1155/678',
+  'w-144.5',
+  '-translate-x-1/2',
+  'rotate-30',
+  'bg-linear-to-tr',
+  'from-primary-foreground',
+  'to-primary',
+  'opacity-30',
+  'sm:left-[calc(50%-30rem)]',
+  'sm:w-288.75',
+];
+
+const BLOB2_CLASSES = [
+  'relative',
+  'left-[calc(50%+3rem)]',
+  'aspect-1155/678',
+  'w-144.5',
+  '-translate-x-1/2',
+  'bg-linear-to-tr',
+  'from-primary-foreground',
+  'to-primary',
+  'opacity-30',
+  'sm:left-[calc(50%+36rem)]',
+  'sm:w-288.75',
+];
+
+const CASES: CaseDef[] = [
+  {
+    name: 'blob1-base',
+    classes: BLOB1_CLASSES,
+    breakpoint: 'base',
+    containerWidth: 600,
+    expected: {
+      width: 578,
+      height: (578 * 678) / 1155,
+      layoutLeft: 124,
+      centerX: 124,
+      rotateDeg: 30,
+      topOffset: 0,
+    },
+  },
+  {
+    name: 'blob1-sm',
+    classes: BLOB1_CLASSES,
+    breakpoint: 'sm',
+    containerWidth: 1024,
+    expected: {
+      width: 1155,
+      height: 678,
+      layoutLeft: 32,
+      centerX: 32,
+      rotateDeg: 30,
+      topOffset: 0,
+    },
+  },
+  {
+    name: 'blob2-base',
+    classes: BLOB2_CLASSES,
+    breakpoint: 'base',
+    containerWidth: 600,
+    expected: {
+      width: 578,
+      height: (578 * 678) / 1155,
+      layoutLeft: 348,
+      centerX: 348,
+      rotateDeg: 0,
+      topOffset: 0,
+    },
+  },
+  {
+    name: 'blob2-sm',
+    classes: BLOB2_CLASSES,
+    breakpoint: 'sm',
+    containerWidth: 1024,
+    expected: {
+      width: 1155,
+      height: 678,
+      layoutLeft: 1088,
+      centerX: 1088,
+      rotateDeg: 0,
+      topOffset: 0,
+    },
+  },
+];
+
+function approxEqual(actual: number, expected: number, epsilon = 0.01): void {
+  assert.ok(Math.abs(actual - expected) <= epsilon, `expected ${expected}, got ${actual}`);
+}
+
+for (const testCase of CASES) {
+  const active = testCase.breakpoint === 'base'
+    ? testCase.classes
+    : getClassesForBreakpoint(testCase.classes, testCase.breakpoint);
+  const dimensions = resolveBlobDimensions(active);
+  const placement = resolveBlobPlacement(
+    active,
+    testCase.containerWidth,
+    dimensions.vectorWidth,
+    dimensions.vectorHeight,
+  );
+
+  approxEqual(dimensions.vectorWidth, testCase.expected.width);
+  approxEqual(dimensions.vectorHeight, testCase.expected.height);
+  approxEqual(placement.layoutLeft, testCase.expected.layoutLeft);
+  approxEqual(placement.desiredCenterX, testCase.expected.centerX);
+  approxEqual(placement.cssRotateDeg, testCase.expected.rotateDeg);
+  approxEqual(placement.topOffset, testCase.expected.topOffset);
+}
+
+console.log(`blob placement regression passed (${CASES.length} cases)`);

package/scanner/class-collector.ts

@@ -0,0 +1,69 @@
+import type { ComponentAnalysis, StoryInfo, JsxNode, JsxElement } from './types';
+
+function splitClasses(value?: string): string[] {
+  if (!value) return [];
+  return value.split(/\s+/).filter(Boolean);
+}
+
+function collectFromJsx(node?: JsxNode, out: string[] = []): string[] {
+  if (!node) return out;
+  if (node.type === 'element') {
+    const el = node as JsxElement;
+    const className = (el.props && el.props.className) || '';
+    out.push(...splitClasses(className));
+    for (const child of el.children || []) {
+      collectFromJsx(child, out);
+    }
+  }
+  return out;
+}
+
+function collectFromStory(story: StoryInfo): string[] {
+  const classes: string[] = [];
+  if (story.layoutClasses) classes.push(...story.layoutClasses);
+  if (story.instances) {
+    for (const inst of story.instances) {
+      if (inst.props && inst.props.className) {
+        classes.push(...splitClasses(inst.props.className));
+      }
+    }
+  }
+  if (story.jsxTree) {
+    collectFromJsx(story.jsxTree, classes);
+  }
+  return classes;
+}
+
+export function collectAllClasses(analyses: ComponentAnalysis[]): string[] {
+  const classes: string[] = [];
+
+  for (const analysis of analyses) {
+    if (analysis.type === 'cva') {
+      classes.push(...analysis.baseClasses);
+      for (const variantGroup of Object.values(analysis.variantClasses)) {
+        for (const cls of Object.values(variantGroup)) {
+          classes.push(...cls);
+        }
+      }
+    } else if (analysis.type === 'compound') {
+      for (const sub of analysis.subComponents) {
+        classes.push(...sub.classes);
+      }
+    } else if (analysis.type === 'state') {
+      classes.push(...analysis.baseClasses);
+      for (const state of Object.values(analysis.states)) {
+        classes.push(...state.classes);
+      }
+    } else if (analysis.type === 'simple') {
+      classes.push(...analysis.classes);
+    }
+
+    if (analysis.stories) {
+      for (const story of analysis.stories) {
+        classes.push(...collectFromStory(story));
+      }
+    }
+  }
+
+  return classes;
+}

package/scanner/cli.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/**
+ * Component Scanner CLI
+ *
+ * Scans component files and generates a JSON definitions file
+ * that the Figma plugin uses to create components.
+ *
+ * Usage (consumer project, after `pnpm add -D inkbridge && pnpm exec inkbridge setup`):
+ *   pnpm figma:scan                   — run scanner manually
+ *   GET /api/figma/scan-components    — called automatically by the Figma plugin
+ *
+ * Usage (monorepo dev):
+ *   npx tsx tools/figma-plugin-tailwind-tokens/scanner/cli.ts
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { ComponentScanner } from './component-scanner';
+import { extractColorTokens, extractPaletteTokens, TAILWIND_SPACING, inferLayout, groupClassesByBreakpoint, groupClassesByColorScheme } from './tailwind-parser';
+import { collectAllClasses } from './class-collector';
+import { buildStyleMap } from './style-map';
+import { readTokenSourceMap } from './css-token-reader';
+import type { ComponentDefinitions, ScannerConfig, LayoutInfo, ResponsiveInfo, ColorSchemeInfo, IconImportSpec, IconRegistryEntry } from './types';
+import type { TokenSourceMode } from '../src/token-source';
+
+// ============================================================================
+// CLI flags
+// ============================================================================
+
+const argv = process.argv.slice(2);
+const getFlag = (flag: string): string | undefined => {
+  const i = argv.indexOf(flag);
+  return i !== -1 ? argv[i + 1] : undefined;
+};
+const hasFlag = (flag: string): boolean => argv.includes(flag);
+
+const CLI_OUTPUT = getFlag('--output');
+const CLI_INCLUDE_TOKENS = hasFlag('--include-tokens');
+const CLI_TOKEN_MODE = (getFlag('--token-mode') || 'auto') as TokenSourceMode;
+const CLI_CSS_TOKEN_PATH = getFlag('--css-token-path');
+const CLI_DTCG_TOKEN_PATH = getFlag('--dtcg-token-path');
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const DEFAULT_CONFIG: ScannerConfig = {
+  componentPaths: ['src'],
+  filePattern: '**/*.tsx',
+  exclude: ['index'],
+  onlyWithStories: true,
+  iconPackages: ['lucide-react', 'react-icons/'],
+};
+
+const COMPONENT_DEFS_SCHEMA_VERSION = 1;
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('🔍 Scanning components...\n');
+
+  const config = loadConfig();
+  const scanner = new ComponentScanner(config);
+
+  try {
+    const analyses = await scanner.scanAll();
+
+    // Collect all classes used across components + stories
+    const allClasses = collectAllClasses(analyses);
+
+    const colorTokens = extractColorTokens(allClasses);
+    const paletteTokens = extractPaletteTokens(allClasses);
+    const styleMap = await buildStyleMap(allClasses);
+    const iconRegistry = await buildIconRegistry(scanner.getIconRegistry());
+
+    // Enrich each analysis with layout, responsive, and color-scheme info
+    const enriched = analyses.map(analysis => {
+      const classes = getAllClassesFromAnalysis(analysis);
+      const layout = inferLayout(classes);
+      const breakpoints = groupClassesByBreakpoint(classes);
+      const hasResponsiveVisibility = classes.some(c =>
+        /^(sm|md|lg|xl|2xl):(hidden|flex|block|grid|inline|table|contents)$/.test(c) ||
+        /^(hidden)\s/.test(c)  // "hidden" at base with responsive show
+      );
+      const responsive: ResponsiveInfo = { breakpoints, hasResponsiveVisibility };
+      const colorScheme = groupClassesByColorScheme(classes);
+
+      return { analysis, layout, responsive, colorScheme };
+    });
+
+    // Build output
+    const output: ComponentDefinitions = {
+      schemaVersion: COMPONENT_DEFS_SCHEMA_VERSION,
+      version: '1.0.0',
+      generatedAt: new Date().toISOString(),
+      components: enriched,
+      spacingScale: TAILWIND_SPACING,
+      colorTokens,
+      paletteTokens,
+      iconRegistry,
+      styleMap,
+    };
+
+    // Optionally include token map when called with --include-tokens
+    const finalOutput: typeof output & { tokens?: ReturnType<typeof readTokenSourceMap> } = output;
+    if (CLI_INCLUDE_TOKENS) {
+      finalOutput.tokens = readTokenSourceMap({
+        projectRoot: process.cwd(),
+        tokenSourceMode: CLI_TOKEN_MODE,
+        cssTokenPath: CLI_CSS_TOKEN_PATH,
+        dtcgTokenPath: CLI_DTCG_TOKEN_PATH,
+      });
+    }
+
+    // Write to JSON file
+    const defaultOutputPath = 'tools/figma-plugin-tailwind-tokens/component-definitions.json';
+    const outputPath = CLI_OUTPUT
+      ? path.resolve(process.cwd(), CLI_OUTPUT)
+      : path.resolve(process.cwd(), defaultOutputPath);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, JSON.stringify(finalOutput, null, 2));
+
+    // Print summary
+    console.log('✅ Scanned components:\n');
+
+    const byType = {
+      cva: enriched.filter(e => e.analysis.type === 'cva'),
+      compound: enriched.filter(e => e.analysis.type === 'compound'),
+      state: enriched.filter(e => e.analysis.type === 'state'),
+      simple: enriched.filter(e => e.analysis.type === 'simple'),
+    };
+
+    // Helper to format story info
+    const storyStr = (a: import('./types').ComponentAnalysis): string => {
+      if (!a.stories || a.stories.length === 0) return '';
+      const names = a.stories.map(s => s.name).join(', ');
+      const totalInstances = a.stories.reduce((sum, s) => sum + s.instances.length, 0);
+      return ` — ${a.stories.length} stories (${names}) [${totalInstances} instances]`;
+    };
+
+    if (byType.cva.length > 0) {
+      console.log('  CVA Components (variants + states):');
+      for (const e of byType.cva) {
+        const a = e.analysis;
+        if (a.type === 'cva') {
+          const variantCount = Object.keys(a.variants).length;
+          const totalVariants = Object.values(a.variants).reduce((sum, arr) => sum + arr.length, 0);
+          console.log(`    • ${a.name} (${variantCount} variant groups, ${totalVariants} values)${storyStr(a)}`);
+        }
+      }
+      console.log();
+    }
+
+    if (byType.compound.length > 0) {
+      console.log('  Compound Components (sub-components):');
+      for (const e of byType.compound) {
+        const a = e.analysis;
+        if (a.type === 'compound') {
+          console.log(`    • ${a.name} (${a.subComponents.length} sub-components)${storyStr(a)}`);
+          for (const sub of a.subComponents) {
+            console.log(`      - ${sub.name} [${sub.slot}]`);
+          }
+        }
+      }
+      console.log();
+    }
+
+    if (byType.state.length > 0) {
+      console.log('  State Components (state modifiers):');
+      for (const e of byType.state) {
+        const a = e.analysis;
+        if (a.type === 'state') {
+          const states = Object.keys(a.states).join(', ');
+          console.log(`    • ${a.name} (states: ${states})${storyStr(a)}`);
+        }
+      }
+      console.log();
+    }
+
+    if (byType.simple.length > 0) {
+      console.log('  Simple Components:');
+      for (const e of byType.simple) {
+        console.log(`    • ${e.analysis.name}${storyStr(e.analysis)}`);
+      }
+      console.log();
+    }
+
+    const totalStories = analyses.reduce((sum, a) => sum + (a.stories?.length || 0), 0);
+    console.log(`\n📦 Output written to: ${outputPath}`);
+    console.log(`   ${analyses.length} components, ${totalStories} stories, ${colorTokens.length} color tokens`);
+
+  } catch (err) {
+    console.error('❌ Scanner failed:', err);
+    process.exit(1);
+  }
+}
+
+/**
+ * Extract all classes from any component analysis type
+ */
+function getAllClassesFromAnalysis(analysis: import('./types').ComponentAnalysis): string[] {
+  const classes: string[] = [];
+  if (analysis.type === 'cva') {
+    classes.push(...analysis.baseClasses);
+    for (const variantGroup of Object.values(analysis.variantClasses)) {
+      for (const cls of Object.values(variantGroup)) {
+        classes.push(...cls);
+      }
+    }
+  } else if (analysis.type === 'compound') {
+    for (const sub of analysis.subComponents) {
+      classes.push(...sub.classes);
+    }
+  } else if (analysis.type === 'state') {
+    classes.push(...analysis.baseClasses);
+    for (const state of Object.values(analysis.states)) {
+      classes.push(...state.classes);
+    }
+  } else if (analysis.type === 'simple') {
+    classes.push(...analysis.classes);
+  }
+  return classes;
+}
+
+/**
+ * Extract component paths from Storybook's stories globs.
+ * e.g. "../src/**\/\*.stories.@(ts|tsx)" → ["src"]
+ */
+function detectStorybookPaths(cwd: string): string[] {
+  const candidates = [
+    '.storybook/main.ts',
+    '.storybook/main.js',
+    '.storybook/main.mjs',
+    '.storybook/main.cjs',
+  ];
+
+  for (const candidate of candidates) {
+    const fullPath = path.resolve(cwd, candidate);
+    if (!fs.existsSync(fullPath)) continue;
+
+    const content = fs.readFileSync(fullPath, 'utf-8');
+
+    // Extract the stories array value (handles single or multi-line)
+    const storiesMatch = content.match(/stories\s*:\s*\[([^\]]+)\]/s);
+    if (!storiesMatch) continue;
+
+    const globs = [...storiesMatch[1].matchAll(/["'`]([^"'`]+)["'`]/g)].map(m => m[1]);
+    const dirs = new Set<string>();
+
+    for (const glob of globs) {
+      // Resolve relative to the project root (strip leading "../" from .storybook/ context)
+      const normalized = glob.replace(/^\.\.\//, '');
+      // Take the first non-glob path segment as the root directory
+      const firstSegment = normalized.split('/')[0];
+      if (firstSegment && !firstSegment.includes('*') && !firstSegment.includes('{')) {
+        dirs.add(firstSegment);
+      }
+    }
+
+    if (dirs.size > 0) {
+      console.log(`  ↳ Detected story paths from ${candidate}: ${[...dirs].join(', ')}`);
+      return [...dirs];
+    }
+  }
+
+  return [];
+}
+
+function loadConfig(): ScannerConfig {
+  const cwd = process.cwd();
+
+  // 1. inkbridge.config.json (primary)
+  const inkbridgeCfg = path.resolve(cwd, 'inkbridge.config.json');
+  if (fs.existsSync(inkbridgeCfg)) {
+    const custom = JSON.parse(fs.readFileSync(inkbridgeCfg, 'utf-8'));
+    return { ...DEFAULT_CONFIG, ...custom };
+  }
+
+  // 2. Legacy figma-scanner.config.json
+  const legacyCfg = path.resolve(cwd, 'figma-scanner.config.json');
+  if (fs.existsSync(legacyCfg)) {
+    const custom = JSON.parse(fs.readFileSync(legacyCfg, 'utf-8'));
+    return { ...DEFAULT_CONFIG, ...custom };
+  }
+
+  // 3. Auto-detect from .storybook/main.{ts,js,mjs}
+  const storybookPaths = detectStorybookPaths(cwd);
+  if (storybookPaths.length > 0) {
+    return { ...DEFAULT_CONFIG, componentPaths: storybookPaths };
+  }
+
+  // 4. Fallback: scan all of src/
+  return DEFAULT_CONFIG;
+}
+
+async function buildIconRegistry(imports: Record<string, IconImportSpec>): Promise<Record<string, IconRegistryEntry>> {
+  const entries: Record<string, IconRegistryEntry> = {};
+  const names = Object.keys(imports);
+  for (const localName of names) {
+    const spec = imports[localName];
+    if (!spec) continue;
+    try {
+      const mod = await import(spec.module);
+      const IconComponent = (mod as any)[spec.exportName];
+      if (!IconComponent) continue;
+      const element = React.createElement(IconComponent, { size: 24, color: '#000' });
+      let svg = renderToStaticMarkup(element);
+      if (!svg.startsWith('<svg')) {
+        svg = `<svg>${svg}</svg>`;
+      }
+      if (!/viewBox=/.test(svg)) {
+        svg = svg.replace('<svg', '<svg viewBox="0 0 24 24"');
+      }
+      if (!/width=/.test(svg)) {
+        svg = svg.replace('<svg', '<svg width="24"');
+      }
+      if (!/height=/.test(svg)) {
+        svg = svg.replace('<svg', '<svg height="24"');
+      }
+      entries[localName] = { ...spec, svg };
+    } catch (err) {
+      console.warn(`Failed to render icon ${spec.module}:${spec.exportName}`, err);
+    }
+  }
+  return entries;
+}
+
+// Run
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});