Nota do autor: o Astryx é um sistema de design para React de código aberto da Meta, ainda em versão Beta. Ele reúne componentes, temas e documentação para agentes. Não é um modelo e não vem com uma interface para Modelos de Linguagem Grande.
Ao usar agentes como Claude Code, Cursor ou Codex para alterar interfaces em React, é comum ver situações como estas: o botão de uma página tem cantos arredondados, mas o da página seguinte não; alguns pop-ups fecham ao clicar no fundo, outros não; e os espaçamentos variam entre 12 px e 14 px. O problema não está na capacidade do modelo, mas no fato de o agente não ter um sistema de design consultável. Ele acaba tentando adivinhar os nomes dos componentes e suas props de memória. A proposta do Astryx é fazer com que pessoas e agentes consultem a mesma referência de componentes: as pessoas acessam o site de documentação, e os agentes obtêm o mesmo conteúdo pelo CLI, pelo AGENTS.md ou via MCP.
Este artigo não é uma repetição dos comandos de instalação. A seguir, explico quais informações foram divulgadas pela própria Meta, quais vêm de um teste pontual feito por um autor independente e quais são contagens que podem ser verificadas, mas mudam com o tempo — considerando a data de 10/11/2026. Também listo separadamente os projetos que não são adequados para migração neste momento.
Principal benefício: ao terminar a leitura, você poderá avaliar se o Astryx é adequado para seu projeto em React e conectá-lo, em 4 etapas, a um caminho compartilhado por pessoas e agentes.
A imagem acima é o banner divulgado oficialmente pelo Astryx. Para ver a interface, acesse um destes três canais oficiais. Não incluímos outras capturas de tela neste artigo:
- Site de documentação:
astryx.atmeta.com - Navegador de componentes (Storybook):
astryx.atmeta.com/storybook/ - Teste online (Sandbox):
astryx.atmeta.com/sandbox/
Principais pontos sobre o Astryx: o que ele é e o que não é
Vamos deixar os limites claros. O repositório oficial descreve o Astryx como um sistema de design de código aberto, totalmente personalizável e desenvolvido para que pessoas e Agents trabalhem juntos. A licença é MIT, a linguagem principal é TypeScript e o README informa que o projeto está atualmente em beta, ainda sem chegar à versão 1.0.
| Ponto | Descrição | O que isso significa para você |
|---|---|---|
| Base técnica | O projeto oficial informa que é baseado em React 19+ e StyleX | Projetos com React 18 não estão entre os compatíveis |
| Quantidade de componentes | Segundo os dados oficiais, são mais de 150 componentes acessíveis, com tipos TypeScript | Você encontra quase todos os elementos comuns de uma página |
| Origem da aparência | Há sete temas prontos. As cores, fontes, bordas arredondadas e animações podem ser alteradas na camada de tokens | Para mudar o estilo, basta trocar o tema, sem editar cada componente |
| Acesso para Agents | CLI, arquivo AGENTS.md gerado e MCP remoto |
O Agent consulta a documentação, em vez de escrever com base apenas na memória |
| Interface com modelos | Não é fornecida. A ferramenta de programação precisa conectar o modelo por conta própria, por exemplo, usando a APIYI em apiyi.com | A renderização dos componentes não precisa de um modelo |
A história do Astryx: o que é declarado oficialmente
As afirmações a seguir vêm do README e de um artigo oficial de apresentação publicado em 2026-06-18, assinado pela equipe do Astryx. São declarações oficiais, sem auditoria independente: o Astryx evoluiu durante oito anos dentro da Meta, é o sistema de design mais usado e de maior escala da empresa e dá suporte a mais de 13.000 aplicativos. O artigo também traz uma avaliação: antes, os sistemas de design eram escritos para pessoas lerem; agora, cada vez mais código é escrito por Agents. Por isso, o Astryx foi projetado desde o início para ser operado por IA, em vez de receber uma camada de suporte a Agents depois de pronto.
Há duas datas na linha do tempo, e elas não devem ser confundidas. O artigo oficial foi publicado em 2026-06-18. Já o pacote @astryxdesign/core apareceu pela primeira vez no npm em 2026-06-24. O repositório do GitHub foi criado em 2026-01-09, mas essa é a data de criação do repositório, não a data de lançamento público.
Diferenças entre Astryx, reaproveitar um sistema inteiro e copiar e colar
A apresentação oficial compara duas práticas comuns. A tabela abaixo apenas resume o posicionamento oficial, sem abordar benchmarks:
| Abordagem | Problema apontado na descrição oficial | Papel do Astryx |
|---|---|---|
| Reaproveitar um sistema inteiro: usar diretamente todo o sistema de design de uma grande empresa | O aplicativo acaba com a identidade visual daquela empresa | O sistema cuida do comportamento, da acessibilidade e da qualidade |
| Copiar e colar: fazer fork do código dos componentes em cada projeto | Não há atualizações centralizadas, e cabe a quem usa garantir a acessibilidade | O tema cuida da aparência, com alterações na camada de tokens |
| Astryx: instalar o pacote e mudar a aparência com temas | Ainda está em Beta, na versão 0.x | Quando necessário, use o swizzle para extrair o código-fonte de um componente específico |
O README também lista quatro diferenças. A primeira é a abertura interna: os componentes podem ser combinados em qualquer nível, as peças mais usadas são exportadas diretamente e o swizzle permite trazer o código-fonte completo de um componente para o projeto, para que você passe a mantê-lo. A segunda é que os estilos não ficam bloqueados: você pode sobrescrevê-los com className e usar Tailwind, CSS modules ou CSS comum. A terceira é que dá para personalizar sem criar uma camada de encapsulamento: o tema é, essencialmente, um conjunto de sobrescritas de propriedades personalizadas do CSS. A quarta é que API, documentação e CLI são projetadas em conjunto, para que pessoas e assistentes de IA consultem a mesma referência.
Caso isolado de terceiros: o teste de um autor com a troca de tema
Em 2026-08-13, o LogRocket publicou um artigo em que o autor, Chizaram Ken, conectou o Claude Code ao Astryx e criou três interfaces. Depois, criou as mesmas três usando shadcn/ui. Segundo o próprio autor, ao trocar o tema de neutral para gothic, ele alterou dois arquivos e quatro linhas de código, sem mexer em nenhum arquivo de componente.
Esse foi um experimento do próprio autor, não um benchmark nem um resultado de teste deste artigo. O experimento é anterior à versão atual, 0.7.11; na época, a versão era diferente. Ele pode servir como exemplo da ideia de separar temas e componentes, mas não como conclusão sobre desempenho.
Primeiros passos com o Astryx: conecte pessoas e agentes ao mesmo fluxo em 4 etapas
As quatro etapas abaixo correspondem à documentação oficial Getting Started e Working with AI. Em cada uma, explicamos o que fazer no terminal ou nos arquivos e qual resultado indica que a etapa foi concluída. As instruções foram organizadas com base na documentação oficial; não executamos a instalação neste artigo.
Etapa 1: instale os quatro pacotes do Astryx
- No terminal, execute:
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex - Depois, execute:
npm install -D @astryxdesign/cli - Há comandos equivalentes para pnpm e yarn; os nomes dos pacotes não mudam.
- Critério de conclusão: os quatro pacotes aparecem em
package.json, ereactereact-domestão na versão 19 ou superior.
É obrigatório instalar o StyleX, pois ele é uma dependência peer do core. No entanto, a documentação oficial também explica que o uso do StyleX pelo Astryx para definir estilos é transparente para quem usa a biblioteca: você não precisa migrar seu projeto para StyleX. Os componentes só recebem estilos por meio de xstyle se você optar por usar o StyleX.
Etapa 2: use o init para gerar a documentação que o Agent vai ler
- No terminal, execute:
npx @astryxdesign/cli init - Esse comando não exige interação: pessoas, CI, scripts e Agents podem executá-lo diretamente.
- Critério de conclusão: o arquivo
AGENTS.mdaparece na raiz do projeto. Se o projeto já tiver umCLAUDE.md, as mesmas instruções também serão adicionadas a esse arquivo.
As instruções também precisam ser incluídas em CLAUDE.md porque, segundo a documentação oficial, o Claude Code ignora o AGENTS.md quando o projeto já tem um CLAUDE.md. Para especificar uma ferramenta, você pode adicionar um parâmetro, como --agent claude, --agent cursor, --agent codex ou --agent all. O Gemini CLI lê apenas o GEMINI.md; o init adiciona uma linha nesse arquivo que faz referência ao AGENTS.md.
O Astryx gerencia o bloco identificado pelos marcadores no arquivo. Os comandos init e upgrade alteram somente esse bloco, sem afetar o conteúdo que você escreveu. A documentação oficial também observa que Agents costumam errar o caminho da CLI e recomenda adicionar um alias de script ao package.json:
- Nome do script:
astryx - Valor do script:
node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs - Como executar:
npm run astryx -- component --list
Etapa 3: adicione CSS e envolva o app com o tema neutral
- Importe
@astryxdesign/core/reset.cssno CSS global. - Em seguida, importe
@astryxdesign/core/astryx.css. - Execute
npx @astryxdesign/cli theme add neutralno terminal para gerar o módulo de tema do app. - Importe
Themede@astryxdesign/core/theme, passethemes[defaultThemeSlug]e envolva todo o app com ele. - Importe
Buttonde@astryxdesign/core/Button. O exemplo oficial usa as duas propslabeleonClick. - Critério de conclusão: um Button com o estilo da Astryx aparece na página, em vez de um botão padrão do navegador.
Esse fluxo não exige plugin de build nem configuração de PostCSS ou Babel. Mas vale ficar atento a um detalhe: o reset fica em @layer reset, e os estilos dos componentes, em @layer astryx-base. Se o projeto já tiver CSS global, um reset antigo ou Tailwind, você precisará declarar a ordem das camadas. Estilos sem camada podem sobrescrever astryx-base, independentemente da especificidade dos seletores. A recomendação oficial é ler as duas seções de npx @astryxdesign/cli docs migration/migration-setup antes de começar a criar as páginas.
A descrição oficial dos sete temas prontos está abaixo. Se você não tiver uma preferência específica, a recomendação oficial é começar pelo neutral:
| Pacote do tema | Descrição oficial | Indicado para |
|---|---|---|
theme-neutral |
Baixa saturação e minimalista | Ponto de partida padrão |
theme-butter |
Dourado quente com toques de azul | Produtos com um visual mais acolhedor |
theme-chocolate |
Tons de chocolate e caramelo | Um estilo mais retrô |
theme-gothic |
Apenas modo escuro, com estilo de tinta e noir | Interfaces totalmente escuras |
theme-matcha |
Verde inspirado na natureza | Um estilo mais natural |
theme-stone |
Tons neutros e quentes, como arenito | Painéis administrativos com visual mais sóbrio |
theme-y2k |
Estilo divertido inspirado nos anos 2000 | Páginas de eventos e produtos descontraídos |
Etapa 4: peça ao Agent para criar a UI seguindo os três passos oficiais e, se necessário, conecte o MCP
As regras geradas pelo init orientam o Agent a seguir esta ordem antes de criar a UI:
npx @astryxdesign/cli build "<想法>": retorna o modelo de página mais próximo do que você precisa (com pelo menos um esqueleto de aplicação), duas alternativas e uma lista dos blocos e componentes que ainda faltam.npx @astryxdesign/cli template <名字> <路径>: adiciona o modelo ao projeto, preservando a estrutura e os espaçamentos existentes e substituindo apenas o conteúdo.npx @astryxdesign/cli component <组件名>: consulta as props e os exemplos de cada componente que será usado.- As regras também incluem algumas proibições: toda página deve começar com um modelo; não use
divsem estilo; não escrevastyle={{}}; use tokens em vez de números mágicos. - Critério de conclusão: os nomes dos componentes e as props mencionados pelo Agent devem vir da saída da CLI, e não ser inventados por ele.
Você pode verificar isso fazendo três perguntas sugeridas oficialmente: qual é o caminho correto para importar Button; como configurar Dialog para impedir que seja fechado sem querer; e qual prop de Selector recebe os items. Se o Agent não souber responder, execute o init antes. Use como referência as respostas exibidas pela CLI instalada na sua máquina.
Se precisar consultar informações remotamente, você pode conectar o MCP oficial pelo endereço https://astryx.atmeta.com/mcp. Ele oferece duas ferramentas: search(query) para buscar componentes, documentação e modelos, e get(name) para obter a documentação completa. A configuração varia conforme o cliente:
| Cliente | Como configurar | Observações |
|---|---|---|
| Claude Code | Execute no terminal claude mcp add --transport http astryx https://astryx.atmeta.com/mcp |
O nome do serviço é astryx |
| Cursor | No arquivo .cursor/mcp.json, informe apenas o url |
Não inclua type para serviços remotos |
| Cline | Defina transport como streamableHttp |
Não use http |
| Claude Desktop | Em Settings → Connectors → Add custom connector, cole o URL | No arquivo de configuração, use apenas stdio local |
| Outros clientes genéricos | Defina type como http e inclua o url |
Um valor de transport não reconhecido será ignorado; parecerá que a conexão foi feita, mas nenhuma ferramenta estará disponível |
A documentação oficial não informa o SLA desse endereço remoto nem como proceder se o serviço ficar indisponível. A CLI é a versão local da mesma documentação; se o MCP não conectar, você ainda pode usar a CLI.
De onde vem o modelo do agente de codificação
O sistema de design cuida dos componentes e da documentação, mas, para gerar código de verdade, o agente de codificação também precisa se conectar a um modelo. Se a equipe quiser fornecer um modelo para ferramentas como Claude Code e Cursor, pode usar a interface compatível com OpenAI da APIYI apiyi.com. Preencha base_url com https://api.apiyi.com/v1 e configure o nome do modelo conforme o que estiver na lista de modelos do dia. Confira os modelos e preços na lista da plataforma APIYI; a APIYI disponibiliza os modelos que constam nela.
Vale lembrar que os componentes são renderizados no navegador e não precisam de nenhuma interface de modelo. Usar ou não a APIYI não afeta a instalação nem a execução do Astryx.
🚀 Sugestão para começar rapidamente: você pode seguir as 4 etapas acima em uma nova branch para montar uma página de template. Depois, peça ao agente para escrever a mesma página duas vezes usando o mesmo modelo: uma com
AGENTS.mde outra sem. Compare os nomes dos componentes e as props nas duas versões. Quem está começando pode obter créditos gratuitos para testes na APIYI apiyi.com e usá-los nessa comparação.
Riscos do Astryx e casos em que não é recomendável migrar
Riscos do próprio Astryx
O Astryx ainda está em Beta e usa versões 0.x. Em 2026-11-10, a versão latest no npm era a 0.7.11, publicada em 2026-11-07. A versão estável anterior, 0.7.10, foi publicada em 2026-11-06, e as versões estáveis recebem atualizações quase todos os dias. Ao atualizar, todos os pacotes @astryxdesign/* usados pelo projeto precisam estar na mesma versão. Depois, execute npx @astryxdesign/cli upgrade --from <versão antiga do core> --apply. Cada tema declara a versão correspondente do core. Se você esquecer de atualizar o tema, ele ficará incompatível com o core. Se o gerenciador de pacotes atrasar a instalação de novas versões com base na data de publicação, exclua todo o escopo @astryxdesign/*. No pnpm, adicione @astryxdesign/* a minimumReleaseAgeExclude.
Para gráficos, @astryxdesign/vega e @astryxdesign/charts são publicados apenas com a tag canary no npm; ainda não há versões estáveis. Em 2026-11-10, a versão canary era 0.7.12-canary.dfd75a6. Embora o número da versão seja mais recente que o de latest, ela não deve ser usada como dependência de produção.
Riscos ao integrar modelos pela APIYI
Esta parte trata apenas da invocação de modelos por agentes de programação. As solicitações passam pelo gateway da APIYI. A chave API e os custos ficam sob a responsabilidade de quem faz as chamadas, e o desempenho real do modelo depende da versão escolhida e das respostas efetivamente retornadas pelo gateway. Isso não é um login em uma conta Meta nem um pool de contas.
Projetos para os quais a migração não é recomendada por enquanto
- O projeto ainda usa React 18: as dependências peer do core exigem
reactereact-domna versão 19.0.0 ou superior. - Você precisa agora de uma garantia de estabilidade da versão 1.0: no momento, o projeto é marcado oficialmente como Beta, sem essa garantia.
- Você precisa agora de uma versão estável dos gráficos: os pacotes de gráficos estão disponíveis apenas em versões canary.
- Você quer que o código-fonte de cada componente esteja no seu próprio repositório desde o primeiro dia: isso seria uma abordagem de copiar e colar. Por padrão, o Astryx é instalado como pacote; o swizzle permite extrair o código-fonte de componentes individuais quando necessário.
Popularidade e versões do Astryx: números de 2026-11-10
Os números abaixo são de 2026-11-10 e podem mudar. Não devem ser tratados como dados fixos:
| Métrica | Valor | Fonte |
|---|---|---|
| Stars no GitHub | 20,217 | API do GitHub meta/astryx |
| Forks | 1,536 | API do GitHub |
| Issues / PRs ainda abertas | 297 / 373 | API de busca do GitHub (670 no total, o que não significa 670 bugs) |
| Downloads semanais do core | 661,968 (2026-11-02 a 11-08) | API de downloads do npm; contabiliza downloads, não usuários |
| Downloads do core nos últimos 30 dias | 1,725,492 (2026-10-10 a 11-08) | API de downloads do npm |
Perguntas frequentes (FAQ)
Q1: Astryx é uma biblioteca de componentes Tailwind?
Não. A documentação oficial informa que ele é baseado em React 19+ e StyleX, e distribui CSS pré-compilado. É possível usar Tailwind junto com ele: a aparência pode ser sobrescrita com `className`, e o diretório `apps/` do repositório também inclui os exemplos `example-vite-tailwind` e `example-nextjs-tailwind`. Ao combinar os dois, preste atenção à ordem das camadas CSS mencionada anteriormente.
Q2: Posso usar Astryx em um projeto React 18?
Não. A versão 0.7.11 do pacote core exige que `react` e `react-dom` estejam na versão 19.0.0 ou superior. O React 18 não atende a esse requisito. Primeiro, é preciso atualizar o projeto para React 19.
Q3: Sem conectar ao MCP, um Agent ainda consegue acessar a documentação do Astryx?
Sim. Com o `AGENTS.md` gerado pelo init e a CLI local, é possível concluir as três etapas: build, template e component. O MCP é apenas outra opção para consultas remotas. Se quiser colar o conteúdo em uma conversa pela web, use `–detail brief`, `–detail compact` ou `–dense` para reduzir a saída.
Q4: facebook/astryx e meta/astryx são repositórios diferentes?
Não, são o mesmo repositório. Em 2026-11-10, acessar `github.com/facebook/astryx` retorna um redirecionamento 301 para `github.com/meta/astryx`, que é o endereço oficial do repositório. Quando artigos antigos mencionam facebook/astryx, estão se referindo a ele.
Q5: Os componentes de gráficos do Astryx podem ser usados em produção?
Por enquanto, não é recomendável. `@astryxdesign/vega` e `@astryxdesign/charts` são publicados apenas com a tag canary, e o README também informa que ainda não há uma versão estável. Em projetos de produção, você pode continuar usando a solução de gráficos atual.
Q6: Na hora de atualizar, posso atualizar apenas o core?
Não. A orientação oficial é atualizar todos os pacotes `@astryxdesign/*` usados pelo projeto para a mesma versão. Caso contrário, o tema não será compatível com o core. Depois da atualização, execute `upgrade –from <旧版本> –apply`. Esse comando também atualiza a seção do Astryx no `AGENTS.md` que estiver desatualizada.
Q7: Preciso de uma API de modelo para usar o Astryx? Qual é a relação com APIYI?
A renderização dos componentes não exige uma API de modelo. Só é necessário conectar a um modelo quando você pede a um Agent de programação para escrever código; essa parte fica a cargo de ferramentas como Claude Code e Cursor. Se a equipe quiser fornecer o próprio modelo, pode usar uma única chave API no APIYI, em apiyi.com, para acessar vários modelos populares. APIYI não tem relação de parceria com a Meta nem com o Astryx.
Q8: Posso copiar o código-fonte de um componente para meu repositório e modificá-lo?
Sim, mas essa não é a abordagem padrão. O swizzle copia o código-fonte completo de um componente para o seu projeto. A partir daí, você fica responsável por mantê-lo e também por lidar com as próximas atualizações. A documentação oficial também recomenda usar `theme eject` apenas quando houver uma necessidade clara de manter uma versão independente do código-fonte.
Astryx: principais pontos
- Posicionamento: sistema de design para React, de código aberto pela Meta e licenciado sob MIT. Ainda está em Beta e na versão 0.x.
- Divisão de responsabilidades: o sistema cuida do comportamento e da acessibilidade; o tema cuida da aparência. Para trocar de tema, não é preciso alterar os arquivos dos componentes.
- Requisitos obrigatórios: é preciso usar React 19 ou superior e instalar o StyleX, que é uma dependência peer.
- Fluxo para agentes: primeiro, execute
initpara gerar oAGENTS.md; depois, crie a página na ordem build → template → component. - MCP opcional: o endereço remoto é
https://astryx.atmeta.com/mcp. A CLI local é uma porta de entrada para a mesma documentação. - Regras de atualização: atualize todos os pacotes
@astryxdesign/*para a mesma versão. O pacote de gráficos só está disponível em canary. - Modelo conectado à parte: os modelos necessários para o agente de codificação podem ser integrados por meio da APIYI, em apiyi.com.
Resumo: Astryx pode ajudar agentes a criar interfaces consistentes?
As interfaces criadas por agentes costumam ser inconsistentes porque eles precisam adivinhar os nomes dos componentes e suas props. A proposta do Astryx é reunir componentes, temas e documentação para os agentes em um único sistema:
- Integração em 4 etapas: instale quatro pacotes, execute
init, importe o CSS e envolva a aplicação comTheme. Depois, peça ao agente para consultar a documentação em três etapas antes de escrever o código. - Diferencie as fontes das informações: mais de 13.000 aplicações e oito anos de uso interno são dados divulgados pela própria equipe; a troca de tema com apenas quatro linhas foi um teste pontual de um autor externo; estrelas e downloads são contagens de 10/11/2026.
- Confirme se a ferramenta é adequada: se o projeto ainda usa React 18, precisa de uma versão estável do pacote de gráficos ou depende de um compromisso com a versão 1.0, talvez seja melhor adiar a migração.
Se o seu projeto já usa React 19 e você quer reduzir as chances de o agente inventar props, experimente primeiro criar uma página com um template em uma branch. Os modelos necessários para o agente de codificação podem ser integrados pela APIYI, em apiyi.com. Use os créditos gratuitos de teste para comparar como diferentes modelos geram código com o mesmo arquivo AGENTS.md.
📚 Referências
- Repositório do Astryx no GitHub: README, lista de pacotes, catálogo de temas e explicação dos princípios
- Link:
github.com/meta/astryx -
Observação: principal fonte das informações divulgadas oficialmente.
facebook/astryxredireciona para este endereço. -
Apresentação oficial do Astryx: explicação dos conceitos de design, publicada em 2026-06-18
- Link:
astryx.atmeta.com/blog/introducing-astryx -
Observação: a comparação com as abordagens de trocar o visual do pacote inteiro e copiar e colar vem deste texto.
-
Documentação Getting Started e Working with AI: instalação, temas, configuração de
inite MCP - Links:
astryx.atmeta.com/docs/getting-started,astryx.atmeta.com/docs/working-with-ai -
Observação: fontes oficiais para as quatro etapas apresentadas neste artigo.
-
Notas de lançamento do Astryx v0.7.11: versão estável atual e instruções de atualização
- Link:
github.com/meta/astryx/releases/tag/v0.7.11 -
Observação: fonte original da exigência de manter todos os pacotes na mesma versão.
-
Artigo comparativo da LogRocket: 2026-08-13, por Chizaram Ken
- Link:
blog.logrocket.com/astryx-vs-shadcn-meta-ai-react-claude - Observação: teste pontual de terceiros, feito com uma versão anterior à 0.7.11.
Autor: equipe técnica da APIYI
Contato técnico: se tiver dúvidas sobre como conectar um agente de programação a um modelo, fale conosco pela página inicial do site da APIYI.
