Bridge

#Overview

SXL Studio Bridge (@sxl-studio/bridge) is a Node.js process that connects your running SXL Studio plugin in Figma to external tools (Cursor, AI clients, scripts, CI). It exposes three interfaces on one port (BRIDGE_PORT, default 37830):

In practice, Bridge gives you one controlled integration point for:

• SXL token and composition workflows;
• real Figma screen/documentation generation through SXL agent skills;
• Dev Mode code generation parity;
• Git Sync file workflows;
• automation scenarios for teams and agents.

#When to use Bridge

Use Bridge when you need to run SXL Studio features remotely (from AI or scripts), not only click them in the plugin UI.

Typical use cases:

• export/apply token and style workflows;
• generate/apply composition JSON in bulk;
• build/update Figma screens from existing design-system components;
• render documentation, palettes, component docs, and scenario flows in Figma;
• run codegen outputs (designer-json, vue3, react, swiftui, uikit, kotlin, divkit);
• automate Git pull/push and token file updates;
• run usage, coverage, drift, component, and prop analytics at scale.

#Requirements

Before using Bridge:

1. Install and run @sxl-studio/bridge.
2. Open the Figma file and launch SXL Studio.
3. Enable Remote Connect inside the plugin.
4. Keep Bridge running while tools execute commands.

Git Sync Local Storage is the exception: it uses Bridge HTTP endpoints (/api/status, /api/workspace-blob) and does not require an active Remote Connect websocket session.

#Install and run

npm (recommended)

npm install -g @sxl-studio/bridge
sxl-bridge

Update to the latest compatible version (1.8.9 for SXL Studio Plugin 2.8.1):

npm install -g @sxl-studio/bridge@latest

After updating, restart Bridge: stop the old process and run sxl-bridge again — a running process keeps the previous version in memory. To check the version: Bridge prints it on startup, or run curl http://127.0.0.1:37830/api/workspace-path — 1.8.0+ returns JSON with a root field.

Monorepo source

cd Utils/bridge
npm install
npm run build
npm start

By default, Bridge runs on port 37830.

BRIDGE_PORT=38000 sxl-bridge

When you use a custom port, set the same value in the SXL Studio plugin Remote Connect overlay and in your MCP client URL.

#Secure access (recommended)

Set a shared secret to protect MCP, HTTP, and plugin Remote Connect WebSocket endpoints.

BRIDGE_AUTH_TOKEN is not issued by Figma, GitHub, GitLab, or SXL Studio. It is a local shared secret that you generate yourself and reuse in Bridge clients:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# or
openssl rand -hex 32

Start Bridge with the generated value:

BRIDGE_AUTH_TOKEN=<generated_secret> sxl-bridge

Then HTTP/MCP clients must send:

• Authorization: Bearer <generated_secret>

For live Remote Connect, enter the same value in the plugin Remote Connect overlay token field. If Git Sync Local Storage is enabled, also enter it in the plugin Sync form under Bridge Auth Token. Leave these fields empty when Bridge runs without BRIDGE_AUTH_TOKEN.

#Optional Figma REST companion

For read-only hosted context without an active plugin session, start Bridge with a Figma REST token:

FIGMA_TOKEN=figd_xxx npm start
# or OAuth/plan token with bearer auth
FIGMA_ACCESS_TOKEN=xxx FIGMA_AUTH_MODE=bearer npm start

Call figma_rest_diagnose first, or use GET /api/figma-rest-diagnostics?checks=whoami,fileMetadata&fileKey=..., to verify token/auth/scopes/permissions without exposing the token. Then use figma_rest_whoami, figma_rest_get_file_metadata, figma_rest_get_file_nodes, figma_rest_get_images, figma_rest_get_file_components, figma_rest_get_file_component_sets, figma_rest_get_file_styles, figma_rest_get_team_components, figma_rest_get_team_component_sets, figma_rest_get_team_styles, figma_rest_get_variables_local, figma_rest_get_variables_published, and figma_rest_search_design_system for known file/team REST reads. For Figma MCP-style library discovery, prefer Bridge get_libraries and search_design_system; they combine active-file enabled libraries with known REST file/team sources when configured. Bridge still does not create new files or handle FigJam/Slides asset upload. For Figma Design asset insertion, use Bridge upload_assets with an active Remote Connect session.

For libraries already enabled in the open Figma file, get_libraries and search_design_system are the primary agent-facing tools. Use search_enabled_library_assets for lower-level enabled-library search, inspect_enabled_libraries for raw enabled descriptors, and list_enabled_library_variables for variables in a specific enabled collection. Figma Plugin API cannot enable libraries from code; Bridge reports that limitation in the compatibility tool responses.

For screenshots or rendered node images, use get_screenshot. mode: "plugin-svg" returns inline SVG from active-file nodes or current selection through Remote Connect. mode: "rest-image" returns Figma-hosted PNG/JPG/SVG/PDF URLs for known fileKey/url + nodeIds using the REST Images endpoint.

For metadata, use get_metadata. mode: "plugin" returns active-file selection/page structure or node tree metadata through Remote Connect. mode: "rest" returns hosted file metadata or node metadata for known fileKey/url and optional nodeIds.

For active-file design context, use get_design_context. It bundles SXL codegen/composition JSON, sparse metadata, native variable/style definitions, optional SVG screenshot, and optional local Code Connect suggestions for the current selection or provided node ids. This mirrors the official MCP get_design_context intent as a structured starting point for the agent; it does not claim to be final production code.

For Code Connect template/binding context, use get_context_for_code_connect. It bundles SXL registry/settings, selection status, existing bindings, SXL codegen/composition context, component discovery with props, and local source-file suggestions. It covers the active-file/local-codebase side of the official MCP get_context_for_code_connect workflow; hosted remote-only context remains official Figma MCP companion scope.

For .figma.ts Code Connect template generation, use generate_code_connect_template. It accepts a full SXL CodeConnectBinding or local targets/component names, returns dry-run content/path by default, and writes only when writeFile: true is explicitly passed. Keep includePropertyAttrs off unless you have verified that Figma property names match the code component props.

For variable/style definitions, use get_variable_defs. mode: "selection" is the official-MCP-style route for variables/styles used in the current Figma Design selection; it reads native boundVariables, text segment bindings, style ids, and resolved variable/style definitions through Remote Connect, then adds SXL applied-token metadata as compatibility context. mode: "local" reads active-file local variables/styles; mode: "enabled-libraries" reads variables from libraries already enabled in the open file; mode: "rest" reads known-file REST variable endpoints.

#Font preflight for migration workflows

Before running migration, rebind, detach, or repair workflows that can mutate text layers, use migration_font_preflight.

Figma Plugin API requires the plugin to load the exact font used by a text node before changing that text node. A font can be visible in the Figma UI and still be unavailable to figma.loadFontAsync() for the current plugin runtime. Bridge therefore exposes a read-only preflight that scans text nodes, groups exact { family, style } pairs, attempts to load them, and reports which text nodes would be blocked.

Example payload:

{
  "scope": "selection",
  "sampleLimit": 20
}

Supported scopes are selection, currentPage, allPages, and node (nodeId is required for node).

The response includes:

• availableFontsCount
• requiredFonts
• missingFamilies
• loadFailures
• textNodesBlocked
• sampleNodeIds
• affectedPages
• requiredAction

If an exact font is not loadable, SXL Studio does not substitute a similar family automatically. For example, SF Pro Display Regular is not replaced with SF Pro Regular unless a future workflow provides an explicit user-approved mapping. The safe action is to enable or upload the exact shared font for the file/user, reload the Figma file, restart SXL Studio, and rerun the preflight.

After the font preflight passes, agents can use migration commands through the SXL Studio plugin runtime:

• migration_text_variable_bindings — typography variables on text ranges (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, paragraph fields).
• migration_text_fill_bindings — text fill color variables on text ranges.

Start with dryRun: true, review affectedTextNodes, affectedRanges or affectedSegments, rebindCount, detachCount, skippedCount, leftoverCount, errors, leftovers, and samples, then repeat with dryRun: false only for the approved mappings. Apply results are post-verified: a command is not successful while old aliases remain. Text typography migration also returns rangeResults with before/after binding snapshots. Text fill migration returns partial, changed, failed, and skipped so agents can detect interrupted instance-sublayer/table-cell runs and resume safely. For large files, use maxTextNodes or maxNodesPerChunk and continue while continueCursor is present.

Example dry-run:

{
  "scope": "page",
  "dryRun": true,
  "mappings": [
    {
      "kind": "variable",
      "fromId": "VariableID:old",
      "fromName": "Projects/ff/label",
      "toId": "VariableID:new",
      "toName": "Projects/ff/label"
    }
  ],
  "sampleLimit": 20
}

The command changes variable bindings only. It does not change text characters, font names, raw typography values, or create missing variables. To detach a legacy binding to raw text formatting, use toId: "__SXL_GHOST_DETACH_RAW__" deliberately and only after a dry-run.

For files migrated between variable collections, use migration_explicit_modes_audit to find page-level explicit mode references pointing to missing collections and to list remaining live collection refs. If cleanup is needed, run migration_clear_orphan_explicit_modes with dryRun: true first. The cleanup uses live collection objects where Figma exposes them. If Figma rejects clearing a missing collection id, Bridge returns unsupportedByFigmaApi, manualFallbackRequired, manualSteps, and unsupportedMissingCollectionRefs instead of reporting a false success. Rerun the audit after manual cleanup and continue only when missingCollectionRefs is 0.

#Connect an AI client (MCP)

Any MCP-capable AI client installed on the same computer as Bridge can call Bridge tools to read and control the open Figma file — while Bridge is running and Remote Connect is enabled in the plugin. The only thing each client needs is the Bridge MCP endpoint: http://127.0.0.1:37830/mcp.

Cursor — .cursor/mcp.json:

{ "mcpServers": { "sxl-studio": { "url": "http://127.0.0.1:37830/mcp" } } }

Claude Desktop — claude_desktop_config.json (bridge the HTTP endpoint with mcp-remote):

{ "mcpServers": { "sxl-studio": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:37830/mcp"] } } }

Codex CLI — ~/.codex/config.toml:

[mcp_servers.sxl-studio]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:37830/mcp"]

If BRIDGE_AUTH_TOKEN is set, add the Authorization: Bearer <token> header (URL clients) or pass --header to mcp-remote, and enter the same token in the plugin Remote Connect overlay.

After saving the config: restart the client's MCP session, confirm Bridge is running, and confirm Remote Connect is enabled in the plugin.

#Verify connection

Quick status check:

curl http://127.0.0.1:37830/api/status

The response includes connection/session fields plus runtime.health (ready, busy, degraded, or disconnected), actionable runtime.issues, the sanitized queue snapshot, and telemetry counters/last-failure metadata without payload values.

Tool catalog check:

curl http://127.0.0.1:37830/api/tools

For MCP clients, use list_tools to get the live command catalog.

#AI agent operating contract

If you give this page to an AI agent, the agent should treat Bridge as a controlled SXL Studio operating layer, not as a generic script runner. The safe default flow is:

1. Check live state with get_bridge_runtime_summary or GET /api/runtime-summary.
2. If the task needs the open Figma file and the summary says Remote Connect is missing, stop and ask the operator to open SXL Studio in Figma and enable Remote Connect. Do not fake a live result.
3. For natural-language requests, call route_intent, then plan_workflow, then preview_workflow before write tools.
4. For design creation, inspect the design system first with inspect_design_system; then run validate_screen_spec; then run build_screen or update_screen with dryRun: true; only then apply.
5. For token export, run preview_export_variables before export_variables. Destructive export options require explicit confirmDestructive: true; delete/reset-class Remote Connect commands may also require the user to enable Allow destructive commands in the plugin overlay for the current session.
6. For documentation in Figma, use apply_doc_spec, build_component_doc, build_doc_flow, bind_variable_palette, or build_scenario_from_md. Do not hand-write composition JSON or ad hoc canvas scripts when a Bridge thick command exists.
7. For large scans, request summaries first and use paginated detail tools only for the required subset.
8. After writes, re-run the relevant read/audit command and report what changed, what was skipped, and whether visual review is still needed.

Agent-critical boundaries:

• Bridge targets Figma Design + SXL Studio active-file workflows.
• Official Figma MCP remains the companion for creating new files, FigJam/Slides-specific editing, generated diagrams, and hosted-only Code Connect context.
• Bridge can read known hosted Figma files through REST when FIGMA_TOKEN / FIGMA_ACCESS_TOKEN is configured, but REST reads do not replace Remote Connect for active canvas writes.
• Git Sync Local Storage and /api/workspace-blob are part of the public Bridge contract. They must keep working without an active Remote Connect websocket session; if BRIDGE_AUTH_TOKEN is enabled, they require the same bearer token as the rest of /api/*.

Useful official context: Figma documents the MCP server as an agent interface for design context and write-to-canvas workflows, and lists several remote-only tools such as create_new_file, generate_diagram, use_figma, get_libraries, search_design_system, and upload_assets. Figma also publishes skills such as figma-use, figma-code-connect, figma-generate-library, and figma-generate-design. Bridge mirrors the parts it can honestly support through the local plugin and SXL workflows, and exposes the rest as companion scope rather than pretending plugin APIs can do it.

Official references:

• Figma MCP server documentation
• Figma MCP tools and prompts
• Figma skills for MCP

Intent routing quick map

Raw HTTP command pattern

MCP clients should prefer MCP tools. HTTP clients can use /api/command directly:

curl -s -X POST http://127.0.0.1:37830/api/command \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: export-preview-001' \
  -d '{
    "commandType": "preview_export_variables",
    "payload": {
      "settings": {
        "dryRun": true
      }
    }
  }'

When BRIDGE_AUTH_TOKEN is enabled, add Authorization: Bearer <token>. Write commands return a normalized envelope with command id, status, result, and typed errors where possible. Use Idempotency-Key for retries from scripts and agents.

For a compact start-here guide, call get_operator_runbook, attach sxl://agent/operator-runbook, or use the sxl-operator prompt. HTTP clients can use GET /api/operator-runbook. It maps common RU/EN requests to the right SXL workflow, required resources, preferred tools, dry-run gates, done criteria, and official Figma MCP companion handoff.

For broad natural-language requests, call route_intent first. It returns ranked SXL recipes, preferred tools, dryRunFirst, and schema resources such as sxl://agent/schemas/design-dsl-v1, sxl://agent/schemas/doc-spec-v2, sxl://agent/schemas/code-connect-context-v1, or sxl://agent/schemas/code-connect-template-v1.

For multi-step work, call plan_workflow, then validate the proposed tool sequence with preview_workflow before executing write tools. The preview reports unknown tools, missing or misordered status checks, design-system discovery, dry-run gates, preflight tools declared by preferredAfter, and guard steps that appear after the write they were meant to protect.

For token export, run preview_export_variables before export_variables. For Figma Design library discovery/search, use Bridge get_libraries / search_design_system. For official Figma MCP companion scope such as new-file creation, FigJam/Slides, diagrams, or hosted Code Connect repository context, the planner adds an explicit handoff step; avoid Bridge write tools unless the user narrows the task back to SXL/active-file Figma Design work.

For larger workflows, call get_capability_matrix first. HTTP clients can use the equivalent endpoint:

curl http://127.0.0.1:37830/api/capabilities

It returns the same catalogue with execution metadata (plugin, bridge-orchestration, bridge-local), exact pluginCommandTypes, aliases, natural-language intents, dryRunSupported, returnsLargeData, preferred order hints, and Bridge timeouts.

To compare Bridge with official Figma MCP tools, use:

curl http://127.0.0.1:37830/api/figma-mcp-parity

MCP clients can call get_figma_mcp_parity or attach sxl://agent/figma-mcp-parity. The matrix marks each official Figma MCP tool as covered by Bridge/SXL, companion-required, future scope, or unsupported by the plugin API. Bridge plugin tools cover enabled-library search and active-file metadata in the open file. Bridge REST tools cover authenticated whoami and known file/team library reads when a Figma REST token is configured. get_libraries / search_design_system provide Figma MCP-compatible Figma Design library discovery/search over active-file and known REST sources. get_design_context covers active-file SXL-native design context. get_metadata covers hosted file/node metadata. get_variable_defs covers selection/local/enabled-library/known-file variable definitions. get_screenshot covers active-file SVG and known-node REST image rendering. Bridge upload_assets covers Figma Design image insertion from URL/base64 with dry-run and a 10MB-per-asset limit. get_context_for_code_connect covers active-file Code Connect context, generate_code_connect_template generates dry-run-first local .figma.ts templates, and get_code_connect_suggestions covers local candidate discovery before codeconnect_save_binding. Remote-only hosted capabilities such as creating a new file, hosted Code Connect repository context, and FigJam/Slides asset upload still require official Figma MCP as a companion.

For skill-level routing, use:

curl http://127.0.0.1:37830/api/figma-mcp-skills-parity

MCP clients can call get_figma_mcp_skills_parity or attach sxl://agent/figma-mcp-skills-parity. It maps the current official Figma MCP skills figma-use, figma-use-figjam, figma-use-slides, figma-swiftui, figma-code-connect, figma-create-new-file, figma-generate-diagram, figma-generate-library, and figma-generate-design to SXL recipes/resources/tools, companion scope, or agent-side codebase work.

route_intent and plan_workflow understand current official skills and legacy/client aliases. FigJam, Slides, new-file, and diagram skills route to the official Figma MCP companion. figma-swiftui uses Bridge for active-file design context and Code Connect hints, then agent-side Swift edits. Older aliases remain supported: figma-implement-design routes to sxl-implement-design, figma-create-design-system-rules routes to sxl-generate-library, and figma-code-connect-components routes to sxl-code-connect.

For performance-sensitive workflows, use the Bridge performance profile:

curl http://127.0.0.1:37830/api/performance-profile

MCP clients can call get_performance_profile or attach sxl://agent/performance-profile. It marks local, summary, paginated-detail, write-preview, and long-running commands, exposes target budgets, and highlights large-data, dry-run-first, and destructive-write risks. Use it before broad scans, screen generation, bulk export/apply, or slow workflow debugging.

For operational preflight, call get_operator_runbook as the start-here workflow chooser, then get_bridge_runtime_summary before live work. HTTP clients can use:

curl http://127.0.0.1:37830/api/operator-runbook
curl http://127.0.0.1:37830/api/runtime-summary

The runbook chooses the workflow, tools, dry-run gates, and companion handoff. The runtime summary reports plugin connection, current/queued commands, recent event/audit failures, auth state, MCP URL, and recommendations so an agent can decide whether to proceed, wait, inspect logs, or ask the operator to open Remote Connect.

For release/readiness evaluation, call get_ultimate_readiness or:

curl http://127.0.0.1:37830/api/ultimate-readiness

Local operators can run the same audit without a running Bridge server:

cd Utils/bridge
npm run readiness
sxl-bridge-readiness --json

It maps the Ultimate Bridge plan to requirement rows across contract surface, SXL skills, Design DSL, analytics, database, variables/styles, compositions, docs, Code Connect, production safety, official Figma MCP tool parity, and official Figma MCP skill parity. The contract row includes Remote Connect whitelist and handler-path evidence when the plugin source is available. Companion/future Figma MCP scope remains explicit. Add --runtime to report running Bridge HTTP/MCP proof next to local readiness; add --require-live when release sign-off must fail unless an active Remote Connect plugin session passes live validation.

Tools marked returnsLargeData support bridgeResponseMode. Use summary first to get counts, preview, and pagination hints; use auto for the default budget-aware behavior; use full only when exact payloads are required. Bridge strips these control fields before forwarding the command to the plugin, while raw HTTP /api/command remains an exact-result fallback.

Bridge also has a destructive confirmation gate. Commands such as delete_*, remove_*, reset_*, git_hard_pull, detach_instance, flatten_nodes, boolean_operation, and export_variables with deleteOrphans or allowDestructiveReorder require top-level confirmDestructive: true. Run dry-run/preview first when available; use preview_export_variables before token export to inspect the exact settings payload, effective plugin defaults, risk flags, and required confirmation without touching Figma. Bridge removes confirmDestructive and destructiveReason before forwarding the payload to the plugin.

Plugin 2.6+ adds a second user-level gate for delete/reset-class Remote Connect commands. Commands like delete_*, batch_delete_variables, remove_variable_mode, reset_diff*, and git_hard_pull stay blocked until the user enables Allow destructive commands in the plugin Remote Connect overlay. confirmDestructive does not bypass that plugin gate. If a command fails with blocked by session policy, enable the overlay toggle and retry.

Bridge persists a sanitized command audit log to disk. Use get_bridge_audit_log or:

curl http://127.0.0.1:37830/api/log?source=disk

The default root is the OS cache directory from env-paths under sxl-studio-bridge/audit; override it with SXL_BRIDGE_AUDIT_ROOT. Audit entries include ids, command type, status, timings, payload key names, and idempotency keys, but never payload values.

For release checks or new agent/client setup, run the Bridge contract audit:

curl http://127.0.0.1:37830/api/contract-audit

MCP clients can call get_contract_audit. It verifies required meta tools, recipe references, schema entrypoints, workflow gates, plugin command declarations, Remote Connect whitelist coverage and handler-path coverage when the plugin source is available, and timeouts. Treat status: "fail" as blocking.

For CLI checks, use the Bridge health gate:

# local contract gate; no running server required
npm run bridge:check

# local agent routing/planning/preview validation; no Figma session required
cd Utils/bridge
npm run workflow:agent

# local Ultimate Bridge requirement audit; no running server required
npm run readiness

# local readiness + running Bridge HTTP/MCP proof
npm run bridge:readiness:runtime
sxl-bridge-readiness --runtime

# strict Figma E2E proof; requires active Remote Connect
npm run bridge:readiness:live
sxl-bridge-readiness --runtime --require-live --suite all

# runtime HTTP + MCP smoke against a running Bridge
npm run health:runtime

# require a live Remote Connect plugin session
node dist/bridge-health-cli.js --runtime --require-plugin

# live workflow smoke through Remote Connect: status -> get_plugin_status -> find_components -> build_mockup dryRun
npm run workflow:smoke

# broader non-destructive live validation: baseline reads + Design DSL dryRun
npm run workflow:validate

# explicit write-path proof: create a tiny frame, verify rootNodeId, delete it
sxl-bridge-live --suite all --write-canary --cleanup

workflow:agent validates representative RU/EN requests through route_intent, plan_workflow, and preview_workflow. It catches stale routing, missing preflight dependencies, unsafe generated plans, and read-only intents that accidentally plan write tools. readiness prints the same Ultimate Bridge requirement audit locally without a running server. health:local includes the same agent workflow gate plus the Ultimate Bridge readiness audit. A healthy build reports PASS; WARN should be reviewed before release, while explicit companion/future scope is listed separately by readiness.

health:runtime checks /mcp initialize/session/tools-list/tools-call (get_libraries + search_design_system zero-config envelopes, get_operator_runbook, list_tools, validate_screen_spec, preview_export_variables, get_figma_mcp_skills_parity, and plan_workflow for Figma Design library discovery routing), resources-list/resources-read for runtime-summary + operator-runbook + figma-mcp-skills-parity, prompts-list/prompts-get for sxl-operator + sxl-generate-design, plus the REST runtime endpoints including /api/operator-runbook. It is status-aware for readiness and performance endpoints, so runtime fail blocks the gate and runtime warn is reported as a warning. It does not require an active plugin session unless --require-plugin is passed.

workflow:smoke requires Bridge to be running and the SXL Studio plugin Remote Connect session to be active. It is non-destructive by default; sxl-bridge-smoke --apply creates a small smoke frame only when you explicitly opt in and Figma reports writesAllowed=true. sxl-bridge-smoke --apply --cleanup deletes the rootNodeId returned by that same apply step, proving create/delete access without leaving the canary frame in the file.

workflow:validate also requires an active Remote Connect session. The default baseline suite verifies Bridge status, /mcp initialize/session/tools-list/tools-call (get_libraries + search_design_system zero-config envelopes, get_operator_runbook, list_tools, validate_screen_spec, preview_export_variables, get_figma_mcp_skills_parity, and plan_workflow for Figma Design library discovery routing), resources-list/resources-read for runtime-summary + operator-runbook + figma-mcp-skills-parity, prompts-list/prompts-get for sxl-operator + sxl-generate-design, ultimate readiness, performance profile, operator runbook, tool catalogue, token/config reads, variable/style reads, component discovery, and a Design DSL dry-run. Readiness/performance status is enforced: fail fails the suite and warn is surfaced as a warning. Run sxl-bridge validate --suite all to also validate Code Connect registry/settings/selection status, selection variable definitions, dry-run .figma.ts template generation, database list commands, database payload export plus import dry-run, variable/style spec dry-runs, dedupe dry-runs, variable/style coverage summary and paginated detail, variable/style coverage dry-run apply previews, unused variable/style scans, composition list plus bulk dry-run and drift audit, component usage summary/detail pagination, component prop usage summary/detail pagination, and Doc Builder build_doc_flow dry-run. Add --write-canary --cleanup only with explicit operator approval; it creates a tiny validation frame, verifies the returned rootNodeId, then deletes that same node.

Live queue diagnostics:

curl http://127.0.0.1:37830/api/queue

It returns current, queued, and immediate commands with ids, status, timings, and payloadKeys. Payload values are never exposed.

Command event timeline:

curl http://127.0.0.1:37830/api/events?limit=100
curl http://127.0.0.1:37830/api/events?commandId=<command-id>

It returns sanitized lifecycle/progress events (queued, started, completed/failed, timeout/cancel, and plugin progress events). Values are not exposed; only ids, status, timings, payloadKeys, and detailKeys.

Persisted audit after restart:

curl http://127.0.0.1:37830/api/log?source=disk&limit=50

#Core workflows

1) Tokens and styles workflows

Use Bridge to:

• export variables/styles;
• reapply token bindings;
• manage token files and token config in workspace;
• run cross-file sync actions.

preview_export_variables is the read-only preflight for export modes. It returns the exact export_variables payload Bridge will send, effective plugin defaults, risk flags, and whether destructive confirmation is required. export_variables follows plugin-safe defaults: it does not apply code syntax/scopes, force-update all entries, delete orphans, or run destructive reorder unless those options are explicitly passed.

The export result is the real Plugin result — counts, warnings, errors, and the partial-mode report are not replaced by a generic success. Missing mode cells complete in the same non-destructive run: existing Figma values stay unchanged, new destinations keep Figma-created values, and orphan cleanup/destructive reorder are disabled. Use get_export_report to read the latest manual, automatic, or Remote Connect result; before the first export it returns available: false.

Start with:

• list_token_files
• get_token_file_content
• save_token_file
• save_tokens_config
• preview_export_variables
• export_variables
• get_export_report

2) Composition workflows

Use Bridge to:

• export composition JSON from selection;
• generate/apply/preview compositions;
• audit composition drift;
• run bulk composition operations.

Start with:

• export_composition_json
• generate_composition
• apply_composition
• bulk_generate_compositions
• audit_composition_drift

Bridge uses the same optimized Composition Generate / Apply pipeline as the plugin UI. For large libraries, pass an explicit list to bulk_generate_compositions, keep Remote Connect open until the run finishes, and verify the result with audit_composition_drift.

For heavy Figma files or runs with dozens of compositions, prefer chunked bulk generation:

{
  "operation": "generate",
  "fileIds": ["button-primary-sm", "button-primary-md"],
  "chunkSize": 12,
  "pauseBetweenChunksMs": 300
}

chunkSize lets Bridge process the same bulk request in smaller resumable batches instead of pushing the whole canvas run through one long plugin command. A chunk size around 10-15 is a good starting point for large component libraries. Bridge returns chunk progress, the next cursor and a target hash, so an agent can continue safely if the operator needs to reopen Figma or Remote Connect.

3) Codegen workflows (Dev Mode parity)

Use get_codegen for the same family of outputs used in SXL Studio Dev Mode:

• designer-json
• vue3
• swiftui
• kotlin
• divkit (generic DivKit JSON card)

4) Design and documentation workflows

Bridge exposes SXL agent skill resources:

• sxl://agent/operator-runbook
• sxl://agent/recipes/sxl-use
• sxl://agent/recipes/sxl-implement-design
• sxl://agent/recipes/sxl-generate-design
• sxl://agent/recipes/sxl-generate-library
• sxl://agent/recipes/sxl-code-connect
• sxl://agent/recipes/sxl-audit
• sxl://agent/recipes/sxl-doc-builder
• sxl://agent/recipes/sxl-data-apply-mapping
• sxl://agent/recipes/sxl-data-apply-all
• sxl://agent/recipes/sxl-data-generate-instances
• sxl://agent/recipes/sxl-database-transfer
• sxl://agent/recipes/figma-mcp-companion
• sxl://agent/schemas/code-connect-context-v1
• sxl://agent/schemas/code-connect-template-v1
• sxl://agent/figma-mcp-parity
• sxl://agent/figma-mcp-skills-parity
• sxl://agent/performance-profile
• sxl://agent/runtime-summary
• sxl://agent/ultimate-readiness

MCP clients that support prompts can also use prompts/list / prompts/get for sxl-operator, sxl-router, sxl-use, sxl-implement-design, sxl-generate-design, sxl-generate-library, sxl-code-connect, sxl-audit, sxl-doc-builder, and figma-mcp-companion. Prompts return the same SXL skill intent as actionable instructions with preferred tools, resources, dry-run gates, and done criteria. Use figma-mcp-companion when route_intent identifies remote-only official Figma MCP scopes such as new-file creation, FigJam/Slides, or diagrams; use Bridge get_libraries / search_design_system for Figma Design library discovery.

Use inspect_design_system, validate_screen_spec, build_screen, and update_screen to build or update editable Figma screens from existing components. Use apply_doc_spec, build_component_doc, build_doc_flow, bind_variable_palette, and build_scenario_from_md for documentation in Figma. build_doc_flow accepts pages with nodeId or compositionFileId; composition pages are generated/applied through the existing composition pipeline and rendered into the flow as an instance or clone.

5) Variables and local styles CRUD

Bridge supports end-to-end operations for:

• variable collections, modes, values, scopes, code syntax;
• local paint/text/effect styles;
• style assignments and import-by-key;
• bulk import/dedupe/rebind/audit flows.

6) Audit, analytics, and coverage workflows

Bridge supports read-first audit scenarios:

• variable usage and coverage;
• style coverage and drift;
• unused variables/styles;
• component usage and component prop usage analytics;
• suggestion-based apply workflows (dry-run first).

Coverage audit recipes are read-only. When the user asks to fix findings, switch to apply_coverage_suggestions / apply_style_coverage_suggestions and run preview mode before committing.

7) Code Connect and database workflows

Bridge exposes Code Connect settings, registry, node UI status, active-file Code Connect context (get_context_for_code_connect), dry-run-first .figma.ts template generation (generate_code_connect_template), local source-file suggestions, and full binding save/read flows, including docs URLs, files, Storybook metadata, and component API status.

Database tools can list/get/save/delete datasets, assets, and mappings. Save/delete tools support dryRun preview before plugin state changes. export_database_payload creates a portable backup/transfer payload through existing CRUD reads; asset content is excluded unless includeAssetContent=true. import_database_payload defaults to dryRun, reports existing-ID conflicts, and requires confirmDestructive=true plus a reason before overwriting datasets, assets, or mappings. Mapping write tools (apply_mapping, apply_all_mappings, generate_instances) also support dryRun previews so agents can inspect mappings, target counts, and row estimates before writing. Apply/count/generate workflows accept explicit targetNodeIds as deterministic selection roots; without them Bridge falls back to the current selection or scope.

8) Git Sync workflows

Bridge can run Git-connected actions used by SXL Studio:

• git_pull
• git_hard_pull
• git_push

#Local Storage for large Git Sync projects

For medium/large datasets, enable Local Storage in Git Sync connection settings.

This keeps large synced data on disk via Bridge and improves stability for large workspaces. The plugin probes GET /api/status before Pull and then reads/writes workspace-scoped payloads through /api/workspace-blob.

If BRIDGE_AUTH_TOKEN is set, also fill Bridge Auth Token in the same Sync connection. Use the same generated secret that starts Bridge, not a Git provider token or a Figma REST token. Local Storage does not need a Remote Connect websocket session, but Bridge must be reachable on localhost.

Use SXL_BRIDGE_WORKSPACE_BLOB_ROOT when you need to move the blob directory to a custom path. If Pull stops with a Local Storage warning, verify Bridge is running on the same machine as Figma, check the port, and confirm the auth token matches.

User-facing details: Git integration

#Dev Mode behavior

In Figma Dev Mode:

• read and file workflows are available;
• direct canvas writes can be restricted by Figma context;
• token/config/git file workflows remain available when connection state is valid.

If a write action is blocked by mode, switch to Design Mode for that operation.

#Command categories (practical map)

Bridge command catalog is large and evolving. Use this map as a navigation layer and use list_tools for the exact current list.

#Recommended operating model

1. Start with read/audit calls.
2. Run dry-run where available.
3. Apply write actions after review.
4. Keep token and composition JSON in git.
5. Re-run audits after write operations.

#Troubleshooting

Bridge is running, but no commands execute

• Check Remote Connect in plugin is enabled.
• Check .cursor/mcp.json URL and port.
• If auth is enabled, check the MCP/HTTP Authorization header, the plugin Remote Connect overlay token, and the Sync connection Bridge Auth Token used by Local Storage.

Unauthorized / forbidden

• Token mismatch in Authorization header, Remote Connect overlay, or Sync connection Bridge Auth Token.
• Restart Bridge after changing env variables.

Commands visible, but canvas writes fail

• Current Figma context may be Dev Mode-restricted.
• Retry the same action in Design Mode.

Git operations fail

• Verify the Sync connection in plugin is valid.
• Verify provider token scopes and repository path settings.

#Version compatibility (quick rule)

Keep Bridge and plugin versions aligned by release notes. For the release documented on this page, use this exact pair:

An older Bridge can omit new tools; an older Plugin can reject a command that the newer Bridge exposes. reapply_compositions is not an advertised tool in this pair because it never performed an Apply. Use apply_composition for one composition or bulk_generate_compositions with operation apply for an explicit reviewed set.

Practical rule:

• update Bridge and SXL Studio plugin together in the same maintenance window;
• after update, run list_tools, get_performance_profile, workflow:smoke, and workflow:validate against a live Remote Connect session.

#Prompts for users

You do not call tools by hand — you describe the task in natural language and the AI client picks the right Bridge tools. Bridge also has a natural-language router (route_intent) that maps RU/EN requests to the correct recipe and tools. Ready-to-use prompts:

#Command reference (MCP tools)

Bridge exposes 250+ MCP tools grouped by category. Each is callable by any connected AI client (and most map to a single plugin Remote Connect command). Read-only and dryRun-first tools are safe to explore; write tools change the Figma file. Diagnostics (5)

Tokens (19)

Variables (25)

Variables — bulk / orchestration (5)

Styles (9)

Styles — bulk / orchestration (5)

Compositions (12)

Compositions — bulk (2)

Canvas & nodes (68)

Datasets, assets, mappings & Code Connect (36)

Audit & analytics (13)

Mockups & Design DSL (7)

Orchestration, docs & meta (24)

Figma REST companion (16)

Git Sync (3)

#Related sections

• Git integration
• Dev Mode overview
• Composition
• Export Variables & Styles