Inicialize o projeto

Initialize the project

Inicializa el proyecto

Dentro da pasta do seu projeto, rode:

Inside your project folder, run:

Dentro de la carpeta de tu proyecto, ejecuta:

$ cd your-project
$ designcontext init

Isso cria uma pasta .designcontext/ com a configuração do projeto.

This creates a .designcontext/ folder with the project's configuration.

Esto crea una carpeta .designcontext/ con la configuración del proyecto.

Conecte o Figma

Connect Figma

Conecta Figma

Cole o link do arquivo do Figma (Compartilhar → Copiar link) no --file. O DesignContext extrai o id do arquivo (e o nó, se o link apontar para uma tela específica) sozinho, reaproveita o Figma MCP que você já usa no seu agente — normalmente nenhum token é necessário — e usa o nome real do arquivo no Figma como apelido (alias) padrão:

Paste the Figma file link (Share → Copy link) into --file. DesignContext extracts the file id (and the node, if the link points at a specific screen) on its own, reuses the Figma MCP you already use in your agent — usually no token is needed — and uses the file's real name in Figma as the default alias:

Pega el link del archivo de Figma (Compartir → Copiar link) en --file. DesignContext extrae el id del archivo (y el nodo, si el link apunta a una pantalla específica) solo, reutiliza el Figma MCP que ya usas en tu agente — normalmente no se necesita ningún token — y usa el nombre real del archivo en Figma como alias predeterminado:

$ designcontext connect --file "https://www.figma.com/design/aBc123XyZ/Checkout-Flow"

Quer escolher o apelido em vez de usar o nome detectado? Passe --alias:

Want to choose the alias instead of the detected name? Pass --alias:

¿Quieres elegir el alias en vez del nombre detectado? Pasa --alias:

$ designcontext connect --file "https://www.figma.com/design/aBc123XyZ/Checkout-Flow" --alias checkout

Se preferir, dá para apontar para um Figma MCP hospedado ou usar um token:

If you prefer, you can point to a hosted Figma MCP or use a token:

Si prefieres, puedes apuntar a un Figma MCP alojado o usar un token:

$ designcontext connect --file <url> --url https://seu-host/mcp
$ designcontext connect --file <url> --token <seuToken>

$ designcontext connect --file <url> --url https://your-host/mcp
$ designcontext connect --file <url> --token <yourToken>

$ designcontext connect --file <url> --url https://tu-host/mcp
$ designcontext connect --file <url> --token <tuToken>

Se nenhum arquivo for informado, ou nenhuma forma de conexão puder ser resolvida, o comando falha com uma mensagem clara em vez de "funcionar" silenciosamente com uma configuração vazia.

If no file is given, or no connection method can be resolved at all, the command fails with a clear message instead of silently "succeeding" with an empty config.

Si no se indica ningún archivo, o no se puede resolver ninguna forma de conexión, el comando falla con un mensaje claro en vez de "funcionar" silenciosamente con una configuración vacía.

Conectando mais de um arquivo

Connecting more than one file

Conectando más de un archivo

Um projeto pode acompanhar vários arquivos do Figma ao mesmo tempo. Rode connect de novo com outro link — ele soma o novo arquivo (com seu próprio apelido) em vez de substituir o que você já conectou:

A project can track several Figma files at once. Run connect again with a different link — it adds the new file (under its own alias) instead of replacing the one you already connected:

Un proyecto puede seguir varios archivos de Figma a la vez. Ejecuta connect de nuevo con otro link — suma el nuevo archivo (con su propio alias) en vez de reemplazar el que ya conectaste:

$ designcontext connect --file "https://www.figma.com/design/qRs456TuV/Cancelamento" --alias cancelamento

Os dois arquivos passam a compartilhar o mesmo grafo/cache local e o mesmo servidor MCP. Assim que houver mais de um arquivo, os comandos que operam em um arquivo específico (diff, inspect) exigem --file <apelido> para saber qual usar.

Both files now share the same local graph/cache and the same MCP server. As soon as there's more than one file, the commands that operate on a specific file (diff, inspect) require --file <alias> to know which one to use.

Ambos archivos pasan a compartir el mismo grafo/cache local y el mismo servidor MCP. En cuanto haya más de un archivo, los comandos que operan sobre un archivo específico (diff, inspect) requieren --file <alias> para saber cuál usar.

Sem token do Figma? Deixe o agente buscar os dados

No Figma token? Let the agent fetch the data

¿Sin token de Figma? Deja que el agente busque los datos

Se você não quer gerar um Personal Access Token do Figma (ex.: conta com acesso só de leitura) e seu agente de IA já tem acesso próprio ao Figma MCP dele, registre o arquivo com --import-only — sem conexão, sem token:

If you don't want to generate a Figma Personal Access Token (e.g. a restricted/View-only account) and your AI agent already has its own Figma MCP access, register the file with --import-only — no connection, no token:

Si no quieres generar un Personal Access Token de Figma (p. ej. una cuenta con acceso solo de lectura) y tu agente de IA ya tiene su propio acceso al Figma MCP, registra el archivo con --import-only — sin conexión, sin token:

$ designcontext connect --file "https://www.figma.com/design/aBc123XyZ/Checkout-Flow" --import-only

Depois, peça ao agente para buscar os dados desse arquivo com a ferramenta Figma MCP dele e repassar para o DesignContext através da ferramenta MCP design_import — ela usa exatamente o mesmo pipeline de scan/cache de um designcontext scan normal, só que alimentado por dados que o agente já tinha acesso, em vez de uma conexão que o DesignContext mantém sozinho.

Then ask the agent to fetch that file's data with its own Figma MCP tool and hand it to DesignContext through the design_import MCP tool — it uses the exact same scan/cache pipeline as a normal designcontext scan, just fed by data the agent already had access to, instead of a connection DesignContext holds itself.

Después, pídele al agente que busque los datos de ese archivo con su propia herramienta Figma MCP y se los pase a DesignContext mediante la herramienta MCP design_import — usa exactamente el mismo pipeline de scan/cache que un designcontext scan normal, solo que alimentado por datos a los que el agente ya tenía acceso, en vez de una conexión que DesignContext mantiene por sí mismo.

Se os dados brutos não tiverem o formato esperado, a ferramenta retorna um aviso claro em vez de indexar silenciosamente um resultado vazio — veja a seção de integração com agentes abaixo para os parâmetros de design_import.

If the raw data doesn't match the expected format, the tool returns a clear warning instead of silently indexing an empty result — see the agent integration section below for design_import's parameters.

Si los datos brutos no tienen el formato esperado, la herramienta devuelve un aviso claro en vez de indexar silenciosamente un resultado vacío — mira la sección de integración con agentes más abajo para los parámetros de design_import.

Indexe uma tela (scan)

Index a screen (scan)

Indexa una pantalla (scan)

Escaneie o arquivo inteiro ou só uma tela específica. Sem --file: se só há um arquivo conectado, ele é escaneado; se há mais de um, todos são escaneados em sequência, com uma linha de relatório por arquivo:

Scan the entire file or just a specific screen. Without --file: if only one file is connected, it's scanned; if there's more than one, all of them are scanned in sequence, with one report line per file:

Escanea el archivo entero o solo una pantalla específica. Sin --file: si solo hay un archivo conectado, se escanea; si hay más de uno, todos se escanean en secuencia, con una línea de reporte por archivo:

$ designcontext scan                        # 1 arquivo: escaneia ele. >1: escaneia todos
$ designcontext scan --file checkout        # escaneia só o arquivo "checkout"
$ designcontext scan --node 123:456          # só uma tela/componente (exige --file com >1 arquivo)

$ designcontext scan                        # 1 file: scans it. >1: scans all of them
$ designcontext scan --file checkout        # scan only the "checkout" file
$ designcontext scan --node 123:456          # a single screen/component (requires --file with >1 file)

$ designcontext scan                        # 1 archivo: lo escanea. >1: escanea todos
$ designcontext scan --file checkout        # escanea solo el archivo "checkout"
$ designcontext scan --node 123:456          # solo una pantalla/componente (exige --file con >1 archivo)

Aqui o DesignContext abre o Figma MCP, lê o design e guarda a versão organizada localmente. Na primeira vez ele faz um scan completo; nas próximas, já detecta só o que mudou.

Here DesignContext opens the Figma MCP, reads the design, and stores the organized version locally. The first time it does a full scan; afterward it only detects what changed.

Aquí DesignContext abre el Figma MCP, lee el diseño y guarda la versión organizada localmente. La primera vez hace un escaneo completo; después, solo detecta lo que cambió.

status também mostra um total acumulado (nunca zerado) de quanto o cache local já economizou de verdade: tokensSaved (tokens do conteúdo completo vs. o resumo otimizado, e o percentual de redução, somando toda chamada design_get_*) e figmaCallsSaved (taxa de acerto do cache nos scans incrementais — um "hit" significa que os dados daquele nó vieram do cache local, sem bater no Figma).

status also reports a running, never-reset total of how much the local cache has actually saved: tokensSaved (full-content vs. optimized-summary token counts, and the reduction percentage, across every design_get_* call served) and figmaCallsSaved (cache hit rate during incremental scans — a hit means that node's data came from the local cache instead of a Figma API call).

status también muestra un total acumulado (nunca se reinicia) de cuánto ha ahorrado realmente el cache local: tokensSaved (tokens del contenido completo vs. el resumen optimizado, y el porcentaje de reducción, sumando cada llamada design_get_*) y figmaCallsSaved (tasa de aciertos del cache en los scans incrementales — un acierto significa que los datos de ese nodo vinieron del cache local, sin llamar a Figma).

Registre no seu agente de IA

Register with your AI agent

Regístralo en tu agente de IA

Um comando registra o DesignContext no agente que você usa:

One command registers DesignContext with the agent you use:

Un comando registra DesignContext en el agente que usas:

$ designcontext setup

Escolha na lista — funciona com Claude Desktop, Claude Code, Gemini CLI, OpenAI Codex e opencode. Prefere pular a pergunta? designcontext setup --agent claude-code,gemini-cli. Depois disso, a IA já consegue consultar o design sozinha — veja a seção de integração.

Pick from the list — works with Claude Desktop, Claude Code, Gemini CLI, OpenAI Codex, and opencode. Want to skip the prompt? designcontext setup --agent claude-code,gemini-cli. After that, the AI can query the design on its own — see the integration section.

Elige de la lista — funciona con Claude Desktop, Claude Code, Gemini CLI, OpenAI Codex y opencode. ¿Prefieres saltar la pregunta? designcontext setup --agent claude-code,gemini-cli. Después de eso, la IA ya puede consultar el diseño por su cuenta — mira la sección de integración.

Se o designcontext não estiver instalado global (ex: npm install sem -g, ou permissão bloqueada), o setup percebe sozinho e configura o agente pra usar npx -y designcontext mcp em vez do comando direto — funciona sem você mexer no PATH.

If designcontext isn't installed globally (e.g. npm install without -g, or a restricted environment), setup detects that on its own and configures the agent to use npx -y designcontext mcp instead of the bare command — works without touching your PATH.

Si designcontext no está instalado globalmente (ej: npm install sin -g, o un entorno restringido), setup lo detecta solo y configura el agente para usar npx -y designcontext mcp en vez del comando directo — funciona sin tocar el PATH.