Contribuindo para o Design System Sem Quebrar o Que Já Existe

A daily da terça-feira é onde essas coisas morrem. Você passou três dias no Figma construindo o que achou ser uma variante limpa de um seletor de período de datas. A liderança do DS dá uma olhada no link compartilhado, recosta na cadeira e diz: "Já temos esse componente." E você faz o cálculo mentalmente. Ou seus três dias estão perdidos, ou a versão que vai para produção é o componente avulso que você montou às pressas, que não tem dono, e em oito meses um novo designer vai reconstruir chamando de quarta vez.

Os dois resultados são ruins. A boa notícia é que a diferença entre eles é um problema de processo, não de talento. Já vi designers IC entregando em sistemas maduros em duas semanas e já vi profissionais sênior queimando seis meses tentando aprovar uma variante de botão com uma pessoa bloqueando. A diferença raramente era o trabalho. Quase sempre era o modelo de contribuição.

Este é o modelo funcional.

Por Que Isso Importa Agora

Sistemas fragmentados custam mais do que sistemas lentos. Existem dois modos de falha que vejo em todas as equipes que enfrentam esse problema, e eles parecem opostos, mas produzem o mesmo resultado.

O primeiro é o sistema bloqueado por guardiões. O time de DS é dono de tudo. Contribuições precisam de três aprovações e uma vaga no roadmap trimestral. Os ICs desistem após a segunda rejeição. A biblioteca se calcifica. Novos padrões são construídos fora dela porque é mais rápido, e agora você tem um design system que é na verdade um museu.

O segundo é o caos aberto. Qualquer pessoa pode publicar qualquer coisa. No sexto mês, cada squad de produto tem seu próprio componente de dropdown, três botões "primários" em azuis ligeiramente diferentes, e uma página no Figma chamada "TEMPORÁRIO, NÃO USAR" que todo mundo usa. Bem-vindo ao imposto da fragmentação.

Um time de produto típico que avalio tem de 3 a 7 versões "do mesmo" botão no segundo ano. Não porque alguém quis isso. Porque o fluxo de contribuição era restrito demais ou solto demais, e o caminho de menor resistência era construir localmente e nunca enviar de volta.

O modelo abaixo é o caminho do meio. Ele assume que contribuir é uma habilidade de craft, não política, e que o IC que entrega trabalho limpo de DS acumula influência mais rápido do que aquele que constrói uma biblioteca de componentes privada.

Quando Usar o DS Versus Construir um Novo Componente

A maioria das conversas sobre "precisamos de um novo componente" termina assim que alguém aplica o teste 80/20. São duas perguntas:

1. Consigo resolver 80% disso com um componente existente mais props ou uma variante?
2. Se eu adicionar isso, pelo menos 20% dos times vão querer usá-lo em seis meses?

Se a resposta à pergunta 1 for sim, você não precisa de um novo componente. Precisa de uma variante ou prop, que é uma contribuição menor, mais rápida e mais barata. Se a resposta à pergunta 1 for não, mas a resposta à pergunta 2 também for não, isso é um componente avulso. Mantenha localmente, não contamine a biblioteca.

Um novo componente se justifica apenas quando as duas respostas apontam para o caminho certo: o kit existente não cobre o caso, e mais de um time vai reutilizá-lo.

A armadilha que vejo com mais frequência é o que chamo de armadilha do quase-serve. Um designer encontra um componente que cobre 70% do caso. Ele desvincula, ajusta o padding, troca um token e entrega como se fosse "baseado" no existente. Seis meses depois, o componente divergiu em sete formas invisíveis e o responsável pelo design system não tem registro de nada disso. O quase-serve é pior que começar do zero porque finge ser reuso.

Uma árvore de decisão mais simples, em ordem:

• Componente existente, sem mudanças, use-o.
• Componente existente, nova prop ou estado, proponha uma variante no existente.
• Componente existente, mas o comportamento subjacente está errado, proponha uma refatoração, não uma bifurcação.
• Padrão genuinamente novo, vários times precisam, proponha um novo componente.
• Padrão genuinamente novo, só o seu time precisa, construa localmente, marque como local, reavalie em 90 dias.

O último caso é válido. Componentes locais não são um pecado. Fingir que um componente local é um componente de sistema é.

O Fluxo de Contribuição: RFC, Revisão, Entrega e Documentação

Depois de decidir que vale a pena adicionar, o fluxo tem quatro etapas, cada uma com tempo definido. O processo completo deve levar menos de duas semanas para uma contribuição normal. Se demorar mais, algo está errado com o processo, não com o componente.

Etapa 1, RFC (1 a 2 dias). Uma página. Problema, solução proposta, alternativas consideradas, notas de acessibilidade e um esboço. Não seis mockups. O erro que cometi por anos foi investir demais em fidelidade antes da conversa. Um único esboço permite que o responsável pelo DS questione a direção sem que você sinta que precisa defender três dias de trabalho em pixels.

O RFC é também onde você sinaliza dependências: novos tokens, novos ícones, comportamento que toca componentes existentes. Se você descobrir que precisa de um novo token de cor para isso funcionar, isso agora faz parte do RFC, não é uma surpresa no oitavo dia.

Etapa 2, Revisão com o responsável pelo DS (1 a 3 dias). Assíncrono primeiro, síncrono se travar. A revisão não é teatro de aprovação. É uma sessão de codesign. O responsável pelo DS não é seu bloqueador. É a pessoa que vai manter o que você entrega, então o input dele sobre nomenclatura, props e casos extremos é estrutural, não estilístico.

Entre com o RFC, faça três perguntas: isso pertence ao sistema, a forma proposta corresponde aos padrões existentes, e o que estou deixando passar do lado de engenharia. Saia com um sim, não ou precisa-ajustar e um responsável definido do lado do DS que vai revisar o PR final.

Etapa 3, Entrega sob uma flag (3 a 5 dias). Construa no Figma, construa no Storybook, entregue o componente React, Vue ou o que for para uma feature flag ou um canal beta na biblioteca publicada. Entregar sob flag importa porque permite que você e um ou dois adotantes iniciais testem a API sob pressão antes de ela entrar no kit de produção. A maioria dos erros de API aparece no primeiro uso real, não no RFC.

Etapa 4, Documentação e promoção (1 dia). Story publicada, documentação de uso escrita, notas de depreciação se substituir algo, anúncio no canal do DS com um parágrafo sobre "quando usar esse componente." Depois promova de beta para GA na próxima versão da biblioteca.

Se alguma etapa ultrapassar o tempo definido, é um sinal. A etapa 1 estendida significa que o problema não está claro. A etapa 2 estendida significa que o responsável pelo DS tem preocupações estruturais e precisa de uma conversa real, não de mais uma revisão. A etapa 3 estendida geralmente significa que a API está errada e você está remendando ao redor dela. A etapa 4 não se estende. Se você está pulando, está pulando a parte que torna tudo real.

Convenções de Nomenclatura que Resistem ao Tempo

Nomenclatura é a metade entediante da contribuição e é onde a maioria das contribuições falha silenciosamente. Um componente chamado BotaoGrandeAzul vai ser usado por exatamente um time, de forma irônica, e nunca mais. Um componente chamado Button/Primary/Large é adotado porque o nome diz o que é, onde fica e como se relaciona com o restante.

A hierarquia de nomenclatura que se sustenta ao longo do tempo é token, componente, variante, estado. Assim:

• Token: color/primary/600
• Componente: Button
• Variante: Primary, Secondary, Ghost
• Tamanho: Small, Medium, Large
• Estado: Default, Hover, Disabled, Loading

Lendo de cima para baixo: Button/Primary/Large/Hover é inequívoco, ordenável e corresponde a como deve aparecer no painel de componentes do Figma e na navegação do Storybook.

Três regras para incorporar como reflexo:

1. Sem substantivos próprios. Sem BotaoDoBob, sem ModalT3, sem HeroMarketing. O nome descreve o objeto, não quem solicitou.
2. Sem abreviações com menos de 5 caracteres. Btn não economiza nada e prejudica a busca. Notif é pior que Notification.
3. Sem adjetivos de tamanho fora da escala. "Grande" não é um tamanho. Large é. Se sua escala é P/M/G, não introduza GG sem adicioná-lo ao sistema de escala de forma global primeiro.

Quando nomes colidem (e vão colidir, especialmente em sistemas maiores), a regra é: o nome mais genérico pertence ao caso de uso mais genérico. Se marketing quer Card para um card de hero estilizado e o sistema já tem Card para o container de conteúdo genérico, o componente de marketing vira Card/Hero ou HeroCard. O nome base fica com o comportamento base.

Mínimos de Acessibilidade: WCAG AA como Piso

Componentes são entregues com os testes de acessibilidade ou não são entregues. Isso não é meta aspiracional. WCAG AA é o piso, não o teto, e é o piso porque abaixo dele você está entregando componentes que excluem usuários legal e eticamente.

Os mínimos que todo componente precisa cumprir antes de ser incorporado:

Todos esses itens têm ferramentas automatizadas hoje. O axe-core no CI captura os problemas estruturais. O addon a11y do Storybook captura os erros óbvios de contraste e ARIA. O que ele não vai capturar (e que o IC precisa fazer de fato) é o teste de armadilha de teclado: percorra com Tab todos os estados, incluindo modal aberto, dropdown expandido, estado de erro. Armadilhas de teclado são o modo de falha que vejo com mais frequência e são as mais fáceis de testar.

Se você não tem certeza se o componente passa, teste antes de enviar para revisão. Um responsável pelo DS que precisa sinalizar uma falha de contraste na etapa 2 descobriu que você não fez o trabalho. Uma contribuição que chega limpa de acessibilidade é uma contribuição que é aprovada rapidamente.

Higiene da Biblioteca no Figma

O Figma é onde as contribuições apodrecem silenciosamente se você não prestar atenção. Duas coisas importam:

Publicado versus local. Componentes publicados vivem na biblioteca da equipe e se propagam para todos os arquivos que a utilizam. Componentes locais vivem no arquivo em que você está trabalhando e não se propagam para lugar nenhum. O erro é usar um componente local para trabalho de prototipagem e depois esquecer de deletá-lo ou promovê-lo. Seis meses depois o arquivo é aberto e alguém copia o componente local porque tem a forma certa.

Regra: um componente local ou é promovido para a biblioteca publicada em duas semanas, ou é deletado. Não existe terceira opção.

Instâncias desvinculadas são um sinal de alerta. Quando um designer desvincula uma instância, está dizendo: "Precisei deste componente mas ligeiramente diferente e não quis lidar com o sistema." Isso é um sinal. Às vezes a resposta certa é adicionar uma variante. Às vezes é corrigir o componente subjacente. Às vezes o designer estava com pressa. Mas cada instância desvinculada é dado, e a varredura mensal deve acompanhá-las.

A varredura em si é mecânica: uma vez por mês, execute a auditoria de instâncias do Figma (ou um plugin como Instance Finder), liste as instâncias desvinculadas e percorra-as com o designer responsável. Ou reconecte, proponha uma variante ou delete. Trinta minutos de trabalho que evitam três meses de fragmentação.

Paridade Código-Design (Storybook)

Todo componente do Figma tem uma story no Storybook ou não é real. Essa é a regra que colocaria na parede.

O Storybook é o único lugar onde o design e o código coexistem como o mesmo artefato. O Figma mostra como o componente deve parecer. O Storybook mostra como ele realmente é. Quando eles divergem (e sempre divergem), o Storybook é a fonte da verdade, porque é o que o usuário vê.

Uma story real no Storybook para um componente contribuído tem:

• Todas as variantes renderizadas (Primary, Secondary, Ghost etc.)
• Todos os estados renderizados (Default, Hover, Focus, Disabled, Loading, Error)
• Um painel de controles que permite ao revisor alternar as props ao vivo
• Uma função play que exercita a interação por teclado
• Um relatório do addon a11y sem violações
• Baselines de regressão visual incorporadas (Chromatic, Percy ou solução própria)

A regressão visual no CI captura a divergência antes que o PM a perceba. Quando alguém atualiza o componente Button e um token de padding muda dois pixels em quarenta stories, o diff aparece no PR. O responsável pelo DS aprova ou rejeita. Sem quebras surpresa em produção.

Sem isso, você descobre a divergência quando um cliente envia uma captura de tela de um formulário desalinhado no Twitter.

Cadência de Depreciação

As coisas que você entrega eventualmente deixam de ser a resposta certa. Uma disciplina de depreciação é como você evita o problema do sistema-museu.

A cadência que adotaria:

• Revisão trimestral. A cada trimestre, o time de DS mais 2 a 3 designers IC percorrem a biblioteca e sinalizam componentes com: baixo uso (menos de 5 instâncias na base de código), substituídos por uma variante mais nova, ou que não atendem mais aos padrões de acessibilidade ou visuais.
• Janela de depreciação de dois releases. Quando um componente é sinalizado, marque-o como @deprecated no Storybook, adicione um banner de depreciação no Figma e entregue um substituto (ou um caminho de migração). Dê dois ciclos de release (normalmente dois meses) antes da remoção.
• Forneça o codemod. Essa é a parte que os times pulam. Se você está depreciando um componente usado em 200 lugares, "por favor, migre" não é um plano. Entregue o codemod (um script pequeno que reescreve automaticamente <BotaoAntigo> para <Button variant="primary">) para que a migração leve minutos, não semanas. Sem o codemod, a depreciação é ignorada e o componente antigo vive para sempre.

Armadilhas Comuns

As quatro formas como as contribuições falham, em ordem aproximada de frequência:

1. Projetar em isolamento e depois apresentar o resultado pronto. Você passou três dias no Figma. O responsável pelo DS tem trinta segundos de contexto e agora você quer que ele valide seis mockups. Não vai acontecer. Traga esboços cedo, trabalho finalizado tarde.
2. Copiar e colar o componente existente mais próximo e "só ajustar um pouco". A armadilha do quase-serve. Ou comprometa-se com uma variante real ou construa algo novo. Nunca entregue uma versão desvinculada e ajustada como se fosse um componente de sistema.
3. Pular a story no Storybook porque "o dev vai fazer". Não vai, ou vai fazer mal porque não conhece a intenção do design. A story é a sua spec, da mesma forma que o componente no Figma é. Se você não escrever, a interpretação do dev se torna a verdade.
4. Tratar o responsável pelo DS como bloqueador em vez de coautor. Esse é o maior erro de mentalidade. O responsável pelo DS tem mais contexto do que você sobre o que está chegando, o que está sendo depreciado e o que os times vão precisar em breve. Envolva-o cedo e ele acelera a sua contribuição. Evite-o e ele vai desacelerá-la porque precisa fazer engenharia reversa do seu raciocínio.

Templates e Ferramentas

Três artefatos para ter sempre à mão:

Template de RFC de uma página. Problema (máximo de 3 frases), solução proposta (1 esboço e 3 pontos), alternativas consideradas (2 a 3, com o motivo de não usar), notas de acessibilidade, dependências, quem é afetado. Se não couber em uma página, a contribuição não está delimitada o suficiente.

Checklist do componente. Tokens usados, variantes definidas, todos os estados projetados, teste de acessibilidade aprovado, story no Storybook publicada com controles e função play, documentação de uso escrita, baseline de regressão visual incorporada, aviso de depreciação se substituir algo. Cole na frente do monitor.

Template de aviso de depreciação. O que está sendo depreciado, o que o substitui, link para o guia de migração, comando do codemod, data de remoção. Postado no canal do DS, adicionado à página do Storybook, banner no componente do Figma.

Medindo o Sucesso

Você vai saber que o modelo está funcionando quando:

• A contribuição chega à biblioteca publicada em até duas semanas após o RFC. Se demorar mais, algo no fluxo está quebrado.
• Zero instâncias desvinculadas do seu componente após trinta dias. Se estão aparecendo, a API não está cobrindo os casos de uso.
• A story no Storybook existe, tem funções play e zero violações de acessibilidade.
• Outro time adota o componente sem te perguntar. Esse é o sinal real: quando o reuso acontece de forma orgânica, você contribuiu de fato para o sistema, não apenas adicionou a ele.

O IC que entrega trabalho limpo de DS acumula influência mais rápido do que aquele que constrói bibliotecas de componentes privadas, porque cada contribuição limpa torna a próxima mais rápida, para você e para todos os outros.

Saiba Mais

• Descrição de Cargo para Product Designer
• Crítica de Design que Realmente Melhora o Trabalho
• Handoff para Engenharia Sem o Ciclo Interminável de Ajustes Visuais
• Acessibilidade Além do Checklist