# https://github.com/CristinaFores/design-context-bridge Project Manual

Generated at: 2026-07-07 11:36:53 UTC

## Table of Contents

- [Overview and Getting Started](#page-overview)
- [System Architecture and Data Flow](#page-architecture)
- [MCP Tools and Capabilities](#page-tools)
- [Figma Plugin, Reliability, Security, and Operations](#page-operations)

<a id='page-overview'></a>

## Overview and Getting Started

### Related Pages

Related topics: [System Architecture and Data Flow](#page-architecture), [MCP Tools and Capabilities](#page-tools)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/CristinaFores/design-context-bridge/blob/main/README.md)
- [package.json](https://github.com/CristinaFores/design-context-bridge/blob/main/package.json)
- [src/index.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/index.ts)
- [docs/clients.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/clients.md)
- [docs/plugin-setup.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/plugin-setup.md)
- [docs/rest-api.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/rest-api.md)
</details>

# Overview and Getting Started

Design Context Bridge is an independent Model Context Protocol (MCP) server that supplies AI agents with real, structured Figma design context. It exposes two interchangeable transport modes — a Figma plugin for live selection-driven access and a REST API for any file reachable by URL plus a personal access token — so that the same MCP tool surface works whether or not the Figma desktop client is running. Source: [README.md:1-40]()

## Purpose and Scope

The server's role is to bridge the gap between design assets (colors, typography, spacing, components, frames) and code-generating or design-aware agents. Without it, an agent must rely on screenshots, hand-written specs, or the Figma UI to interpret a file; with it, the agent receives normalized, queryable values that can be reused across a tool chain. Source: [README.md:14-38]()

The scope deliberately excludes rendering, code generation, and asset export. It focuses on three concerns:

- **Context extraction** — reading nodes, styles, variables, and tokens from a Figma document.
- **Context navigation** — walking the document tree by frame, page, or selection.
- **Context delivery** — exposing the above as MCP tools consumable by any compatible client.

Source: [README.md:20-44]()

## Architecture and the Two Modes

The MCP server is implemented in TypeScript and packaged as an npm module. The entry point composes the tool registry and wires up the transport, which is selected at startup based on configuration. Source: [src/index.ts:1-80]()

```
                  ┌──────────────────────────┐
                  │   MCP-compatible client  │
                  │  (Claude, Cursor, etc.)  │
                  └────────────┬─────────────┘
                               │ MCP protocol
                  ┌────────────▼─────────────┐
                  │  design-context-bridge   │
                  │        (MCP server)      │
                  └─────┬───────────────┬────┘
                        │               │
              ┌─────────▼─────┐   ┌─────▼────────┐
              │  Figma plugin │   │   REST API   │
              │ (live select) │   │ (url+token)  │
              └─────────┬─────┘   └─────┬────────┘
                        │               │
                        └───────┬───────┘
                                ▼
                       Figma REST / Plugin API
```

The two modes are functionally equivalent for document and navigation tools, but only the plugin mode can read the user's currently selected node without a file URL. The REST mode requires a `url` parameter and a `FIGMA_TOKEN` for any read operation, and is therefore suitable for headless agents and CI workflows. Source: [README.md:30-56](), [docs/rest-api.md:1-40]()

The plugin is not yet listed on the Figma Community page, so manual installation is the supported path. Source: [docs/plugin-setup.md:1-30]()

## Getting Started

Prerequisites are intentionally minimal:

- Node.js 18 or later (for the npm-published server). Source: [package.json:18-42]()
- A Figma personal access token, exported as `FIGMA_TOKEN`. Source: [README.md:46-58]()
- Either a Figma desktop client (plugin mode) or a file URL you have access to (REST mode). Source: [docs/rest-api.md:8-22]()

### REST API path

1. Install the server into your MCP-compatible client, or run it locally via `npx design-context-bridge`. Source: [README.md:48-62]()
2. Set `FIGMA_TOKEN` in the environment so outgoing requests can authenticate. Source: [docs/rest-api.md:12-26]()
3. Pass a `url` parameter — either a Figma file URL or a node URL — to tools such as `extract_design` or `get_document`. Source: [docs/rest-api.md:20-44]()

Network behavior is hardened against Figma rate limits: a 30-second in-memory cache prevents redundant calls within a single tool chain, and 429 responses are retried up to three times with exponential backoff while honoring the `Retry-After` header. Source: [README.md:64-72]()

### Plugin path

1. Build the plugin bundle and load it as an unsaved plugin via `Plugins → Development → Import plugin from manifest`. Source: [docs/plugin-setup.md:10-38]()
2. Start the local MCP server so the plugin can hand selections to it. Source: [docs/plugin-setup.md:24-52]()
3. Select a node in Figma; the inspector surfaces colors, typography (family, size, weight, and full CSS), and spacing, and every value is one click away from being copied to the clipboard. Source: [README.md:74-90]()

The plugin UI respects the host's appearance via Figma's `themeColors`, and typography values now include `fontStyle` so weight is reported explicitly. Source: [README.md:78-92]()

## Client Configuration

Both modes are exposed to clients through a standard MCP server entry point. Common clients (Claude Desktop, Cursor, and other MCP-aware tools) are configured by pointing the client at the package and providing the environment variables documented in [docs/clients.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/clients.md). Configuration snippets typically include:

- `command`: the server entry (commonly `npx design-context-bridge`).
- `args`: optional flags to force REST mode or set a default file.
- `env`: `FIGMA_TOKEN` and any optional cache/timeout overrides.

Source: [docs/clients.md:1-60]()

After configuration, restart the client so it re-reads the MCP server list. New tools such as `extract_design`, `get_document`, and navigation helpers will appear under the server's namespace and can be invoked directly by the agent. Source: [src/index.ts:60-120](), [docs/clients.md:30-72]()

## Where to Go Next

- For tool-by-tool reference, see the dedicated pages generated from `src/index.ts` and the README's tool catalog. Source: [README.md:90-130]()
- For transport-specific options, consult [docs/plugin-setup.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/plugin-setup.md) and [docs/rest-api.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/rest-api.md).
- For client wiring examples, see [docs/clients.md](https://github.com/CristinaFores/design-context-bridge/blob/main/docs/clients.md).

---

<a id='page-architecture'></a>

## System Architecture and Data Flow

### Related Pages

Related topics: [Overview and Getting Started](#page-overview), [MCP Tools and Capabilities](#page-tools), [Figma Plugin, Reliability, Security, and Operations](#page-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/index.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/index.ts)
- [src/core/types.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/core/types.ts)
- [src/figma-bridge/ws-server.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/figma-bridge/ws-server.ts)
- [src/figma-bridge/store.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/figma-bridge/store.ts)
- [src/figma-rest/client.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/figma-rest/client.ts)
- [src/figma-rest/resolve.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/figma-rest/resolve.ts)
</details>

# System Architecture and Data Flow

Design Context Bridge is an independent Model Context Protocol (MCP) server that exposes Figma design data to AI agents. The codebase is split into two parallel data acquisition channels — a live plugin channel over WebSocket and a stateless REST channel against the Figma HTTP API — unified behind a single MCP tool surface so that agents get consistent shapes regardless of source. Source: [src/index.ts:1-40]()

## High-Level Architecture

The server entry point at `src/index.ts` boots the MCP transport, registers tool handlers, and routes each incoming tool call to either the plugin bridge or the REST client based on the arguments supplied. The tool surface is identical in both modes; only the acquisition backend differs. Source: [src/index.ts:40-120]()

Shared type definitions live in `src/core/types.ts` and describe the normalized representations of nodes, styles, colors, typography, and spacing that both backends must return, so downstream analysis tools (such as `extract_design_tokens`) can consume either channel without branching. Source: [src/core/types.ts:1-80]()

```mermaid
flowchart LR
  Agent[AI Agent] -->|MCP call| Server[design-context-bridge<br/>src/index.ts]
  Server -->|plugin tools| WS[ws-server.ts]
  WS <-->|WebSocket| Plugin[Figma Plugin]
  WS --> Store[store.ts<br/>selection cache]
  Server -->|REST tools| Client[client.ts<br/>+ cache + 429 retry]
  Resolve[resolve.ts] --> Client
  Client -->|HTTP| API[Figma REST API]
  Server -->|normalized types| Agent
```

## Plugin Mode — Live Selection

When the user prefers live context from an open Figma file, the Figma plugin connects to a WebSocket server implemented in `src/figma-bridge/ws-server.ts`. The plugin pushes events such as `selectionchange` and `documentinfo`; the server accepts them, validates payloads against `src/core/types.ts`, and stores the latest snapshot. Source: [src/figma-bridge/ws-server.ts:1-100]()

`src/figma-bridge/store.ts` is the in-memory state layer for this mode. It exposes read accessors keyed by session and node ID so MCP handlers can resolve the currently selected node synchronously without re-asking the plugin on every call. Because the plugin is the source of truth, there is no HTTP caching here — staleness is bounded by the plugin's event stream. Source: [src/figma-bridge/store.ts:1-90]()

This mode is the foundation of the v1.1.0 copy-to-clipboard inspector, which reads selection state from the store and renders normalized values (hex colors, typography with `fontStyle`, spacing) back into the plugin UI. Source: [src/core/types.ts:80-140]()

## REST Mode — Stateless URL

When no plugin is connected, the server accepts a Figma file `url` plus a personal access token. `src/figma-rest/resolve.ts` parses the URL into the canonical `file_key` and optional `node_id`, producing a stable cache key for downstream requests. Source: [src/figma-rest/resolve.ts:1-70]()

`src/figma-rest/client.ts` wraps the Figma REST endpoints (`/v1/files/:key`, `/v1/files/:key/nodes`, etc.) and applies two reliability layers introduced in v1.0.1:

- A **30-second in-memory cache** keyed by `(file_key, node_id, endpoint)`. This deduplicates calls inside a single tool chain where the agent may redundantly re-query the same node. Source: [src/figma-rest/client.ts:1-90]()
- A **429 retry policy** that retries up to 3 times with exponential backoff, respecting the `Retry-After` header set by Figma. Source: [src/figma-rest/client.ts:90-160]()

REST parity ensures document and navigation tools work without the plugin, which is critical when the agent is working against a file the user does not have open in Figma.

## Request Lifecycle and Dispatch

A typical tool call follows this path:

1. The MCP client (agent) invokes a tool by name with arguments.
2. `src/index.ts` resolves the handler; if arguments include a `url`, the REST resolver is engaged, otherwise the WebSocket store is queried for live selection.
3. The chosen backend returns raw Figma data, which is mapped through `src/core/types.ts` normalizers.
4. The server serializes the result as an MCP response; the cache layer records it for the configured TTL.

Because both backends converge on the same normalized types, higher-level analysis tools remain single-implementation. The plugin is currently distributed via manual install (documented as the primary path in v1.1.0), while the REST mode requires only a token — which lowers friction for cloud-hosted agents that cannot run the Figma desktop client.

This separation of concerns — shared types, two interchangeable backends, and reliability middleware in the REST client — is what lets the project describe itself as "an independent MCP server that gives AI agents real Figma design context" without coupling agents to a specific Figma session.

---

<a id='page-tools'></a>

## MCP Tools and Capabilities

### Related Pages

Related topics: [Overview and Getting Started](#page-overview), [System Architecture and Data Flow](#page-architecture)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcp-server/tool-registry.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/mcp-server/tool-registry.ts)
- [src/mcp-server/tools/get-current-selection.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/mcp-server/tools/get-current-selection.ts)
- [src/mcp-server/tools/get-selected-colors.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/mcp-server/tools/get-selected-colors.ts)
- [src/mcp-server/tools/get-selected-texts.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/mcp-server/tools/get-selected-texts.ts)
- [src/mcp-server/tools/get-selected-spacing.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/mcp-server/tools/get-selected-spacing.ts)
- [src/mcp-server/tools/get-selected-interactions.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/mcp-server/tools/get-selected-interactions.ts)
</details>

# MCP Tools and Capabilities

The `design-context-bridge` project exposes its functionality to AI agents through the **Model Context Protocol (MCP)**. The MCP layer is a thin, well-typed contract surface: each design-context operation (inspecting colors, typography, spacing, interactions, the current selection) is implemented as a discrete MCP tool and registered with the MCP server via a central tool registry. Agents consume these tools through their normal MCP client, while humans inspect the same data visually through the Figma plugin UI.

## 1. Architectural Role

The MCP server acts as the protocol bridge between an LLM agent and two backends:

1. The **Figma plugin backend**, which forwards the live selection and document state from the user's Figma editor.
2. The **REST API backend**, which can resolve any Figma file by URL + personal access token without requiring the plugin to be installed.

Source: [src/mcp-server/tool-registry.ts:1-40]()

Most tools are written so that both backends can satisfy them. Document- and navigation-style tools (`get_current_selection` style reads, structure queries) work over REST, while richer selection-bound tools (colors, text, spacing, interactions) prefer plugin data when available. This split is described as "REST parity" in the v1.0.0 release notes and is the reason a tool like `get-current-selection` can degrade gracefully when no plugin is connected.

## 2. Tool Registry and Dispatch

All MCP tools are registered through a single registry module. The registry owns:

- The canonical list of tool names and their MCP-compatible schemas (name, description, `inputSchema`).
- A dispatcher that resolves incoming `tools/call` requests to the correct handler.
- Shared cross-cutting concerns: the 30-second in-memory cache, the 429 retry policy with exponential backoff honoring `Retry-After`, and error normalization for the MCP response envelope.

Source: [src/mcp-server/tool-registry.ts:41-90]()

Because each tool is registered as a small module under `src/mcp-server/tools/`, the registry can be extended without touching the server core. Adding a new capability means: implement the handler, declare its schema, and append it to the registry. This keeps the surface area auditable for an AI agent and easy to test in isolation.

## 3. Selection-Bound Tools

The selection-bound tools all follow the same shape: read the current Figma selection (from the plugin channel when available, otherwise from REST given a `nodeId` / URL), normalize the result into a deterministic JSON shape, and return it. The plugin side additionally renders an inspector panel where each emitted value can be clicked to copy it to the clipboard (hex colors, font properties, CSS, spacing values), as introduced in v1.1.0.

| Tool | Purpose | Key output |
|---|---|---|
| `get-current-selection` | Resolve the nodes the user has selected in Figma | List of node ids + lightweight metadata |
| `get-selected-colors` | Extract fill/stroke colors from the selection | Hex values, opacity, color roles |
| `get-selected-texts` | Extract typography from the selection | Font family, size, weight (`fontStyle`), full CSS |
| `get-selected-spacing` | Extract layout spacing from the selection | Padding, gap, item-spacing values |
| `get-selected-interactions` | Extract prototype interactions from the selection | Triggers, actions, destinations |

### `get-current-selection`

Resolves the active selection and returns the node identifiers that downstream tools can pivot on. It is the typical entry point for an agent that wants to inspect what the user is currently looking at in Figma.

Source: [src/mcp-server/tools/get-current-selection.ts:1-60]()

### `get-selected-colors`

Walks the selection tree, collects solid fills and strokes, and emits normalized hex strings. The v1.1.0 plugin inspector renders each hex with a click-to-copy affordance, matching the JSON value the MCP client receives.

Source: [src/mcp-server/tools/get-selected-colors.ts:1-80]()

### `get-selected-texts`

Returns typography descriptors for each text node in the selection. As of v1.1.0, the payload includes `fontStyle` (weight) alongside `fontFamily`, `fontSize`, and a full CSS string for direct paste into stylesheets.

Source: [src/mcp-server/tools/get-selected-texts.ts:1-80]()

### `get-selected-spacing`

Reads layout spacing properties (padding, item spacing, constraints) from frames and auto-layout containers in the selection and emits them as discrete numeric values. The plugin inspector exposes these as click-to-copy values for design handoff.

Source: [src/mcp-server/tools/get-selected-spacing.ts:1-80]()

### `get-selected-interactions`

Enumerates prototype `reactions` on the selection — triggers, action types, and destination node ids — so agents can reason about user flows rather than just static visuals.

Source: [src/mcp-server/tools/get-selected-interactions.ts:1-80]()

## 4. Resilience Layer

Two behaviors added in v1.0.1 apply uniformly across the tool surface:

- **In-memory cache (30s TTL)**: redundant calls inside a single tool chain (for example, an agent that asks for selection, then colors, then texts in quick succession) hit the cache instead of round-tripping to Figma again.
- **429 retry with exponential backoff**: when the Figma API rate-limits a request, the tool retries up to three times, honoring the `Retry-After` header between attempts.

Source: [src/mcp-server/tool-registry.ts:91-140]()

These are deliberately implemented at the registry level rather than inside each tool, so every capability inherits the same stability guarantees without per-tool duplication.

## 5. Tool Flow

```mermaid
flowchart LR
    A[AI Agent / MCP Client] -->|tools/call| B[tool-registry.ts]
    B --> C{Plugin Connected?}
    C -- yes --> D[Plugin Channel]
    C -- no --> E[REST API + Token]
    D --> F[Selection Tools]
    E --> F
    F --> G[30s Cache]
    G --> H[429 Retry Layer]
    H --> I[Figma API]
    I --> H
    H --> G
    G --> F
    F --> J[Normalized JSON]
    J --> A
```

The flow illustrates that regardless of which tool the agent invokes, requests converge on the registry, are routed to the appropriate backend, and pass through the shared cache and retry layer before returning a normalized payload.

## Summary

The MCP surface of `design-context-bridge` is intentionally small and uniform: a registry that owns dispatch, caching, and retries, plus a set of focused selection-bound tools (`get-current-selection`, `get-selected-colors`, `get-selected-texts`, `get-selected-spacing`, `get-selected-interactions`). The plugin backend and REST backend are interchangeable for document-level reads, and the v1.1.0 inspector mirrors the tool payloads visually for human design work.

---

<a id='page-operations'></a>

## Figma Plugin, Reliability, Security, and Operations

### Related Pages

Related topics: [System Architecture and Data Flow](#page-architecture), [MCP Tools and Capabilities](#page-tools)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [figma-plugin/code.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/figma-plugin/code.ts)
- [figma-plugin/code.js](https://github.com/CristinaFores/design-context-bridge/blob/main/figma-plugin/code.js)
- [figma-plugin/ui.html](https://github.com/CristinaFores/design-context-bridge/blob/main/figma-plugin/ui.html)
- [figma-plugin/manifest.json](https://github.com/CristinaFores/design-context-bridge/blob/main/figma-plugin/manifest.json)
- [figma-plugin/tsconfig.json](https://github.com/CristinaFores/design-context-bridge/blob/main/figma-plugin/tsconfig.json)
- [src/figma-rest/client.ts](https://github.com/CristinaFores/design-context-bridge/blob/main/src/figma-rest/client.ts)
</details>

# Figma Plugin, Reliability, Security, and Operations

The **design-context-bridge** project exposes Figma design context to AI agents through two complementary surfaces: a Figma plugin that operates on the user's live selection, and an independent MCP server that talks to Figma's REST API. The topics below cover the plugin's runtime structure, the reliability safeguards that protect tool chains against throttling, the security posture of the system, and the operational steps required to run it.

## 1. Figma Plugin Architecture

The plugin lives entirely under `figma-plugin/` and is shipped as an unpacked bundle that must be installed manually because it is not yet listed on the Figma Community marketplace. The bundle is intentionally small and uses Figma's standard sandboxed plugin model.

- `figma-plugin/manifest.json` declares the plugin identity, the document access level, and the entry points. It binds the plugin's main thread (`code.js`) and its UI (`ui.html`) and requests the network capability required to reach the MCP server. Source: [figma-plugin/manifest.json]()
- `figma-plugin/code.ts` is the TypeScript source that runs in the plugin sandbox. It listens for selection changes, walks the current page tree, extracts styles (colors, typography, spacing), and posts structured payloads to the UI. Source: [figma-plugin/code.ts]()
- `figma-plugin/code.js` is the compiled JavaScript produced from `code.ts`; Figma loads this file at runtime, so the build step is part of normal operations. Source: [figma-plugin/code.js]()
- `figma-plugin/ui.html` renders the inspector panel. In v1.1.0 it gained a click-to-copy inspector (colors → hex, typography → family/size/weight or full CSS, spacing → pixels) and switched to native light/dark theming via Figma's `themeColors`. It also now exposes `fontStyle` for typography entries. Source: [figma-plugin/ui.html]()
- `figma-plugin/tsconfig.json` configures the TypeScript build that produces `code.js` from `code.ts`. Source: [figma-plugin/tsconfig.json]()

The plugin does not, by itself, talk to Figma's REST API for the document it is inspecting; it reads the live document through Figma's plugin APIs. The MCP server (`src/figma-rest/client.ts`) handles remote access via `url` plus a personal access token.

## 2. Reliability: Caching and 429 Handling

Reliability matters because a single agent workflow may chain many tool calls in quick succession, each of which can hit the Figma REST API. Version v1.0.1 introduced two safeguards inside `src/figma-rest/client.ts`:

- **In-memory cache (30s TTL)** — Identical requests issued within a 30-second window are served from cache instead of re-hitting Figma. This reduces redundant round-trips inside a single tool chain and lowers the chance of triggering rate limits. Source: [src/figma-rest/client.ts]()
- **429 retry with exponential backoff** — When the API responds with HTTP 429 (Too Many Requests), the client retries up to three times. Each retry waits exponentially longer and respects any `Retry-After` header returned by Figma, so the client yields backoff time the server actually requested rather than guessing. Source: [src/figma-rest/client.ts]()

Together, these mechanisms turn transient throttling into transparent retries and collapse repeated calls within a workflow into a single network request, which keeps multi-step agent runs stable.

## 3. Security Posture

The project is designed so that credentials never leave the operator's machine unless explicitly configured:

- The Figma personal access token is supplied by the caller (CLI flag, environment variable, or MCP client config) and is forwarded per request inside `src/figma-rest/client.ts`. It is not persisted to disk by the server.
- The Figma plugin runs inside Figma's sandbox and only communicates with the MCP server endpoint the user configures. Because the plugin is installed manually from source, the user audits `manifest.json`, `code.ts`, and `ui.html` before loading it.
- No telemetry is collected by the MCP server; the only outbound traffic is the authenticated request to `api.figma.com`.

## 4. Operations: Install and Build

Operational steps reflect the "manual install is primary" guidance introduced with v1.1.0:

| Step | Action | File / Artifact |
|------|--------|-----------------|
| 1 | Install dependencies at the repo root | project `package.json` |
| 2 | Build the plugin (`tsc` against `figma-plugin/tsconfig.json`) | produces `figma-plugin/code.js` |
| 3 | In Figma → Plugins → Development → Import plugin from manifest | selects `figma-plugin/manifest.json` |
| 4 | Start the MCP server with a Figma token available | reads token at runtime |
| 5 | Use REST mode (`url`) without the plugin, or Plugin mode for live selection | depends on use case |

Because the plugin is not on the Figma Community, every operator must perform steps 2–3 locally. Keeping `code.ts` and `manifest.json` under version control makes the install auditable, and rebuilding `code.js` after edits to `code.ts` ensures the loaded bundle matches reviewed source. Source: [figma-plugin/tsconfig.json](), [figma-plugin/manifest.json]()

## Summary

The plugin surface (`figma-plugin/code.ts`, `ui.html`, `manifest.json`) gives AI agents low-latency access to the currently selected node, while `src/figma-rest/client.ts` provides a parity path for any file by URL. The 30-second cache and 429 retry logic introduced in v1.0.1 keep chained tool calls reliable, the security model keeps the Figma token local to the operator, and the manual install path keeps the deployment auditable — consistent with the v1.1.0 release notes that document manual install as the primary workflow.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: CristinaFores/design-context-bridge

Summary: Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.1.0 — copy-to-clipboard inspector
- User impact: Upgrade or migration may change expected behavior: v1.1.0 — copy-to-clipboard inspector
- Evidence: failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.1.0

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/CristinaFores/design-context-bridge

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/CristinaFores/design-context-bridge

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/CristinaFores/design-context-bridge

## 6. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: v1.0.1 — fix: in-memory cache + 429 retry
- User impact: Upgrade or migration may change expected behavior: v1.0.1 — fix: in-memory cache + 429 retry
- Evidence: failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.0.1

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.0 — Design Context Bridge
- User impact: Upgrade or migration may change expected behavior: v1.0.0 — Design Context Bridge
- Evidence: failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.0.0

<!-- canonical_name: CristinaFores/design-context-bridge; human_manual_source: deepwiki_human_wiki -->