Análise independente da documentação pública para desenvolvedores da Shopify. A Identity Forge não é afiliada nem endossada 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 escrita: verifique em shopify.dev antes de planejar uma migração.
A descontinuação, 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, ao lado de um banner apontando para os Polaris Web Components. Se você está procurando pelo Polaris e cai na documentação de componentes React, você está lendo a geração anterior.
A biblioteca React não sumiu (as documentações de bases, componentes, tokens e ícones ainda são publicadas), mas a direção é inequívoca. Novos apps do Shopify recebem web components, e o Shopify CLI os integra durante o scaffolding.
Como os Polaris Web Components são entregues
Esta é a parte que mais difere do que os usuários de design system estão acostumados, e trata-se de 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>Isso é toda a instalação. Em um app Remix, é a mesma tag inserida 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 do 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 acompanhem as atualizações.
Leia esta última frase duas vezes se você tiver opiniões 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 de @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 ter a aparência e a sensação de ser nativo do admin do 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 do Shopify mudar (uma revisão de espaçamento, uma nova escala tipográfica, um modo escuro), um app travado em uma versão de componente de dezoito meses atrás parecerá errado dentro dele. Não quebrado. Errado, daquela forma específica que faz um lojista ler 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 culpa de qualquer desenvolvedor individual.
Servir componentes de um 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 kit de UI de apps da Stripe recusar CSS arbitrário: quando sua UI é renderizada na interface de outra pessoa, eles retomam as decisões de estilização.
| Pacote npm | Script de CDN | |
|---|---|---|
| Quem controla a versão | Você, via lockfile | O fornecedor |
| Breaking change | Chega quando você escolhe. Pode nunca chegar | Chega quando o fornecedor lança |
| Consistência da plataforma | Degrada com o tempo conforme os apps ficam desatualizados | Mantida automaticamente |
| Offline / air-gapped | Funciona | Não funciona |
| Tamanho do bundle | Você otimiza, suporta tree-shaking | Fora do seu bundle; uma requisição separada |
| Exatamente quando | Seu app é a interface | O app de outra pessoa é a interface |
A linha inferior resume a decisão. Isso não é uma recomendação geral para servir seu design system via CDN em um produto onde você detém a interface; abrir mão do controle de versão não traz benefícios e compromete a reprodutibilidade dos builds. Esta é a resposta correta para uma questão 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 justifica 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 tudo: é 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 do 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ê; para uma plataforma que serve a um marketplace de apps, ela 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 está nos 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, envio, conceitos de 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, vale a pena dedicar uma hora do seu tempo e analisar os 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, não escrito por 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 código 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, sempre atualizada) informa ao agente quais componentes existem e como chamá-los. Ela não diz nada sobre a aparência do seu produto porque, 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, o que 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 direciona 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 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 automaticamente ao criar 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 que o app fica 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 criados 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 publicar 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.