Análisis independiente de la documentación pública para desarrolladores de Shopify. Identity Forge no está afiliado ni respaldado por Shopify. Shopify y Polaris son marcas comerciales de su propietario. El estado de la migración y los detalles del paquete reflejan la documentación en el momento de la redacción; verifíquelos en shopify.dev antes de planificar una migración.
La obsolescencia, explicada sencillamente
El sitio de documentación de Polaris React ahora muestra una etiqueta de obsolescencia en su propio encabezado, junto con un banner que redirige a Polaris Web Components. Si busca Polaris y llega a la documentación de componentes de React, está leyendo la generación anterior.
La librería de React no ha desaparecido —la documentación de fundamentos, componentes, tokens e iconos sigue publicada— pero la dirección es inequívoca. Las nuevas aplicaciones de Shopify utilizan web components, y Shopify CLI los integra durante el andamiaje.
Cómo se distribuyen los Polaris Web Components
Esta es la parte que más difiere de lo que los usuarios de sistemas de diseño están acostumbrados: una única etiqueta de script:
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>Eso es toda la instalación. En una aplicación Remix, es la misma etiqueta colocada en el documento raíz:
// 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>
)
}Los usuarios de TypeScript añaden un paquete complementario, @shopify/polaris-types, desde npm. La documentación de Shopify es específica sobre cómo mantenerlos alineados: dado que el CDN siempre sirve los componentes más recientes, debe especificar @shopify/polaris-types@latest en package.json para que los tipos los sigan.
Lea esa última frase dos veces si tiene opiniones sobre los lockfiles. Los componentes en tiempo de ejecución no son versionados por usted —el CDN sirve la versión actual— y la forma recomendada de mantener los tipos correctos es depender de @latest. Se trata de una inversión deliberada de la higiene normal de dependencias, y si esto es aceptable depende enteramente del contexto de despliegue.
Por qué el proveedor quiere controlar la versión
El propósito declarado de Polaris en el contexto de las aplicaciones es que su aplicación debe verse y sentirse nativa en el administrador de Shopify. Este es un requisito genuinamente diferente a "su aplicación debe ser consistente", y explica completamente el modelo de distribución.
Si el lenguaje visual del administrador de Shopify cambia —una revisión del espaciado, una nueva escala tipográfica, un modo oscuro— una aplicación anclada a una versión de componentes de hace dieciocho meses se verá mal en su interior. No rota, sino incorrecta, de esa manera específica que el comerciante percibe como una aplicación de baja calidad. Multiplique esto por un marketplace de aplicaciones y la propia superficie de la plataforma se vuelve visiblemente inconsistente sin que sea culpa de ningún desarrollador individual.
Servir componentes desde un CDN traslada ese riesgo de miles de desarrolladores de aplicaciones, que no tienen incentivos para actualizar una dependencia que funciona, a un único equipo de plataforma que sí los tiene. Es el mismo instinto detrás de el kit de UI de aplicaciones de Stripe que rechaza el CSS arbitrario: cuando su UI se renderiza en la superficie de otro, ellos recuperan las decisiones de estilo.
| Paquete npm | Script de CDN | |
|---|---|---|
| Quién controla la versión | Usted, a través del lockfile | El proveedor |
| Cambio disruptivo (Breaking change) | Llega cuando usted lo decide. Puede que nunca llegue | Llega cuando el proveedor lo publica |
| Consistencia de la plataforma | Se degrada con el tiempo a medida que las apps quedan obsoletas | Mantenido automáticamente |
| Offline / air-gapped | Funciona | No funciona |
| Tamaño del bundle | Usted lo optimiza, permite tree-shaking | No está en su bundle; es una solicitud independiente |
| Justo cuando | Su app es la superficie | La app de otro es la superficie |
La fila inferior resume toda la decisión. Esto no es una recomendación general para servir su sistema de diseño desde un CDN; para un producto donde usted es dueño de la superficie, renunciar al control de versiones no aporta nada y le quita la capacidad de tener builds reproducibles. Es la respuesta correcta a una pregunta estructural específica sobre quién es responsable de la apariencia de la página.
Por qué web components en lugar de React
El modelo de CDN se explica por sí solo una vez que se acepta el objetivo de consistencia de la plataforma, pero también fuerza, más o menos, la elección tecnológica. No se pueden enviar componentes de React desde una etiqueta de script a una app que podría estar construida con Remix, HTML puro, Vue o algo que ni siquiera existía cuando se tomó la decisión. Los custom elements son el único formato ampliamente compatible que se renderiza de forma idéntica independientemente de lo que los envuelva.
La documentación de Shopify indica que se puede añadir la etiqueta de script en cualquier framework. Esa frase encierra mucho: es la razón completa de la migración expresada como una capacidad.
Vale la pena mencionar el coste, porque los web components no son gratuitos. Se renuncia a la ergonomía de React —props tipadas verificadas en el build en lugar de en el runtime, patrones de composición familiares, el ecosistema de herramientas específicas de React— a cambio de la independencia del framework. El paquete @shopify/polaris-types existe precisamente para recuperar lo primero. Si el intercambio es favorable depende de si la independencia del framework tiene valor para usted; para una plataforma que sirve un marketplace de apps, tiene un valor enorme.
Qué es Polaris más allá de los componentes
La rotación de la librería de componentes oculta el hecho de que la mayor parte del valor transferible de Polaris no son componentes. El sitio de documentación publica cuatro cosas, y tres de ellas sobreviven a cualquier cambio de implementación:
| Qué es | ¿Útil fuera de Shopify? | |
|---|---|---|
| Foundations | Guía de diseño para crear experiencias de administración de calidad | Sí. Una guía de UX de administración es una guía de UX de administración |
| Tokens | Nombres codificados que representan decisiones de diseño: color, espaciado, tipografía | Como modelo, sí. Como valores, solo si quiere parecerse a Shopify |
| Iconos | Más de 400 iconos centrados en el comercio y el emprendimiento | Sí, si desarrolla software de comercio. Consulte la licencia |
| Componentes | La implementación, ahora mediante web components | No. Están creados específicamente para el administrador de Shopify |
El conjunto de iconos es el más infravalorado. Cuatrocientos iconos dibujados para el comercio —estados de cumplimiento, descuentos, inventario, conceptos de envío y pago— representan una gran cantidad de trabajo de dibujo especializado, y los conjuntos de iconos genéricos son notablemente deficientes en estos conceptos exactos. Si construye cualquier cosa relacionada con el comercio, esto merece una hora de su tiempo y una revisión de los términos de la licencia.
Los tokens merecen ser estudiados como un ejercicio de nomenclatura, incluso si los valores le resultan inútiles. La descripción de Shopify —nombres codificados que representan decisiones de diseño— es la definición correcta, y es la que la mayoría de los equipos no implementan cuando nombran un token como blue-500 en lugar de nombrar el rol que desempeña.
El patrón en tres sistemas
Polaris es uno de los tres grandes sistemas de diseño empresariales que realizaron un cambio estructural en un periodo similar, cada uno apostando de forma distinta por la misma premisa: que el código que consume un sistema de diseño es, cada vez más, escrito por un agente de código y no por un humano que lee la documentación.
| Qué ha cambiado | La apuesta subyacente | |
|---|---|---|
| Shopify Polaris | React deprecado; web components agnósticos al framework desde un CDN | El formato de entrega no debe asumir qué generó la página |
| IBM Carbon | Un servidor MCP que expone documentación y ejemplos de código a los agentes | Los agentes deben recuperar el sistema en lugar de intentar recordarlo |
| Salesforce Lightning (SLDS 2) | Arquitectura CSS desacoplada del estilo visual; un linter que valida el marcado según las reglas | El sistema debe ser lo suficientemente tematizable para la UI generada, y las infracciones deben detectarse mecánicamente |
La versión de Polaris es la menos discutida y, posiblemente, la más trascendental para cualquiera que construya sobre una plataforma. Si un agente de código genera la estructura de una app de Shopify, no necesita saber qué framework eligió el desarrollador, ya que los componentes son los mismos elementos personalizados en cualquier caso. La entrega agnóstica al framework es una entrega agnóstica al agente, independientemente de si esa fue la motivación.
Lo que esto no resuelve
Una librería de componentes —entregada por CDN, agnóstica al framework y siempre actualizada— le indica a un agente qué componentes existen y cómo llamarlos. No dice nada sobre cómo debería verse su producto porque, en el caso de las apps de Shopify, la respuesta es fija: debe verse como el administrador de Shopify.
Fuera de ese caso, la pregunta queda abierta y nada en una librería de componentes la responde. Analizamos 299 archivos DESIGN.md escritos para dar esa respuesta a los agentes. El 86% enumeraba los colores como hex puros sin un rol asignado, el 76% no indicaba prohibiciones, el 57% no definía motivos y el 54% dependía de un adjetivo vago: "limpio" en el 39%, "moderno" en el 36%. Un modelo que lee ese archivo tiene una paleta, pero no un diseño.
Los kits de diseño de Identity Forge responden a la otra mitad: roles de color semánticos para modo claro y oscuro, escalas de tipografía y espaciado, motivos y directrices explícitas de qué hacer y qué no hacer, serializados en un DESIGN.md que funciona junto a cualquier librería de componentes. Explore los kits o comience por qué es un archivo DESIGN.md.
Guía práctica
- ¿Está creando una app de Shopify ahora? Use Polaris Web Components. Genere la estructura con Shopify CLI y ya vendrán integrados; añada
@shopify/polaris-types@latestsi utiliza TypeScript. - ¿Mantiene una app de Polaris React? Sigue funcionando, pero utiliza una implementación deprecada. Lea la guía de migración actual antes de planificar cualquier otra modificación importante en esa base de código.
- ¿Está construyendo algo fuera de Shopify? No adopte los componentes de Polaris. Sí observe los fundamentos y el set de iconos de comercio, y utilice la nomenclatura de los design tokens como un ejemplo práctico.
- ¿Mantiene su propio sistema de diseño? La pregunta transferible no es React frente a web components. Es si usted o sus consumidores deben controlar la versión, lo cual depende de quién sea el responsable de la apariencia del resultado final.
¿Está deprecado Polaris React?
Sí. El sitio de documentación de Polaris React incluye una etiqueta de deprecación y redirige a Polaris Web Components. Las apps de React existentes siguen funcionando, pero el desarrollo de nuevas apps de Shopify utiliza los web components, que Shopify CLI añade automáticamente al generar la estructura.
¿Cómo instalo Polaris Web Components?
No se instalan desde npm. Añada una etiqueta script que apunte a https://cdn.shopify.com/shopifycloud/polaris.js en el head de su documento, junto con la etiqueta meta shopify-api-key. Shopify CLI hace esto por usted al generar la app. Los usuarios de TypeScript añaden @shopify/polaris-types desde npm para obtener los tipos.
¿Por qué Shopify sirve los componentes desde un CDN en lugar de npm?
Para que las apps mantengan una apariencia nativa del administrador de Shopify a medida que este cambia. Una dependencia de npm fijada implica una app congelada en un lenguaje visual antiguo dentro de una interfaz que ha evolucionado, lo que los comerciantes perciben como una app de baja calidad. Trasladar el control de versiones a la plataforma soluciona esto para todo el marketplace a la vez.
¿Puedo usar Polaris fuera de una app de Shopify?
Los componentes están creados para el administrador de Shopify y no son la elección correcta en otros contextos: harán que su producto parezca Shopify. La documentación de fundamentos, el enfoque de nomenclatura de tokens y los más de 400 iconos enfocados al comercio son genuinamente útiles fuera de Shopify; revise los términos de la licencia antes de implementar los iconos.
¿Qué son los tokens de Polaris?
Nombres codificados que representan decisiones de diseño para color, espaciado, tipografía y más. El enfoque de nomenclatura es la parte transferible: un token debe nombrarse según la decisión que codifica y no según el valor que contiene, que es la diferencia entre un sistema de tokens y una lista de variables.