@bongos/core 1.17.0

package/src/ui/adapters/claude-design/index.js

@@ -0,0 +1,333 @@
+'use strict';
+// Claude Design adapter — wires the repo design system to Claude Design.
+//
+// Conforms to the adapter interface in docs/design-contract.md §4.
+//
+// import(opts): repo → Claude Design
+//   Resolves design tokens, scans src/ui/ surfaces, and writes a token-preview
+//   bundle (HTML cards + CSS vars + JSON manifest) to a temp directory.
+//   The /design-sync skill then pushes the bundle via the DesignSync MCP tool.
+//
+// export(opts): Claude Design → repo
+//   Receives Claude Design's generated HTML/CSS/JS output (toolOutput.files[])
+//   and writes it as a committed-ready diff under src/ui/<surfaceId>/.
+//   Updates config/design-sources.json with the sync timestamp.
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+const ID = 'claude-design';
+
+// ── token helpers ─────────────────────────────────────────────────────────────
+
+function camelToKebab(s) {
+  return s.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+function deepMerge(base, over) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && typeof out[k] === 'object') {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function resolveTokens(repoRoot) {
+  const neutral = JSON.parse(fs.readFileSync(
+    path.join(repoRoot, 'config', 'design-tokens.neutral.json'), 'utf8',
+  ));
+  let instance = {};
+  try {
+    instance = JSON.parse(fs.readFileSync(
+      path.join(repoRoot, 'config', 'design-tokens.json'), 'utf8',
+    ));
+  } catch { /* no instance pack — fine */ }
+  return deepMerge(neutral, instance);
+}
+
+function tokensToCss(tokens) {
+  const lines = [':root {'];
+  for (const [group, vals] of Object.entries(tokens)) {
+    if (group.startsWith('_') || !vals || typeof vals !== 'object') continue;
+    for (const [key, val] of Object.entries(vals)) {
+      if (key === 'links') continue;
+      if (Array.isArray(val)) continue;
+      lines.push(`  --dt-${camelToKebab(group)}-${camelToKebab(key)}: ${val};`);
+    }
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+// ── design-sources helpers ────────────────────────────────────────────────────
+
+function readDesignSources(repoRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(
+      path.join(repoRoot, 'config', 'design-sources.json'), 'utf8',
+    ));
+  } catch { return { surfaces: {} }; }
+}
+
+// ── surface scanner ───────────────────────────────────────────────────────────
+
+function scanSurfaces(repoRoot, designSources) {
+  const uiDir = path.join(repoRoot, 'src', 'ui');
+  const sourcesMap = (designSources && designSources.surfaces) || {};
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(uiDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== 'adapters')
+      .map(e => e.name);
+  } catch { /* src/ui/ may not exist yet */ }
+
+  return dirs.map(id => ({
+    id,
+    path: path.join(uiDir, id),
+    tool: (sourcesMap[id] && sourcesMap[id].tool) || undefined,
+    sourceUrl: (sourcesMap[id] && sourcesMap[id].sourceUrl) || undefined,
+  }));
+}
+
+// ── HTML card builders ────────────────────────────────────────────────────────
+
+function colorsHtml(tokens) {
+  const colors = tokens.colors || {};
+  const fontImport = (tokens.fonts && tokens.fonts.links || [])
+    .map(l => `@import url('${l}');`).join('\n');
+  const swatches = Object.entries(colors).map(([name, val]) => `
+    <div class="swatch">
+      <div class="chip" style="background:${val}"></div>
+      <code>--dt-color-${camelToKebab(name)}</code>
+      <small>${val}</small>
+    </div>`).join('');
+
+  return `<!-- @dsCard group="Tokens" -->
+<!doctype html><html lang="en">
+<head><meta charset="utf-8"><title>Colors</title>
+<style>
+${fontImport}
+body{font-family:${(tokens.fonts && tokens.fonts.body) || 'sans-serif'};padding:16px;margin:0;background:#fff;}
+.grid{display:flex;flex-wrap:wrap;gap:12px;}
+.swatch{width:110px;}
+.chip{height:56px;border-radius:8px;border:1px solid rgba(0,0,0,.07);margin-bottom:6px;}
+code{font-size:10px;display:block;word-break:break-all;color:#444;}
+small{color:#888;font-size:10px;}
+</style></head>
+<body><div class="grid">${swatches}</div></body>
+</html>`;
+}
+
+function typographyHtml(tokens) {
+  const fonts = tokens.fonts || {};
+  const fontImport = (fonts.links || []).map(l => `@import url('${l}');`).join('\n');
+  const mono = fonts.mono
+    ? `<div class="specimen"><label>Mono</label><code style="font-family:${fonts.mono};font-size:13px;">const answer = 42; // ${fonts.mono}</code></div>`
+    : '';
+
+  return `<!-- @dsCard group="Tokens" -->
+<!doctype html><html lang="en">
+<head><meta charset="utf-8"><title>Typography</title>
+<style>
+${fontImport}
+body{padding:16px;margin:0;background:#fff;}
+.specimen+.specimen{margin-top:24px;border-top:1px solid #eee;padding-top:24px;}
+label{display:block;font-size:10px;color:#888;text-transform:uppercase;letter-spacing:1px;margin-bottom:8px;}
+</style></head>
+<body>
+  <div class="specimen">
+    <label>Display · ${fonts.display || 'system-ui'}</label>
+    <div style="font-family:${fonts.display || 'sans-serif'};font-size:32px;font-weight:700;">The quick brown fox</div>
+    <div style="font-family:${fonts.display || 'sans-serif'};font-size:20px;font-weight:600;color:#555;margin-top:8px;">Jumps over the lazy dog</div>
+  </div>
+  <div class="specimen">
+    <label>Body · ${fonts.body || 'system-ui'}</label>
+    <div style="font-family:${fonts.body || 'sans-serif'};font-size:16px;">The quick brown fox jumps over the lazy dog.</div>
+    <div style="font-family:${fonts.body || 'sans-serif'};font-size:13px;color:#555;margin-top:6px;">Smaller body — captions, labels, secondary info.</div>
+  </div>
+  ${mono}
+</body>
+</html>`;
+}
+
+function spacingHtml(tokens) {
+  const scale = tokens.scale || {};
+  const colors = tokens.colors || {};
+  const accent = colors.accent || '#f97316';
+  const rows = Object.entries(scale).map(([k, v]) => `
+    <tr>
+      <td><code>${k}</code></td>
+      <td style="color:#888;font-size:11px;">${v}</td>
+      <td><div style="background:${accent};height:12px;width:${v};border-radius:2px;max-width:200px;"></div></td>
+    </tr>`).join('');
+
+  return `<!-- @dsCard group="Tokens" -->
+<!doctype html><html lang="en">
+<head><meta charset="utf-8"><title>Spacing scale</title>
+<style>
+body{font-family:sans-serif;padding:16px;margin:0;background:#fff;}
+table{border-collapse:collapse;width:100%;}
+td{padding:6px 8px;border-bottom:1px solid #eee;vertical-align:middle;}
+code{font-size:12px;}
+</style></head>
+<body><table><tbody>${rows}</tbody></table></body>
+</html>`;
+}
+
+function radiiHtml(tokens) {
+  const radius = tokens.radius || {};
+  const accent = (tokens.colors && tokens.colors.accent) || '#f97316';
+  const boxes = Object.entries(radius).map(([k, v]) => `
+    <div style="display:inline-block;margin:8px;">
+      <div style="width:64px;height:64px;background:${accent};border-radius:${v};"></div>
+      <div style="font-size:11px;margin-top:4px;text-align:center;color:#555;">${k} · ${v}</div>
+    </div>`).join('');
+
+  return `<!-- @dsCard group="Tokens" -->
+<!doctype html><html lang="en">
+<head><meta charset="utf-8"><title>Radii</title>
+<style>body{font-family:sans-serif;padding:16px;margin:0;background:#fff;}</style></head>
+<body>${boxes}</body>
+</html>`;
+}
+
+// ── bundle writer ─────────────────────────────────────────────────────────────
+
+async function writeBundleDir(tokens, surfaces) {
+  const bundleDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'otb-design-bundle-'));
+
+  const tokensDir = path.join(bundleDir, 'tokens');
+  await fsp.mkdir(tokensDir, { recursive: true });
+
+  await fsp.writeFile(path.join(tokensDir, 'colors.html'), colorsHtml(tokens), 'utf8');
+  await fsp.writeFile(path.join(tokensDir, 'typography.html'), typographyHtml(tokens), 'utf8');
+  await fsp.writeFile(path.join(tokensDir, 'spacing.html'), spacingHtml(tokens), 'utf8');
+  await fsp.writeFile(path.join(tokensDir, 'radii.html'), radiiHtml(tokens), 'utf8');
+
+  // tokens.css — --dt-* CSS custom properties for prototype stylesheets
+  await fsp.writeFile(path.join(bundleDir, 'tokens.css'), tokensToCss(tokens), 'utf8');
+
+  // tokens.json — resolved values for tooling / reference
+  await fsp.writeFile(
+    path.join(bundleDir, 'tokens.json'),
+    JSON.stringify(tokens, null, 2),
+    'utf8',
+  );
+
+  // surfaces manifest — tells Claude Design which surfaces exist + who owns them
+  await fsp.writeFile(
+    path.join(bundleDir, 'surfaces.json'),
+    JSON.stringify({
+      surfaces: surfaces.map(s => ({
+        id: s.id,
+        tool: s.tool || 'hand',
+        sourceUrl: s.sourceUrl || null,
+      })),
+    }, null, 2),
+    'utf8',
+  );
+
+  return bundleDir;
+}
+
+// ── path-escape guard ─────────────────────────────────────────────────────────
+
+function assertSafePath(relPath, repoRoot, surfaceId) {
+  const uiBase = path.resolve(repoRoot, 'src', 'ui', surfaceId);
+  const assetBase = path.resolve(repoRoot, 'assets', 'ui', surfaceId);
+  const resolved = path.resolve(uiBase, relPath);
+  const inUi = resolved.startsWith(uiBase + path.sep) || resolved === uiBase;
+  const inAsset = resolved.startsWith(assetBase + path.sep) || resolved === assetBase;
+  if (!inUi && !inAsset) {
+    throw new Error(
+      `path-escape: "${relPath}" would write outside src/ui/${surfaceId}/ or assets/ui/${surfaceId}/`,
+    );
+  }
+  return resolved;
+}
+
+// ── exported adapter ──────────────────────────────────────────────────────────
+
+module.exports = {
+  id: ID,
+
+  /**
+   * repo → Claude Design.
+   * Builds a token-preview bundle (HTML cards + CSS vars + JSON) in a temp
+   * directory. Returns { bundlePath, surfaceIds, summary }.
+   * The /design-sync skill pushes the bundle via the DesignSync MCP tool.
+   */
+  async import({ repoRoot, tokens, surfaces } = {}) {
+    if (!repoRoot) throw new Error('claude-design import: repoRoot is required');
+    const resolvedTokens = tokens || resolveTokens(repoRoot);
+    const sources = readDesignSources(repoRoot);
+    const surfaceList = surfaces || scanSurfaces(repoRoot, sources);
+    const bundlePath = await writeBundleDir(resolvedTokens, surfaceList);
+
+    return {
+      bundlePath,
+      surfaceIds: surfaceList.map(s => s.id),
+      summary: `bundle → ${bundlePath} · ${surfaceList.length} surface(s) · tokens: colors, typography, spacing, radii`,
+    };
+  },
+
+  /**
+   * Claude Design → repo.
+   * toolOutput: { files: [{ path: string, content: string }] }
+   * Writes files to src/ui/<surfaceId>/ and updates config/design-sources.json.
+   * Returns { filePaths, diff, commitMessage, designSourcesUpdated, warnings }.
+   */
+  async export({ repoRoot, surfaceId, toolOutput, taskId } = {}) {
+    if (!repoRoot) throw new Error('claude-design export: repoRoot is required');
+    if (!surfaceId) throw new Error('claude-design export: surfaceId is required');
+    if (!toolOutput || !Array.isArray(toolOutput.files)) {
+      throw new Error('claude-design export: toolOutput.files[] is required');
+    }
+
+    const surfaceDir = path.resolve(repoRoot, 'src', 'ui', surfaceId);
+    await fsp.mkdir(surfaceDir, { recursive: true });
+
+    const written = [];
+    const warnings = [];
+
+    for (const { path: relPath, content } of toolOutput.files) {
+      if (!relPath || typeof content !== 'string') {
+        warnings.push(`skipped malformed file entry: ${JSON.stringify({ path: relPath })}`);
+        continue;
+      }
+      const dest = assertSafePath(relPath, repoRoot, surfaceId);
+      await fsp.mkdir(path.dirname(dest), { recursive: true });
+      // idempotent: skip if content is identical
+      const existing = await fsp.readFile(dest, 'utf8').catch(() => null);
+      if (existing === content) continue;
+      await fsp.writeFile(dest, content, 'utf8');
+      written.push(path.relative(repoRoot, dest));
+    }
+
+    // Update config/design-sources.json
+    const sourcesPath = path.join(repoRoot, 'config', 'design-sources.json');
+    const sources = readDesignSources(repoRoot);
+    sources.surfaces = sources.surfaces || {};
+    sources.surfaces[surfaceId] = {
+      ...(sources.surfaces[surfaceId] || {}),
+      tool: ID,
+      lastSyncedAt: new Date().toISOString(),
+      ...(taskId ? { notes: `GDS task ${taskId}` } : {}),
+    };
+    await fsp.writeFile(sourcesPath, JSON.stringify(sources, null, 2) + '\n', 'utf8');
+
+    return {
+      filePaths: written,
+      diff: '',
+      commitMessage: `ui(${surfaceId}): Claude Design export${taskId ? ` (task ${taskId})` : ''}`,
+      designSourcesUpdated: true,
+      warnings,
+    };
+  },
+};

package/src/ui/adapters/figma/index.js

@@ -0,0 +1,328 @@
+'use strict';
+// Figma adapter — the human escape hatch in ADR 0081's tool-agnostic design layer.
+//
+// Conforms to the adapter interface in docs/design-contract.md §4.
+//
+// import(opts): repo → Figma
+//   Resolves design tokens + surfaces and builds a "push plan" (frames to
+//   create: color swatches, typography specimens, one preview frame per
+//   surface) in a temp directory. The figma-design-sync skill executes the
+//   plan against the live Figma MCP tool so a designer never opens a stale
+//   file.
+//
+// export(opts): Figma → repo
+//   Receives either ready-made code (Code Connect output — the common case)
+//   or a raw Figma node snapshot (MCP output with no Code Connect mapping)
+//   and writes it as a committed-ready diff under src/ui/<surfaceId>/.
+//   A snapshot node that carries no code-representable content (image/vector
+//   fills) is reported as a warning, not silently dropped — per ADR 0081,
+//   arbitrary canvas art becomes an asset, not code.
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+const ID = 'figma';
+
+// Figma node types that carry no code-representable content — the round-trip
+// is honestly lossy here (docs/design-contract.md §2.3 / ADR 0081).
+const ASSET_ONLY_NODE_TYPES = new Set(['VECTOR', 'BOOLEAN_OPERATION', 'STAR', 'ELLIPSE', 'LINE']);
+
+// ── token helpers ─────────────────────────────────────────────────────────────
+
+function camelToKebab(s) {
+  return s.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+function deepMerge(base, over) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && typeof out[k] === 'object') {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function resolveTokens(repoRoot) {
+  const neutral = JSON.parse(fs.readFileSync(
+    path.join(repoRoot, 'config', 'design-tokens.neutral.json'), 'utf8',
+  ));
+  let instance = {};
+  try {
+    instance = JSON.parse(fs.readFileSync(
+      path.join(repoRoot, 'config', 'design-tokens.json'), 'utf8',
+    ));
+  } catch { /* no instance pack — fine */ }
+  return deepMerge(neutral, instance);
+}
+
+// Reverse lookup: hex color -> --dt-color-<key> token name, so exported CSS
+// prefers a token reference over a raw hex when Figma's fill matches one.
+function buildColorTokenIndex(tokens) {
+  const index = new Map();
+  const colors = (tokens && tokens.colors) || {};
+  for (const [key, val] of Object.entries(colors)) {
+    if (typeof val === 'string') index.set(val.toLowerCase(), `var(--dt-color-${camelToKebab(key)})`);
+  }
+  return index;
+}
+
+// ── design-sources helpers ────────────────────────────────────────────────────
+
+function readDesignSources(repoRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(
+      path.join(repoRoot, 'config', 'design-sources.json'), 'utf8',
+    ));
+  } catch { return { surfaces: {} }; }
+}
+
+// ── surface scanner ───────────────────────────────────────────────────────────
+
+function scanSurfaces(repoRoot, designSources) {
+  const uiDir = path.join(repoRoot, 'src', 'ui');
+  const sourcesMap = (designSources && designSources.surfaces) || {};
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(uiDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== 'adapters')
+      .map(e => e.name);
+  } catch { /* src/ui/ may not exist yet */ }
+
+  return dirs.map(id => ({
+    id,
+    path: path.join(uiDir, id),
+    tool: (sourcesMap[id] && sourcesMap[id].tool) || undefined,
+    sourceUrl: (sourcesMap[id] && sourcesMap[id].sourceUrl) || undefined,
+  }));
+}
+
+// ── push-plan builder (repo → Figma) ──────────────────────────────────────────
+
+// Figma has no HTML renderer, so unlike the Claude Design bundle this is a
+// plan of nodes to create, not markup — the figma-design-sync skill turns
+// each entry into a real Figma frame via the live MCP tool.
+function buildPushPlan(tokens, surfaces) {
+  const colorFrame = {
+    frame: 'Tokens · colors',
+    nodes: Object.entries(tokens.colors || {}).map(([key, val]) => ({
+      type: 'swatch',
+      name: `--dt-color-${camelToKebab(key)}`,
+      fill: val,
+    })),
+  };
+
+  const fonts = tokens.fonts || {};
+  const typographyFrame = {
+    frame: 'Tokens · typography',
+    nodes: [
+      fonts.display ? { type: 'text-specimen', name: 'display', fontFamily: fonts.display, sample: 'The quick brown fox' } : null,
+      fonts.body ? { type: 'text-specimen', name: 'body', fontFamily: fonts.body, sample: 'The quick brown fox jumps over the lazy dog.' } : null,
+      fonts.mono ? { type: 'text-specimen', name: 'mono', fontFamily: fonts.mono, sample: 'const answer = 42;' } : null,
+    ].filter(Boolean),
+  };
+
+  const surfaceFrames = surfaces.map(s => ({
+    frame: `Surface · ${s.id}`,
+    nodes: [{ type: 'surface-ref', name: s.id, currentTool: s.tool || 'hand', sourceUrl: s.sourceUrl || null }],
+  }));
+
+  return { frames: [colorFrame, typographyFrame, ...surfaceFrames] };
+}
+
+async function writePlanDir(tokens, surfaces) {
+  const planDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'otb-figma-plan-'));
+  const plan = buildPushPlan(tokens, surfaces);
+
+  await fsp.writeFile(path.join(planDir, 'figma-plan.json'), JSON.stringify(plan, null, 2), 'utf8');
+  await fsp.writeFile(path.join(planDir, 'tokens.json'), JSON.stringify(tokens, null, 2), 'utf8');
+  await fsp.writeFile(
+    path.join(planDir, 'surfaces.json'),
+    JSON.stringify({ surfaces: surfaces.map(s => ({ id: s.id, tool: s.tool || 'hand', sourceUrl: s.sourceUrl || null })) }, null, 2),
+    'utf8',
+  );
+
+  return planDir;
+}
+
+// ── snapshot translator (Figma MCP node snapshot → code, when Code Connect
+//    output isn't already provided) ──────────────────────────────────────────
+
+function rgbaToHex({ r, g, b }) {
+  const to255 = v => Math.round(Math.max(0, Math.min(1, v)) * 255);
+  const hex = n => to255(n).toString(16).padStart(2, '0');
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+function nodeFillColor(node) {
+  const fill = Array.isArray(node.fills) ? node.fills.find(f => f.type === 'SOLID') : null;
+  return fill ? rgbaToHex(fill.color) : null;
+}
+
+function componentNameFor(node) {
+  return (node.name || 'Component').replace(/[^a-zA-Z0-9]/g, '') || 'Component';
+}
+
+// Walks a Figma node snapshot and produces { files, warnings } — files are
+// only emitted for nodes whose content is genuinely code-representable
+// (frames, text, solid-fill rectangles). Image/vector content is skipped with
+// a warning, matching the asset-not-code rule (docs/design-contract.md §2.3).
+function snapshotToFiles(surfaceId, snapshot, colorTokenIndex) {
+  const files = [];
+  const warnings = [];
+  const topNodes = Array.isArray(snapshot.nodes) ? snapshot.nodes : (snapshot.node ? [snapshot.node] : []);
+
+  for (const node of topNodes) {
+    if (ASSET_ONLY_NODE_TYPES.has(node.type)) {
+      warnings.push(`node "${node.name}" (${node.type}) is not code-representable — export it as an asset under assets/ui/${surfaceId}/ instead`);
+      continue;
+    }
+    if (node.fills && node.fills.some(f => f.type === 'IMAGE')) {
+      warnings.push(`node "${node.name}" has an image fill — not code-representable, export as an asset instead`);
+      continue;
+    }
+
+    const componentName = componentNameFor(node);
+    const box = node.absoluteBoundingBox || {};
+    const fillHex = nodeFillColor(node);
+    const fillCss = fillHex
+      ? (colorTokenIndex.get(fillHex.toLowerCase()) || fillHex)
+      : null;
+    if (fillHex && fillCss === fillHex) {
+      warnings.push(`node "${node.name}": color ${fillHex} has no matching design token — emitted as a raw hex value`);
+    }
+
+    const cssLines = [`.${componentName} {`];
+    if (typeof box.width === 'number') cssLines.push(`  width: ${Math.round(box.width)}px;`);
+    if (typeof box.height === 'number') cssLines.push(`  height: ${Math.round(box.height)}px;`);
+    if (fillCss) cssLines.push(`  background: ${fillCss};`);
+    cssLines.push('}');
+
+    files.push({ path: `${componentName}.css`, content: cssLines.join('\n') + '\n' });
+
+    if (node.type === 'TEXT' && typeof node.characters === 'string') {
+      files.push({
+        path: `${componentName}.js`,
+        content: `module.exports.${componentName} = () => ${JSON.stringify(node.characters)};\n`,
+      });
+    } else if (Array.isArray(node.children) && node.children.length) {
+      const childNames = node.children.map(c => c.name).filter(Boolean);
+      files.push({
+        path: `${componentName}.js`,
+        content: `// generated from Figma node "${node.name}" (${node.type})\nmodule.exports.${componentName} = { children: ${JSON.stringify(childNames)} };\n`,
+      });
+    }
+  }
+
+  return { files, warnings };
+}
+
+// ── path-escape guard ─────────────────────────────────────────────────────────
+
+function assertSafePath(relPath, repoRoot, surfaceId) {
+  const uiBase = path.resolve(repoRoot, 'src', 'ui', surfaceId);
+  const assetBase = path.resolve(repoRoot, 'assets', 'ui', surfaceId);
+  const resolved = path.resolve(uiBase, relPath);
+  const inUi = resolved.startsWith(uiBase + path.sep) || resolved === uiBase;
+  const inAsset = resolved.startsWith(assetBase + path.sep) || resolved === assetBase;
+  if (!inUi && !inAsset) {
+    throw new Error(
+      `path-escape: "${relPath}" would write outside src/ui/${surfaceId}/ or assets/ui/${surfaceId}/`,
+    );
+  }
+  return resolved;
+}
+
+// ── exported adapter ──────────────────────────────────────────────────────────
+
+module.exports = {
+  id: ID,
+
+  /**
+   * repo → Figma.
+   * Builds a push plan (frames to create: color swatches, typography
+   * specimens, one reference frame per surface) in a temp directory.
+   * Returns { surfaceIds, summary }. The figma-design-sync skill executes
+   * the plan against the live Figma MCP tool.
+   */
+  async import({ repoRoot, tokens, surfaces } = {}) {
+    if (!repoRoot) throw new Error('figma import: repoRoot is required');
+    const resolvedTokens = tokens || resolveTokens(repoRoot);
+    const sources = readDesignSources(repoRoot);
+    const surfaceList = surfaces || scanSurfaces(repoRoot, sources);
+    const planDir = await writePlanDir(resolvedTokens, surfaceList);
+
+    return {
+      planPath: planDir,
+      surfaceIds: surfaceList.map(s => s.id),
+      summary: `plan → ${planDir} · ${surfaceList.length} surface(s) · frames: colors, typography, ${surfaceList.length} surface ref(s)`,
+    };
+  },
+
+  /**
+   * Figma → repo.
+   * toolOutput is one of:
+   *   { files: [{ path, content }] }         — Code Connect output (ready code)
+   *   { snapshot: { nodes: [...] } }          — raw Figma MCP node snapshot
+   * Writes files to src/ui/<surfaceId>/ and updates config/design-sources.json.
+   * Returns { filePaths, diff, commitMessage, designSourcesUpdated, warnings }.
+   */
+  async export({ repoRoot, surfaceId, toolOutput, taskId } = {}) {
+    if (!repoRoot) throw new Error('figma export: repoRoot is required');
+    if (!surfaceId) throw new Error('figma export: surfaceId is required');
+    if (!toolOutput || (!Array.isArray(toolOutput.files) && !toolOutput.snapshot)) {
+      throw new Error('figma export: toolOutput.files[] or toolOutput.snapshot is required');
+    }
+
+    const surfaceDir = path.resolve(repoRoot, 'src', 'ui', surfaceId);
+    await fsp.mkdir(surfaceDir, { recursive: true });
+
+    let incomingFiles = toolOutput.files;
+    let warnings = [];
+    if (!incomingFiles) {
+      const tokens = resolveTokens(repoRoot);
+      const translated = snapshotToFiles(surfaceId, toolOutput.snapshot, buildColorTokenIndex(tokens));
+      incomingFiles = translated.files;
+      warnings = translated.warnings;
+    }
+
+    const written = [];
+    for (const { path: relPath, content } of incomingFiles) {
+      if (!relPath || typeof content !== 'string') {
+        warnings.push(`skipped malformed file entry: ${JSON.stringify({ path: relPath })}`);
+        continue;
+      }
+      const dest = assertSafePath(relPath, repoRoot, surfaceId);
+      await fsp.mkdir(path.dirname(dest), { recursive: true });
+      // idempotent: skip if content is identical
+      const existing = await fsp.readFile(dest, 'utf8').catch(() => null);
+      if (existing === content) continue;
+      await fsp.writeFile(dest, content, 'utf8');
+      written.push(path.relative(repoRoot, dest));
+    }
+
+    // Update config/design-sources.json
+    const sourcesPath = path.join(repoRoot, 'config', 'design-sources.json');
+    const sources = readDesignSources(repoRoot);
+    sources.surfaces = sources.surfaces || {};
+    sources.surfaces[surfaceId] = {
+      ...(sources.surfaces[surfaceId] || {}),
+      tool: ID,
+      lastSyncedAt: new Date().toISOString(),
+      ...(taskId ? { notes: `GDS task ${taskId}` } : {}),
+    };
+    await fsp.writeFile(sourcesPath, JSON.stringify(sources, null, 2) + '\n', 'utf8');
+
+    return {
+      filePaths: written,
+      diff: '',
+      commitMessage: `ui(${surfaceId}): Figma export${taskId ? ` (task ${taskId})` : ''}`,
+      designSourcesUpdated: true,
+      warnings,
+    };
+  },
+};