Design system vs component library: a diferença que custa dinheiro

Uma component library é um conjunto de partes de interface codificadas e reutilizáveis com APIs definidas. Um design system é o conjunto completo de decisões que governa como uma interface parece e se comporta — além dos artefatos que codificam essas decisões, sendo que um deles geralmente é uma component library.

Isso é preciso, mas levemente inútil, pois não ajuda você a identificar qual dos dois você possui. Aqui está um teste que ajuda.

A maioria das equipes falha nesse teste e fica surpresa, porque a component library parecia ser a parte difícil. Era a parte cara. Mas não era a parte que determina se o produto tem identidade própria.

Essa última linha é a que merece ser lida duas vezes. O fracasso de uma component library é visível — dois date pickers, três implementações de botões, um bug corrigido em um e não no outro. O fracasso de um design system é invisível por dentro: tudo é consistente, nada está errado e o produto poderia ser de qualquer pessoa.

Aqui está a parte contraintuitiva. Adotar uma component library bem feita às vezes faz com que um produto pareça *mais* genérico, e não menos, e vale a pena entender o mecanismo em vez de culpar a biblioteca.

Uma biblioteca vem com padrões. Esses padrões são, por necessidade, neutros — eles precisam funcionar para milhares de produtos não relacionados, portanto, codificam a versão menos opinativa de cada decisão. Instale-a e você terá herdado um conjunto completo de decisões de design que foram escolhidas especificamente por serem inofensivas.

Antes da biblioteca, o produto não tinha sistema e parecia inconsistente. Depois, ele tem um sistema, mas é de outra pessoa, ajustado para a máxima generalidade. A inconsistência é corrigida e o problema de identidade é criado — e como o segundo problema não gera erros, ele passa muito tempo sem ser nomeado.

Este não é um argumento contra component libraries. É um argumento de que instalar uma completa apenas metade do trabalho, e a metade que ela completa é aquela que já era visível.

Vários termos adjacentes são usados de forma intercambiável. Eles não são sinônimos; são fatias diferentes.

Um token set merece atenção especial porque é o artefato mais frequentemente confundido com um sistema completo. Um arquivo de valores nomeados é genuinamente necessário e não diz a ninguém para que --color-primary pode ser usado — que é a decisão que determina se a interface parece contida ou como um template temático.

Quatro coisas, nenhuma das quais pode viver na API de um componente, e todas elas decidem a aparência do produto.

1. 1

   Regras de composição

   Como os componentes se posicionam juntos. Uma ação primária por seção. Controles relacionados agrupados, não relacionados separados por um passo completo de espaçamento. Tabelas nunca aninhadas dentro de cards. Uma component library não tem opinião sobre o que envolve seus componentes, e o espaço entre componentes ocupa a maior parte de uma tela.

2. 2

   Densidade e ritmo

   Se esta é uma ferramenta densa ou uma superfície de marketing espaçosa. O mesmo Button, com 8px de padding em uma linha de tabela e 16px em um hero, produz dois produtos diferentes. A biblioteca suporta ambos e não escolhe nenhum.

3. 3

   Motivos

   Aquele elemento recorrente e específico que torna o design único — um tratamento de borda particular, o uso característico de uma linha de regra, uma forma consistente de desenhar gráficos. Motifs são a diferença entre o que é correto e o que é característico, e eles não existem em lugar nenhum de uma API de componentes.

4. 4

   Proibições

   O que nunca deve ser feito. Sem gradientes. Sem elevação de sombra. Sem peso de fonte acima de 600. Nenhuma cor fora do conjunto de tokens. Uma biblioteca de componentes não pode proibir nada, porque proibir é a única coisa que uma biblioteca de propósito geral não deve fazer.

O ponto de proibição generaliza além do design. O trabalho de uma biblioteca é ser utilizável por muitos produtos, o que significa permitir tudo o que for razoável. O trabalho de um sistema é tornar um único produto coerente, o que exige descartar a maior parte disso. Eles são estruturalmente opostos, e é por isso que um não pode substituir o outro.

A diferença é mais fácil de notar em uma única primitiva. Uma biblioteca de componentes oferece um Button com uma prop variant e nenhuma opinião sobre a aparência de cada variante. Um sistema decide — e a decisão cobre estados para os quais a biblioteca deixou apenas um espaço:

A distinção era suportável quando humanos escreviam cada tela. Um desenvolvedor que tivesse visto as últimas dez telas absorvia as convenções não escritas e, em grande parte, as reproduzia. O design system existia na cabeça das pessoas, sem documentação, e isso funcionava enquanto as pessoas permaneciam na equipe.

Um agente de código de IA não possui essa memória. Ele lê o que está no repositório, escreve uma tela e começa do zero. Tudo o que a equipe sabia e nunca escreveu simplesmente não existe, e o agente preenche a lacuna com a média estatística de tudo o que já viu — que é por que interfaces geradas por IA convergem para a mesma aparência.

Analisamos 299 arquivos DESIGN.md escritos especificamente para fechar essa lacuna. Os números mostram que a maioria não consegue: 86% especificam cores como hex puro sem função semântica, 76% não declaram proibição alguma, 57% não definem motifs, 69% não dizem nada sobre dark mode e 44% não contêm nenhum valor de tamanho concreto. 54% dependem de pelo menos um adjetivo vago, com "clean" em 39% e "modern" em 36%.

Comparando com os quatro itens acima, temos um corpus de arquivos que documentam a biblioteca de componentes e a chamam de design system. As regras de composição, a decisão de densidade, os motifs e as proibições estão, em sua maioria, ausentes.

A boa notícia é que você não precisa reconstruir nada. Se você tem uma biblioteca de componentes e tokens, a camada do design system é um documento, e ele é curto.

## Intent

A dense tool for people who work in it for hours. Quiet, information-first.
Not a marketing surface: nothing here has to convince anyone of anything.

## Density

Controls: 8-12px padding. Table rows: 32px. Section gap: 32px.
Marketing surfaces run one step up on every value.

## Elevation

A surface step plus a 1px border. Never a box-shadow.

## Composition

One primary action per section. Related controls share a group;
unrelated ones are separated by a full spacing step.
Tables are never nested inside cards.

## Motifs

Section headings carry a 2px accent rule on the left edge.
Numeric columns are always tabular-nums, always right-aligned.

## Never

- No gradients
- No drop shadows
- No font-weight above 600
- No colour value outside the token set
- No border-radius above 12px

Trinta linhas. Ele não contém nada que sua biblioteca de componentes já saiba, mas contém tudo o que um novo engenheiro — ou um agente — precisa para construir uma tela que pertença ao seu produto, e não aos padrões da biblioteca.

Quase sempre de ambos, mas a ordem depende de onde está a dor.