Usando a grade

A grade Master é o editor de variáveis da aba Master de um projeto. Cada linha é uma variável; há uma coluna de valor por modo (claro/escuro, idiomas e assim por diante). As mudanças feitas na grade chegam ao Figma quando você clica em Sincronizar no plugin.

Coleções e grupos

• Troque de coleção na lista Coleções da barra lateral esquerda e crie uma com o botão + (Nova coleção). Clique com o botão direito numa coleção para Renomear / Exportar esta coleção / Excluir.
• Clique no cabeçalho Coleções da barra lateral para abrir o menu Ordem das coleções — Ordem de criação (padrão) ou Nome (A→Z). A ordem de coleções reorganizada no painel do Figma não pode ser lida por plugins, então não é importada.
• Uma / no nome de uma variável forma um grupo (por exemplo, color/primary → o grupo color). Escolha um grupo na árvore Grupos para filtrar a grade só para ele; escolha Todos para ver a coleção inteira de novo.

Criar, renomear e mover grupos

• Selecione linhas e clique com o botão direito em Novo grupo com a seleção — as variáveis selecionadas são reunidas num grupo chamado Novo grupo. Renomeie-o logo em seguida na barra lateral.
• Clique com o botão direito num grupo da barra lateral e escolha Renomear para mudar o caminho de todas as variáveis daquele grupo (subgrupos incluídos). Os aliases que apontam para essas variáveis acompanham automaticamente. O nome de um grupo não pode ficar vazio nem conter /.
• As células de nome da grade mostram só o último segmento; o cabeçalho do grupo carrega o caminho. A edição com clique duplo muda só o último segmento — para editar o caminho completo, use o campo Nome em clique direito → Editar variável.
• Arraste um grupo da barra lateral para cima de outro grupo (ou de Todos) para mover o caminho dele para baixo do destino. Ctrl(⌘)+Z desfaz, e o mesmo caminho chega ao Figma depois da próxima sincronização. Não é possível soltar um grupo sobre ele mesmo, sobre um dos seus subgrupos ou sobre o pai atual.
• Grupos e variáveis não podem ser reordenados arrastando.

Editar células

• Clique numa célula de valor para editá-la. Enter confirma e desce; Escape restaura o valor original.
• Entrada por tipo: string = texto, número = entrada numérica, booleano = chave liga/desliga, cor = seletor de cor + hexadecimal.
• As células de cor mostram o hexadecimal sem # ao lado de um segmento de alfa em %, como no Figma. Formas curtas são expandidas (f → FFFFFF), e com 8 dígitos os dois últimos são o alfa — a dica de entrada diz “Hex de 6 ou 8 dígitos (os 2 últimos = alfa); formas curtas são expandidas (f → FFFFFF); {reference} também funciona”. Um valor que não é cor nunca é salvo: ele volta ao original quando você sai da célula, com o aviso “Não é uma cor, revertido: {value}”.
• O seletor de cor tem as abas Personalizada / Bibliotecas. Em Bibliotecas, escolha outra variável de cor da mesma coleção para vinculá-la como referência (alias); Capturar cor da tela captura uma cor da sua tela.
• Uma célula que referencia outra variável aparece como uma etiqueta — a etiqueta mostra só o último segmento, e ao passar o mouse você vê o caminho completo e o valor resolvido. Clique na etiqueta para reabrir o seletor e trocar para outra variável.
• Variáveis de string e número também podem referenciar. Passe o mouse sobre a célula e use o botão Definir alias para escolher uma variável do mesmo tipo; os três tipos compartilham o botão Desvincular alias, que remove a referência e deixa o valor resolvido como um valor comum.
• Uma escolha que formaria um laço é bloqueada no seletor (“Criaria uma referência circular”). A colagem pula as células que formariam laço e avisa (“Células ignoradas (referência circular): {count}”).
• Clique duas vezes numa célula de nome para renomear uma variável.
• Para deixar um comentário numa célula, aperte C e clique na célula (Comentários — “Pressione C e clique em uma célula. Fica ativo até você pressionar Esc.”). As células de descrição, tag e escopo também aceitam comentários.

Adicionar, excluir e duplicar linhas

• Escolha um tipo (COR / NÚMERO / STRING / BOOLEANO) no + mais à esquerda da barra de ferramentas (Adicionar variável) e uma linha é criada e focada na hora. Não há formulário de nome antes — a nova variável nasce com um valor padrão conforme o tipo; renomeie ali mesmo.
• Para excluir, selecione linhas e aperte Delete, ou use Excluir no menu de contexto.
• Shift+Enter — numa linha só, insere logo abaixo uma nova linha do mesmo tipo; com várias linhas selecionadas, duplica todas.
• A opção Duplicar do menu de contexto também funciona.
• Menu de contexto da linha: Copiar · Duplicar · Editar variável · Novo grupo com a seleção · Mover para coleção ▸ (lista de coleções + Nova coleção) · Ver referências · Exportar esta coleção · Excluir.

Mover variáveis para outra coleção

• Selecione linhas, clique com o botão direito em Mover para coleção ▸ e escolha a coleção de destino ou Nova coleção. Se as duas coleções tiverem os mesmos nomes de modo, as linhas são movidas na hora.
• Se os modos forem diferentes, abre a caixa Mover para {collection} com um quadro Quais valores manter. Para cada modo da coleção atual, coloque o valor dele numa das colunas de modo do destino ou escolha Descartar. Enquanto houver modo sem lugar, o botão fica travado e a caixa diz “Ainda sem posição: {modes}”. O botão diz Mover, ou Descartar {count} e mover quando uma escolha descarta valores — não há confirmação separada. Restaurar padrão restaura a disposição inicial.
• Depois da movimentação, aparece o aviso “Variáveis movidas para {collection}: {count}” com Desfazer para desfazer na hora.
• Num projeto com um arquivo do Figma conectado, a caixa diz “As camadas do Figma são reconectadas na próxima sincronização. O que não puder ser reconectado fica sinalizado na linha.” As linhas movidas ficam com o selo Aguardando no Figma até você clicar em Sincronizar no plugin, o que cria as variáveis na nova coleção do lado do Figma e reconecta as camadas.

Seleção múltipla — dois modos

Seleção de linhas (linha inteira destacada) — para operações por linha:

• Shift+clique: seleciona um intervalo a partir da última linha selecionada
• Ctrl(⌘)+clique: adiciona/remove linhas avulsas
• Shift+Ctrl(⌘)+↑↓: amplia pelo teclado
• Ações disponíveis: clique direito Copiar (com nomes e modos) / Duplicar / Excluir, a tecla Delete, duplicar com Shift+Enter, Novo grupo com a seleção, Mover para coleção

Seleção de intervalo de células (borda tracejada) — para operações de valores em bloco:

• Clique numa célula de valor para definir a âncora e depois Shift+clique ou Shift+setas para ampliar um retângulo
• Ações disponíveis: entrada em lote, copiar com Ctrl(⌘)+C, Delete para limpar valores

Entrada em lote

Com um intervalo de células selecionado, é só começar a digitar — a edição abre na célula âncora, e o Enter coloca esse valor em todas as células selecionadas de uma vez.

Copiar e colar

Você pode levar valores entre a grade e o Google Sheets ou o Excel copiando e colando. Cole na grade uma tabela copiada de uma planilha e copie os valores da grade de volta para uma planilha.

Copiar:

• Selecione duas ou mais células e aperte Ctrl(⌘)+C para copiar os valores.
• Selecione linhas e clique com o botão direito em Copiar para incluir os nomes das variáveis e os modos. Cole numa planilha e você terá uma tabela.

Colar (Ctrl(⌘)+V): cole direto na grade uma tabela copiada de uma planilha. Onde ela entra depende da sua seleção.

• Há uma célula de valor selecionada — o preenchimento começa nessa célula e segue para a direita e para baixo. Linhas e colunas que passam da borda da grade são puladas.
• Nenhuma célula selecionada — a primeira linha é lida como cabeçalho, e os valores são associados às linhas existentes pelo nome da variável e pelo nome do modo. Nomes de variável que não estão na grade viram linhas novas (o aviso mostra “Novas variáveis: {count}”). Colunas sem correspondência são puladas.

Nos dois casos, um aviso informa quantas células foram preenchidas e quantas foram puladas. Células que formariam uma referência circular são puladas.

Colar numa célula de valor selecionada só preenche linhas existentes — para criar variáveis novas ao colar, limpe a seleção de células e cole uma tabela com linha de cabeçalho, ou crie as linhas antes com + (Adicionar variável). Se houver uma busca ou um filtro ativo, só as linhas visíveis na grade são afetadas.

Desfazer / Refazer

Ctrl(⌘)+Z para desfazer, Ctrl(⌘)+Shift+Z para refazer (até 50 passos). Também há botões na barra de ferramentas. Edições, exclusões, colagens, entradas em lote e renomeações e movimentações de grupos podem ser desfeitas.

Gerenciar modos (colunas)

• Adicione modos com o botão + (Adicionar modo) na ponta direita do cabeçalho do último modo. No limite de idiomas do seu plano, aparece um convite para fazer upgrade.
• Clique duas vezes no cabeçalho de um modo para renomeá-lo, ou use Renomear / Excluir do menu de contexto. O último modo que sobrar não pode ser excluído.
• Arraste a borda de uma coluna para mudar a largura — as larguras ficam salvas para a próxima vez.

Buscar e ordenar

A barra de ferramentas tem uma caixa de busca e filtros de tipo (Todos os tipos · Cor / String / Número / Booleano). Clique no cabeçalho Nome · Descrição · Tag · Escopos para ordenar por aquela coluna; clique de novo para inverter a direção. A ordenação vale só dentro de cada seção de grupo — a ordem das próprias seções de grupo não muda.

O botão Exibir — colunas e cor da barra de ferramentas liga e desliga as colunas Modos · Descrição · Tag · Escopos (o menu continua aberto para você alternar várias) — explicado em Metadados de variáveis.

Atalhos de teclado

Grafo de tokens

A aba Grafo de tokens de um projeto visualiza, passo a passo, as relações de referência (alias) entre variáveis, e a aba Mapa de tokens dispõe o projeto inteiro num único mapa. Clique num token do grafo e o resumo mostra “Mudar isto afeta {count}” e “Valores referenciados: {count}”, para você ver o alcance antes de editar. Na grade, clique com o botão direito numa linha e escolha Ver referências para ir direto. Veja o guia completo em Grafo de tokens.

Exportar dados

Exporte direto pela web — Exportar no menu ⋮ do cartão do projeto, ou clique com o botão direito numa coleção da barra lateral ou numa linha da grade e escolha Exportar esta coleção. Há seis formatos (DTCG · JSON · CSV · CSS · SwiftUI · Jetpack Compose); veja os detalhes em Exportação e código. A opção Mais (…) → Exportar do plugin do Figma também salva um arquivo. Para buscar design tokens a partir do código ou da CI, use a API somente leitura e o servidor MCP.