Componente.md

Um sistema de projeto é o conjunto de regras, comportamentos e relações que governam como uma linguagem de projeto se expressa. Os componentes são uma expressão dessa linguagem, em uma superfície, em um momento específico. Na última década, a área usou os termos “sistema de projeto” e “biblioteca de componentes” como se fossem sinônimos. Nunca foram. Essa fusão funcionava quando o leitor do artefato era um engenheiro humano capaz de preencher as lacunas do arquivo. Ela deixa de funcionar no momento em que o leitor se torna uma ferramenta.

Durante o último ano, tenho testado ferramentas de IA nos meus arquivos do Figma. Figma Make, Claude Code, Lovable. Na semana passada, o Claude Design foi lançado e eu estava ansioso para experimentá-lo.

O design nunca fica exatamente como eu o imaginei. Fica parecido, mas nunca perfeito. O alinhamento óptico está errado. A fonte está incorreta. O espaçamento entre os elementos está alguns pixels fora do lugar. Os detalhes que tornam um componente único foram definidos por palpite: microinterações, comportamentos e atribuições específicas de tokens.

É isso que acontece quando um projeto é entregue a uma ferramenta sem uma especificação. Um arquivo do Figma está repleto de informações. Uma ferramenta que trabalha apenas com essas informações precisa adivinhar tudo o que o arquivo não diz.

Este não é um problema exclusivo da Claude Design. É um problema de todas as ferramentas da categoria, e a origem do problema está no modelo em si. Essa lacuna é a linha divisória entre um brinquedo e uma ferramenta que pode ser comercializada.

Os LLMs são bons na estrutura geral. Eles perdem a essência, a parte que torna um componente único, a parte que uma captura de tela e um prompt não conseguem transmitir. Descobrir o que deu errado e consertar custa mais tempo e tokens do que construir o componente.

Eu crio e mantenho linguagens de design e bibliotecas de componentes que centenas de engenheiros e designers utilizam diariamente em seus projetos. As lacunas que descreverei a seguir não são um exercício teórico. São os problemas que ocorreram esta semana e que eu precisei corrigir. Corrigi-los é o meu trabalho.

A qualidade dessas ferramentas é determinada pela equipe de projeto durante a transição para o modelo, e não pela equipe de modelagem em si.

As soluções alternativas já estão por toda parte. Colamos capturas de tela em prompts. Executamos servidores MCP que extraem frames do Figma e esperamos que a ferramenta os junte novamente em algo coerente. Elas existem porque o arquivo do Figma nunca foi concebido para ser lido por uma ferramenta. Ele foi feito para ser lido por um humano que pudesse preencher as lacunas. O leitor mudou.

Por que isso continua acontecendo?

Algo mudou silenciosamente em relação ao que é o trabalho de um designer. Não faz muito tempo, o produto final era um frame. Do outro lado, um humano, geralmente um engenheiro, lia, interpretava, preenchia as lacunas e enviava o código. Essa camada de interpretação era compreendida, estava prevista no orçamento e fazia parte do trabalho.

Essa camada de interpretação agora é uma ferramenta. Quando um designer entrega um componente para o Claude Design ou o Figma Make, não há mais um tradutor humano no meio. A ferramenta lê o artefato diretamente e gera o código. A maioria dos sistemas de design ainda não chegou a esse ponto. Ainda estamos enviando frames para um leitor que precisa de uma especificação.

A fonte de verdade para um componente hoje em dia está dispersa: parte no arquivo do Figma, parte na cabeça do designer, o resto em conversas no Slack e revisões de código. A maioria das equipes de design não pensa nisso como um problema de fonte de verdade. Mas é exatamente isso que é.

O Figma é uma fonte de informação, não a fonte da verdade.

É um bom ponto de partida para definir o que um componente deve ser: mover pixels de forma eficiente, testar variantes e compartilhar ideias. Ele fornece muitas informações à ferramenta: dimensões, cores, variantes, a árvore de camadas. Mas não informa qual token controla qual estado, como o foco se move ou o que o componente comunica a um leitor de tela. Uma ferramenta que lê o arquivo obtém a aparência e tenta adivinhar o resto. É aí que começam as suposições.

O que tem que ser verdade

Duas coisas precisam ser verdadeiras para que tudo isso funcione. O componente precisa se tornar o artefato, e não uma imagem dele.

Os componentes precisam se autoavaliar. O modelo antigo era de documentação estática, lida da mesma forma por todos e interpretada individualmente. O novo modelo é de documentação interativa, que se adapta a quem a lê. Mesmo arquivo, leitores diferentes, respostas diferentes.

Os componentes precisam ser compiláveis. Qualquer LLM deve ser capaz de ler um componente e produzir uma implementação fiel em qualquer plataforma. Sem necessidade de adivinhar a intenção, pois a ferramenta está lendo uma especificação em vez de interpretar uma renderização.

Essa é a mudança. Um sistema onde cada componente pode ser consultado, analisado e utilizado para construção, tanto por humanos quanto por LLMs (Learning Learning Machines), sem a necessidade de um tradutor humano em cada etapa do processo.

Componente.md

O arquivo Component.md é o artefato que torna ambas as afirmações verdadeiras simultaneamente. Um arquivo Markdown por componente. Independente de plataforma. Concebido para ser a fonte da verdade que o arquivo Figma nunca foi projetado para ser. Um repositório do conhecimento necessário para que um componente seja construído em qualquer plataforma.

O esquema é o seguinte:

• Especificação da API: propriedades, subcomponentes, exemplos de configuração
• Especificações estruturais: dimensões, espaçamento, como os valores variam em função da densidade, tamanho e forma.
• Atribuição de cores: os tokens que regem cada elemento em cada estado.
• Especificações de voz/leitor de tela: ordem de foco, anúncios, diferenças entre plataformas (VoiceOver, TalkBack, ARIA)
• Especificação comportamental: regras de dispensa, estados de erro, estados vazios

Além do esquema, o arquivo se adapta ao componente. Especificações de movimento. Árvores de decisão para quando usar cada variante. Contraexemplos de como o componente não deve ser usado. Notas de migração. O esquema é o contrato. O que o preenche é o componente.

Eis como um estado de erro se apresenta na prática. A especificação de cores e a especificação do leitor de tela estão no mesmo arquivo, pertencem ao mesmo componente e são distribuídas juntas.

# Text field

## When validationState === 'error'

### Color
| Element          | Token                    |
|------------------|--------------------------|
| Container stroke | error-border-accessible  |
| Hint icon        | error-content-primary    |
| Hint text        | error-content-primary    |

### Voice (ARIA)
| Property         | Value       |
|------------------|-------------|
| aria-invalid     | true        |
| aria-errormessage| error-id    |
| hint node role   | alert       |

Implement together, or the component ships half-broken.

Ele fica ao lado do arquivo Figma, não no lugar dele. O Figma permanece onde é mais eficiente. O arquivo .md armazena as decisões depois de tomadas.

Por ser Markdown, qualquer editor de código consegue lê-lo. Ele pode ser exposto através do MCP. Você pode entregá-lo ao Claude Design, Claude Code, Figma Make ou qualquer outra ferramenta que surgir no futuro e receber de volta uma implementação que corresponda à sua intenção, independentemente da plataforma que você esteja visando.

Os humanos também o leem. Um designer ou engenheiro o consulta quando precisa de uma resposta.

Um designer de funcionalidades que está criando um fluxo de finalização de compra pergunta: qual é a ordem das ações em um grupo de botões empilhados?

Um engenheiro que analisa uma solicitação de pull request se depara com uma questão diferente: posso misturar tamanhos de botões em um grupo empilhado?

Os sites de documentação estática foram construídos partindo do pressuposto de que o leitor era um ser humano com vinte minutos disponíveis e o contexto necessário para interpretar uma página. Essa premissa já não se sustenta. O leitor, por vezes, é uma ferramenta sem contexto, e frequentemente um designer ou engenheiro de funcionalidades que tem uma dúvida e precisa de uma resposta, não de uma página para analisar. Uma especificação que uma pessoa pode consultar é a mesma especificação a partir da qual uma ferramenta pode construir.

A especificação é a interface. Qualquer pessoa, ou qualquer coisa, pode consultá-la.

Como funciona

Duas etapas: extração determinística, criação agentiva.

A extração é feita através do plugin uSpec para Figma. Ele guia você pelos subcomponentes do elemento que você está especificando e pergunta quais deles precisam de suas próprias especificações e quais são apenas decorativos. Um campo de texto possui um rótulo, uma entrada e um texto de dica. Cada um desses elementos pode ser digno de especificação por si só, ou pode ser apenas um complemento. Você decide. O resultado final é um conjunto de arquivos JSON que descrevem a essência do componente.

Quando a criação começa, a maior parte do trabalho já está feita. O plugin extraiu todas as informações do arquivo Figma: layout, variantes, tokens, a árvore de camadas, tudo. O que resta é a interpretação.

A criação é feita por meio de uma nova habilidade: create-component-md . Ela repassa os dados extraídos para um conjunto de agentes especializados, cada um analisando uma parte diferente do que foi gerado pelo Figma: um para estrutura, um para cor, um para comportamento do leitor de tela. Eles são executados em paralelo. Nenhum deles precisa esperar pelo outro para concluir sua tarefa.

Só então, os resultados são convergidos e analisados ​​em um único arquivo component.md. Uma etapa de reconciliação identifica quaisquer lacunas e executa novamente o programa especializado responsável por elas.

O mesmo campo de texto, de três maneiras: o arquivo Figma que a ferramenta lê hoje, o que a ferramenta envia apenas desse arquivo e o que ela envia com o arquivo component.md incluído. A diferença é a variação entre as duas versões, agora visível.

Por que a separação é importante?

Um script pode extrair números de qualquer arquivo do Figma, organizado ou não. Mas ele não consegue explicar o significado desses números. Essa é a lacuna. A forma como um componente é construído no Figma raramente corresponde à forma como ele é construído no código. Arquivos reais têm nomes inconsistentes, soluções alternativas criadas para contornar as limitações do Figma e padrões estruturais que carregam um significado semântico que a árvore de camadas não consegue expressar.

Um caso comum: um item de lista com uma opção booleana que alterna o conteúdo inicial. Quando a opção booleana está ativada, o designer pode escolher entre imagem, ícone ou texto.

Programaticamente, o Figma lê isso como

leadingContent: true, 
subcomponent: icon 

Em engenharia, é um único enum:

leadingContent: "icon" | "image" | "text" | "none". 

A extração mecânica fornece o primeiro resultado. Chegar ao segundo requer interpretação.

Extrair dados sem raciocinar é despejar dados sem pensar. Raciocinar sem extrair dados é uma ilusão.

Extrair números de um arquivo do Figma não exige um modelo para raciocinar sobre eles. Exige um script, e scripts são gratuitos.

O raciocínio só entra em ação onde realmente importa: na interpretação do significado desses números. O LLM nunca executa tarefas que um script pode fazer automaticamente e nunca precisa manter o despejo de dados bruto em sua janela de contexto enquanto tenta processar os dados. O resultado é uma especificação que retorna resultados mais rápidos e com menor custo, e um modelo capaz de pensar onde o raciocínio é essencial.

O que muda quando os componentes podem responder?

O público-alvo do sistema de design dobrou. Na última década, o construímos pensando nos humanos que o utilizavam. Agora, o construímos pensando nos humanos e nas ferramentas que esses humanos usam. Esse segundo público está crescendo rapidamente e seus critérios são diferentes: ele precisa que as decisões sejam documentadas, não implícitas.

A equipe deixa de ser o gargalo. As dúvidas são respondidas sem que ninguém da equipe de sistemas de design precise estar online. O que resta é o trabalho que impulsiona o sistema.

As ferramentas de design estão mortas?

Toda semana me fazem uma pergunta parecida. De gerentes de engenharia. De designers. De gerentes de projeto. Da minha esposa, no último domingo. A resposta é sempre a mesma.

Não. O papel deles está prestes a mudar.

As ferramentas de design são onde o planejamento acontece. Onde os detalhes são fáceis de iterar, onde as variantes são testadas, onde a estrutura é refinada antes de qualquer coisa ser implementada. Os detalhes são o trabalho, e o Figma é onde você pode se preocupar com eles sem consequências. Esse trabalho importa ainda mais agora.

O que está mudando é a transição. Pela primeira vez, o construtor não é um humano interpretando um arquivo. É uma ferramenta lendo uma especificação. O Figma não morre. Ele simplesmente deixa de ser solicitado a realizar uma tarefa para a qual nunca foi projetado.

Para onde isso está nos levando?

Um arquiteto não inicia uma obra a partir de um esboço. Ele esboça no estúdio, modela variantes, testa a estrutura e, em seguida, registra as decisões em uma planta. A planta é o que todo empreiteiro lê. Ninguém liga para o arquiteto à meia-noite. O Figma é o estúdio. A especificação é a planta. O edifício é o que é entregue.

O trabalho de sistemas de design sempre teve como objetivo garantir que a intenção do projeto se mantenha na implementação. Essa aposta se mostra diferente agora que a camada de implementação é um LLM (Learning Learning Machine). Os componentes deixam de ser imagens em um arquivo. Eles se tornam objetos a partir dos quais qualquer ferramenta pode construir e objetos que qualquer pessoa pode consultar.

Qualquer pessoa que lidere um sistema de design tem a mesma pergunta a responder: seus componentes ainda serão legíveis apenas por humanos daqui a um ano?

O sistema de design sempre foi a linguagem. Finalmente, ele tem um lugar para viver.