mobile-ai-agents 1.0.37 → 1.0.38

package/AGENTS.md

@@ -230,3 +230,9 @@ Short version:
 ## Questions / Discussion
 
 Open a GitHub Discussion or Issue. PRs are always welcome.
+
+## Figma Design Handoff
+
+Use `skills/cross-platform/figma-mcp-setup.md` for connection setup, `skills/cross-platform/figma-spec-harvest.md` for source-traced specs, and `skills/cross-platform/figma-to-implementation.md` for native integration. Follow `workflows/figma-to-code.md` for the full pipeline. Setup examples are in `docs/figma-mcp.md`. Preserve the existing platform and never claim live design fidelity without captured evidence.
+
+Portable Figma helpers: `npx mobile-ai-agents figma tools init`. Read `tools/figma-spec/README.md`, run fresh crosschecks and strict source validation, then verify native implementation evidence separately.

package/CLAUDE.md

@@ -234,3 +234,7 @@ See `CONTRIBUTING.md` for the full guide.
 ## Release Process
 
 For npm releases, follow `docs/release-process.md`. Do not run `npm publish` manually. Update `package.json`, commit, create a local `vX.Y.Z` tag, push `main`, then push the tag so GitHub Actions publishes npm.
+
+## Figma specs and implementation
+
+Use `/figma-mcp-setup` to connect official Figma MCP, `/figma-spec-harvest` to extract source-traced specs, and `/figma-to-implementation` to build in the existing native platform. FIGMA handles both specs and implementation modes; `/figma-to-code` is the complete workflow. Install portable helpers with `npx mobile-ai-agents figma tools init`, then follow `tools/figma-spec/README.md`. Run fresh crosschecks and strict source validation; verify native builds, behavior and runtime screenshots separately. See `docs/figma-mcp.md`.

package/README.md

@@ -2,7 +2,7 @@
 
 **The complete AI dev team for mobile engineers.**
 
-19 personality-driven agents · 53 composable skills · 16 end-to-end workflows
+19 personality-driven agents · 56 composable skills · 17 end-to-end workflows
 Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Unreal
 
 [![npm](https://img.shields.io/npm/v/mobile-ai-agents?color=CB3837&label=npm)](https://www.npmjs.com/package/mobile-ai-agents)
@@ -217,11 +217,11 @@ Not sure where to begin? Pick your situation:
 |---|---|---|
 | Platform knowledge | Generic | Android · iOS · Flutter · React Native · Unity · Unreal |
 | Agent personalities | None | 19 named specialists with opinions |
-| Real workflows | No | 16 end-to-end processes |
+| Real workflows | No | 17 end-to-end processes |
 | Real examples | Toy pseudocode | Production code input/output pairs |
 | Installable | Copy-paste | `npx mobile-ai-agents install` |
 | Severity levels | None | CRITICAL · WARNING · INFO |
-| Slash commands | No | 53 composable skills |
+| Slash commands | No | 56 composable skills |
 
 ---
 
@@ -308,6 +308,9 @@ Not sure where to begin? Pick your situation:
 ### Cross-Platform
 | Skill | What It Does |
 |---|---|
+| `/figma-mcp-setup` | Connect official Figma MCP and verify frame access |
+| `/figma-spec-harvest` | Figma → traceable requirements, tokens, component specs and references |
+| `/figma-to-implementation` | Design contract → integrated UI in your existing platform |
 | `/grill-mobile` | 20 questions before any mobile code is written |
 | `/mobile-app-design` | Lovable/Stitch-style mobile UI generation, redesigns, and full app reskins |
 | `/crash-triage` | Paste stacktrace → root cause → fix |
@@ -330,13 +333,14 @@ Not sure where to begin? Pick your situation:
 
 ## Workflows
 
-16 end-to-end processes that chain agents and skills together.
+17 end-to-end processes that chain agents and skills together.
 
 | Workflow | What It Covers |
 |---|---|
 | `feature-ship` | Ticket → /grill-mobile → /feature-slice → implement → review → test → PR |
 | `crash-to-fix` | Crash alert → CRASHER → fix → regression test → deploy |
 | `app-launch` | Release build → SENTINEL → PERF → LAUNCHPAD → SCRIBE → /release-prep → store |
+| `figma-to-code` | Figma MCP setup → spec harvest → native implementation → visual and behavior verification |
 | `new-screen` | Figma spec → FIGMA → implement → review → performance check |
 | `ci-setup` | PIPELINE → generate config → secrets → test → document |
 | `release-cycle` | Feature freeze → CRASHER → SENTINEL → SCRIBE → /release-prep → staged rollout |
@@ -703,3 +707,7 @@ If Mobile AI Agents saved you time, a star helps others find it.
 ---
 
 *Built for mobile engineers who ship real apps.*
+
+## Figma MCP: from design to implementation
+
+Start with the [Figma setup and usage guide](docs/figma-mcp.md). Install the toolkit, connect your assistant to Figma, then use `/figma-spec-harvest` for specs or `/figma-to-code` for the complete workflow. Works with Android, iOS, Flutter, React Native, KMP, Unity, Unreal, and other explicitly selected repository stacks. Build and screenshot verification require the corresponding local tools. Install portable harvest/crosscheck/image helpers in your project with `npx mobile-ai-agents figma tools init`; existing files are preserved.

package/agents/cross-platform/appforge/agent.md

@@ -90,6 +90,8 @@ Create `PRD.md` with product overview, target audience, personas, core features,
 
 Create a low-cost design plan using Pencil Project, Figma free plan, Penpot, Excalidraw, Canva free, or hand-drawn wireframes.
 
+When Figma is supplied, use `/figma-spec-harvest` before design planning. Carry source node IDs, AC IDs, open questions, token/component gaps and reference screenshots into DESIGN.md. Connect MCP with `/figma-mcp-setup` if needed; record disconnected reads as unverified. Preserve existing stage approval rules.
+
 Output includes screen list, wireframe descriptions, design system, colors, typography, component list, states, and screenshot plan.
 
 Before creating the design plan, confirm or infer the design direction:
@@ -114,7 +116,7 @@ Create:
 - `DEPENDENCIES.md`
 - `ROADMAP.md`
 
-Each task includes title, goal, dependencies, likely files, acceptance criteria, QA checklist, complexity, and implementation notes.
+Each task includes title, goal, dependencies, likely files, acceptance criteria, QA checklist, complexity, and implementation notes. For harvested Figma scope, include component spec paths, node/AC IDs and verification methods. Do not treat proposed criteria as approved or lose unresolved questions during task breakdown.
 
 ### Stage 5 — Implementation Loop
 
@@ -138,7 +140,7 @@ For every subtask:
 
 After each feature implementation, compare UI against design for layout, spacing, typography, colors, components, responsiveness, empty states, loading states, error states, and accessibility.
 
-Output match percentage, differences, fixes, and priority list.
+Output differences, fixes, priority and captured evidence. If reporting a numerical match, include method, threshold/tolerance and matched viewport/state/theme; an unmeasured percentage remains unverified.
 
 ### Stage 7 — Full QA
 

package/agents/cross-platform/figma/agent.md

@@ -1,23 +1,27 @@
 # FIGMA — Design-to-Code Translator
 
-**Platform:** Cross-Platform (Compose / SwiftUI / Flutter / React Native)
-**Personality:** Pixel-perfect or it didn't happen. Every 1dp matters.
+**Platform:** Cross-Platform (Android / iOS / Flutter / React Native / KMP / Unity / Unreal / other selected stacks)
+**Personality:** Precise about design evidence, honest about verification.
 **Category:** UI / Design Handoff
 
 ---
 
 ## Purpose
 
-Translates Figma design specifications into production-ready UI code for Android (Jetpack Compose), iOS (SwiftUI), Flutter, or React Native. Takes a design description, component spec, or Figma JSON and outputs complete, styled, accessible component code.
+Extracts source-traced Figma specifications and translates them into native UI in the target repository. Supports connected MCP reads and supplied descriptions/exports, with explicit coverage and verification limits.
 
 ---
 
 ## Input Format
 
 ```
-PLATFORM: <Android-Compose | iOS-SwiftUI | Flutter | React Native>
+MODE: <specs | implementation; default implementation>
+PLATFORM: <repository stack or explicit target>
+FIGMA_URL: <optional frame link including node-id>
+SPEC_PATH: <optional harvested contract folder>
+SCOPE: <optional page/node scope; default linked subtree>
 DESIGN_DESCRIPTION:
-<Describe the design in detail:>
+<Supply this when no accessible URL or harvested contract is available:>
 - Component name and purpose
 - Layout: dimensions, padding, spacing (in dp/pt)
 - Typography: font, weight, size, color (hex or design token)
@@ -35,12 +39,29 @@ EXISTING_COMPONENTS: <optional: list reusable components already in your codebas
 
 ## Output Format
 
+For `MODE: specs` return this schema (use zero counts and explicit unverified checks when disconnected):
+
+```text
+FIGMA SPECS
+===========
+Source: <URL or supplied input>
+Scope: <requested; inspected; skipped; unreadable>
+Contract: <folder or inline supplied spec>
+Counts: pages=<n>; components=<n>; criteria=<n>; references=<n>
+Verification: <crosscheck pass|fail|unverified; evidence>
+Questions: <blocking questions or none>
+Tasks: <node/component; AC IDs; target; reference>
+Verdict: <READY|PARTIAL|BLOCKED>
+```
+
+For `MODE: implementation` use the format below:
+
 ```
 FIGMA TRANSLATION
 =================
 Component: <name>
 Platform: <platform>
-Accessibility: <WCAG compliance level — A | AA | AAA>
+Accessibility: <target A | AA | AAA; verified or unverified>
 
 COMPONENT CODE
 --------------
@@ -64,11 +85,11 @@ ACCESSIBILITY CHECKLIST
 ☑/☐ Touch target ≥ 44×44pt / 48×48dp
 ☑/☐ Color contrast ≥ 4.5:1 (AA)
 ☑/☐ Focus order correct
-☑/☐ Screen reader tested (simulated)
+☑/☐ Screen reader tested (actual evidence or unverified)
 
 NOTES
 -----
-<Any deviations from spec or platform limitations>
+<Deviations, node/AC-to-file mapping, actual checks/evidence, open gaps; verdict VERIFIED|IMPLEMENTED_UNVERIFIED|BLOCKED>
 ```
 
 ---
@@ -76,42 +97,36 @@ NOTES
 ## System Prompt
 
 ```
-You are FIGMA — a UI engineer who has built design systems for apps with 10 million users.
-You believe that pixel-perfect implementation is not perfectionism — it's respect for the
-designer's work and the user's experience. You know every dp of the Compose spacing system,
-every SwiftUI modifier, every Flutter decoration, and you will not let a 4dp padding error
-ship to production.
-
-Translate the provided design description into production-ready component code:
-
-For Android (Jetpack Compose):
-- Use MaterialTheme tokens for colors and typography (not hardcoded hex values).
-- Use Modifier with correct semantics for accessibility (.semantics { contentDescription = ... }).
-- Touch targets: min 48×48dp (Modifier.sizeIn(minWidth = 48.dp, minHeight = 48.dp)).
-- Animations: use animate*AsState for state transitions, spring() for physics-based.
-- Spacing: use dp extensions, not raw pixels.
-
-For iOS (SwiftUI):
-- Use environment color scheme and dynamic type for accessibility.
-- Apply .accessibilityLabel(), .accessibilityHint(), .accessibilityAddTraits().
-- Touch targets: min 44×44pt (.frame(minWidth: 44, minHeight: 44)).
-- Use @Environment(\.colorScheme) for dark mode.
-- Animations: withAnimation { } + spring() easing for interactive elements.
-
-For Flutter:
-- Use ThemeData tokens, not hardcoded colors.
-- Add semanticsLabel to all visual-only widgets.
-- Minimum touch target: 48×48dp via SizedBox or GestureDetector with padding.
-- Use const where possible for rebuild optimization.
-
-For React Native:
-- Use StyleSheet.create for style definitions.
-- Add accessibilityLabel and accessibilityRole to interactive elements.
-- Touch targets: minHeight: 44, minWidth: 44 (iOS) / 48, 48 (Android).
-- Use Animated.Value or Reanimated 2 for interactions.
-
-Always implement ALL states described. Flag any design property that is not achievable on
-the target platform and suggest the closest native equivalent.
+You are FIGMA, a design handoff and native UI engineer. Detect the repository's
+framework, architecture, tokens, components and state management. Never switch
+platforms because MCP returns React/Tailwind code.
+
+Discover Figma tools and load vendor prerequisites. Read the linked subtree or
+explicit scope in bounded batches: variants, nested requirements/copy, variables
+and screenshots. Keep Figma read-only. Record unknown values and unreadable scope.
+Separate observed values, derived criteria and proposed behavior; retain source
+node IDs/text. Screenshots cannot establish hidden behavior or exact tokens.
+
+In specs mode follow figma-spec-harvest guidance when available. Save a contract,
+cross-check against fresh reads, and report coverage, questions and tasks using
+the SPECS format. Supplied descriptions remain supplied evidence, not live reads.
+
+In implementation mode follow figma-to-implementation guidance when available.
+Reuse native components and semantic tokens; trace nodes/criteria to changed files.
+Preserve API contracts and resolve blockers before dependent edits. Translate Auto
+Layout into responsive native constraints and logical units. Preserve safe areas,
+text scaling, keyboard/focus behavior, accessibility, variants and actions.
+Android/iOS use existing Compose/XML or SwiftUI/UIKit. Flutter requires bounded
+flex/scroll/Stack layouts. React Native preserves navigation and virtualization.
+KMP respects shared/native ownership. Unity/Unreal preserve UI systems, anchors,
+DPI scaling and controller focus. Other targets follow their actual stack.
+Record unavailable fonts/assets and necessary deviations without silent substitution.
+
+Run relevant checks and compare captured runtime UI with design references at
+matched viewport, theme and state. Report commands, actual evidence and gaps.
+Never claim build, contrast, visual or screen-reader checks passed without evidence;
+unrun checks remain unverified. Accessibility is a target, not certification.
+Use the selected mode's exact output; code may be returned or linked to edited files.
 
 Output MUST follow the exact format specified. Do not add extra sections or omit any section.
 ```
@@ -228,14 +243,16 @@ ACCESSIBILITY CHECKLIST
 ☑ Touch target ≥ 48×48dp (height is 56dp, fills width)
 ☑ Color contrast ≥ 4.5:1 (white on #1A73E8 = 4.62:1 — passes AA)
 ☑ Focus order correct (default focus traversal)
-☑ Screen reader: button role provided by Button composable
+☐ Screen reader: unverified; native Button semantics alone do not prove runtime testing
 
 NOTES
 -----
 - The #1557B0 pressed state is delivered via Material3's built-in ripple indication on
   top of the base color. If you need the exact hex, override indication with a custom
   PressedColor in ButtonDefaults.
-- Animated color state transitions are included for smooth enabled/disabled switching.
+- Source is a supplied description; no live Figma node/AC mapping is available.
+- Build, visual match and runtime accessibility checks: unverified.
+- Verdict: IMPLEMENTED_UNVERIFIED.
 ```
 
 ---
@@ -244,4 +261,5 @@ NOTES
 
 - The more precise your design description (exact px/dp, font weights, hex values), the more accurate the output.
 - For design system integration, provide your existing token names — FIGMA will use them instead of raw values.
-- Tested with: Claude Sonnet 4.6.
+- Original component prompt tested with: Claude Sonnet 4.6. Revised MCP/specs workflow reviewed in Codex; live Figma and platform runtime checks not performed.
+- Full setup and pipeline: [Figma MCP guide](../../../docs/figma-mcp.md), [Figma to code workflow](../../../workflows/figma-to-code.md).

package/agents/cross-platform/mobile-harness/agent.md

@@ -299,7 +299,7 @@ For high or regulated risk, define rollback before implementation: trigger, owne
 - Use the platform reviewer after code changes: AXIOM, SWIFT, DART, or BRIDGE.
 - Run the configured build, lint/static-analysis, and test checks after every task. If commands are missing, discover safe platform defaults; mark unavailable checks explicitly instead of silently skipping them.
 - Run `/prd-verification` to verify behavior against `PRD.md`, `DESIGN.md`, `TASKS.md`, tests, screenshots, and QA reports.
-- Verify UI against the design artifact, not memory.
+- Verify UI against the design artifact, not memory. For Figma, use `/figma-spec-harvest` before implementation and carry contract paths/node/AC IDs into tasks and `/prd-verification`. Require complete scoped source checks and native runtime evidence separately; partial or missing component results remain pending.
 - Use Mobile MCP for device, emulator, or simulator evidence when available.
 - Capture screenshots, element lists, and failures in the report.
 - Record evidence by artifact ID in `evidence.json`; narrative statements alone are not proof.

package/cli/commands/figma.js

@@ -0,0 +1,42 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseOptions } = require('../lib/options');
+const SOURCE = path.resolve(__dirname, '../../tools/figma-spec');
+const FILES = ['README.md', 'requirements.txt', 'page_index.js', 'text_dump.js', 'node_dump.js',
+  'yaml_io.py', 'dump_to_yaml.py', 'crosscheck.py', 'compare_screens.py', 'validate_spec.py'];
+
+function initFigmaTools(cwd = process.cwd()) {
+  const realRoot = fs.realpathSync(cwd);
+  const destination = path.join(realRoot, 'tools/figma-spec');
+  // Check existing ancestors before creating anything; never follow redirected paths.
+  for (const relative of ['tools', 'tools/figma-spec']) {
+    const candidate = path.join(realRoot, relative);
+    if (fs.existsSync(candidate) || (() => { try { return fs.lstatSync(candidate).isSymbolicLink(); } catch { return false; } })()) {
+      if (fs.lstatSync(candidate).isSymbolicLink()) throw new Error('Tools directory must be inside the project without symlink redirects');
+      if (!fs.statSync(candidate).isDirectory()) throw new Error(`Expected directory: ${candidate}`);
+    }
+  }
+  fs.mkdirSync(destination, { recursive: true });
+  return FILES.map(name => {
+    const target = path.join(destination, name);
+    try {
+      fs.copyFileSync(path.join(SOURCE, name), target, fs.constants.COPYFILE_EXCL);
+      return { name, status: 'created' };
+    } catch (error) {
+      if (error.code === 'EEXIST') return { name, status: 'preserved' };
+      throw error;
+    }
+  });
+}
+
+function cmdFigma(args) {
+  const options = parseOptions(args);
+  if (options._.join(' ') !== 'tools init' || Object.keys(options).some(key => key !== '_')) {
+    throw new Error('Usage: mobile-ai-agents figma tools init (run in the target project)');
+  }
+  const results = initFigmaTools();
+  for (const { name, status } of results) console.log(`${status}: tools/figma-spec/${name}`);
+  console.log('Helpers installed. Connect/authenticate Figma separately; see tools/figma-spec/README.md.');
+}
+module.exports = { initFigmaTools, cmdFigma };

package/cli/commands/router.js

@@ -3,6 +3,7 @@
 const { cmdDoctor } = require('./doctor');
 const { cmdHarness } = require('./harness');
 const { cmdMcp } = require('./mcp');
+const { cmdFigma } = require('./figma');
 
 function createCommandRouter(legacyHandlers) {
   const routes = new Map([
@@ -14,6 +15,7 @@ function createCommandRouter(legacyHandlers) {
     ['doctor', cmdDoctor],
     ['harness', cmdHarness],
     ['mcp', cmdMcp],
+    ['figma', cmdFigma],
     ['help', legacyHandlers.help],
     ['--help', legacyHandlers.help],
     ['-h', legacyHandlers.help],

package/cli/index.js

@@ -65,6 +65,9 @@ const AGENTS = {
 };
 
 const SKILLS = {
+  'figma-mcp-setup': { file: 'skills/cross-platform/figma-mcp-setup.md', platform: 'cross' },
+  'figma-spec-harvest': { file: 'skills/cross-platform/figma-spec-harvest.md', platform: 'cross' },
+  'figma-to-implementation': { file: 'skills/cross-platform/figma-to-implementation.md', platform: 'cross' },
   // Android
   'anr-investigation':  { file: 'skills/android/anr-investigation.md',         platform: 'android' },
   'android-tdd':        { file: 'skills/android/android-tdd.md',               platform: 'android' },
@@ -128,6 +131,7 @@ const SKILLS = {
 };
 
 const WORKFLOWS = {
+  'figma-to-code': { file: 'workflows/figma-to-code.md' },
   'feature-ship':      { file: 'workflows/feature-ship.md'      },
   'release-cycle':     { file: 'workflows/release-cycle.md'     },
   'game-level':        { file: 'workflows/game-level.md'        },
@@ -194,8 +198,11 @@ const PLATFORM_AGENTS = {
   ],
 };
 
+const FIGMA_SKILLS = ['figma-mcp-setup', 'figma-spec-harvest', 'figma-to-implementation'];
+
 const PLATFORM_SKILLS = {
   android: [
+    ...FIGMA_SKILLS,
     'anr-investigation', 'android-tdd', 'code-review', 'compose-migration', 'compose-review',
     'kotlin-modernize', 'memory-leak-investigation', 'proguard-rules',
     // cross-platform bundled for android
@@ -205,6 +212,7 @@ const PLATFORM_SKILLS = {
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
   ios: [
+    ...FIGMA_SKILLS,
     'data-persistence', 'ios-tdd', 'networking', 'ios-performance',
     'swift-concurrency', 'swift-review', 'swiftui-review', 'swiftui-state',
     'unit-testing', 'xcode-warnings',
@@ -215,6 +223,7 @@ const PLATFORM_SKILLS = {
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
   flutter: [
+    ...FIGMA_SKILLS,
     'dart-modernize', 'flutter-review', 'flutter-tdd', 'widget-extract', 'widget-gen',
     // cross-platform bundled for flutter
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
@@ -223,6 +232,7 @@ const PLATFORM_SKILLS = {
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
   rn: [
+    ...FIGMA_SKILLS,
     'bridge-audit', 'expo-optimize', 'new-arch-migrate', 'rn-performance',
     'rn-review', 'rn-tdd',
     // cross-platform bundled for rn
@@ -232,11 +242,13 @@ const PLATFORM_SKILLS = {
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
   gaming: [
+    ...FIGMA_SKILLS,
     'blueprint-to-cpp', 'clean-code-audit', 'game-perf', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'prd-verification', 'security-audit', 'shader-gen',
     'unity-tdd', 'shader-review',
   ],
   cross: [
+    ...FIGMA_SKILLS,
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
     'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'perf-audit', 'prd-verification',
@@ -1208,6 +1220,7 @@ function cmdMemory(args) {
     console.log('    --files   Comma-separated related files');
     console.log('');
     console.log('  Examples:');
+  console.log(dim('    npx mobile-ai-agents figma tools init'));
     console.log(dim('    npx mobile-ai-agents memory init'));
     console.log(dim('    npx mobile-ai-agents memory capture --type decision --title "Use Room" --text "Persist habits locally with Room."'));
     console.log(dim('    git diff | npx mobile-ai-agents memory capture --type code-state --title "Current diff"'));
@@ -1424,6 +1437,7 @@ function cmdHelp() {
   console.log('    codex     All agents/skills/workflows → AGENTS.md');
   console.log('');
   console.log('  Examples:');
+  console.log(dim('    npx mobile-ai-agents figma tools init'));
   console.log(dim('    npx mobile-ai-agents start'));
   console.log(dim('    npx mobile-ai-agents start --platform flutter --idea "Habit tracker"'));
   console.log(dim('    npx mobile-ai-agents install'));

package/docs/figma-mcp.md

@@ -0,0 +1,131 @@
+# Figma MCP: setup, specs, and implementation
+
+Connect your coding assistant once, extract a design contract, then implement it in your project's own framework. Installing this toolkit installs prompts; it does **not** connect your Figma account or grant access to files.
+
+## 1. Connect Figma
+
+Use the official remote endpoint `https://mcp.figma.com/mcp` and complete Figma OAuth. No personal access token is needed for this route. Choose one setup below; preserve your existing MCP servers when adding configuration.
+
+### Codex
+
+In the Codex app, open Plugins, find Figma, install it, and complete authentication. Alternatively, with Codex CLI installed:
+
+```sh
+codex mcp add figma --url https://mcp.figma.com/mcp
+codex mcp login figma
+codex mcp list
+```
+
+### Claude Code
+
+```sh
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+Start a new session, run `/mcp`, select Figma, and authenticate. Use `--scope user` on the add command if you want it across projects.
+
+### Cursor
+
+Use `/add-plugin figma` in agent chat and authenticate, or follow Figma's manual Cursor installation guide linked below.
+
+### VS Code
+
+Run **MCP: Open Workspace Folder MCP Configuration** (or **MCP: Open User Configuration** for global setup). Merge this entry into the `servers` object:
+
+```json
+{
+  "servers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}
+```
+
+Start the server and complete authentication. This `servers` shape belongs to VS Code; do not paste it into clients expecting `mcpServers` or TOML.
+
+### Desktop alternative
+
+Open the file in Figma desktop, switch to Dev Mode, and enable the desktop MCP server in the inspect panel. Configure your supported client with Streamable HTTP URL `http://127.0.0.1:3845/mcp`. Keep Figma desktop running on the same machine as the MCP client. Desktop access depends on your seat/plan; consult current Figma documentation. Selection-based prompts are available here; use explicit frame links for reproducible handoffs.
+
+### Check the connection
+
+Copy a frame's link, including `node-id`, from a file your authenticated account can access. Ask:
+
+```text
+Use Figma MCP to read this frame's metadata and capture a reference screenshot.
+Report the file key, node ID, tools available, and any access failures.
+Do not change the Figma file or app code.
+URL: paste your frame link here
+```
+
+Success means a real node read and screenshot, not just a configured server. Tool names and capabilities vary by client and server. Load the Figma plugin's prerequisite skills when supplied, especially before `get_design_context` or `use_figma`. `use_figma` is optional; do not require it for basic design-to-code.
+
+## 2. Load the toolkit workflows
+
+```sh
+npx mobile-ai-agents install
+```
+
+Select your coding tool and platform. Install the portable extraction and verification helpers inside your target project:
+
+```sh
+npx mobile-ai-agents figma tools init
+```
+
+This preserves existing helper files. Read `tools/figma-spec/README.md` for Python prerequisites, raw-dump conversion, strict validation and screenshot comparison. In a checkout of this toolkit, you can also run `node /absolute/path/to/mobile-dev-skills/cli/index.js figma tools init` from the target project. Available starting with v1.0.38.
+
+ The three Figma skills are included for every platform. In tools supporting the installed slash commands:
+
+```text
+/figma-mcp-setup
+Help me connect Figma MCP and verify a read of my frame.
+
+/figma-spec-harvest
+URL: paste your frame link here
+FEATURE: checkout
+SCOPE: this frame and its variants
+Extract written requirements, exact available values, assets, and reference screenshots.
+
+/figma-to-implementation
+SPEC: docs/design-spec/checkout
+PLATFORM: detect from this repository
+Implement the verified scope and report requirement and screenshot evidence.
+```
+
+For tools without those commands, ask the assistant to read the corresponding `skills/cross-platform/figma-*.md` files. Use `/figma-to-code` for the combined workflow; `/figma` remains the component translation agent. There is no automatic Figma authentication during toolkit installation. The existing `mobile-ai-agents mcp setup` command configures **Mobile MCP device QA**, not Figma.
+
+## 3. Platform mapping
+
+| Target | Native implementation | Verification |
+|---|---|---|
+| Android | Compose or existing XML Views; semantic theme tokens | Gradle checks and emulator/device captures |
+| iOS | SwiftUI or existing UIKit; dynamic type and safe areas | Xcode build/tests and simulator/device captures |
+| Flutter | Existing Dart state management, bounded flex/scroll layout | Analyze, widget tests, golden/device captures |
+| React Native | Existing JS/TS components and navigation | Project checks and iOS/Android captures |
+| Kotlin Multiplatform | Existing shared UI or separate native UIs | Checks/captures per rendered target |
+| Unity | Existing UI Toolkit or uGUI; canvas scaling and anchors | Editor/player checks and target resolution captures |
+| Unreal | Existing UMG/Slate; anchors and DPI scaling | Compile/automation and viewport captures |
+| Web or other framework | User-selected repository stack | Native build/tests and browser/runtime captures |
+
+Figma pixels describe the reference canvas. Record how they map to logical dp/pt/framework units and responsive constraints; do not use device pixel ratio as a universal conversion. A generated React/Tailwind snippet is evidence about the design, not a reason to change the project's platform.
+
+## Troubleshooting
+
+- **No tools:** restart the client/session, confirm the server is enabled, and check client support. If both remote and desktop are configured, confirm which server is selected.
+- **Access denied:** authenticate the account that can open the design; a shared URL does not guarantee API access.
+- **Rate limit:** record incomplete scope, retry within server guidance, and resume from saved evidence. Do not report a partial harvest as complete.
+- **Missing exact values or written notes:** request the missing export/data or use read-only file inspection if available. Record unknowns; screenshots cannot prove exact token values or hidden behavior.
+- **Missing assets/fonts:** list the gap and resolve licensing/availability before substituting. Respect the client's media-download rules.
+- **Only web code returned:** specify the target framework, reuse repository components, and select the matching Code Connect label when available.
+
+## Sources and validation
+
+Setup checked against official documentation on 2026-10-08:
+- [Figma remote setup](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
+- [Figma desktop setup](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/)
+- [Figma tools and prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
+- [OpenAI Codex MCP configuration](https://developers.openai.com/codex/mcp/)
+
+Adapted from the seller-app's `figma-spec-harvest`, `figma-spec-harvester`, `figma-to-flutter`, `figma-to-implementation`, and `design-sync` workflows. No seller-app file IDs, business copy, or package paths are included. Live Figma extraction and per-platform compilation must be validated in users' connected projects; they were not run when authoring this guide.

package/docs/wiki.md

@@ -768,3 +768,7 @@ A: Yes. The repo is MIT licensed — free to use, modify, and incorporate into c
 ---
 
 *Last updated: v1.0.25 — August 2026*
+
+## Figma MCP and Design Handoff
+
+Connect your coding assistant using the [Figma MCP guide](figma-mcp.md). Use `/figma-spec-harvest` for source-traced specs and `/figma-to-implementation` to build in the existing platform. `/figma-to-code` chains setup, harvest, implementation and evidence checks. Install portable helpers with `npx mobile-ai-agents figma tools init`; this preserves existing files and does not authenticate Figma. APPFORGE, Mobile Harness and `/prd-verification` carry node/AC traceability into planning and verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-ai-agents",
-  "version": "1.0.37",
+  "version": "1.0.38",
   "description": "AI agents, skills, and Loop Engineering workflows for building, testing, auditing, and releasing mobile apps.",
   "bin": {
     "mobile-ai-agents": "cli/index.js",
@@ -19,7 +19,8 @@
     "mobile-karpathy.md",
     "skills/",
     "templates/",
-    "workflows/"
+    "workflows/",
+    "tools/figma-spec/"
   ],
   "keywords": [
     "mobile",