01 / 10

Trabalho com o Claude Code ligado ao Figma todos os dias. Ele lê o ficheiro, escreve nele e conta o que lá está. Este artigo diz onde é que essa ajuda entra: primeiro na construção do design system, depois no uso dele nos ecrãs dos produtos da marca, o LMS e o ICP.

O projeto onde mais o uso é o do SkillUp, uma plataforma de e-learning B2B onde sou responsável pelo design de produto e pelo design system, para várias marcas. Não mostro ecrãs do produto: os desenhos são esquemas, com exemplos inventados.

Onde ajuda, numa tabela

Onde	O que lhe peço	O que fica comigo
Tokens	Escrever os que faltam e religar os componentes	Os nomes e as camadas
Grelha	Encontrar os valores fora da escala	A escala
Componentes	Contar o uso, mover para a biblioteca, reduzir variantes	O que entra na biblioteca
Ecrãs	Tablet e telemóvel, e todos os estados	O conteúdo e a hierarquia
Verificação	Auditorias e críticas	O que se corrige, e como
Entrega	Handoffs e protótipos	O que segue para desenvolvimento

Na construção do design system

Tokens: a fundação que ele respeita

Um token é um valor com nome. A fundação tem três camadas, e a regra entre elas é curta:

• Primitivos. Os valores em bruto: as rampas de cor, a escala numérica, os tamanhos de letra. É a única camada onde existe um valor hexadecimal.
• Semânticos. Nomes que dizem o papel e não a cor: text-primary, bg-brand-solid, border-brand. Só apontam para primitivos.
• Componentes. Ligam-se aos semânticos, nunca aos primitivos.

No Figma, isto são quatro coleções de variáveis: os primitivos; os semânticos, onde vivem o claro e o escuro; as marcas, com um modo por marca; e uma coleção responsiva, com os modos desktop, tablet e telemóvel. Quando a biblioteca foi publicada, tinha mais de mil variáveis.

Onde o Claude ajuda. No trabalho de precisão que se repete centenas de vezes. O sistema partiu de uma base que já existia, e quando quis retirar a camada de cor antiga havia algumas centenas de tokens antigos, dos quais só umas dezenas tinham equivalente no nosso sistema. Escrevemos os que faltavam e ele religou os componentes. No fim, dezenas de páginas da biblioteca ficaram com zero ligações à camada antiga, confirmadas por uma contagem separada do script que fez as alterações.

Porque começo aqui. Um agente trabalha bem dentro de regras. Com um token para cada decisão, o que ele desenha sai dentro do sistema. Sem tokens, sai um valor parecido.

A grelha de 4 pontos: ele encontra o que foge

Uso uma grelha de 4 pontos. A escala de espaçamento é esta: 0, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, e continua. O 2 e o 6 não são múltiplos de 4, mas fazem parte da escala. Os tokens têm nomes de tamanho (spacing-md são 8, spacing-lg 12, spacing-xl 16, spacing-3xl 24), e cada margem, padding e intervalo usa um deles.

Onde o Claude ajuda. Nas auditorias. Numa delas, encontrou em componentes espaçamentos de 10, 14, 18 e 22. Nenhum existe na escala. Passaram para 8, 12, 16 e 20, o que mexeu as coisas 2 px. Um raio de 3 passou a 2. Com uma escala fechada, um valor fora dela é um erro que se consegue contar, e contar é o que ele faz depressa.

A tipografia não segue a grelha à risca: o texto de 14 tem entrelinha de 20, e o de 12 tem 18. Mantive a rampa que existia.

Componentes: ele conta o uso e faz a mudança

Os componentes base já existiam. Os do produto saem dos ecrãs: só depois de os ecrãs existirem é que sei quantas variantes um componente precisa, e quais nunca chegaram a ser usadas.

• Mover para a biblioteca. Algumas dezenas de componentes locais foram movidos para a biblioteca. Depois da troca, o Claude contou: mais de mil instâncias a apontar para a biblioteca, e nenhuma para um componente local.
• Medir o uso. Pedi-lhe para ler no Figma que componentes os ecrãs usam, e quantas vezes. Um deles foi colocado à mão um punhado de vezes e aparece centenas de vezes dentro de outros componentes. É um número que ninguém adivinha.
• Reduzir variantes. A etiqueta que herdámos tinha algumas centenas de variantes. A nova tem cerca de uma centena: estilos, tamanhos e cores, com um átomo privado que guarda a estrutura.
• Procurar antes de construir. Numa só página, estivemos mais de uma vez para construir uma coisa que a biblioteca já tinha, com um nome que as nossas pesquisas não apanhavam.

No uso, nos ecrãs dos produtos

Com a fundação feita, o trabalho de todos os dias passa a ser desenhar ecrãs reais, com o conteúdo e os estados que cada produto tem, no LMS e no ICP, em três larguras. O que a biblioteca já tem usa-se. O que falta desenha-se no próprio ecrã, ligado aos tokens, e fica local ao ficheiro até passar pela revisão dos colegas.

É aqui que peço mais coisas ao Claude:

• Ecrãs. As versões de tablet e de telemóvel de um ecrã de desktop, com os mesmos componentes e tokens. Uma das páginas entregues para desenvolvimento tem mais de uma dúzia de cartões: cada ecrã nas três larguras.
• Casos-limite. Uma página com todos os estados de um componente. Num cartão de pergunta, eram muitos, e ao catálogo faltava precisamente o estado mais recente.
• Auditorias. Contar os valores sem token, página a página: numa passagem deu de nenhum a várias dezenas por página. Ou os nomes das camadas: algumas centenas, em vários milhares, tinham o nome que o Figma dá por omissão. Ou o contraste: várias centenas de verificações, nenhuma a falhar no nível AA, com os pares lidos do ficheiro de tokens e não de uma lista escrita à mão.
• Críticas. Uma leitura do protótipo a 1280 e a 375 de largura. Uma delas apontou três botões primários iguais na mesma vista. A correção foi uma ação primária por lista.
• Handoffs. Os tokens em CSS, o inventário de componentes, a especificação dos ecrãs e os fluxos do protótipo. No Figma, as molduras de entrega ficam sem nomes genéricos e sem camadas escondidas.
• Protótipos. Uma aplicação React a sério, construída a partir desse pacote, e um Storybook. Os tokens do protótipo foram comparados com os do Figma: mais de uma centena de cores nos modos das marcas, todas iguais menos duas. Essas duas juntam cor e opacidade, e a comparação não as conseguiu ler.

Antes de cada alteração grande à biblioteca, fica uma versão com nome no Figma, para poder voltar atrás.

O que custou, e o que tive de corrigir

Tema e marca no mesmo eixo. Na primeira versão, o claro e o escuro partilhavam os modos com a marca: duas marcas e dois temas davam quatro modos, e uma terceira marca daria seis. As marcas ganharam uma coleção própria. Durante algum tempo, a marca ficou expressa em dois sítios, e um componente só se pode ligar a um.

O que vem com uma base herdada. Partir de uma base que já existe poupa os componentes base, mas traz os tokens dela. Faltavam categorias inteiras: não existia um único token para o estado desativado. A coleção antiga ainda não pôde ser apagada: sobram rampas e valores sem destino.

Uma regra que não aguentou. «O secundário fica um passo dentro do primário» deu um rosa forte no erro, ao lado de tons pálidos no aviso e no sucesso. As rampas de cor não são paralelas. Uma regra escrita como número de passo tem de ser conferida na cor que aparece.

Sucessos silenciosos. Há chamadas à API do Figma que não dão erro e deixam o resultado errado. O Claude mantém uma lista com dezenas. Numa auditoria feita depois de umas horas de alterações seguidas apareceram vários defeitos, todos introduzidos nessas horas. A regra que ficou: depois de qualquer alteração de estrutura, ler o estado de volta e contar.

O que fica comigo, e o que não medi

A ordem, as regras, os nomes e o que entra na biblioteca são decisões minhas e da equipa. O Claude executa, conta e avisa quando a contagem não bate certo.

Não medi quanto tempo isto poupa, e por isso este artigo não tem esse número. O que consigo mostrar é o que passou a ser contável: valores sem token, instâncias locais, pares de contraste.

Se queres montar ou arrumar um design system para trabalhar com IA, fala comigo.