figma-code-agent 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# Figma Agent
+
+A Claude Code plugin that provides expert-level Figma development knowledge through 19 knowledge modules and 10 invokable skills.
+
+## What It Does
+
+Figma Agent is a **developer expert tool** that helps you build software integrating with Figma. It encodes production-proven patterns for:
+
+- **Plugin development** — Architecture, IPC, data flow, error handling, performance, caching, async patterns, testing
+- **Codegen plugins** — Dev Mode integration, 3-second timeout strategy, preference system, language routing
+- **Import pipelines** — REST API fetching, node traversal, platform-specific transformation, asset handling
+- **Token synchronization** — Variables API, alias resolution, mode classification, multi-format rendering
+- **Design-to-code** — Auto Layout to Flexbox, visual properties, typography, assets, semantic HTML
+- **CMS integration** — PayloadCMS block mapping, field factories, container nesting, visual builder
+
+## Installation
+
+### npx (recommended)
+
+```bash
+# Install globally — available in all projects
+npx figma-code-agent
+
+# Install to current project only
+npx figma-code-agent --local
+
+# Remove installed files
+npx figma-code-agent --uninstall
+```
+
+### Plugin mode (for development)
+
+```bash
+# Load directly when starting Claude Code
+claude --plugin-dir /path/to/figma-code-agent
+```
+
+### Manual (requires clone)
+
+```bash
+# Symlink all skills to ~/.claude/skills/
+./install.sh
+```
+
+## Skills
+
+After installation, invoke skills directly in Claude Code:
+
+### Tier 1: Developer Workflow
+
+| Skill | What It Does |
+|-------|-------------|
+| `/fca:build-plugin` | Build a Figma plugin from scratch or enhance an existing one |
+| `/fca:build-codegen-plugin` | Build a Dev Mode codegen plugin that generates code from designs |
+| `/fca:build-importer` | Build a service that fetches Figma designs into a CMS or React app |
+| `/fca:build-token-pipeline` | Build a pipeline that syncs Figma design tokens to code |
+
+### Tier 2: Reference / Validation
+
+| Skill | What It Does |
+|-------|-------------|
+| `/fca:ref-layout` | Interpret Figma Auto Layout and generate CSS Flexbox |
+| `/fca:ref-react` | Generate a React/TSX component from Figma node data |
+| `/fca:ref-html` | Generate semantic HTML + CSS from Figma node data |
+| `/fca:ref-tokens` | Extract design tokens into CSS variables + Tailwind config |
+| `/fca:ref-payload-block` | Map a Figma component to a PayloadCMS block |
+
+### Tier 3: Audit
+
+| Skill | What It Does |
+|-------|-------------|
+| `/fca:audit-plugin` | Audit a Figma plugin against production best practices |
+
+### Example
+
+```
+/fca:build-plugin I want to build a plugin that exports frames as React components
+```
+
+Tier 1 skills follow a 4-phase process: **Assess** the project → **Recommend** architecture → **Implement** code → **Validate** against best practices. Tier 2 skills follow a structured step-by-step process for direct code generation from Figma data.
+
+## Knowledge Modules
+
+19 modules organized by domain, usable as standalone `@file` references in any project:
+
+| Domain | Modules | Topics |
+|--------|---------|--------|
+| Figma API | 5 | REST API, Plugin API, Variables, Webhooks, Dev Mode |
+| Design-to-Code | 5 | Layout, Visual, Typography, Assets, Semantic HTML |
+| CSS & Tokens | 3 | Three-layer CSS, Token extraction, Variables-to-CSS bridge |
+| PayloadCMS | 3 | Block system, Figma-to-block mapping, Visual builder |
+| Plugin Dev | 3 | Architecture, Codegen plugins, Best practices |
+
+Reference any module directly in your project:
+
+```
+@/path/to/figma-code-agent/knowledge/design-to-code-layout.md
+```
+
+## Project Structure
+
+```
+figma-code-agent/
+  bin/
+    install.js               # npx installer (copies files to ~/.claude/)
+  .claude-plugin/
+    plugin.json              # Claude Code plugin manifest
+  skills/
+    build-plugin/            # Build a Figma plugin
+    build-codegen-plugin/    # Build a codegen plugin
+    build-importer/          # Build a Figma importer
+    build-token-pipeline/    # Build a token sync pipeline
+    ref-layout/              # Reference: Auto Layout -> Flexbox
+    ref-react/               # Reference: Figma -> React/TSX
+    ref-html/                # Reference: Figma -> HTML + CSS
+    ref-tokens/              # Reference: Figma -> CSS variables + Tailwind
+    ref-payload-block/       # Reference: Figma -> PayloadCMS block
+    audit-plugin/            # Plugin quality audit
+  knowledge/                 # 19 standalone knowledge modules
+  package.json               # npm package for npx installation
+```
+
+## CSS Strategy
+
+Generated CSS follows a three-layer architecture:
+
+1. **Tailwind** — Layout structure (flexbox, spacing, sizing)
+2. **CSS Custom Properties** — Design tokens (colors, typography, radii, shadows)
+3. **CSS Modules** — Visual skin (component-specific styles)
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// --- Constants ---
+
+const PLUGIN_NAME = 'fca';
+
+const SKILL_NAMES = [
+  // Tier 1: Developer workflow skills
+  'build-plugin',
+  'build-codegen-plugin',
+  'build-importer',
+  'build-token-pipeline',
+  // Tier 2: Reference/validation skills
+  'ref-layout',
+  'ref-react',
+  'ref-html',
+  'ref-tokens',
+  'ref-payload-block',
+  // Tier 3: Audit
+  'audit-plugin',
+];
+
+const SKILL_DESCRIPTIONS = {
+  'build-plugin':         'Build a Figma plugin from scratch or enhance one',
+  'build-codegen-plugin': 'Build a Dev Mode codegen plugin',
+  'build-importer':       'Build a Figma-to-CMS/React importer service',
+  'build-token-pipeline': 'Build a Figma token sync pipeline',
+  'ref-layout':           'Reference: Interpret Auto Layout -> CSS Flexbox',
+  'ref-react':            'Reference: Generate React/TSX from Figma node',
+  'ref-html':             'Reference: Generate HTML + layered CSS',
+  'ref-tokens':           'Reference: Extract design tokens -> CSS vars + Tailwind',
+  'ref-payload-block':    'Reference: Map Figma component -> PayloadCMS block',
+  'audit-plugin':         'Audit plugin against best practices',
+};
+
+// --- Paths ---
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function getGlobalBase() {
+  return path.join(os.homedir(), '.claude');
+}
+
+function getLocalBase() {
+  return path.join(process.cwd(), '.claude');
+}
+
+function getTargets(base) {
+  return {
+    commands: path.join(base, 'commands', PLUGIN_NAME),
+    knowledge: path.join(base, PLUGIN_NAME, 'knowledge'),
+  };
+}
+
+function getKnowledgeRefPath(base) {
+  // For global: @~/.claude/fca/knowledge/filename.md
+  // For local: @.claude/fca/knowledge/filename.md
+  const home = os.homedir();
+  if (base.startsWith(home)) {
+    return `~/.claude/${PLUGIN_NAME}/knowledge`;
+  }
+  return `.claude/${PLUGIN_NAME}/knowledge`;
+}
+
+// --- File operations ---
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function getKnowledgeFiles() {
+  const knowledgeDir = path.join(PKG_ROOT, 'knowledge');
+  return fs.readdirSync(knowledgeDir)
+    .filter(f => f.endsWith('.md') && f !== 'README.md')
+    .sort();
+}
+
+function copyWithPathReplacement(src, dest, replacements) {
+  let content = fs.readFileSync(src, 'utf-8');
+  for (const [search, replace] of replacements) {
+    content = content.replaceAll(search, replace);
+  }
+  ensureDir(path.dirname(dest));
+  fs.writeFileSync(dest, content, 'utf-8');
+}
+
+// --- Install ---
+
+function install(base) {
+  const targets = getTargets(base);
+  const knowledgeRefPath = getKnowledgeRefPath(base);
+  const replacements = [
+    ['@knowledge/', `@${knowledgeRefPath}/`],
+  ];
+
+  // Validate source files
+  console.log('Validating source files...');
+  let missing = 0;
+
+  for (const name of SKILL_NAMES) {
+    const src = path.join(PKG_ROOT, 'skills', name, 'SKILL.md');
+    if (!fs.existsSync(src)) {
+      console.log(`  ERROR: Missing skill: skills/${name}/SKILL.md`);
+      missing++;
+    }
+  }
+
+  const knowledgeFiles = getKnowledgeFiles();
+  for (const file of knowledgeFiles) {
+    const src = path.join(PKG_ROOT, 'knowledge', file);
+    if (!fs.existsSync(src)) {
+      console.log(`  ERROR: Missing knowledge file: knowledge/${file}`);
+      missing++;
+    }
+  }
+
+  if (missing > 0) {
+    console.log(`\nAborting: ${missing} source file(s) missing.`);
+    process.exit(1);
+  }
+  console.log(`  ${SKILL_NAMES.length} skills + ${knowledgeFiles.length} knowledge files found.`);
+  console.log('');
+
+  // Copy skills as commands
+  console.log('Installing skills...');
+  let skillCount = 0;
+  for (const name of SKILL_NAMES) {
+    const src = path.join(PKG_ROOT, 'skills', name, 'SKILL.md');
+    const dest = path.join(targets.commands, `${name}.md`);
+    copyWithPathReplacement(src, dest, replacements);
+    console.log(`  ${name}.md`);
+    skillCount++;
+  }
+  console.log('');
+
+  // Copy knowledge files
+  console.log('Installing knowledge modules...');
+  let knowledgeCount = 0;
+  for (const file of knowledgeFiles) {
+    const src = path.join(PKG_ROOT, 'knowledge', file);
+    const dest = path.join(targets.knowledge, file);
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+    console.log(`  ${file}`);
+    knowledgeCount++;
+  }
+  console.log('');
+
+  // Summary
+  const location = base === getGlobalBase() ? 'global (~/.claude/)' : `local (${path.relative(process.cwd(), base) || '.claude/'})`;
+  console.log(`Installed ${skillCount} skills + ${knowledgeCount} knowledge modules (${location})`);
+  console.log('');
+  console.log('Invoke skills in Claude Code:');
+  for (const name of SKILL_NAMES) {
+    const desc = SKILL_DESCRIPTIONS[name] || '';
+    console.log(`  /fca:${name.padEnd(22)} ${desc}`);
+  }
+  console.log('');
+  console.log('Tip: Use /clear before invoking a skill for a fresh context window.');
+}
+
+// --- Uninstall ---
+
+function uninstall(base) {
+  const targets = getTargets(base);
+  let removed = 0;
+
+  console.log('Uninstalling Figma Agent...');
+  console.log('');
+
+  // Remove command files
+  if (fs.existsSync(targets.commands)) {
+    const files = fs.readdirSync(targets.commands);
+    for (const file of files) {
+      fs.unlinkSync(path.join(targets.commands, file));
+      console.log(`  Removed command: ${file}`);
+      removed++;
+    }
+    fs.rmSync(targets.commands, { recursive: true, force: true });
+  }
+
+  // Remove knowledge files
+  if (fs.existsSync(targets.knowledge)) {
+    const files = fs.readdirSync(targets.knowledge);
+    for (const file of files) {
+      fs.unlinkSync(path.join(targets.knowledge, file));
+      console.log(`  Removed knowledge: ${file}`);
+      removed++;
+    }
+    fs.rmSync(targets.knowledge, { recursive: true, force: true });
+
+    // Remove parent fca directory if empty
+    const parentDir = path.dirname(targets.knowledge);
+    try {
+      const remaining = fs.readdirSync(parentDir);
+      if (remaining.length === 0) {
+        fs.rmdirSync(parentDir);
+      }
+    } catch {
+      // Ignore — parent may not exist or may not be empty
+    }
+  }
+
+  console.log('');
+  if (removed === 0) {
+    console.log('Nothing to remove — Figma Agent is not installed at this location.');
+  } else {
+    console.log(`Done. Removed ${removed} file(s).`);
+  }
+}
+
+// --- Interactive prompt ---
+
+function prompt(question, choices) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    console.log(question);
+    console.log('');
+    choices.forEach((choice, i) => {
+      console.log(`  ${i + 1}) ${choice.label}`);
+    });
+    console.log('');
+
+    rl.question('Choose [1-' + choices.length + ']: ', (answer) => {
+      rl.close();
+      const idx = parseInt(answer, 10) - 1;
+      if (idx >= 0 && idx < choices.length) {
+        resolve(choices[idx].value);
+      } else {
+        console.log('Invalid choice. Defaulting to global install.');
+        resolve('global');
+      }
+    });
+  });
+}
+
+// --- CLI ---
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse flags
+  let mode = null;
+  let isUninstall = false;
+  let showHelp = false;
+
+  for (const arg of args) {
+    switch (arg) {
+      case '--global':
+      case '-g':
+        mode = 'global';
+        break;
+      case '--local':
+      case '-l':
+        mode = 'local';
+        break;
+      case '--uninstall':
+      case '-u':
+        isUninstall = true;
+        break;
+      case '--help':
+      case '-h':
+        showHelp = true;
+        break;
+      default:
+        console.log(`Unknown option: ${arg}`);
+        showHelp = true;
+        break;
+    }
+  }
+
+  if (showHelp) {
+    console.log(`
+Figma Agent — npx installer
+
+Usage: npx figma-code-agent [OPTIONS]
+
+Options:
+  --global, -g     Install to ~/.claude/ (available in all projects)
+  --local, -l      Install to .claude/ in current project
+  --uninstall, -u  Remove installed files
+  --help, -h       Show this help message
+
+Examples:
+  npx figma-code-agent              Interactive mode (choose global or local)
+  npx figma-code-agent --global     Install globally to ~/.claude/
+  npx figma-code-agent --local      Install to current project's .claude/
+  npx figma-code-agent --uninstall  Remove from ~/.claude/ (default)
+  npx figma-code-agent --uninstall --local  Remove from .claude/
+`);
+    process.exit(0);
+  }
+
+  // Handle uninstall
+  if (isUninstall) {
+    const base = mode === 'local' ? getLocalBase() : getGlobalBase();
+    uninstall(base);
+    return;
+  }
+
+  // If no mode specified, prompt interactively
+  if (!mode) {
+    mode = await prompt('Where should Figma Agent be installed?', [
+      { label: 'Global — ~/.claude/ (available in all projects)', value: 'global' },
+      { label: 'Local — .claude/ (current project only)', value: 'local' },
+    ]);
+    console.log('');
+  }
+
+  const base = mode === 'local' ? getLocalBase() : getGlobalBase();
+  install(base);
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/knowledge/README.md

@@ -0,0 +1,62 @@
+# Knowledge Modules
+
+Modular knowledge files optimized for Claude Code `@file` reference consumption. Each module is a self-contained reference document that can be @referenced independently.
+
+## Naming Convention
+
+Files follow `{domain}-{topic}.md` format:
+- `figma-api-rest.md` -- Figma REST API reference
+- `design-to-code-layout.md` -- Auto Layout to Flexbox mapping
+- `css-strategy.md` -- Layered CSS approach documentation
+
+## Module Structure
+
+Each knowledge file follows this structure:
+
+1. **Title** -- Clear module name
+2. **Purpose** -- What knowledge this module contains
+3. **When to Use** -- Scenarios where this module should be @referenced
+4. **Content** -- The knowledge itself (rules, mappings, patterns, examples)
+5. **Cross-References** -- Related modules to consult for full context
+
+## Available Modules (19)
+
+### Figma API (5 modules)
+- `figma-api-rest.md` -- REST API endpoints, authentication, pagination, rate limits, node structure
+- `figma-api-plugin.md` -- Plugin API sandbox model, SceneNode types, IPC patterns, manifest format
+- `figma-api-variables.md` -- Variables API (collections, modes, bound variables, fallbacks)
+- `figma-api-webhooks.md` -- Webhooks v2 format, event types, verification
+- `figma-api-devmode.md` -- Dev Mode, codegen plugins, Dev Resources API
+
+### Design-to-Code (5 modules)
+- `design-to-code-layout.md` -- Auto Layout → Flexbox mapping (sizing modes, alignment, spacing)
+- `design-to-code-visual.md` -- Visual property extraction (fills, strokes, effects, gradients)
+- `design-to-code-typography.md` -- Text extraction (font mapping, line height, text styles)
+- `design-to-code-assets.md` -- Asset management (vector containers, image dedup, SVG export)
+- `design-to-code-semantic.md` -- Semantic HTML generation (element selection, ARIA, BEM naming)
+
+### CSS Strategy & Design Tokens (3 modules)
+- `css-strategy.md` -- Layered CSS approach (Tailwind + CSS Custom Properties + CSS Modules)
+- `design-tokens.md` -- Token extraction (threshold-based promotion, CSS variable naming)
+- `design-tokens-variables.md` -- Figma Variables deep dive (modes, fallback chains, scopes)
+
+### PayloadCMS Integration (3 modules)
+- `payload-blocks.md` -- Block system (config, fields, renderers, type generation, plugins)
+- `payload-figma-mapping.md` -- Figma component → block mapping patterns
+- `payload-visual-builder.md` -- Visual builder plugin architecture
+
+### Plugin Development (3 modules)
+- `plugin-architecture.md` -- Plugin sandbox model, IPC, @create-figma-plugin patterns
+- `plugin-codegen.md` -- Codegen plugin patterns (Dev Mode integration)
+- `plugin-best-practices.md` -- Production patterns for Figma plugins
+
+## Usage
+
+Reference any module in your project's `CLAUDE.md` or inline:
+
+```
+@/path/to/figma-code-agent/knowledge/figma-api-rest.md
+@/path/to/figma-code-agent/knowledge/design-to-code-layout.md
+```
+
+Skills in `skills/` automatically @reference the knowledge modules they depend on.