Design system para uma plataforma de IA B2B

Visão geral

Um design system para uma plataforma B2B de IA, há cinco anos em produção. Reconstruí uma UI fragmentada e hardcoded numa biblioteca baseada em tokens que os times de produto e engenharia consomem todo dia.

Contexto

A interface tinha crescido por remendo. A maioria dos componentes era hardcoded, os estilos eram copiados entre eles, e o mesmo elemento aparecia e se comportava diferente de uma tela pra outra. Não havia camada de token nem contrato de componente compartilhado, então cada novo estado significava duplicar CSS e adicionar mais uma prop avulsa. A camada legada carregava cerca de oitenta componentes feitos assim, cada um com a própria lógica de variante (um usava variant, outro category, outro size), então nada compunha e nada era previsível.

Papel

Conduzi o design system de ponta a ponta. Arquitetura, camada de tokens, contrato de componentes e documentação, tudo construído em código, junto dos times de produto e engenharia que consomem o sistema todo dia. Dono único do design do sistema, do primeiro token a uma biblioteca de cerca de sessenta componentes em produção diária.

Processo

Reconstruí o sistema do fundamento pra cima, em código, sem parar o produto.

• Base no shadcn, estendida. Importei os componentes pro projeto e fui além, adaptando e atualizando, adicionando funcionalidade e subcomponentes, e criando novos primitivos, em vez de consumir uma lib fechada.
• Camada de token primeiro. Cerca de duzentos tokens, paletas primitivas de cor mais uma camada semântica (primary, secondary, success, warning, destructive, superfícies, bordas), com escalas de tipografia, espaçamento e radius. A cor mora em variáveis CSS, então o mesmo componente carrega light e dark sem ramificar.
• Um contrato único de componente. Cada componente novo expõe as opções por uma API declarativa de variante em vez de classes condicionais escritas à mão, então um badge varia por intenção, radius e shape de uma vez sem duplicar estilo.
• Primitivos acessíveis por baixo. Os componentes interativos compõem primitivos headless, então comportamento de teclado e ARIA fica correto por padrão, não reimplementado componente a componente.
• Migração por reuso, não reescrever tudo. Movi primeiro os fundacionais de maior reuso (input, button, badge), depois os overlays, depois os componentes de dados, substituindo os legados conforme o produto adotava.

Resultado

• Há cinco anos em produção, consumido todo dia pelos times de produto e engenharia.
• Cerca de sessenta componentes reconstruídos sobre o novo fundamento, substituindo a camada legada hardcoded conforme são adotados.
• Documentado em Storybook com 200+ stories e visual regression, então uma mudança é revisada antes de subir.
• Light e dark dos mesmos tokens, com as decisões de design escritas em vez de viverem na cabeça das pessoas.

Arquitetura de componentes

O sistema é organizado em camadas, do bloco mais genérico ao mais composto.

• Primitivos. Os blocos base, agnósticos de uso (button, input, badge e os de layout). Carregam os tokens e não conhecem o produto.
• Semânticos. Primitivos com intenção. A API fala em significado (intent, status, superfície), ligada à camada semântica de tokens em vez de valor cru.
• Shared. Componentes reusados entre features, ainda agnósticos de caso de uso, que mantêm o produto consistente.
• Featured. Componentes presos a uma feature específica do produto, que já conhecem seus dados e contexto.
• Shell. A camada que compõe as features na moldura do app, navegação, rotas e layout. O DocView vive aqui, os painéis que exibem os itens do produto, com drag-and-drop pra reordenar e painéis de detalhe que abrem sobre o item.

Documentação, para pessoas e máquinas

O sistema entrega duas camadas de documentação. O Storybook é a superfície de auditoria, cada componente e cada estado com visual regression, então uma mudança é revisada antes de subir. O Fumadocs é a referência que o time lê, as regras de uso e o porquê, escritas pra serem entendidas, não só folheadas.

A documentação é escrita para pessoas e para máquinas. O formato é estruturado pra um agente de IA consumir e ajudar o dev a montar telas a partir do sistema em vez do zero. Isso corta o tempo de construir uma tela, os tokens gastos no caminho e o retrabalho que vem de adivinhar. Documentação bem organizada é o mecanismo inteiro.

Componentes de UI e de IA

A biblioteca não é só de primitivos de UI. Entrega também componentes de IA, os blocos que as features de IA do produto usam, chat, prompt input, chain-of-thought, artifacts, citações. O sistema cobre a superfície que um produto conversacional baseado em RAG realmente precisa.

Aprendizados

Três coisas foram decisivas. Migrar por reuso em vez de reescrever tudo foi o que deixou o sistema substituir a camada legada sem nunca parar o produto. O caminho mais lento foi o único que entregou. Tratar a documentação como parte do produto, não como anexo, foi o que fez o sistema ser de fato adotado. Os componentes pesaram menos que o fato de as pessoas, e agora a IA, encontrarem o porquê por trás deles. E estruturar os componentes em camadas, do primitivo ao shell, foi a parte mais nova pra mim e a que deu ordem ao sistema.

Tags

Design System · IA · Product