Alinhar Design System com desenvolvimento não é apenas “usar os mesmos nomes” ou “exportar tokens”. É garantir que o que existe no Figma possa ser consumido no código com previsibilidade, que o time de produto consiga evoluir o sistema sem criar divergências e que as decisões de design tenham um caminho claro até a implementação. Neste capítulo, o foco é estabelecer estratégias práticas para paridade entre Figma e código em três frentes: tokens (como contrato), nomenclatura (como linguagem comum) e paridade com código (como validação contínua).
O que significa alinhamento com desenvolvimento na prática
Quando falamos em alinhamento, estamos falando de reduzir “tradução” manual. Tradução manual acontece quando o designer entrega uma intenção (ex.: “use a cor primária e um espaçamento médio”) e o desenvolvedor precisa adivinhar qual variável, qual classe, qual componente e qual comportamento equivalem àquela intenção. O resultado típico são implementações levemente diferentes, criação de novas variáveis “temporárias” no código, e um sistema que cresce com duplicações.
Alinhamento, portanto, é transformar o Design System em um contrato verificável. Esse contrato precisa responder, com clareza, a perguntas como: qual token corresponde a este valor? qual componente de código corresponde a este componente do Figma? como eu sei que o componente em produção está usando os tokens corretos? como tratamos exceções sem quebrar o sistema?
Tokens como contrato entre design e código (sem repetir fundamentos)
Mesmo que tokens já tenham sido abordados em capítulos anteriores, aqui o ponto é como eles viram um contrato com desenvolvimento. Um contrato tem três características: (1) é estável o suficiente para ser confiável, (2) tem regras de mudança, e (3) pode ser validado. Para tokens, isso significa: definir um conjunto mínimo “público” (consumido por produto), separar o que é “interno” (aliases e valores base), e garantir que o pipeline de exportação/consumo preserve nomes, tipos e escopos.
Separação entre tokens públicos e internos
Uma estratégia comum para evitar que o código dependa de detalhes frágeis é separar tokens em camadas. A camada pública é a que os componentes e telas devem consumir. A camada interna pode mudar sem quebrar consumidores, desde que a pública permaneça estável.
Continue em nosso aplicativo
Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.
ou continue lendo abaixo...
Baixar o aplicativo
Tokens base (internos): representam valores brutos (ex.: paleta, escala de espaçamento, escala tipográfica). Podem mudar com mais frequência.
Tokens semânticos (públicos): representam intenção (ex.: fundo de superfície, texto primário, borda sutil). Devem ser o principal ponto de consumo.
Tokens de componente (semi-públicos): quando necessário, descrevem decisões específicas de um componente (ex.: altura do botão, padding do chip). Devem existir apenas quando a decisão não é bem representada por tokens semânticos.
O alinhamento com desenvolvimento melhora quando o time combina: “componentes consomem tokens semânticos; tokens de componente são exceção e precisam de justificativa”. Isso reduz o risco de cada componente virar um universo próprio.
Paridade de tipos e unidades
Um ponto que costuma gerar divergência é unidade e tipo. No Figma, tudo parece “px”. No código, você pode ter rem, em, dp, sp, ou números sem unidade dependendo da plataforma. A estratégia aqui é definir um “tipo lógico” para cada token e como ele é representado em cada plataforma.
Espaçamento: no design pode ser 4, 8, 12… No código web pode virar rem (ex.: 8px = 0.5rem se base 16). O token deve manter o nome e o valor pode ser transformado por build.
Raio: pode ser número (React Native) ou string com unidade (CSS). Defina a regra de serialização.
Cor: defina formato (hex, rgba, hsl) e como lidar com alpha. Se o código usa rgba por padrão, o export deve respeitar.
O alinhamento não exige que Figma “fale CSS”, mas exige que o token tenha um tipo claro e que o build/transform seja previsível. O erro comum é exportar “como está” e depois cada time converter manualmente.
Nomenclatura alinhada: o que precisa ser igual e o que pode ser diferente
Mesmo que regras de nomenclatura já tenham sido tratadas, aqui a questão é: quais nomes precisam ser idênticos entre Figma e código para reduzir atrito? E onde faz sentido permitir diferenças?
Três níveis de nomenclatura para alinhar
Nomes de tokens: idealmente idênticos (ou com mapeamento 1:1 automatizado). Se o token chama
color.text.primaryno design, o código deveria consumircolor.text.primary(ou--color-text-primarycom transformação mecânica).Nomes de componentes: devem ser equivalentes, mesmo que não idênticos. Ex.: Figma “Button” e código “Button” é o ideal. Se o código usa “PrimaryButton”, isso já cria ambiguidade quando existem variantes.
Nomes de propriedades/variants: devem mapear para props do componente no código. Ex.: variant=primary/secondary, size=sm/md/lg, state=default/disabled/loading. Quanto mais próximo, menos “tradução” no handoff.
Estratégia de mapeamento quando não dá para ser idêntico
Às vezes o código tem restrições (ex.: tokens em CSS custom properties usam hífen; Android usa nomes em snake_case). A estratégia é assumir que existe um “nome canônico” (geralmente em dot notation) e que cada plataforma aplica uma transformação determinística.
// Nome canônico (design / fonte de verdade lógica): color.text.primary// Web (CSS custom property): --color-text-primary// iOS (Swift): ColorTextPrimary// Android (Kotlin/Compose): color_text_primaryO ponto-chave é: não permitir que cada plataforma invente nomes diferentes sem regra. A regra precisa ser documentada e aplicada por automação (scripts, build, transform). Isso reduz discussões e evita drift.
Paridade com código: como garantir que o que está no Figma existe no repositório
Paridade não é “o código tem um componente parecido”. Paridade é: o componente existe, tem as mesmas variantes e estados relevantes, consome tokens equivalentes, e é usado pelos times de produto. Para chegar nisso, você precisa de um método de comparação e um ritual de sincronização.
Matriz de paridade (design x código)
Uma ferramenta simples e muito eficaz é criar uma matriz de paridade por componente. Ela não precisa ser um documento enorme; pode ser uma tabela em uma página de documentação interna. O objetivo é tornar explícito o que está “em dia” e o que está “faltando”.
Colunas recomendadas: Nome do componente, status (Design pronto / Código pronto / Em progresso), variantes, propriedades, estados, tokens críticos, observações.
Tokens críticos: liste os tokens que não podem divergir (ex.: cor de texto, background, border, spacing principal). Isso ajuda a revisar implementação.
Essa matriz vira uma referência para priorização: em vez de discutir “parece pronto”, o time discute “faltam as variantes X e Y e o estado loading”.
Definição de “Done” compartilhada
Uma das maiores fontes de desalinhamento é cada área ter um “pronto” diferente. O design considera pronto quando o layout está aprovado; o desenvolvimento considera pronto quando passa nos testes; o Design System considera pronto quando é reutilizável e documentado. Para paridade, defina critérios mínimos compartilhados para um componente ser considerado “pronto para consumo”.
Design: variantes e estados definidos, tokens aplicados, comportamento descrito (mesmo que de forma objetiva e curta).
Código: API do componente estável (props), tokens conectados, exemplos de uso, testes mínimos (snapshot/visual ou unit), e publicação em versão consumível.
Integração: ao menos um uso real em produto ou uma story de referência que prove que funciona no fluxo.
Sem esse acordo, o time tende a “empurrar” a responsabilidade para o outro lado, e a paridade nunca se fecha.
Passo a passo prático: desenhando um “contrato” de tokens e props para um componente
A seguir, um passo a passo aplicável para alinhar um componente comum (ex.: Button) entre Figma e código, focando em tokens, nomenclatura e paridade. Adapte para outros componentes.
Passo 1 — Liste decisões que precisam virar tokens (e as que não precisam)
Comece pelo que deve ser consistente em todo o produto. Para um botão, normalmente: cores por intenção, tipografia, altura/padding por tamanho, raio, borda, e estados (hover/focus/pressed/disabled/loading).
Vira token semântico: cor de texto em ação primária, cor de fundo de ação primária, cor de borda em ação secundária, cor de foco.
Vira token de componente (se necessário): altura do botão por size, padding horizontal por size, gap entre ícone e texto.
Não vira token: detalhes puramente estruturais que o componente resolve internamente e não precisam ser expostos (ex.: alinhamento interno padrão), a menos que haja necessidade real de customização.
Passo 2 — Defina um esquema de props que reflita o design (sem expor valores)
O objetivo é que o desenvolvedor não precise de valores. Ele precisa de escolhas. Em vez de “padding=16”, a API deve ser “size=md”. Em vez de “background=#…”, “variant=primary”.
// Exemplo de API esperada no código (conceitual)<Button variant="primary" size="md" iconLeft="plus" loading={false} disabled={false}>Criar</Button>Agora alinhe isso com o que existe no Figma: as propriedades do componente (variants/properties) devem ter os mesmos valores possíveis. Se no Figma existe size=Small/Medium/Large e no código size=sm/md/lg, defina a regra e padronize. O ideal é que ambos usem a mesma enumeração (mesmo texto), para reduzir fricção.
Passo 3 — Mapeie props para tokens (tabela de decisão)
Crie uma tabela simples que diga: para cada combinação relevante de props, quais tokens são usados. Isso evita que o código “improvise” cores e espaçamentos.
variant=primary: background =
color.action.primary.bg, text =color.action.primary.fgvariant=secondary: background =
color.surface.default, border =color.border.default, text =color.text.primarystate=disabled: opacity não deve ser “mágica”; prefira tokens (ex.:
opacity.disabled) ou cores semânticas específicas (ex.:color.action.disabled.bg)
Se o time ainda não tem tokens suficientes para cobrir estados, esse passo revela lacunas reais. A lacuna vira backlog do Design System, não uma solução ad-hoc no componente.
Passo 4 — Defina transformações de nome (se houver múltiplas plataformas)
Se o design usa dot notation e a web usa CSS variables, formalize a transformação. Exemplo: dot notation vira kebab-case com prefixo.
// Regra: color.action.primary.bg -> --color-action-primary-bg// Regra: size.button.height.md -> --size-button-height-mdEsse passo é pequeno, mas evita que cada dev “chute” o nome da variável. A regra deve ser aplicada por automação no build de tokens.
Passo 5 — Valide paridade visual com um “caso de referência”
Escolha um conjunto mínimo de casos que cubra as combinações mais importantes: variantes principais, tamanhos e estados críticos. Exemplo para Button: primary md default, primary md disabled, secondary md default, tertiary sm default, primary md loading.
O objetivo é ter um “pacote de referência” que pode ser comparado entre Figma e código. Em times maduros, isso pode virar testes visuais automatizados. Em times menores, pode ser uma revisão manual guiada por checklist, mas sempre com os mesmos casos.
Estratégias para reduzir divergência ao longo do tempo
Mesmo com contrato inicial, divergência aparece quando produto precisa de algo novo sob pressão. As estratégias abaixo ajudam a absorver mudanças sem quebrar paridade.
Política de exceções: como permitir sem virar regra
Exceções acontecem: uma campanha, uma tela especial, uma necessidade de marca. O problema é quando exceções viram “novos padrões” sem governança. Uma estratégia prática é classificar exceções em três tipos:
Exceção local (não vira sistema): implementada no produto, não entra no Design System. Deve ter prazo ou justificativa.
Extensão do sistema: vira novo token semântico ou nova variante, com revisão e versionamento.
Customização controlada: o componente expõe um ponto de extensão (ex.: slot, override de ícone), mas não expõe valores de estilo arbitrários.
O alinhamento com desenvolvimento melhora quando existe um caminho oficial para cada tipo, evitando “só cria uma variável nova aí”.
Evite “props de estilo” como atalho
Um anti-padrão comum é expor props como padding, color, background no componente do Design System para “resolver rápido”. Isso destrói a paridade com tokens e cria um sistema impossível de manter. Prefira props semânticas (variant, tone, emphasis) e, quando necessário, crie novas opções aprovadas.
Checklist de revisão de implementação (focado em tokens e nomes)
Para cada componente implementado/alterado, revise:
Os tokens usados são semânticos (e não valores hardcoded)?
Os nomes de tokens no código seguem a transformação oficial?
As props do componente correspondem às propriedades do componente no Figma?
Estados críticos (disabled, focus, loading) estão cobertos e usam tokens apropriados?
Há algum novo token criado no código que não existe na fonte de tokens? Se sim, por quê?
Esse checklist é simples, mas cria um hábito de “auditar paridade” em vez de apenas “aprovar visualmente”.
Passo a passo prático: alinhando tokens com repositório e evitando drift
Além do componente, você precisa alinhar o fluxo de tokens com o repositório para evitar que o design mude e o código fique para trás (ou vice-versa). Um passo a passo genérico e aplicável:
Passo 1 — Defina a fonte de verdade operacional
Mesmo que o design seja a fonte de verdade conceitual, operacionalmente o time precisa decidir onde a versão “publicada” vive. Em geral, tokens publicados devem viver no repositório (como artefato versionado), mesmo que sejam gerados a partir do Figma. Isso permite rastrear mudanças, revisar diffs e reverter.
Passo 2 — Estabeleça um ciclo de atualização com gatilhos claros
Gatilho por mudança de design: alteração aprovada em tokens no Figma gera uma atualização no pacote de tokens.
Gatilho por necessidade de produto: demanda por novo estado/variante gera proposta de token/prop, revisada antes de entrar.
Gatilho por auditoria: revisão periódica identifica tokens não usados, duplicados ou inconsistentes.
Sem gatilhos, atualizações viram “quando der”, e o drift cresce.
Passo 3 — Use revisão por diff para tokens
Tokens são dados. Dados devem ser revisados como código: olhando o que mudou. Ao publicar tokens no repositório, a revisão consegue responder: “este token mudou de valor”, “este token foi renomeado”, “este token foi removido”. Isso é essencial para desenvolvimento planejar impacto.
Passo 4 — Garanta compatibilidade por alias quando renomear
Renomear token quebra consumidores. Uma estratégia é manter aliases temporários: o token antigo aponta para o novo durante um período de migração. Isso permite atualizar componentes gradualmente. O importante é que o alias seja explícito e tenha prazo.
// Exemplo conceitual de alias (não depende de ferramenta específica)color.text.default -> alias para color.text.primary (deprecado em 2 versões)Como lidar com diferenças inevitáveis entre Figma e código
Algumas diferenças são inevitáveis: limitações de renderização, fontes, antialiasing, comportamento de layout, e diferenças entre plataformas. O alinhamento saudável não tenta eliminar toda diferença, mas sim tornar diferenças previsíveis e documentadas.
Defina tolerâncias e prioridades
Prioridade alta: tokens semânticos (cores, tipografia, espaçamento), estados de acessibilidade (foco), e comportamento de interação.
Prioridade média: microdiferenças de alinhamento por fonte/renderização, desde que não afetem layout e legibilidade.
Prioridade baixa: diferenças imperceptíveis em sombras/blur quando a plataforma não suporta exatamente o mesmo efeito.
Essa priorização evita discussões intermináveis e foca no que realmente quebra consistência.
Crie “decisões de plataforma” como tokens ou regras
Se uma plataforma precisa de um ajuste sistemático (ex.: tipografia em iOS com line-height diferente), trate isso como regra de transformação ou token específico por plataforma, em vez de ajustes manuais por componente. Assim, a diferença fica centralizada e auditável.
Integração entre times: rituais e artefatos mínimos para manter paridade
Alinhamento não é um evento; é um processo. Para manter paridade, você precisa de rituais leves e artefatos mínimos que conectem design e desenvolvimento.
Ritual: revisão conjunta de mudanças do sistema
Quando houver mudanças em tokens, componentes ou nomenclatura, faça uma revisão curta com representantes de design e dev. A pauta deve ser objetiva: o que mudou, por que mudou, impacto, plano de migração, e data de publicação.
Artefato mínimo: “mapa de equivalência” componente a componente
Para cada componente, mantenha um mapa simples:
Nome no Figma
Nome no código (pacote/import)
Props principais e valores
Tokens críticos consumidos
Exemplos de uso (um ou dois)
Esse mapa reduz dúvidas no dia a dia e acelera onboarding de novos membros.
