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

Trocar a cor de um botão que mora numa biblioteca de terceiro pode levar dias de disputa com quem a mantém; o mesmo botão como arquivo seu muda em um commit. Todo componente do site tem um dono do código, e essa escolha decide quanto custa mudar a aparência 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.

O teste de foco leva cinco segundos: 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.

Instale o primeiro componente do shadcn/ui, altere o raio de canto no arquivo e confira que a mudança chega a toda tela que o usa, sem editar mais nada. Rode o instalador de novo só depois de checar o git diff: ele sobrescreve o que você editou. Teste o foco com Tab no componente mais difícil antes de aprovar a tela.

Monte um mini design system e publique o catálogo com token aberto

Três a cinco componentes consistentes bastam para nascer um design system (o conjunto de peças da empresa com cores e nomes iguais), e o catálogo deles 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.

O terceiro é 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. E contraste não é o 4,5:1 do texto sozinho: 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.

Registro de componentes: o código copiado que vira seu

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, sabendo onde buscar, o que cada fonte cobra e como adaptar a peça ao 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, e 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 é dar os nomes dos seus tokens, os valores de cor e espaço guardados com nome, para a peça ser adaptada no mesmo passo em que entra.

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 de abril de 2026 aponta o shadcn sem modificação, com raio, cor, tipografia e escala de fábrica, enquanto Resend e Cal.com 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, peça quatro opções com restrição antes do código e 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.