@noemuch/bridge-ds 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Noe Chague
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# Bridge DS
+
+AI-powered design generation in Figma — 100% design system compliant.
+
+Bridge turns [Claude Code](https://claude.ai/download) into a designer that knows your design system inside out. It extracts, documents, and uses your real Figma components, tokens, and text styles to generate production-ready designs.
+
+```
+You describe what you want
+  → Claude consults the knowledge base (your DS, documented)
+  → Claude writes the spec (exact components, tokens, layout)
+  → Claude generates in Figma via figma_execute (real DS components, bound variables)
+  → You review in Figma
+```
+
+## How it works
+
+Bridge is two things:
+
+1. **A CLI** (`bridge-ds init`) that scaffolds your project with the design workflow skill
+2. **A Claude Code skill** (`/design-workflow`) that handles the intelligence — spec writing, DS knowledge, Figma generation
+
+The transport layer is [figma-console-mcp](https://github.com/southleft/figma-console-mcp), an MCP server that gives Claude native access to Figma (57+ tools).
+
+```
+Claude Code  ──MCP──>  figma-console-mcp  ──WebSocket──>  Figma Desktop
+                                                            (your DS library,
+                                                             real components,
+                                                             bound variables)
+```
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/download) installed
+- [Node.js 18+](https://nodejs.org)
+- [Figma Desktop](https://www.figma.com/downloads/) (not the web app)
+- A Figma file with a published design system library
+
+## Quick Start
+
+### 1. Install figma-console-mcp
+
+```bash
+claude mcp add figma-console -s user \
+  -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN \
+  -- npx -y figma-console-mcp@latest
+```
+
+Get your token from [Figma Settings → Personal access tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens).
+
+### 2. Connect Figma Desktop
+
+1. Run `npx figma-console-mcp@latest --print-path` to find the plugin directory
+2. In Figma Desktop: **Plugins → Development → Import plugin from manifest...**
+3. Select `figma-desktop-bridge/manifest.json`
+4. Run the plugin in your Figma file
+
+### 3. Initialize your project
+
+```bash
+cd your-project
+npx @noemuch/bridge-ds init
+```
+
+This scaffolds:
+- `.claude/skills/design-workflow/` — the workflow skill + references
+- `.claude/commands/design-workflow.md` — the `/design-workflow` slash command
+- `specs/` — directory for active, shipped, and dropped specs
+
+### 4. Build your knowledge base
+
+Open Claude Code in your project:
+
+```
+/design-workflow setup
+```
+
+Claude will:
+1. Extract your entire DS from Figma (`figma_get_design_system_kit`)
+2. Analyze every component, token, and style
+3. Generate intelligent guides (when to use what, decision trees, pattern catalog)
+4. Ask for product screenshots to document layout patterns
+
+### 5. Start designing
+
+```
+/design-workflow spec a settings page for account information
+```
+
+Claude consults the knowledge base, identifies the right pattern, components, and tokens, and writes a complete spec. Then:
+
+```
+/design-workflow design    # Generate in Figma (atomic, verified)
+/design-workflow review    # Validate against spec
+/design-workflow done      # Archive and ship
+```
+
+## The Workflow
+
+```
+setup (once)  →  spec  →  design  →  review  →  done
+                   ↑                    |
+                   └── iterate ─────────┘
+```
+
+### Spec-first
+No design without a validated specification. Claude knows exactly which components, tokens, and layout patterns to use because it has your DS documented.
+
+### Atomic generation
+Designs are generated in 4-6 small sequential scripts (~30-80 lines each). After each step, Claude takes a screenshot and verifies before continuing. Bug in step 3? Fix and re-run step 3 only.
+
+### DS-native
+Zero hardcoded hex colors. Zero recreated components. Everything imported from your library via `importComponentByKeyAsync`, bound to variables via `setBoundVariableForPaint`.
+
+### Quality gates
+Blocking checks at every phase transition: spec validation, pattern matching, pre-script element audit, visual fidelity review, DS component reuse audit.
+
+## Knowledge Base
+
+The knowledge base is what makes Bridge different from "just executing Figma scripts". During setup, Claude builds a complete understanding of your DS:
+
+```
+knowledge-base/
+  registries/          ← Raw DS data (components, variables, text styles)
+  guides/
+    design-patterns.md ← Layout patterns from your product screenshots
+    tokens/            ← When to use which color, spacing, typography
+    components/        ← Decision tree: "I need X" → use component Y
+    patterns/          ← Form, navigation, feedback, multi-step patterns
+    assets/            ← Icons, logos, illustrations catalog
+  ui-references/       ← Product screenshots for pattern extraction
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/design-workflow setup` | Extract DS + build knowledge base |
+| `/design-workflow spec {name}` | Write a component or screen spec |
+| `/design-workflow design` | Generate in Figma from active spec |
+| `/design-workflow review` | Validate design against spec + tokens |
+| `/design-workflow done` | Archive spec and ship |
+| `/design-workflow drop` | Abandon with preserved learnings |
+| `/design-workflow status` | Show current state, suggest next action |
+
+## License
+
+MIT

package/bin/bridge.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require('../lib/cli');
+run(process.argv.slice(2));

package/commands/design-workflow.md

@@ -0,0 +1 @@
+Read and follow the skill defined in `.claude/skills/design-workflow/SKILL.md`.

package/lib/cli.js

@@ -0,0 +1,172 @@
+const path = require('path');
+const { scaffold } = require('./scaffold');
+const { checkMcp, setupMcp } = require('./mcp-setup');
+
+// ── Branding ──────────────────────────────────────────────
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  orange: '\x1b[38;2;237;112;46m',
+  green: '\x1b[38;2;76;175;80m',
+  red: '\x1b[38;2;244;67;54m',
+  yellow: '\x1b[38;2;255;193;7m',
+  gray: '\x1b[38;2;158;158;158m',
+  white: '\x1b[38;2;255;255;255m',
+};
+
+function print(msg = '') { process.stdout.write(msg + '\n'); }
+function header(msg) { print(`\n${C.orange}${C.bold}🧱 ${msg}${C.reset}\n`); }
+function success(msg) { print(`${C.green}  ✓ ${msg}${C.reset}`); }
+function info(msg) { print(`${C.white}  ℹ ${msg}${C.reset}`); }
+function warn(msg) { print(`${C.yellow}  ⚠ ${msg}${C.reset}`); }
+function error(msg) { print(`${C.red}  ✗ ${msg}${C.reset}`); }
+function muted(msg) { print(`${C.gray}    ${msg}${C.reset}`); }
+function step(n, total, msg) { print(`${C.orange}  [${n}/${total}]${C.reset} ${C.bold}${msg}${C.reset}`); }
+
+// ── Spinner ───────────────────────────────────────────────
+const FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+class Spinner {
+  constructor(msg) { this.msg = msg; this.i = 0; this.id = null; }
+  start() {
+    this.id = setInterval(() => {
+      process.stdout.write(`\r${C.orange}  ${FRAMES[this.i++ % FRAMES.length]}${C.reset} ${this.msg}`);
+    }, 80);
+    return this;
+  }
+  stop(result) {
+    clearInterval(this.id);
+    process.stdout.write('\r' + ' '.repeat(this.msg.length + 10) + '\r');
+    if (result) success(result);
+  }
+}
+
+// ── ASCII Art ─────────────────────────────────────────────
+function banner() {
+  print('');
+  print(`${C.orange}${C.bold}  ┌──────────────────────────────────────┐${C.reset}`);
+  print(`${C.orange}${C.bold}  │  🧱  Bridge DS                       │${C.reset}`);
+  print(`${C.orange}${C.bold}  │  AI-powered design in Figma           │${C.reset}`);
+  print(`${C.orange}${C.bold}  │  100% design system compliant         │${C.reset}`);
+  print(`${C.orange}${C.bold}  └──────────────────────────────────────┘${C.reset}`);
+  print('');
+}
+
+// ── Commands ──────────────────────────────────────────────
+
+async function cmdInit() {
+  banner();
+  header('Initializing Bridge DS');
+
+  const cwd = process.cwd();
+  const totalSteps = 4;
+
+  // Step 1: Check prerequisites
+  step(1, totalSteps, 'Checking prerequisites');
+  const nodeVersion = process.version.replace('v', '').split('.').map(Number);
+  if (nodeVersion[0] < 18) {
+    error(`Node.js 18+ required (found ${process.version})`);
+    process.exit(1);
+  }
+  success(`Node.js ${process.version}`);
+
+  // Step 2: Configure figma-console-mcp
+  step(2, totalSteps, 'Checking figma-console-mcp');
+  const mcpConfigured = checkMcp();
+  if (mcpConfigured) {
+    success('figma-console-mcp is configured');
+  } else {
+    warn('figma-console-mcp not found in Claude Code settings');
+    info('Run this command to add it:');
+    print('');
+    print(`${C.dim}    claude mcp add figma-console -s user \\${C.reset}`);
+    print(`${C.dim}      -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN \\${C.reset}`);
+    print(`${C.dim}      -- npx -y figma-console-mcp@latest${C.reset}`);
+    print('');
+    info('Then re-run: bridge-ds init');
+    info('Continuing with file setup...');
+  }
+
+  // Step 3: Scaffold project files
+  step(3, totalSteps, 'Scaffolding project files');
+  const spinner = new Spinner('Copying skills, commands, templates...').start();
+  const result = scaffold(cwd);
+  spinner.stop('Project files created');
+
+  for (const f of result.created) {
+    muted(f);
+  }
+
+  // Step 4: Summary
+  step(4, totalSteps, 'Done!');
+  print('');
+  print(`${C.orange}${C.bold}  ┌──────────────────────────────────────┐${C.reset}`);
+  print(`${C.orange}${C.bold}  │  Setup complete!                      │${C.reset}`);
+  print(`${C.orange}${C.bold}  │                                       │${C.reset}`);
+  print(`${C.orange}${C.bold}  │  Next steps:                          │${C.reset}`);
+  print(`${C.orange}${C.bold}  │  1. Open Claude Code in this project  │${C.reset}`);
+  print(`${C.orange}${C.bold}  │  2. Run: /design-workflow setup       │${C.reset}`);
+  print(`${C.orange}${C.bold}  │     → Extracts & documents your DS    │${C.reset}`);
+  print(`${C.orange}${C.bold}  │  3. Run: /design-workflow spec ...    │${C.reset}`);
+  print(`${C.orange}${C.bold}  │     → Start designing!                │${C.reset}`);
+  print(`${C.orange}${C.bold}  └──────────────────────────────────────┘${C.reset}`);
+  print('');
+}
+
+function cmdHelp() {
+  banner();
+  print(`${C.bold}  Commands:${C.reset}`);
+  print('');
+  print(`    ${C.orange}init${C.reset}       Initialize Bridge DS in current project`);
+  print(`               Scaffolds skills, commands, and specs directories`);
+  print('');
+  print(`    ${C.orange}help${C.reset}       Show this help message`);
+  print(`    ${C.orange}version${C.reset}    Show version`);
+  print('');
+  print(`${C.bold}  Usage:${C.reset}`);
+  print('');
+  print(`    ${C.dim}npx bridge-ds init${C.reset}     # Initialize in current project`);
+  print(`    ${C.dim}bridge-ds help${C.reset}          # Show help`);
+  print('');
+  print(`${C.bold}  After init:${C.reset}`);
+  print('');
+  print(`    ${C.dim}/design-workflow setup${C.reset}  # Extract & document your DS (in Claude Code)`);
+  print(`    ${C.dim}/design-workflow spec${C.reset}   # Spec a component or screen`);
+  print(`    ${C.dim}/design-workflow design${C.reset} # Generate in Figma`);
+  print(`    ${C.dim}/design-workflow review${C.reset} # Validate against spec`);
+  print(`    ${C.dim}/design-workflow done${C.reset}   # Archive & ship`);
+  print('');
+}
+
+function cmdVersion() {
+  const pkg = require('../package.json');
+  print(`bridge-ds v${pkg.version}`);
+}
+
+// ── Router ────────────────────────────────────────────────
+
+async function run(args) {
+  const cmd = args[0] || 'help';
+
+  switch (cmd) {
+    case 'init':
+      await cmdInit();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      cmdHelp();
+      break;
+    case 'version':
+    case '--version':
+    case '-v':
+      cmdVersion();
+      break;
+    default:
+      error(`Unknown command: ${cmd}`);
+      cmdHelp();
+      process.exit(1);
+  }
+}
+
+module.exports = { run };

package/lib/mcp-setup.js

@@ -0,0 +1,47 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Check if figma-console-mcp is configured in Claude Code settings.
+ * Checks multiple possible locations.
+ */
+function checkMcp() {
+  const locations = [
+    // User-level Claude Code settings
+    path.join(os.homedir(), '.claude.json'),
+    // Project-level settings
+    path.join(process.cwd(), '.claude', 'settings.local.json'),
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc)) {
+      try {
+        const content = JSON.parse(fs.readFileSync(loc, 'utf8'));
+        const servers = content.mcpServers || {};
+        // Check for any figma-console-mcp configuration
+        for (const [name, config] of Object.entries(servers)) {
+          if (name.includes('figma') && config.command) {
+            const args = (config.args || []).join(' ');
+            if (args.includes('figma-console-mcp')) {
+              return true;
+            }
+          }
+        }
+      } catch (_) {
+        // Ignore parse errors
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Return the MCP add command for the user to run.
+ */
+function getMcpAddCommand() {
+  return 'claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN -- npx -y figma-console-mcp@latest';
+}
+
+module.exports = { checkMcp, getMcpAddCommand };

package/lib/scaffold.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively copy a directory, preserving structure.
+ */
+function copyDir(src, dest) {
+  const created = [];
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      created.push(...copyDir(srcPath, destPath));
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      created.push(destPath);
+    }
+  }
+  return created;
+}
+
+/**
+ * Scaffold Bridge DS into the target project directory.
+ * Returns { created: string[] } with relative paths of created files.
+ */
+function scaffold(projectDir) {
+  const created = [];
+  const pkgRoot = path.resolve(__dirname, '..');
+
+  // 1. Copy skills/design-workflow → .claude/skills/design-workflow
+  const skillsSrc = path.join(pkgRoot, 'skills', 'design-workflow');
+  const skillsDest = path.join(projectDir, '.claude', 'skills', 'design-workflow');
+  if (fs.existsSync(skillsSrc)) {
+    const files = copyDir(skillsSrc, skillsDest);
+    created.push(...files.map(f => path.relative(projectDir, f)));
+  }
+
+  // 2. Copy commands/design-workflow.md → .claude/commands/design-workflow.md
+  const cmdSrc = path.join(pkgRoot, 'commands', 'design-workflow.md');
+  const cmdDest = path.join(projectDir, '.claude', 'commands', 'design-workflow.md');
+  if (fs.existsSync(cmdSrc)) {
+    fs.mkdirSync(path.dirname(cmdDest), { recursive: true });
+    fs.copyFileSync(cmdSrc, cmdDest);
+    created.push(path.relative(projectDir, cmdDest));
+  }
+
+  // 3. Create specs/ directory structure
+  const specsDirs = [
+    'specs/active',
+    'specs/backlog',
+    'specs/shipped',
+    'specs/dropped',
+  ];
+  for (const dir of specsDirs) {
+    const fullPath = path.join(projectDir, dir);
+    if (!fs.existsSync(fullPath)) {
+      fs.mkdirSync(fullPath, { recursive: true });
+      // Add .gitkeep
+      const gitkeep = path.join(fullPath, '.gitkeep');
+      fs.writeFileSync(gitkeep, '');
+      created.push(path.relative(projectDir, gitkeep));
+    }
+  }
+
+  // Create history.log if not exists
+  const historyLog = path.join(projectDir, 'specs', 'history.log');
+  if (!fs.existsSync(historyLog)) {
+    fs.writeFileSync(historyLog, '# Design History\n# date | name | type | figma_url | author\n');
+    created.push(path.relative(projectDir, historyLog));
+  }
+
+  // 4. Create empty knowledge-base directories
+  const kbDirs = [
+    '.claude/skills/design-workflow/references/knowledge-base/registries',
+    '.claude/skills/design-workflow/references/knowledge-base/guides/tokens',
+    '.claude/skills/design-workflow/references/knowledge-base/guides/components',
+    '.claude/skills/design-workflow/references/knowledge-base/guides/patterns',
+    '.claude/skills/design-workflow/references/knowledge-base/guides/assets',
+    '.claude/skills/design-workflow/references/knowledge-base/ui-references/screenshots',
+  ];
+  for (const dir of kbDirs) {
+    const fullPath = path.join(projectDir, dir);
+    if (!fs.existsSync(fullPath)) {
+      fs.mkdirSync(fullPath, { recursive: true });
+      const gitkeep = path.join(fullPath, '.gitkeep');
+      if (!fs.existsSync(gitkeep)) {
+        fs.writeFileSync(gitkeep, '');
+      }
+    }
+  }
+
+  // 5. Update .gitignore
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  const gitignoreEntries = [
+    '',
+    '# Bridge DS — knowledge base data (regenerated via /design-workflow setup)',
+    '.claude/skills/design-workflow/references/knowledge-base/registries/*.json',
+    '.claude/skills/design-workflow/references/knowledge-base/ui-references/screenshots/*.png',
+    '.claude/skills/design-workflow/references/knowledge-base/ui-references/screenshots/*.jpg',
+  ];
+  const gitignoreBlock = gitignoreEntries.join('\n') + '\n';
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (!content.includes('Bridge DS')) {
+      fs.appendFileSync(gitignorePath, gitignoreBlock);
+      created.push('.gitignore (updated)');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, 'node_modules/\n.DS_Store\n' + gitignoreBlock);
+    created.push('.gitignore');
+  }
+
+  return { created };
+}
+
+module.exports = { scaffold };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@noemuch/bridge-ds",
+  "version": "2.0.0",
+  "description": "AI-powered design generation in Figma — 100% design system compliant. Connects Claude Code to Figma via MCP for spec-first, token-bound, component-native design.",
+  "main": "lib/cli.js",
+  "bin": {
+    "bridge-ds": "./bin/bridge.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "commands/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node bin/bridge.js help"
+  },
+  "keywords": [
+    "claude-code",
+    "figma",
+    "design-system",
+    "mcp",
+    "design-tokens",
+    "ai-design",
+    "figma-plugin-api"
+  ],
+  "author": "noemuch",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/noemuch/bridge.git"
+  },
+  "homepage": "https://github.com/noemuch/bridge"
+}