Do design ao código

Da maquete ao componente: mudar de estado de espírito

Até aqui, produzias páginas: resultados para mostrar, discutir, validar. O programador do cliente, esse, não integra páginas — integra componentes: blocos autónomos e reutilizáveis (um botão, um cartão, um campo de formulário) que monta na sua aplicação. A passagem do design ao código é antes de mais essa mudança de unidade de pensamento: já não entregas um ecrã, entregas um vocabulário de blocos.

Porque é que isso conta tanto? Porque um botão codificado como componente existe em um único exemplar no código, declinado por parâmetros (a sua variante, o seu tamanho, o seu estado). Corrigir um defeito corrige-o em todo o lado. Pelo contrário, uma página monolítica onde o mesmo botão é copiado-colado doze vezes torna-se ingerível à primeira evolução. É a mesma lógica que os design tokens, um nível acima: o sistema antes da página.

flowchart LR
  D["Design validado no artifact"] --> T["Tokens: variáveis CSS"]
  T --> C["Componentes: props + estados + acessibilidade"]
  C --> I["Integração pelo programador"]
  I --> V["Verificação: estados, teclado, contrastes"]

Anatomia de um bom componente

Um componente bem concebido descreve-se pelas suas props (os seus parâmetros de entrada): para um botão, tipicamente variant (primary, secondary, ghost), size (sm, md, lg) e disabled. Esta interface não é um detalhe técnico: é a tradução em código das decisões do teu design system. Três variantes de botão na maquete = uma prop variant com três valores no código. Se deres por ti a pedir uma quarta variante «só para esta página», é o sinal de que uma decisão de design está a fugir do sistema.

Pede sempre à IA o componente mais um exemplo de uso: ver <Button variant="primary" size="lg">Experimentar gratuitamente</Button> permite avaliar imediatamente se a interface é intuitiva. E precisa o formato de saída desde o início — HTML/CSS puro, React, com ou sem Tailwind — porque converter depois faz perder tempo e introduz desvios.

Os estados interativos: hover, focus, disabled

Eis a diferença mais visível entre um resultado de demonstração e um componente profissional: os estados. Um verdadeiro botão vive quatro vidas no mínimo: repouso, hover (sobrevoo — feedback de que o elemento é clicável), focus (seleção pelo teclado — indispensável, voltaremos a isso), active (o instante do clique) e disabled (ação indisponível). Um componente sem estados não está acabado: é uma imagem que se parece com um botão.

Cada estado deve ser percetível mas coerente: no hover, escurece-se ligeiramente a cor (daí o token --color-primary-hover) e pode elevar-se subtilmente a sombra; no estado disabled, reduz-se a opacidade e muda-se o cursor. As transições devem ser suaves — 150 a 200 ms — para o ambiente tranquilizante da Sereno. E pensa nos componentes para além do botão: um campo de formulário também tem os seus estados (focus, erro, preenchido), um cartão clicável tem o seu hover.

Transforma o botão da landing Sereno num componente React reutilizável:
- props: variant (primary | secondary | ghost), size (sm | md | lg), disabled
- estados visuais: hover (escurece para --color-primary-hover, transição 180ms), focus-visible (anel de 2px em --color-accent, afastado 2px), active (ligeira redução de escala), disabled (opacidade 0.5, cursor not-allowed)
- usa exclusivamente as variáveis CSS do design system fornecido — nenhum valor fixo
- acessibilidade: elemento <button> nativo, focus visível pelo teclado, tamanho mínimo de 44px de altura em md
Entrega o código completo + 3 exemplos de uso (um por variant) + a lista dos tokens usados.

A acessibilidade no código: para além dos contrastes

No capítulo 2, a acessibilidade dizia respeito aos contrastes. No código, ela ganha duas dimensões suplementares. Primeiro a navegação pelo teclado: uma parte dos teus utilizadores não usa rato (deficiência motora, leitores de ecrã, ou simples preferência). Cada elemento interativo deve ser alcançável com Tab e mostrar claramente que está selecionado — é o papel do estado focus-visible, esse anel à volta do botão que certos designers eliminam «porque é feio». Nunca o elimines: estiliza-o para que fique bonito.

Depois a semântica HTML: um botão deve ser um <button>, não um <div> estilizado com um handler de clique. O elemento nativo traz gratuitamente o focus pelo teclado, a ativação com Enter e Espaço, e o anúncio correto aos leitores de ecrã. Mesma lógica para os títulos (<h1>…<h2> por ordem, sem saltar níveis), as listas e os links. A IA produz HTML semântico correto… se o pedires. Acrescenta sistematicamente «HTML semântico e acessível» nos teus prompts de código, e pede uma auditoria: «verifica este componente do ponto de vista da acessibilidade e lista os problemas».

Imagem → interface: partir de uma captura ou de um esboço

Capacidade espetacular e realmente útil: dar uma imagem à IA — captura de ecrã, maquete exportada, ou foto de um esboço a marcador num canto da mesa — e pedir-lhe que reproduza a estrutura em código. Os modelos atuais analisam a disposição, identificam os componentes (navegação, hero, cartões, formulários) e produzem uma interface funcional próxima do original.

Os usos concretos em estúdio: digitalizar um workshop (o cliente desenhou a sua visão no quadro branco — fotografa e codifica em cinco minutos, o efeito é garantido), partir de uma referência («retoma a estrutura desta captura, mas aplica inteiramente o meu design system» — estrutura emprestada, pele personalizada), ou reconstruir o existente (captura do antigo site do cliente como ponto de partida do redesign).

Eis a foto do esboço feito pelo cliente no workshop [imagem anexa].
Reproduz a estrutura desta disposição em HTML/CSS:
- identifica cada zona (navegação, hero, colunas, footer) e nomeia-as em comentários
- aplica o meu design system fornecido abaixo — a estrutura vem do esboço, o estilo vem dos tokens
- onde o esboço for ambíguo, escolhe a interpretação mais simples e assinala-a em comentário
[cola aqui o teu bloco :root]

Manter o código limpo e ligado aos tokens

Último elo: a qualidade do código entregue. Três exigências a formular explicitamente. Um: o código reutiliza os tokens — todo o valor fixo é um bug de coerência (podes pedir uma auditoria: «lista todos os valores fixos restantes neste código e substitui-os pelos tokens apropriados»). Dois: os comentários explicam as escolhas não evidentes, não cada linha — «porquê este z-index» merece um comentário, «isto é um botão» não. Três: os nomes (classes, props, ficheiros) seguem uma convenção coerente que o programador do cliente poderá prolongar.

Ganha também o hábito da releitura crítica: o código gerado é geralmente correto, mas nem sempre ótimo. Regras CSS duplicadas, um seletor demasiado específico, um estado esquecido — pede à IA que releia o seu próprio código («relê este componente como um programador sénior exigente: qualidade, acessibilidade, coerência com os tokens») antes de entregar. Um componente limpo mantém-se; um componente remendado torna-se rapidamente ingerível, e é a reputação do estúdio que está em jogo a cada entrega.