Yesterday's lesson covered how an agent reads a Figma file. Today: how a whole team keeps design and code in sync over time — without redlines, screenshots, or "just eyeball it".
A designer works in a tool that thinks in shapes, layers, and pixels. A developer works in a tool that thinks in components, variables, and constraints. Handoff is the process — and the artifacts — that translate one into the other without losing intent along the way.
Done badly, handoff means a developer squinting at a static image, guessing at a hex code, and shipping something that's "close enough." Multiply that by every button, spacing value, and font size in a product, and small drifts compound into a UI that visibly doesn't match the design file anymore — the classic complaint of "design debt."
2. The old way: redlines and screenshots
For years, handoff meant a designer manually annotating a screenshot: arrows pointing at spacing values, a callout box with a hex code, a note saying "16px padding, this exact blue." Tools like Zeplin and Figma's own older inspect panel formalized this into auto-generated redlines — still just numbers on top of a static image.
Problem
Why it happens
Values go stale
The design file gets updated; the redline screenshot doesn't. Nobody remembers to regenerate it.
No source of truth
The same blue might get typed as #1a73e8 in one component and #1A73E8 (or a slightly different shade) in another — both "correct" by eye, both wrong in practice.
States are invisible
A screenshot shows one state (usually default). Hover, focus, disabled, error — all left to the developer's imagination.
Doesn't scale
Fine for five screens. Falls apart for a product with hundreds of components across multiple platforms.
3. Design tokens: the actual fix
A design token is a named, platform-agnostic value that stands in for a raw design decision — a color, a spacing unit, a font size, a border radius, an animation duration. Instead of a component using #7c3aed directly, it uses a token like color.accent.default, which resolves to that hex value in one single place.
The point isn't the naming convention — it's the indirection. Change the token's definition once, and every component referencing it updates automatically, in both the design file and the codebase, without hunting down every occurrence.
The mental model: tokens are to design what environment variables are to code. You don't hardcode a database URL in twenty files — you reference DATABASE_URL once and let it resolve differently per environment. Tokens do the same for visual decisions, and can resolve differently per theme (light/dark) or per brand.
4. How tokens travel from Figma to code
Figma's native Variables feature (colors, numbers, strings, booleans) is the design-side half of a token system. The pipeline that turns those into usable code generally looks like this:
Define — a designer sets up variables in Figma: color/bg/primary, space/md, radius/sm, organized into collections, often with light/dark modes as different values of the same variable.
Extract — variables get pulled out of Figma, either via the REST API, a plugin (Tokens Studio is the most established one), or — as covered in yesterday's lesson — an MCP server that an agent can query directly (get_variable_defs in Figma's MCP tools returns exactly this).
Transform — a tool like Style Dictionary takes that raw token data (usually JSON) and generates platform-specific output: CSS custom properties for web, a Tailwind config, XML for Android, Swift constants for iOS — all from one source.
Consume — components reference the generated tokens (var(--color-accent), or a Tailwind class backed by the token), never a raw value.
5. A worked example: one button, three layers
Take a primary button. In Figma, its fill is bound to a variable called color/accent/default, its corner radius to radius/md, its horizontal padding to space/lg.
Style Dictionary transforms that token set into CSS:
Now when the designer nudges the accent color in Figma — say, for a rebrand — updating that one variable regenerates the CSS, and every button, badge, and link across the entire product shifts color at once. No hunting through components, no drift.
6. Where token systems break in practice
Failure mode
What causes it
Token sprawl
Someone creates color/blue/2 instead of reusing an existing token, because they didn't know it existed. Without governance, the token list grows as messy as raw hex codes ever were.
Semantic vs primitive confusion
Primitive tokens (blue-500) describe a raw value; semantic tokens (color/accent/default) describe intent. Skipping the semantic layer and wiring components straight to primitives means a rebrand requires touching every component again — the exact problem tokens were meant to solve.
One-way sync
Tokens get extracted from Figma into code once, then the two drift apart as each side gets edited independently with no pipeline keeping them aligned.
Missing responsive/state variants
A token system covering only default states still leaves hover, focus, disabled, and breakpoint behavior to guesswork — tokens solve the value problem, not the completeness problem.
7. What a good handoff spec includes
Tokens solve the "what's this color" problem. A complete handoff spec still needs to cover everything tokens don't:
Layout — spacing, alignment, and how the component behaves in its container (fixed width vs fill vs hug).
Design tokens used — which color, spacing, radius, and typography tokens this specific component consumes.
Component props — the variants that exist (size, tone, disabled) and how each maps to a visual change.
Interaction states — default, hover, focus, active, disabled, loading, error — each one, not just the happy path.
Responsive breakpoints — what changes at each screen size, not just "it's responsive."
Edge cases — empty states, overflow/truncation behavior, extremely long text.
Animation details — duration, easing curve, what triggers it.
A token system without this layer still leaves a developer guessing at behavior. A handoff spec without a token system still leaves colors and spacing drifting over time. The two are complementary — not a choice between one or the other.
Share:
Newsletter
Learn what AI is creating for you. Don't get lost.
Get notified when a new deep dive or lesson goes up. No spam, just new posts.
Semana 4 · Lição 18
Do Figma ao código: handoff e design tokens
A lição de ontem cobriu como um agente lê um arquivo do Figma. Hoje: como um time inteiro mantém design e código sincronizados ao longo do tempo — sem redline, sem print de tela, sem "olhometro".
Um designer trabalha numa ferramenta que pensa em formas, camadas e pixels. Um desenvolvedor trabalha numa ferramenta que pensa em componentes, variáveis e restrições. Handoff é o processo — e os artefatos — que traduzem um pro outro sem perder a intenção pelo caminho.
Feito mal, handoff significa um desenvolvedor apertando os olhos pra uma imagem estática, chutando um código hexadecimal, e entregando algo "próximo o suficiente". Multiplique isso por cada botão, valor de espaçamento e tamanho de fonte de um produto, e pequenos desvios se acumulam até a UI visivelmente não bater mais com o arquivo de design — a clássica "dívida de design".
2. O jeito antigo: redlines e prints
Por anos, handoff significava um designer anotando manualmente um print de tela: setas apontando pra valores de espaçamento, uma caixa de anotação com um código hex, uma nota dizendo "16px de padding, esse azul exato". Ferramentas como Zeplin e o antigo painel de inspeção do próprio Figma formalizaram isso em redlines gerados automaticamente — mas ainda são só números em cima de uma imagem estática.
Problema
Por que acontece
Valores ficam desatualizados
O arquivo de design é atualizado; o print do redline não. Ninguém lembra de regerar.
Sem fonte única de verdade
O mesmo azul pode acabar digitado como #1a73e8 num componente e #1A73E8 (ou um tom ligeiramente diferente) em outro — ambos "corretos" a olho nu, ambos errados na prática.
Estados ficam invisíveis
Um print mostra um estado (geralmente o padrão). Hover, foco, desabilitado, erro — tudo deixado pra imaginação do desenvolvedor.
Não escala
Funciona bem pra cinco telas. Desmorona pra um produto com centenas de componentes em múltiplas plataformas.
3. Design tokens: a solução de verdade
Um design token é um valor nomeado e agnóstico de plataforma que substitui uma decisão de design crua — uma cor, uma unidade de espaçamento, um tamanho de fonte, um raio de borda, uma duração de animação. Em vez de um componente usar #7c3aed diretamente, ele usa um token como color.accent.default, que resolve pra esse valor hex num único lugar.
O ponto não é a convenção de nome — é a indireção. Mude a definição do token uma vez, e todo componente que referencia ele é atualizado automaticamente, tanto no arquivo de design quanto no código, sem precisar caçar cada ocorrência.
O modelo mental: tokens estão pro design assim como variáveis de ambiente estão pro código. Você não hardcoda uma URL de banco de dados em vinte arquivos — você referencia DATABASE_URL uma vez e deixa ela resolver diferente por ambiente. Tokens fazem o mesmo pra decisões visuais, e podem resolver diferente por tema (claro/escuro) ou por marca.
4. Como os tokens viajam do Figma pro código
O recurso nativo de Variables do Figma (cores, números, strings, booleanos) é a metade do lado do design de um sistema de tokens. O pipeline que transforma isso em código utilizável geralmente é assim:
Definir — um designer configura variáveis no Figma: color/bg/primary, space/md, radius/sm, organizadas em coleções, muitas vezes com modos claro/escuro como valores diferentes da mesma variável.
Extrair — as variáveis são puxadas do Figma, seja via API REST, um plugin (o Tokens Studio é o mais consolidado), ou — como visto na lição de ontem — um servidor MCP que um agente consegue consultar diretamente (get_variable_defs nas ferramentas MCP do Figma retorna exatamente isso).
Transformar — uma ferramenta como o Style Dictionary pega esses dados brutos de token (geralmente JSON) e gera saída específica de plataforma: custom properties de CSS pra web, um config do Tailwind, XML pro Android, constantes Swift pro iOS — tudo a partir de uma fonte só.
Consumir — os componentes referenciam os tokens gerados (var(--color-accent), ou uma classe do Tailwind apoiada no token), nunca um valor cru.
5. Um exemplo prático: um botão, três camadas
Pegue um botão primário. No Figma, o preenchimento dele está vinculado a uma variável chamada color/accent/default, o raio da borda a radius/md, o padding horizontal a space/lg.
O Style Dictionary transforma esse conjunto de tokens em CSS:
Agora, quando o designer ajusta a cor de destaque no Figma — digamos, pra um rebranding — atualizar essa única variável regera o CSS, e todo botão, badge e link do produto inteiro muda de cor de uma vez. Sem caçar componente por componente, sem desvio.
6. Onde sistemas de token quebram na prática
Modo de falha
O que causa
Explosão de tokens
Alguém cria color/blue/2 em vez de reusar um token existente, porque não sabia que ele existia. Sem governança, a lista de tokens cresce tão bagunçada quanto os códigos hex crus eram antes.
Confusão entre semântico e primitivo
Tokens primitivos (blue-500) descrevem um valor cru; tokens semânticos (color/accent/default) descrevem intenção. Pular a camada semântica e ligar componentes direto nos primitivos significa que um rebranding exige mexer em todo componente de novo — exatamente o problema que os tokens deveriam resolver.
Sincronização de mão única
Os tokens são extraídos do Figma pro código uma vez, e depois os dois se distanciam conforme cada lado é editado independentemente, sem um pipeline mantendo os dois alinhados.
Faltam variantes responsivas/de estado
Um sistema de tokens que cobre só o estado padrão ainda deixa hover, foco, desabilitado e comportamento por breakpoint no chute — tokens resolvem o problema do valor, não o da completude.
7. O que uma boa spec de handoff inclui
Tokens resolvem o problema de "qual é essa cor". Uma spec de handoff completa ainda precisa cobrir tudo que os tokens não cobrem:
Layout — espaçamento, alinhamento, e como o componente se comporta dentro do container (largura fixa vs preencher vs abraçar o conteúdo).
Tokens de design usados — quais tokens de cor, espaçamento, raio e tipografia esse componente específico consome.
Props do componente — as variantes que existem (tamanho, tom, desabilitado) e como cada uma mapeia pra uma mudança visual.
Estados de interação — padrão, hover, foco, ativo, desabilitado, carregando, erro — cada um deles, não só o caminho feliz.
Breakpoints responsivos — o que muda em cada tamanho de tela, não só "é responsivo".
Casos extremos — estados vazios, comportamento de overflow/truncamento, texto extremamente longo.
Detalhes de animação — duração, curva de easing, o que dispara.
Um sistema de tokens sem essa camada ainda deixa um desenvolvedor chutando comportamento. Uma spec de handoff sem sistema de tokens ainda deixa cores e espaçamentos se desviando com o tempo. Os dois são complementares — não uma escolha entre um ou outro.
Compartilhar:
Newsletter
Saiba o que a IA está criando pra você. Não fique por fora.
Seja avisado quando eu postar uma imersão ou lição nova. Sem spam, só posts novos.