Analyse indépendante de la documentation publique pour développeurs de Shopify. Identity Forge n'est pas affilié à Shopify et n'est pas approuvé par Shopify. Shopify et Polaris sont des marques déposées de leur propriétaire. L'état de la migration et les détails des packages reflètent la documentation au moment de la rédaction : vérifiez sur shopify.dev avant de planifier une migration.
La dépréciation, explicitement
Le site de documentation de Polaris React affiche désormais une mention de dépréciation dans son propre titre, accompagnée d'une bannière pointant vers Polaris Web Components. Si vous recherchez Polaris et arrivez sur la documentation des composants React, vous consultez la génération précédente.
La bibliothèque React n'a pas disparu (la documentation des fondations, des composants, des tokens et des icônes est toujours publiée), mais la direction est sans ambiguïté. Les nouvelles applications Shopify utilisent des web components, et Shopify CLI les intègre lors du scaffolding.
Comment sont distribués les Polaris Web Components
C'est l'aspect qui diffère le plus de ce dont les utilisateurs de design system ont l'habitude : il s'agit d'une simple balise script :
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>C'est tout pour l'installation. Dans une application Remix, c'est la même balise placée dans le document racine :
// 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>
)
}Les utilisateurs de TypeScript ajoutent un package complémentaire, @shopify/polaris-types, via npm. La documentation de Shopify est précise sur la manière de les maintenir alignés : comme le CDN sert toujours les composants les plus récents, vous devez spécifier @shopify/polaris-types@latest dans le package.json pour que les types suivent le rythme.
Lisez cette dernière phrase deux fois si vous avez des opinions tranchées sur les lockfiles. Les composants au runtime ne sont pas versionnés par vous (le CDN sert la version actuelle), et la méthode recommandée pour maintenir des types corrects est de dépendre de @latest. C'est une inversion délibérée de l'hygiène normale des dépendances, et son acceptabilité dépend entièrement du contexte de déploiement.
Pourquoi le fournisseur veut contrôler la version
L'objectif affiché de Polaris dans le contexte des applications est que votre application doit paraître et se ressentir comme native à l'administration Shopify. C'est une exigence fondamentalement différente de « votre application doit être cohérente », et cela explique entièrement le modèle de distribution.
Si le langage visuel de l'administration Shopify change (une révision des espacements, une nouvelle échelle typographique, un mode sombre), une application figée sur une version de composants datant d'il y a dix-huit mois paraîtra désormais incorrecte à l'intérieur. Pas cassée. Incorrecte, d'une manière spécifique qui est perçue par un marchand comme le signe d'une application de faible qualité. Multipliez cela par un marketplace d'applications et la surface même de la plateforme devient visiblement incohérente, sans que ce soit la faute d'un développeur individuel.
Servir les composants depuis un CDN déplace ce risque des milliers de développeurs d'applications, qui n'ont aucun intérêt à mettre à jour une dépendance fonctionnelle, vers une seule équipe plateforme qui en a l'intérêt. C'est le même instinct que derrière le kit UI d'application de Stripe qui refuse le CSS arbitraire : quand votre UI s'affiche sur la surface de quelqu'un d'autre, c'est lui qui reprend les décisions de style.
| Package npm | Script CDN | |
|---|---|---|
| Qui contrôle la version | Vous, via le lockfile | Le fournisseur |
| Changement majeur (breaking change) | Arrive quand vous le décidez. Peut ne jamais arriver | Arrive dès que le fournisseur le déploie |
| Cohérence de la plateforme | Se dégrade avec le temps à mesure que les apps deviennent obsolètes | Maintenue automatiquement |
| Hors ligne / air-gapped | Fonctionne | Ne fonctionne pas |
| Taille du bundle | À optimiser par vos soins, compatible tree-shaking | Absent de votre bundle ; requête séparée |
| Lorsque | Votre app est la surface | L'app d'un tiers est la surface |
La dernière ligne résume toute la décision. Il ne s'agit pas d'une recommandation générale de servir votre design system via un CDN pour un produit dont vous maîtrisez la surface ; renoncer au contrôle des versions n'apporte rien et compromet la reproductibilité des builds. C'est en revanche la réponse correcte à une question structurelle précise : qui est responsable de l'apparence de la page.
Pourquoi des web components plutôt que React
Le modèle CDN s'explique de lui-même dès lors que l'on accepte l'objectif de cohérence de la plateforme, mais il impose également plus ou moins le choix technologique. Vous ne pouvez pas livrer des composants React via une balise script dans une app qui pourrait être construite avec Remix, du HTML pur, Vue, ou une technologie inexistante au moment de la décision. Les custom elements sont le seul format largement supporté qui s'affiche de manière identique, quel que soit l'environnement qui les enveloppe.
La documentation de Shopify précise que vous pouvez ajouter la balise script dans n'importe quel framework. Cette phrase est cruciale : elle exprime toute la raison de la migration sous forme de capacité technique.
Il est important d'en préciser le coût, car les web components ne sont pas gratuits. Vous sacrifiez l'ergonomie de React (props typées vérifiées au build plutôt qu'au runtime, patterns de composition familiers, écosystème d'outils spécifiques à React) en échange de l'indépendance vis-à-vis du framework. Le package @shopify/polaris-types existe précisément pour compenser ce premier point. La pertinence de cet échange dépend de la valeur que vous accordez à l'indépendance du framework ; pour une plateforme hébergeant une marketplace d'apps, cette valeur est immense.
Ce qu'est Polaris au-delà des composants
Le renouvellement de la bibliothèque de composants occulte le fait que la majeure partie de la valeur transférable de Polaris ne réside pas dans les composants. Le site de documentation publie quatre éléments, dont trois survivent à tout changement d'implémentation :
| Nature | Utile hors Shopify ? | |
|---|---|---|
| Foundations | Directives de design pour créer des expériences d'administration de qualité | Oui. Des directives UX d'administration restent des directives UX d'administration |
| Tokens | Noms codés représentant des décisions de design : couleur, espacement, typographie | En tant que modèle, oui. En tant que valeurs, seulement si vous voulez ressembler à Shopify |
| Icônes | Plus de 400 icônes axées sur le commerce et l'entrepreneuriat | Oui, si vous développez des logiciels de commerce. Vérifiez la licence |
| Composants | L'implémentation, désormais via des web components | Non. Ils sont conçus spécifiquement pour l'administration Shopify |
Le jeu d'icônes est l'élément le plus sous-estimé. Quatre cents icônes dessinées pour le commerce (états de traitement des commandes, remises, inventaire, expédition, concepts de paiement) représentent un travail de dessin spécialisé considérable, et les jeux d'icônes génériques sont notoirement médiocres sur ces concepts précis. Si vous travaillez dans le commerce, cela mérite une heure de votre temps et une lecture des conditions de licence.
Les tokens valent la peine d'être étudiés comme exercice de nommage, même si les valeurs ne vous sont d'aucune utilité. La description de Shopify — des noms codés qui représentent des décisions de design — est la définition correcte, et c'est celle que la plupart des équipes ne parviennent pas à mettre en œuvre lorsqu'elles nomment un token blue-500 au lieu de nommer le rôle qu'il joue.
Le schéma commun à trois systèmes
Polaris est l'un des trois grands design systems d'entreprise ayant opéré un changement structurel à peu près au même moment, chacun misant différemment sur le même postulat : le code qui consomme un design system n'est plus, de plus en plus, écrit par un humain lisant la documentation.
| Ce qui a changé | Le pari sous-jacent | |
|---|---|---|
| Shopify Polaris | React obsolète ; composants web agnostiques du framework via CDN | Le format de diffusion ne doit pas présumer de ce qui a généré la page |
| IBM Carbon | Un serveur MCP exposant la documentation et des exemples de code aux agents | Les agents doivent récupérer le système plutôt que de s'en souvenir |
| Salesforce Lightning (SLDS 2) | Architecture CSS découplée du style visuel ; un linter validant le balisage selon les règles | Le système doit être suffisamment thémisable pour l'UI générée, et les violations doivent être détectées mécaniquement |
La version de Polaris est la moins discutée et sans doute la plus lourde de conséquences pour quiconque développe sur une plateforme. Si un agent de code génère la structure d'une application Shopify, il n'a pas besoin de savoir quel framework le développeur a choisi, car les composants sont, dans les deux cas, les mêmes éléments personnalisés. Une diffusion agnostique du framework est une diffusion agnostique de l'agent, que cela ait été la motivation initiale ou non.
Ce que cela ne résout pas
Une bibliothèque de composants (diffusée par CDN, agnostique du framework, toujours à jour) indique à un agent quels composants existent et comment les appeler. Elle ne dit rien sur l'apparence que devrait avoir votre produit car, dans le cas d'une application Shopify, la réponse est fixe : elle doit ressembler à l'administration Shopify.
En dehors de ce cas, la question reste ouverte et rien dans une bibliothèque de composants n'y répond. Nous avons analysé 299 fichiers DESIGN.md rédigés pour apporter cette réponse aux agents. 86 % listaient les couleurs sous forme de hex bruts sans rôle associé, 76 % ne mentionnaient aucune interdiction, 57 % ne définissaient aucun motif, et 54 % s'appuyaient sur un adjectif vague : « clean » dans 39 % des cas, « moderne » dans 36 %. Un modèle lisant ce fichier dispose d'une palette, mais pas d'un design.
Les kits de design Identity Forge répondent à l'autre moitié du problème : rôles sémantiques des couleurs pour les modes clair et sombre, échelles de typographie et d'espacement, motifs, et consignes explicites (do's and don'ts), le tout sérialisé dans un fichier DESIGN.md qui fonctionne avec n'importe quelle bibliothèque de composants. Parcourez les kits ou commencez par ce qu'est un fichier DESIGN.md.
Conseils pratiques
- Vous créez une application Shopify actuellement ? Utilisez Polaris Web Components. Générez votre structure avec Shopify CLI et l'intégration est automatique ; ajoutez
@shopify/polaris-types@latestsi vous utilisez TypeScript. - Vous maintenez une application Polaris React ? Elle fonctionne toujours, mais vous utilisez une implémentation obsolète. Consultez le guide de migration actuel avant de planifier toute modification majeure dans cette base de code.
- Vous créez un produit en dehors de Shopify ? N'adoptez pas les composants Polaris. Étudiez en revanche les fondations et le kit d'icônes de commerce, et utilisez le nommage des tokens comme exemple concret.
- Vous maintenez votre propre design system ? La question transférable n'est pas l'opposition entre React et les composants web. Il s'agit de savoir si c'est vous ou vos utilisateurs qui devez contrôler la version, ce qui dépend de qui est responsable de l'aspect visuel final.
Polaris React est-il obsolète ?
Oui. Le site de documentation de Polaris React affiche une mention d'obsolescence et renvoie vers Polaris Web Components. Les applications React existantes continuent de fonctionner, mais le développement de nouvelles applications Shopify utilise les composants web, que Shopify CLI ajoute automatiquement lors de la génération du projet.
Comment installer Polaris Web Components ?
Ils ne s'installent pas via npm. Ajoutez une balise script pointant vers https://cdn.shopify.com/shopifycloud/polaris.js dans l'en-tête de votre document, ainsi que la balise meta shopify-api-key. Shopify CLI s'en charge pour vous lors de la création de l'application. Les utilisateurs de TypeScript ajoutent @shopify/polaris-types via npm pour les types.
Pourquoi Shopify diffuse-t-il les composants via un CDN plutôt que via npm ?
Pour que les applications restent visuellement natives à l'administration Shopify lors de ses mises à jour. Une dépendance npm figée signifie qu'une application reste bloquée sur un ancien langage visuel au sein d'une interface qui a évolué, ce qui est perçu par les marchands comme un manque de qualité. Déplacer le contrôle des versions vers la plateforme règle ce problème pour l'ensemble de la marketplace simultanément.
Puis-je utiliser Polaris en dehors d'une application Shopify ?
Les composants sont conçus pour l'administration Shopify et sont inappropriés ailleurs. Ils donneront à votre produit l'apparence de Shopify. En revanche, la documentation des fondations, l'approche de nommage des tokens et les plus de 400 icônes axées sur le commerce sont réellement utiles en dehors de Shopify ; vérifiez les conditions de licence avant d'utiliser les icônes.
Que sont les tokens Polaris ?
Des noms codés représentant des décisions de design pour les couleurs, l'espacement, la typographie, etc. L'approche de nommage est l'élément transférable : un token doit être nommé selon la décision qu'il encode plutôt que selon la valeur qu'il contient, ce qui marque la différence entre un système de tokens et une simple liste de variables.