A maioria dos arquivos Figma não está pronta para handoff de desenvolvimento. Eles parecem impressionantes. As telas são polidas, o alinhamento é perfeito, as escolhas de cor são deliberadas. Mas quando um desenvolvedor abre o arquivo e tenta extrair o que precisa para construir, ele bate numa parede. Os componentes não têm nomenclatura consistente. O auto layout é aplicado de forma inconsistente, então os valores de espaçamento estão escondidos em posicionamento manual. Existem variantes para o estado hover, mas não para os estados disabled ou de erro. Os design tokens no Figma não correspondem a nada no código.
Estive dos dois lados desse problema ao longo da minha carreira. Como designer UX/UI, entreguei arquivos que achava completos e recebi mensagens confusas de desenvolvedores dois dias depois. Como desenvolvedor Angular Sênior, recebi arquivos Figma que exigiram horas de calls de esclarecimento antes de eu conseguir escrever uma única linha de código. A solução, que refinei ao longo de anos de trabalho em dupla função, é um conjunto de práticas que agora aplico consistentemente a todo arquivo Figma que crio. Este post documenta essas práticas.
Nomenclatura: a base de tudo
Nomenclatura ruim no Figma é a causa raiz da maioria dos problemas de handoff. Quando um desenvolvedor abre o painel Inspect e vê 'Frame 247' ou 'Rectangle copy 3', ele não tem nenhuma informação útil. Pior, nomenclatura inconsistente significa que o desenvolvedor não consegue mapear com confiança os componentes do Figma aos componentes correspondentes no código do design system.
Eu sigo uma convenção de nomenclatura que espelha a API do componente o mais próximo possível. Os nomes dos componentes no Figma usam o mesmo formato que o seletor do componente Angular ou o token do design system. Um botão no Figma se chama Button, não 'CTA' ou 'Primary Action'. Suas variantes são nomeadas usando os nomes de propriedade e valores que aparecerão no código: variant=Primary, size=Medium, state=Default.
// Figma component naming convention
Button
variant: Primary | Secondary | Tertiary | Destructive
size: Small | Medium | Large
state: Default | Hover | Focus | Disabled | Loading
// Maps directly to Angular component usage
<app-button
variant="primary"
size="medium"
[disabled]="isLoading">
Submit
</app-button>Quando a linguagem de nomenclatura no Figma corresponde à linguagem de nomenclatura no código, a conversa de handoff fica muito mais curta. O desenvolvedor pode olhar para um componente no Figma, identificar sua variante e estado pelo painel de propriedades e saber exatamente qual componente Angular e quais valores de input usar.
Auto Layout feito direito
O auto layout é o único recurso do Figma que atravessa o handoff carregando o modelo CSS flexbox intacto. Usado corretamente, o desenvolvedor lê o layout em vez de adivinhar. Usado errado, ou simplesmente pulado, ele deixa a pessoa inferindo a lógica de layout a partir de medidas em pixels que descrevem um único frame congelado e não dizem nada sobre como a coisa se comporta quando a viewport muda.
Minhas regras para auto layout em arquivos prontos para handoff:
- Todo componente que será construído com flexbox ou grid em CSS deve usar auto layout no Figma. Sem exceções.
- O espaçamento entre elementos deve vir do gap do auto layout, não de elementos posicionados manualmente. Um valor de gap no Figma se traduz diretamente em gap no CSS.
- Use 'Fill container' para elementos que esticam para ocupar o espaço disponível, e 'Hug contents' para elementos dimensionados pelo que têm dentro. O mapeamento para CSS é próximo, não exato, e quem decide é o eixo. Fill ao longo do eixo do layout é flex-grow: 1. Fill atravessando o eixo do layout é align-self: stretch. Hug é fit-content no eixo e auto atravessando ele. Diga de qual eixo você está falando na anotação e o desenvolvedor para de adivinhar.
- O padding deve ser definido no painel de auto layout, não adicionando frames espaçadores invisíveis. Os valores de padding no Figma são o que o desenvolvedor vai implementar no CSS.
- Use restrições de largura min/max para componentes que precisam de comportamento responsivo. Um card que deve ter no mínimo 280px de largura mas pode crescer é expresso nas restrições do auto layout.
Variantes e estados interativos
Um componente sem todos os seus estados documentados não é um componente. É uma especificação parcial. Já escrevi sobre isso pela perspectiva de escrita de briefing, mas no Figma especificamente, o padrão é: todo componente interativo deve ter variantes para todos os estados que existem na implementação.
Para um campo de input de texto, isso significa: Default, Focused, Filled, Error, Disabled e Read-only. Para um botão: Default, Hover, Focus, Active, Disabled e Loading. Esses não são casos extremos. São o conjunto mínimo que qualquer botão vai encontrar em produção.
O recurso de componentes interativos do Figma (conexões de protótipo entre variantes) é valioso para comunicar comportamento de hover e focus em protótipos. Mas não confie nele como substituto para documentação de variantes. Cada estado deve existir como uma variante distinta no conjunto de componentes, rotulada claramente, para que um desenvolvedor possa inspecioná-la diretamente sem precisar acionar uma interação de protótipo.
Design Tokens: a ponte entre Figma e código
Design tokens são a ferramenta mais importante para reduzir atrito no handoff, e também a mais comumente mal implementada. O objetivo é simples: toda decisão de design no Figma (cor, espaçamento, tipografia, border radius, sombra, duração) deve referenciar um token nomeado, e esse token deve existir no código com o mesmo nome.
Na prática, isso significa configurar suas variáveis do Figma para corresponder exatamente às suas custom properties CSS ou ao objeto de tokens JavaScript. O arranjo que se sustenta exporta as Figma Variables como JSON e roda o arquivo pelo Style Dictionary para gerar o CSS. O Tokens Studio (antigo Figma Tokens) é outra opção: ele administra o conjunto de tokens dentro do Figma e consegue sincronizar com um repositório.
/* In CSS (design system tokens) */
:root {
--color-action-primary: #0052cc;
--color-action-primary-hover: #003d99;
--color-surface-default: #ffffff;
--color-text-primary: #172b4d;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--radius-md: 6px;
--shadow-card: 0 1px 3px rgba(0,0,0,0.12);
}Quando o desenvolvedor inspeciona um botão no Figma e vê que a cor de fundo é var(--color-action-primary) em vez de um valor hexadecimal, ele pode implementar imediatamente com o token correto. Sem color picking, sem valores hexadecimais hardcoded, sem divergência entre design e implementação.
Sincronizando tokens entre Figma e código
Outro fluxo que elimina a deriva, quando a mesma pessoa ou o mesmo time é dono da biblioteca do Figma e da biblioteca de componentes, é código primeiro: os design tokens ficam em um arquivo JSON no repositório como fonte única de verdade. Um plugin de sincronização como o Tokens Studio lê esse arquivo e popula o conjunto de tokens no Figma. Quando um token muda (atualização de cor da marca, ajuste de espaçamento), a mudança é feita no arquivo JSON, um PR é aberto e, uma vez mergeado, a biblioteca do Figma é sincronizada a partir do arquivo atualizado. O Figma sempre reflete o que está no código, não o contrário. Escrever os tokens nas Figma Variables e exportar o JSON, o arranjo que descrevi acima, funciona igualmente bem, desde que o time escolha uma direção e deixe isso escrito. No BMO o design system pertencia a outro time e eu trabalhava do lado consumidor, onde a pergunta que importa é a mesma: em qual direção a verdade flui?
Plugins de anotação e especificações
O painel de inspeção do Figma é útil, mas insuficiente para componentes complexos. Quatro tipos de nota precisam morar em algum lugar do canvas: notas de interação (o que acontece no clique, quais interações de teclado são suportadas), notas de comportamento responsivo, anotações de acessibilidade (roles ARIA, ordem de foco) e notas de restrição de conteúdo (contagem máxima de caracteres, proporções de imagem). Nenhuma delas aparece sozinha no Inspect.
Comece pelo caminho gratuito, porque ele funciona em qualquer assento e é onde eu ainda começo por padrão. Um componente de callout e um estilo de texto para as notas já te dão uma camada de especificação completa de graça. Se você quiser que as partes de medição e anatomia sejam geradas em vez de desenhadas à mão, o plugin Specs da EightShapes tem um nível gratuito que cobre anotações de anatomia, layout e espaçamento, e o Redlines & Annotations na comunidade do Figma faz as sobreposições de medida. Os dois escrevem camadas comuns no canvas, então qualquer pessoa com acesso de leitura consegue ler o resultado.
O Figma Dev Mode tem anotações e medições nativas, e elas são melhores do que qualquer coisa que você desenhe à mão: a anotação fica presa à camada, sobrevive a uma renomeação, se atualiza quando a camada se move, e aparece no painel Inspect, onde o desenvolvedor já está olhando. O problema é o assento. O Dev Mode exige um assento pago Full ou Dev desde janeiro de 2024. Trate como um upgrade que você compra quando o volume de handoff justifica, não como o ponto de partida. Se o seu time já paga por isso, use e apague a sua camada manual de anotações.
De onde quer que venham as notas, elas moram na própria página do Figma nos meus arquivos, chamada 'Specs & Annotations'. Ela guarda uma duplicata de cada tela com as anotações sobrepostas, em vez de anotações em cima dos próprios frames de design, porque isso polui o design no instante em que um stakeholder abre. O desenvolvedor precisa da especificação, vai à página de Specs. O stakeholder quer o design limpo, fica na página de design.
Organização de arquivo que desenvolvedores conseguem navegar
Um arquivo Figma que é visualmente bonito mas estruturalmente caótico é inútil para handoff. Minha estrutura de arquivo para qualquer projeto pronto para desenvolvimento:
- Página de capa: nome do projeto, status (In Progress / Ready for Dev / In Development / Done), data da última atualização, responsável pelo design, contato do desenvolvedor.
- Página de tokens: todas as variáveis e estilos documentados com seus valores e notas de uso.
- Página de componentes: a biblioteca de componentes. Todas as variantes de todos os componentes organizadas por categoria.
- Página de fluxos: fluxos tela a tela organizados por jornada do usuário, com conexões de protótipo.
- Página de Specs & Annotations: versões anotadas de todas as telas prontas para inspeção do desenvolvedor.
- Página de arquivo: explorações antigas e conceitos rejeitados, mantidos para referência mas claramente rotulados.
A vantagem do papel duplo no handoff
Escrever este post me faz perceber o quanto minha experiência de desenvolvimento moldou como eu projeto. Quando crio uma variante de componente para o estado de loading de um botão, não faço por exaustividade por si só. Faço porque sei por experiência que um desenvolvedor implementando aquele botão vai precisar saber como ele fica quando isLoading é true, e sem uma referência de design ele vai me perguntar ou inventar algo.
Cada anotação que escrevo em uma especificação é uma resposta a uma pergunta que sei que um desenvolvedor vai fazer, porque eu mesmo já fiz essas perguntas. Como deve ser o anel de foco? Quantas linhas esse campo de texto suporta antes de transbordar? O que acontece com o layout do card se não houver imagem de thumbnail?
Se você é designer e não programa, a forma mais rápida de melhorar a qualidade do seu handoff é fazer pair com um desenvolvedor por um sprint e pedir para ele narrar sua experiência ao abrir seu arquivo Figma e implementar a partir dele. Os pontos de atrito que ele encontrar vão te dizer exatamente o que melhorar. O desenvolvedor é seu usuário quando o produto é um arquivo Figma, e pesquisa com usuário se aplica.
Um arquivo Figma é um documento de especificação. Um documento de especificação é uma ferramenta de comunicação. Julgue-o não pela beleza visual, mas pela clareza com que responde às perguntas do desenvolvedor.
O objetivo não é um arquivo perfeito. É um arquivo que permite ao desenvolvedor começar a construir na segunda-feira de manhã sem uma única pergunta de esclarecimento. Esse é um padrão alto, mas alcançável, e vale o investimento inicial sempre.
Referências
- Figma auto-layout. https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout
- Figma variants. https://help.figma.com/hc/en-us/articles/360056440594-Create-and-use-variants
- Guia do Figma Dev Mode, exige assento pago Full ou Dev. https://help.figma.com/hc/en-us/articles/15023124644247-Guide-to-Dev-Mode
- Anúncio de disponibilidade geral do Figma Dev Mode, janeiro de 2024. https://www.figma.com/blog/dev-mode-ga/
- Tokens Studio. https://tokens.studio/
- API REST do Figma Variables (somente plano Enterprise; plugins de exportação da comunidade são o caminho gratuito). https://developers.figma.com/docs/rest-api/variables/