Análise independente da documentação pública para desenvolvedores da Shopify. O Identity Forge não é afiliado nem endossado pela Shopify. Shopify e Polaris são marcas registradas de seus proprietários. O status de migração e os detalhes dos pacotes refletem a documentação no momento da redação — verifique em shopify.dev antes de planejar uma migração.
A descontinuação, explicada de forma direta
O site de documentação do Polaris React agora exibe um rótulo de descontinuação em seu próprio cabeçalho, junto a um banner apontando para os Polaris Web Components. Se você está procurando por Polaris e cai na documentação de componentes React, está lendo a geração anterior.
A biblioteca React não sumiu — a documentação de foundations, componentes, tokens e ícones ainda está publicada — mas a direção é inequívoca. Novos apps da Shopify recebem web components, e o Shopify CLI os configura durante a criação da estrutura.
Como os Polaris Web Components são entregues
Esta é a parte que mais difere do que os usuários de design systems estão acostumados, e resume-se a uma única tag de script:
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>Essa é a instalação completa. Em um app Remix, é a mesma tag colocada no documento raiz:
// app/root.tsx
export default function App() {
return (
<html>
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js" />
</head>
</html>
)
}Usuários de TypeScript adicionam um pacote complementar, @shopify/polaris-types, via npm. A documentação da Shopify é específica sobre como mantê-los alinhados: como o CDN sempre serve os componentes mais recentes, você deve especificar @shopify/polaris-types@latest no package.json para que os tipos os acompanhem.
Leia a frase anterior duas vezes se você tiver opiniões fortes sobre lockfiles. Os componentes de runtime não são versionados por você — o CDN serve a versão atual — e a maneira recomendada de manter os tipos corretos é depender do @latest. Isso é uma inversão deliberada da higiene normal de dependências, e se isso é aceitável depende inteiramente do contexto de implantação.
Por que o fornecedor quer controlar a versão
O propósito declarado do Polaris no contexto de apps é que seu app deve parecer e soar nativo ao admin da Shopify. Esse é um requisito genuinamente diferente de "seu app deve ser consistente", e isso explica completamente o modelo de entrega.
Se a linguagem visual do admin da Shopify mudar — uma revisão de espaçamento, uma nova escala tipográfica, um modo escuro — um app fixado em uma versão de componente de dezoito meses atrás parecerá errado dentro dele. Não quebrado. Errado, daquela forma específica que o lojista interpreta como um app de baixa qualidade. Multiplique isso por um marketplace de apps e a própria interface da plataforma torna-se visivelmente inconsistente, sem que seja culpa de nenhum desenvolvedor individual.
Servir componentes via CDN transfere esse risco de milhares de desenvolvedores de apps, que não têm incentivo para atualizar uma dependência que funciona, para uma única equipe de plataforma que tem. É o mesmo instinto por trás do toolkit de UI de apps da Stripe que recusa CSS arbitrário: quando sua UI é renderizada na interface de outra pessoa, eles retomam as decisões de estilização.
| pacote npm | script CDN | |
|---|---|---|
| Quem controla a versão | Você, via lockfile | O fornecedor |
| Breaking change | Chega quando você escolhe. Pode nunca chegar | Chega quando o fornecedor a lança |
| Consistência da plataforma | Degrada com o tempo à medida que os apps ficam desatualizados | Mantida automaticamente |
| Offline / air-gapped | Funciona | Não funciona |
| Tamanho do bundle | Você otimiza, suporta tree-shaking | Não fica no seu bundle; é uma requisição separada |
| Exatamente quando | Seu app é a interface | O app de outra pessoa é a interface |
A linha inferior resume toda a decisão. Isso não é uma recomendação geral para servir seu design system via CDN — para um produto onde você detém a interface, abrir mão do controle de versão não traz benefício algum e custa a reprodutibilidade dos builds. Esta é a resposta correta para uma pergunta estrutural específica sobre quem é o responsável pela aparência da página.
Por que web components em vez de React
O modelo de CDN se explica assim que você aceita o objetivo de consistência da plataforma, mas ele também praticamente impõe a escolha tecnológica. Você não pode entregar componentes React via script tag para um app que pode ter sido construído com Remix, HTML puro, Vue ou algo que nem existia quando a decisão foi tomada. Custom elements são o único formato amplamente suportado que renderiza de forma idêntica, independentemente do que os envolva.
A documentação do Shopify observa que você pode adicionar a script tag em qualquer framework. Essa frase resume muita coisa: é todo o motivo da migração expresso como uma capacidade.
Vale a pena mencionar o custo, pois web components não são gratuitos. Você abre mão da ergonomia do React — props tipadas verificadas no build em vez de no runtime, padrões de composição familiares, o ecossistema de ferramentas específicas do React — em troca da independência de framework. O pacote @shopify/polaris-types existe precisamente para recuperar o primeiro desses pontos. Se a troca vale a pena depende de quanto a independência de framework é importante para você e, para uma plataforma que serve a um marketplace de apps, isso vale muitíssimo.
O que o Polaris é além de componentes
A rotatividade da biblioteca de componentes mascara o fato de que a maior parte do valor transferível do Polaris não são componentes. O site de documentação publica quatro coisas, e três delas sobrevivem a qualquer mudança de implementação:
| O que é | Útil fora do Shopify? | |
|---|---|---|
| Foundations | Diretrizes de design para criar experiências de admin de qualidade | Sim. Diretrizes de UX de admin são diretrizes de UX de admin |
| Tokens | Nomes codificados que representam decisões de design — cor, espaçamento, tipografia | Como modelo, sim. Como valores, apenas se você quiser ter a aparência do Shopify |
| Ícones | Mais de 400 ícones focados em comércio e empreendedorismo | Sim, se você desenvolve software de comércio. Verifique a licença |
| Componentes | A implementação, agora como web components | Não. Eles foram construídos especificamente para o admin do Shopify |
O conjunto de ícones é o mais subestimado. Quatrocentos ícones desenhados para comércio — estados de fulfillment, descontos, inventário, conceitos de envio e pagamento — representam um volume enorme de trabalho de desenho especializado, e conjuntos de ícones genéricos são visivelmente ruins exatamente nesses conceitos. Se você constrói qualquer coisa voltada ao comércio, isso vale uma hora do seu tempo e uma olhada nos termos da licença.
Os tokens valem o estudo como um exercício de nomenclatura, mesmo que os valores sejam inúteis para você. A descrição do Shopify — nomes codificados que representam decisões de design — é a definição correta, e é a que a maioria das equipes falha em implementar ao nomear um token como blue-500 em vez de nomear a função que ele desempenha.
O padrão entre três sistemas
O Polaris é um de três grandes design systems corporativos que fizeram uma mudança estrutural aproximadamente no mesmo período, cada um apostando de forma diferente na mesma premissa: a de que o código que consome um design system é, cada vez mais, escrito por algo que não é um humano lendo a documentação.
| O que mudou | A aposta fundamental | |
|---|---|---|
| Shopify Polaris | React descontinuado; web components agnósticos a framework via CDN | O formato de entrega não deve presumir o que gerou a página |
| IBM Carbon | Um servidor MCP que expõe documentação e exemplos de código para agentes | Agentes devem recuperar o sistema em vez de tentar lembrá-lo |
| Salesforce Lightning (SLDS 2) | Arquitetura CSS desacoplada do estilo visual; um linter validando a marcação conforme as regras | O sistema deve ser customizável o suficiente para UIs geradas, e as violações devem ser detectadas mecanicamente |
A versão do Polaris é a menos discutida e, possivelmente, a mais consequente para quem constrói sobre uma plataforma. Se um agente de IA cria a estrutura de um app Shopify, ele não precisa saber qual framework o desenvolvedor escolheu, pois os componentes são os mesmos custom elements de qualquer maneira. A entrega agnóstica a framework é, na prática, uma entrega agnóstica a agente, independentemente de essa ter sido a motivação.
O que isso não resolve
Uma biblioteca de componentes — entregue via CDN, agnóstica a framework e sempre atualizada — informa ao agente quais componentes existem e como chamá-los. Ela não diz nada sobre a aparência que seu produto deve ter, pois, no caso de apps Shopify, a resposta é fixa: deve ter a aparência do admin do Shopify.
Fora desse caso, a questão permanece aberta e nada em uma biblioteca de componentes a responde. Analisamos 299 arquivos DESIGN.md escritos para dar essa resposta aos agentes. 86% listavam cores como hexadecimais puros sem função atribuída, 76% não declaravam proibições, 57% não definiam motivos e 54% dependiam de um adjetivo vago — "clean" em 39%, "moderno" em 36%. Um modelo que lê esse arquivo encontra uma paleta, mas não um design.
Os design kits do Identity Forge respondem à outra metade: funções semânticas de cores para temas claro e escuro, escalas de tipografia e espaçamento, motivos e diretrizes explícitas de "faça e não faça", serializados em um DESIGN.md que funciona com qualquer biblioteca de componentes. Explore os kits ou comece entendendo o que é um arquivo DESIGN.md.
Orientações práticas
- Construindo um app Shopify agora? Use Polaris Web Components. Crie a estrutura com o Shopify CLI e eles já virão configurados; adicione
@shopify/polaris-types@latestse estiver usando TypeScript. - Mantendo um app Polaris React? Ele ainda funciona, mas você está em uma implementação descontinuada. Leia as orientações de migração atuais antes de planejar qualquer outra alteração significativa nessa base de código.
- Construindo algo fora do Shopify? Não adote os componentes Polaris. No entanto, observe as fundações e o conjunto de ícones de comércio, e utilize a nomenclatura dos tokens como um exemplo prático.
- Mantendo seu próprio design system? A questão transferível não é React versus web components. É se você ou seus consumidores devem controlar a versão — e isso depende de quem é o responsável pela aparência do resultado final.
O Polaris React foi descontinuado?
Sim. O site de documentação do Polaris React exibe um aviso de descontinuação e aponta para o Polaris Web Components. Apps React existentes continuam funcionando, mas o desenvolvimento de novos apps Shopify utiliza web components, que o Shopify CLI adiciona automaticamente durante a criação da estrutura.
Como instalo o Polaris Web Components?
Você não os instala via npm. Adicione uma tag de script apontando para https://cdn.shopify.com/shopifycloud/polaris.js no head do seu documento, junto com a meta tag shopify-api-key. O Shopify CLI faz isso por você ao criar a estrutura de um app. Usuários de TypeScript adicionam @shopify/polaris-types via npm para obter as tipagens.
Por que o Shopify serve componentes via CDN em vez de npm?
Para que os apps permaneçam visualmente nativos ao admin do Shopify conforme ele muda. Uma dependência de npm fixada significa um app congelado em uma linguagem visual antiga dentro de uma interface que evoluiu, o que é percebido pelos lojistas como um app de baixa qualidade. Transferir o controle de versão para a plataforma resolve isso para todo o marketplace de uma só vez.
Posso usar o Polaris fora de um app Shopify?
Os componentes foram feitos para o admin do Shopify e são a escolha errada para outros contextos — eles farão seu produto parecer o Shopify. A documentação de fundações, a abordagem de nomenclatura de tokens e os mais de 400 ícones focados em comércio são genuinamente úteis fora do Shopify; verifique os termos de licença antes de implementar os ícones.
O que são tokens do Polaris?
Nomes codificados que representam decisões de design para cores, espaçamento, tipografia e mais. A abordagem de nomenclatura é a parte transferível: um token deve ser nomeado com base na decisão que ele codifica, e não no valor que ele detém — essa é a diferença entre um sistema de tokens e uma lista de variáveis.