Estou dos dois lados do handoff há mais de 10 anos. Escrevi briefs como designer e recebi como desenvolvedor. A lacuna entre o que a maioria dos designers escreve e o que os desenvolvedores precisam para construir corretamente não é causada por desenvolvedores não se importarem com design. O brief é otimizado para o leitor errado.
Para Que Serve um Brief de Verdade
Um brief existe para dar ao desenvolvedor tudo que ele precisa para implementar a feature corretamente sem precisar agendar uma reunião de acompanhamento. Cada seção que não serve a esse propósito é ruído que reduz a probabilidade do desenvolvedor ler o documento. Parei de participar de handoffs de revisão de design que na verdade eram showcases do processo de design. Os que eu bloqueava na agenda eram aqueles onde o autor claramente tinha pensado no que eu precisaria para não voltar com perguntas.
As Cinco Seções Que Importam
- 1. Especificação de comportamento: o que acontece quando o usuário faz X. Não como parece. O que faz. Cubra todo estado interativo: hover, focus, active, disabled, loading.
- 2. Casos extremos e estados de erro: estados vazios, estados de carregamento, estados de erro de API, mensagens de validação. Essas são as partes que os desenvolvedores vão inventar se você não especificar. Estados inventados são estados inconsistentes.
- 3. Comportamento responsivo: breakpoints exatos, o que muda no layout em cada breakpoint, quais elementos se reordenam ou colapsam. Não 'mobile-friendly'. Específico.
- 4. Inventário de componentes: quais componentes existentes são usados, quais são novos, nomes exatos dos componentes Figma que correspondem aos nomes dos componentes Angular.
- 5. Fora do escopo: liste explicitamente o que NÃO está nesta implementação. Isso previne scope creep e cria um registro compartilhado para decisões futuras.
Estados de Erro São Inegociáveis em Produtos Financeiros
Em um produto financeiro, mensagens de erro não são polimento de UX. Uma mensagem de falha de pagamento vaga demais vira uma ligação para o suporte em vez de uma nova tentativa. Um alerta de cheque especial ambíguo gera volume no call center. Quando liderei a UX do PWA de cartão de crédito na Wonderlabs, eu especificava cada estado de erro, o texto exato e a condição de gatilho, e fiz o mesmo no redesign da plataforma IRIS na Strongest Families, onde o que estava em jogo era diferente mas a disciplina era idêntica. Se o brief não tem essa tabela, a implementação terá mensagens de erro inventadas. A tabela abaixo foi escrita para este post. É uma ilustração, não uma spec de nenhum produto em que trabalhei.
## Error States: Transfer Form (illustrative)
| State | Trigger | Message | Component |
|-------|---------|---------|----------|
| Required field empty | Submit with empty field | "This field is required" | FormFieldError |
| Amount exceeds balance | amount > accountBalance | "Insufficient funds. Your available balance is $X.XX" | FormFieldError |
| API timeout | Response > 30s | "Something went wrong. Please try again." | InlineAlert (warning) |
| Daily limit exceeded | amount > dailyTransferLimit | "You've reached your daily transfer limit of $X,XXX" | InlineAlert (warning) |
| Invalid recipient account | 422 from API | "We couldn't find an account with that number. Check the details and try again." | FormFieldError |Comportamento Responsivo Exige Especificidade
Dizer 'mobile-friendly' em um brief não é uma especificação. Especifique os breakpoints para os quais você está projetando. Certifique-se de que correspondam aos breakpoints definidos nos seus design tokens. Documente o que muda no layout em cada um e quais interações mudam. Uma sidebar que colapsa para um bottom sheet em 768px precisa estar escrita, não visível apenas nos frames do Figma se você souber onde procurar. Um desenvolvedor trabalhando a partir de um brief não deveria precisar fazer engenharia reversa do comportamento responsivo comparando frames.
Veja como isso fica para um exemplo inventado, um card de resumo de fatura em um app de cartão de crédito. Nenhum dos valores abaixo vem de um produto real. Em 1280px ou mais, o card renderiza em um grid de duas colunas com os detalhes da conta à esquerda e os botões de ação empilhados à direita. Abaixo de 1280px o layout muda para coluna única: os botões de ação vão para baixo dos detalhes, e o card vai de ponta a ponta com 16px de padding horizontal. Em 375px ou menos o card remove a ação secundária completamente. O link 'Ver histórico' fica oculto e acessível apenas pela página de detalhes da conta. Essa decisão precisa estar no brief. Um desenvolvedor que não a vê vai ou renderizar o link mesmo assim e quebrar o layout, ou removê-lo globalmente e quebrar o desktop.
## Responsive Behavior: Statement Summary Card (illustrative)
| Breakpoint | Layout | Changes |
|------------|--------|---------|
| >= 1280px | 2-column grid | Account details left, actions right |
| 376px to 1279px | 1-column stack | Actions move below details, edge-to-edge card, 16px horizontal padding |
| <= 375px | 1-column, reduced | Hide 'View history' link |Nomenclatura de Componentes Que Conecta os Dois Mundos
Eu insisto em alinhar os nomes dos componentes Figma com os nomes dos componentes Angular antes de qualquer brief ser escrito. Se o componente Figma se chama 'Pill/Status/Success' e o componente Angular é StatusBadge, cada brief que referencia esse componente cria um problema de tradução. Nomenclatura inconsistente se acumula em um time até que os handoffs precisem de um glossário.
A convenção que eu uso: PascalCase, substantivo primeiro, específico ao invés de genérico. Não 'Card' quando 'StatementSummaryCard' é o que você quer dizer. Não 'Dialog' quando 'ConfirmTransferDialog' é o que você quer dizer. Nomes genéricos no Figma se tornam referências ambíguas nos briefs que se tornam escolhas erradas de componentes no Angular. A sessão de alinhamento de nomenclatura é uma reunião só. Ela se paga na primeira vez que um brief nomeia um componente e ninguém precisa perguntar qual é.
Um brief não está pronto quando todos os caminhos felizes estão documentados. Está pronto quando cada estado que um usuário pode encontrar tem um comportamento especificado.
O Formato Importa Mais Do Que Você Pensa
Mantenha o brief curto. Use tabelas para estados. Use links anotados do Figma que vão diretamente ao frame relevante, não à raiz do arquivo. Se o documento tem mais de quatro páginas, você provavelmente incluiu coisas que deveriam estar no ticket do Jira ou no arquivo de design. Desenvolvedores têm contexto do planejamento e refinamento de stories. O brief preenche as lacunas de implementação nesse contexto. Ele não substitui todos os outros documentos.
Um link do Figma que aponta para a raiz do arquivo força o desenvolvedor a navegar até o frame certo por conta própria. Em um arquivo grande isso é um desvio, e acontece toda vez que ele cruza referências com o brief. Linke diretamente para o frame. Use o 'Copy link to selection' do Figma (clique com o botão direito no frame, depois Copy/Paste as) em cada frame que você referencia. Se estiver referenciando uma variante específica de componente, selecione essa variante e copie o link. Isso custa alguns segundos por link. Economiza minutos por sessão para o desenvolvedor e elimina a fricção ambiente que faz as pessoas pararem de abrir o brief.
Os briefs que são lidos são os que tratam o tempo do desenvolvedor como valioso. Curtos, estruturados, completos em estados e comportamento, com links diretos do Figma. Os que não são lidos são os que documentam o processo de pensamento de design para uma audiência que não estava na revisão de design. Conheça seu leitor.
Aqui está a diferença em uma única visão. Os nomes de componentes e endpoints abaixo são inventados para este post.
Referências
- Figma developer handoff guide. https://www.figma.com/best-practices/guide-to-developer-handoff/
- WCAG 2.2 Understanding SC 3.3.1 Error Identification. https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html
- WCAG 2.2 Understanding SC 3.3.3 Error Suggestion. https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html