Storefront Best Practices

• Construir o extender una tienda de comercio electrónico — cualquier framework (Next.js, SvelteKit, TanStack Start, React, Vue): páginas de producto, listados de productos, carrito, pago, navegación, página de inicio, búsqueda, páginas de cuenta o confirmación de pedido.
• Integrar un backend (incluido Medusa) — configuración del SDK, obtención de productos/categorías/regiones, visualización de precios, selección de métodos de pago y gestión del carrito.
• Optimizar una tienda existente — mejorar las tasas de conversión, solucionar problemas de experiencia móvil, añadir datos estructurados SEO o mejorar la accesibilidad en el flujo de compra.
• Planificar la implementación de una tienda — generar un plan de construcción paso a paso que haga referencia a los archivos de referencia correctos y evite los errores conocidos antes de escribir cualquier código.

• Proyectos que no son de comercio electrónico — paneles de administración, aplicaciones SaaS, blogs o cualquier sitio sin un flujo de compra/adquisición no tienen ningún uso para los patrones de esta habilidad.
• Trabajo exclusivamente de backend o API — si solo estás trabajando en la lógica de comercio del lado del servidor sin ningún componente de storefront frontend involucrado, esta habilidad aporta poco valor.

Antes de escribir cualquier código que llame a una API o SDK de backend, la habilidad impone un flujo de trabajo de 5 pasos: pausar, consultar la documentación o el servidor MCP, verificar el método con el usuario, escribir el código y luego comprobar si hay errores de TypeScript. Esto previene nombres de métodos inventados, ejemplos desactualizados y fallos silenciosos en tiempo de ejecución.

La habilidad mapea cada tarea del storefront — pago, listado de productos, navegación, SEO, móvil, integración con Medusa y más — a un archivo de referencia específico (por ejemplo, reference/layouts/checkout.md, reference/medusa.md). Especifica exactamente qué archivos cargar antes de implementar cada funcionalidad, garantizando que los patrones se apliquen de manera consistente.

Cubre reglas de alto impacto únicas para storefronts: aria-live="polite" en contadores de carrito para lectores de pantalla, env(safe-area-inset-bottom) para botones fijos en iOS, tamaño mínimo de área táctil de 44px, uso obligatorio de loading="lazy" en imágenes de productos por debajo del pliegue, y prohibición de emojis en la interfaz de usuario del storefront.

Proporciona patrones de rutas dinámicas correctos para Next.js (App Router y Pages Router), SvelteKit, TanStack Start y Remix para páginas de productos y categorías. Advierte explícitamente contra las rutas estáticas por elemento que no escalan.

Cubre la inicialización del SDK de Medusa (se requiere clave API publicable), la visualización correcta de precios (no dividir entre 100), el requisito de region_id al obtener productos, las convenciones de puerto CORS (8000), la configuración SSR de Vite, el uso de @medusajs/types en lugar de tipos personalizados, y la limpieza del estado del carrito tras realizar un pedido.

Una lista categorizada de más de 30 antipatrones identificados en áreas como carrito/navegación, exploración de productos, proceso de pago, móvil, SEO, rendimiento, coherencia de diseño e integración de backend — cada uno formulado como una regla concreta ❌ para verificar antes y durante la implementación.

La habilidad proporciona un flujo de trabajo secuencial de 10 pasos que va desde el descubrimiento (cargando design.md) hasta la fundación, los componentes principales, el flujo de compra y la optimización. Cada paso hace referencia al archivo exacto que se debe cargar antes de implementar, asegurando que no se omita nada y que los estilos se mantengan coherentes.

Guía las decisiones de arquitectura del proceso de compra (página única vs. múltiples pasos), exige la obtención de los métodos de pago desde el backend en lugar de codificarlos directamente, señala el requisito de compra como invitado y proporciona los pasos de integración de pagos específicos de Medusa a través de reference/layouts/checkout.md y reference/medusa.md.

Cubre la configuración del SDK, patrones de región y precios, obtención de productos con region_id, listas de países limitadas a la región del carrito, configuración de Vite SSR y uso del servidor Medusa MCP para verificación de métodos — previniendo los errores de integración de storefront más comunes en Medusa.

Dirige a los desarrolladores a reference/mobile-responsiveness.md para conocer los tamaños de los objetivos táctiles, los márgenes de área segura y la optimización de imágenes, y a reference/seo.md para el esquema JSON-LD de productos, las metaetiquetas, Open Graph y la medición de Core Web Vitals mediante PageSpeed Insights.