Construir componentes, usar o registro e publicar o catálogo

Mudar a cor de um botão que vive na biblioteca de outra empresa leva dias de conversa com quem a mantém. O mesmo botão, como arquivo seu, muda em um commit, a gravação da mudança no projeto.

Todo componente, a peça repetida da tela como o botão ou o cartão, tem um dono do código. Esse dono decide o custo de mudar a cara do site daqui a um ano.

Quem aprova ou constrói o produto da empresa escolhe entre biblioteca instalada, componente copiado e primitiva sem estilo, com o foco de teclado testado em cinco segundos.

Na biblioteca instalada, como Mantine ou HeroUI, o código fica na pasta de dependências. Mudar a aparência vira disputa com quem desenhou. No modelo do shadcn/ui, o componente vira um arquivo seu, com Tailwind (as classes prontas de estilo) no visual e uma primitiva acessível por baixo. Editar o arquivo muda a peça em todas as telas.

A primitiva sem estilo, como Radix, Base UI ou React Aria, entrega comportamento e acessibilidade. A aparência sai inteira dos seus tokens (os valores de cor e espaço guardados com nome, como a etiqueta na lata de tinta). É a resposta certa quando a marca já tem desenho próprio e nenhum visual pronto serve.

O shadcn/ui segue a recomendação padrão em React (a biblioteca mais usada para montar telas), e 2026 mostra o ritmo. Dependências unificadas no pacote radix-ui em fevereiro, CLI v4 em março, registries próprios com validação em maio, componentes de chat em junho e componentes React Aria em julho.

Com o arquivo no seu repositório, o agente (a ferramenta de IA que escreve o código) muda uma variante ou corrige o foco sem esbarrar em código alheio. Abra o arquivo LICENSE antes de instalar qualquer peça: MIT e Apache 2.0 liberam uso comercial, e a checagem leva menos de um minuto.

A primitiva decide o que é difícil: prender o foco no diálogo, devolvê-lo ao fechar, fechar com Esc e falar com o leitor de tela. O Base UI, do MUI, está estável desde dezembro de 2025, com Drawer e OTPField estáveis e a camada mais ativa de 2026. O Radix UI 1.6.7 virou pacote único, com o PasswordToggleField em prévia.

O React Aria lança peça todo mês e é a escolha quando teclado e leitor de tela são requisito de contrato, em governo ou finanças. Fora do React, a primitiva segue o framework (a base que organiza o código das telas). Ark UI com Zag.js, Headless UI, Melt UI, Bits UI e Kobalte cobrem React, Vue, Svelte e Solid.

Dois avisos de 2026. O Chakra UI v3 foi reescrito sobre Panda CSS e Ark UI, e sair do v2 custa migração; o Mantine é a troca natural para quem desiste. O HeroUI v3 está em beta, e o daisyUI segue com classes semânticas e mais de 30 temas sem JavaScript.

O Web Awesome 3.0, ex-Shoelace, foi rebatizado pela Font Awesome com núcleo gratuito, e o repositório antigo foi arquivado em 14/05/2026. É a escolha para Web Components puros (as peças que rodam sem framework nenhum), quando o site precisa durar mais que o framework da vez.

Kits de blocos montam a página inteira sobre o shadcn. Origin UI traz primitivas neutras, Magic UI marketing animado e Aceternity UI efeito visual. Shadcn Blocks soma 193 blocos até agosto, 21st.dev é um registry com o Magic MCP para o agente instalar, e Tremor Blocks cobre painéis.

O risco é o kit de cartões SaaS que a skill frontend-design lista como padrão genérico. Cartões idênticos, um raio de canto para tudo e a mesma sombra cinza embaixo de cada um. Peça o bloco e depois peça a hierarquia de volta: o cartão que importa maior, o resto quieto.

Cinco segundos bastam para o teste de foco: aperte Tab várias vezes e veja se dá para saber onde o teclado está em cada parada. O erro mais comum é focus:ring-2 no lugar de focus-visible:ring-2. O primeiro esconde o anel de todo mundo; o segundo mostra só a quem navega pelo teclado.

role="menu" em navegação simples é anti-padrão, e o agente aplica esse papel sempre que lê a palavra menu. O papel promete setas, Home, End e Esc, e uma lista de links do site não os entrega. Navegar entre páginas pede lista de links; executar comando pede menu de ação, com teclado próprio.

Numa imobiliária com agenda de visita pelo site, o diálogo de confirmação foi feito com div solto. O interessado aperta Tab, cai atrás da janela e não sabe se a visita foi marcada. Trocar o div pela primitiva do Base UI prende o foco, fecha com Esc e devolve o foco ao botão, sem linha própria.

O laboratório abaixo monta esse diálogo com o Dialog e o Popover do Base UI. A biblioteca não traz uma linha de estilo: cor, raio e sombra saem dos tokens do curso. O elemento raiz recebe isolation: isolate, como a documentação pede, para a janela ficar acima de qualquer camada da página, sem disputa de z-index (a ordem de empilhamento).

Abra a janela, aperte Tab até dar a volta, feche com Esc e leia o painel que registra onde o teclado parou. O botão que pergunta por que pedimos o telefone abre um Popover posicionado ao lado; Esc fecha só ele e devolve o foco. O que a primitiva entrega de graça é o que o div solto negava.

Instale o primeiro componente do shadcn/ui e altere o raio de canto no arquivo. A mudança tem de chegar a toda tela que usa a peça, sem você editar mais nada. Rode o instalador de novo só depois de ler o git diff, porque ele sobrescreve o que você editou. Teste o foco com Tab antes de aprovar.

Organize suas peças num conjunto e publique o catálogo

Com a primitiva escolhida e o foco de teclado testado, falta a ordem de montagem: tokens, peças, variantes, página de prova e catálogo publicado.

Três a cinco componentes consistentes bastam para nascer um design system, o conjunto de peças da casa com cores e nomes iguais, como um jogo de louça. O catálogo desse conjunto se instala com um comando.

Quem tem dois ou três componentes soltos organiza antes que cresçam, com os quatro passos, o catálogo no Storybook e o registry no ar.

O primeiro passo são os tokens (os valores de cor, espaço e tipografia guardados com nome, como a etiqueta na lata de tinta). O segundo são as peças lendo esses tokens: depois do botão vêm o campo, o cartão e o diálogo. Cor cravada num arquivo é a peça que sobrevive à próxima troca de marca e denuncia a inconsistência.

Terceiro vem um vocabulário único de variantes e tamanhos. Quando principal, perigo, pequeno, médio e grande significam a mesma coisa em todo componente, o agente (a ferramenta de IA que escreve o código) acerta. O quarto é a página de prova, que mostra cada componente em cada variante e estado, lendo os tokens. Quando algo quebra, quebra ali primeiro.

Quando o mesmo botão aparece em mais de três telas, a página de prova sobe um degrau para o Storybook. É o catálogo que mostra cada peça isolada, como a vitrine de amostras da loja de tintas. Cada estado vira uma história, e o painel de acessibilidade acusa a violação antes de o produto abrir.

A versão 10 é só ESM, com instalação 29% menor. A regressão visual fecha o ciclo. O Playwright fotografa componente e SVG compilado a cada PR (a proposta de mudança no código) e compara com a foto anterior. Um pixel trocado barra a mudança. Ele pega o raio de canto alterado num arquivo compartilhado, invisível na revisão de texto.

O catálogo se distribui de dois jeitos. Os tokens saem no formato DTCG, lido por Figma, Penpot, Tokens Studio, Style Dictionary e Terrazzo, com $value e $type em cada entrada.

As peças saem por um registry do shadcn, o endereço de onde outro projeto instala a peça, como um catálogo de reposição. Desde maio de 2026 a validação barra o item mal descrito antes de publicar.

Um sistema para relatório precisa nomear as peças que a diretoria lê, e o manual dá o vocabulário: kpi-card, variance-table, executive-callout, risk-matrix, marketing-funnel, waterfall-bridge, decision-card, confidence-badge e methodology-note. Nomear faz o agente reaproveitar a peça em vez de inventar outra a cada tela. O cartão de indicador do relatório de vendas é o mesmo do relatório de caixa.

Peça a licença com cada componente instalado, porque código sem licença vira problema quando o produto passa a valer dinheiro. Escreva no CLAUDE.md o alvo de acessibilidade: WCAG 2.2 no nível AA. A norma técnica e a obrigação legal têm escopos diferentes, e a regra do país e do setor se confere antes de declarar conformidade.

A 2.2 acrescentou nove critérios à 2.1, removeu o 4.1.1 de análise de marcação e totaliza 86 critérios somando A, AA e AAA. Dois deles mudam o desenho das peças. O 2.5.8 fixa alvo mínimo de 24 por 24 pixels CSS, com exceções para alvo em linha e espaçamento equivalente. O 3.3.8 proíbe teste cognitivo como única forma de autenticação.

Na prática, o 3.3.8 obriga o campo de senha a aceitar colar e a conviver com gerenciador de credenciais e chave de acesso. O contraste também vai além do 4,5:1 do texto. O critério 1.4.11 pede 3:1 no componente de interface e no elemento gráfico essencial, e é o mais esquecido em design system.

A WCAG 3.0 segue como rascunho de trabalho, sem status normativo e sem jurisdição que a exija, com modelo de conformidade por resultados observáveis. Ela não é meta de conformidade.

Dois botões com verdes diferentes, escolhidos de cabeça, é o que os quatro passos corrigem. Depois deles, o botão de matricular e o de baixar apostila leem o mesmo token, e o Storybook mostra os dois lado a lado.

Suba o Storybook 10 com uma história por variante, o painel de acessibilidade ligado como teste, e publique o primeiro item no registry com npx shadcn build. Fixe fonte e tema antes de fotografar a regressão no Playwright: sem isso, a foto muda sozinha e vira ruído que ninguém confere.

Pegue um componente pronto e adapte à sua marca na hora

O catálogo publicado mostra o que já existe na casa, e componente novo pode chegar do registro adaptado aos seus tokens no mesmo passo.

Um herói colado sem ajuste carrega o azul do autor para dentro da sua marca em um clique. Adaptado no mesmo pedido, ele nasce na cor certa. Um registro é o catálogo de onde o código é copiado, como uma feira de fornecedores, e ele entrega o componente como código seu.

Quem já tem tokens e DESIGN.md ganha um herói ou um formulário pronto sem herdar a estética alheia. Você sabe onde buscar, o que cada fonte cobra e como adaptar a peça no momento de instalar.

A biblioteca é um pacote de peças instalado como dependência, um kit fechado com uma estética e uma versão que alguém mantém. O registro tem muitos autores e muitos estilos, e o código é copiado para o seu repositório. Você vira o dono, e não existe versão deles para atualizar.

O 21st.dev se apresenta como a biblioteca viva de interfaces, com mais de 12 mil componentes React, templates e temas shadcn de mais de 700 autores nomeados. Aceternity UI, Magic UI, shadcn/ui e Origin UI estão entre eles, e os 2 mil blocos de marketing trazem heróis animados, fundos e degradês.

Cada componente, a peça repetida da tela como o botão ou o cartão, sai como um pedido copiável. O Cursor, o Claude Code, o v0 ou o Lovable reconstroem a peça no projeto, ou ela entra por comando do shadcn CLI. Navegar é grátis, com duas cópias por dia no plano sem assinatura.

O MCP é o protocolo que dá ao agente ferramentas de busca e instalação, como um balcão de pedidos na feira. Ele muda o comportamento da ferramenta de IA que escreve o código. Com o catálogo à mão, o agente escolhe um herói em vez de inventar um, e as prévias chegam como imagem antes do código.

Um registro próprio do time faz o agente instalar o botão da casa em vez de escrever o quarto.

O pedido segue quatro regras. Nomeie a seção e a restrição. Diga o que não pode, como sem biblioteca de animação ou compatível com server component. Peça opções antes do código: mostre quatro heróis que usem CSS em vez de vídeo.

A quarta regra é dar os nomes dos seus tokens, que são os valores de cor e espaço guardados com nome. Assim a peça já entra adaptada, sem segunda rodada.

Os riscos vêm declarados pelo próprio 21st. Registro não tem versão, então ninguém avisa quando o autor corrige um defeito, e dois registros podem sobrescrever o mesmo button.tsx. O CLI resolve dependências sem julgá-las: um item que puxa um runtime de animação por uma transição instala limpo e custa o runtime em toda página.

O shadcn documenta o próprio MCP. A configuração fica no .mcp.json do projeto, criada por npx shadcn@latest mcp, e os registros, inclusive privados com token de acesso, ficam no components.json. O pedido é em linguagem comum: adicione o botão, o diálogo e o card ao projeto.

Duas outras fontes cobrem casos diferentes. O Uiverse é a maior biblioteca aberta de elementos de interface, em HTML e CSS, Tailwind, React e Figma. O Framer Marketplace distribui componentes e plugins presos ao Framer, parte deles gratuita.

O shadcn em si passa despercebido. O relatório da Sailop aponta o shadcn sem modificação, com raio, cor, tipografia e escala de fábrica. Resend e Cal.com, no outro caminho, reescreveram os tokens do tema.

A mesma casa varreu mil sites gerados por IA entre janeiro e março de 2026. O padrão de fábrica apareceu em 89,2% com Tailwind, 78,3% com Inter, 72,1% com a cor primária no arco azul-violeta e 11,2% com #3b82f6. A cadeia explica o número, porque o shadcn/ui nasce sobre o Tailwind e é a biblioteca padrão do v0 da Vercel.

O componente colado como veio carrega esse padrão para dentro da sua marca e vira o padrão da casa na tela seguinte. A adaptação aos tokens acontece no mesmo pedido de instalação, e o componente ganha uma linha no DESIGN.md antes da segunda tela.

Citar o token no próprio pedido de instalação é o que muda o resultado. Numa loja de materiais de construção, o herói animado do 21st.dev chegou com o laranja-ferrugem da marca no botão porque o pedido nomeou o token. O diff mostrou um runtime de animação inteiro por uma transição de entrada, e ele saiu.

Configure o MCP do shadcn com npx shadcn@latest mcp e peça quatro opções com restrição antes do código. Instale a escolhida citando os nomes dos seus tokens no mesmo pedido. Leia o diff antes de aceitar e anote a peça no DESIGN.md; sem token seu citado e sem o diff lido, o componente ainda é do autor.

Guia prático: seção de prova social com o MCP do shadcn/ui

Prova social é o conjunto de sinais de que outras pessoas já compraram e aprovaram: depoimento, logotipo de cliente, nota e número de alunos. Na landing page ela responde à objeção antes do formulário. O roteiro abaixo monta a seção com peças do registro, adaptadas aos seus tokens no mesmo pedido.

O que mudou desde a escrita deste capítulo: a documentação do shadcn/ui passou a indicar o comando shadcn@latest mcp init --client claude para o Claude Code, com arquivo próprio para Cursor, VS Code e Codex. Em agosto de 2026 os registros no GitHub passaram a funcionar com repositório privado, e em setembro todo componente passou a importar cn de um pacote único.

A Tailwind Labs anunciou em 9 de setembro de 2026 a entrada na Shopify. O Tailwind CSS e os demais projetos abertos seguem com licença MIT e a mesma equipe; o Tailwind Plus fechou para novos clientes.

Guia prático: pedir um componente da biblioteca e adaptá-lo à sua marca

Bibliotecas de componentes como o 21st.dev oferecem, ao lado de cada peça, um botão que copia um pedido pronto para colar no agente. A biblioteca de 1.451 componentes estudada em 07/10/2026 segue essa ideia, e todos os pedidos têm a mesma anatomia, com 179 palavras em média:

1. 01O que é: uma linha de descrição.
2. 02Referência: categoria, características visuais e a stack do original.
3. 03Como é usado: o exemplo de import e uso, que fixa a interface do componente.
4. 04Parâmetros: paleta e ajustes numéricos, nos 451 que são shader.
5. 05Requisitos: arquivo único, mobile primeiro, tema claro e escuro, acessibilidade e a lista de dependências permitidas.

A anatomia é boa e serve para qualquer pedido seu. O fecho é que pede cuidado: os pedidos mandam reproduzir o visual o mais fiel possível, e só 5 dos 1.451 falam em adaptar. Copiar fiel traz a paleta e a fonte de outra pessoa para a sua página.

Três números orientam a escolha. Do acervo, 42% (615) não têm licença declarada, mais 18 marcados sem licença; 47% (687) não declaram dependência npm; e 22% (319) usam WebGL, shader ou biblioteca 3D, a maioria com o código de desenho dentro do próprio componente. Escolha primeiro pela licença, depois pelo peso, e só então pela beleza.

Aplicar os recursos ao projeto