Bonnes pratiques pour vitrine e-commerce

Guide complet pour la création de vitrines e-commerce modernes et à haut taux de conversion couvrant les motifs UI/UX, la conception de composants, les structures de mise en page, l'optimisation SEO et la réactivité mobile.

Quand appliquer

TOUJOURS charger cette skill lors de TOUTE tâche de vitrine :

Ajouter une page/flux de paiement - Paiement, livraison, passation de commande
Implémenter un panier - Page panier, popup panier, fonctionnalité d'ajout au panier
Créer des pages produit - Détails produit, listes produits, grilles produits
Créer la navigation - Navbar, megamenu, footer, menu mobile
Intégrer backend Medusa - Configuration SDK, panier, produits, paiement
Tout composant de vitrine - Page d'accueil, recherche, filtres, pages compte
Construire de nouvelles vitrines e-commerce à partir de zéro
Améliorer les expériences d'achat existantes et les taux de conversion
Optimiser l'accessibilité, la convivialité et le SEO
Concevoir des expériences e-commerce réactives sur mobile

Exemples de prompts qui devraient déclencher cette skill :

« Ajouter une page de paiement »
« Implémenter le panier »
« Créer une page de liste produits »
« Se connecter au backend Medusa »
« Ajouter un menu de navigation »
« Construire la page d'accueil de la boutique »

CRITIQUE : Charger les fichiers de référence si nécessaire

⚠️ TOUJOURS charger reference/design.md AVANT de créer UN composant UI

Découvre les tokens de design existants (couleurs, polices, espacements, motifs)
Évite d'introduire des styles incohérents
Fournit des garde-fous pour maintenir la cohérence de marque
Requis pour chaque composant, pas seulement les nouvelles vitrines

Charger ces références selon ce que vous implémentez :

Démarrer une nouvelle vitrine ? → DOIT charger reference/design.md en premier pour découvrir les préférences utilisateur
Vous connecter à l'API backend ? → DOIT charger reference/connecting-to-backend.md en premier
Vous connecter au backend Medusa ? → DOIT charger reference/medusa.md pour la configuration SDK, les prix, les régions et les motifs Medusa
Implémenter la page d'accueil ? → DOIT charger reference/components/navbar.md, reference/components/hero.md, reference/components/footer.md et reference/layouts/home-page.md
Implémenter la navigation ? → DOIT charger reference/components/navbar.md et optionnellement reference/components/megamenu.md
Construire une liste produits ? → DOIT charger reference/layouts/product-listing.md en premier
Construire des détails produit ? → DOIT charger reference/layouts/product-details.md en premier
Implémenter le paiement ? → DOIT charger reference/layouts/checkout.md en premier
Optimiser pour le SEO ? → DOIT charger reference/seo.md en premier
Optimiser pour mobile ? → DOIT charger reference/mobile-responsiveness.md en premier

Minimum requis : Charger au moins 1-2 fichiers de référence pertinents à votre tâche spécifique avant l'implémentation.

Flux de travail de planification et d'implémentation

IMPORTANT : Si vous créez un plan pour implémenter des fonctionnalités de vitrine, incluez les éléments suivants dans votre plan :

Lors de l'implémentation de chaque composant, page, mise en page ou fonctionnalité du plan :

Faire référence à cette skill avant de commencer l'implémentation
Charger les fichiers de référence pertinents listés ci-dessus pour le composant/page spécifique que vous construisez
Suivre les motifs et les conseils dans les fichiers de référence
Vérifier les sections des erreurs communes pour éviter les pièges connus

Exemple de structure de plan :

Tâche 1 : Implémenter la navigation
- Charger reference/components/navbar.md
- Suivre les motifs de navbar.md (récupération dynamique de catégories, visibilité du panier, etc.)
- Faire référence à la skill pour les erreurs communes (p. ex., codage en dur des catégories)

Tâche 2 : Implémenter la page de liste produits
- Charger reference/layouts/product-listing.md
- Suivre les motifs de pagination/filtrage de product-listing.md
- Utiliser reference/components/product-card.md pour les éléments de grille produits
- Vérifier la skill pour les conseils d'intégration backend

Tâche 3 : Implémenter le flux de paiement
- Charger reference/layouts/checkout.md
- Charger reference/medusa.md pour l'intégration paiement Medusa
- Suivre les recommandations d'architecture de composants (composants d'étapes séparés)
- Faire référence à la skill pour les exigences de récupération des méthodes de paiement

Pourquoi cela importe :

Les plans fournissent une stratégie haut niveau
Les fichiers de référence fournissent des motifs d'implémentation détaillés
Le fichier de skill contient des erreurs critiques à éviter
Suivre ce flux de travail garantit la cohérence et les meilleures pratiques

Motifs critiques spécifiques à l'e-commerce

Accessibilité

CRITIQUE : Les mises à jour du nombre d'articles du panier nécessitent aria-live="polite" - Les lecteurs d'écran n'annonceront pas sans cela
Assurer la navigation au clavier pour toutes les interactions panier/paiement

Mobile

Les éléments sticky en bas DOIVENT utiliser env(safe-area-inset-bottom) - L'indicateur d'accueil iOS coupera sinon les boutons d'achat
44px minimum de cibles tactiles pour les actions panier, sélecteurs de variantes, boutons de quantité

Performance

TOUJOURS ajouter loading="lazy" aux images produit en bas de page - Ne pas se fier aux valeurs par défaut du navigateur
Optimiser les images produit pour mobile (<500 Ko) - La plupart du trafic e-commerce est mobile

Optimisation de la conversion

CTAs clairs dans tout le flux d'achat
Friction minimale au paiement (paiement invité si supporté)
Signaux de confiance (avis, badges de sécurité, politique de retour) près des boutons d'achat
Informations de prix et livraison claires dès le départ

SEO

Schéma produit (JSON-LD) requis - Critique pour Google Shopping et les extraits enrichis
Utiliser PageSpeed Insights pour mesurer les Core Web Vitals

Conception visuelle

NE JAMAIS utiliser d'emojis dans l'UI de vitrine - Utiliser des icônes ou des images à la place (non professionnel, problèmes d'accessibilité)

Intégration backend

Détection du backend : Si en monorepo, vérifier le répertoire backend. Si incertain, demander à l'utilisateur quel backend est utilisé.
NE JAMAIS coder en dur du contenu dynamique : Toujours récupérer les catégories, régions, produits, options de livraison, etc. du backend - ils changent fréquemment
Ne pas supposer la structure API - vérifier les endpoints et les formats de données

⚠️ CRITIQUE : Flux de travail de vérification de méthode SDK backend

VOUS DEVEZ SUIVRE CE FLUX DE TRAVAIL EXACT AVANT D'ÉCRIRE DU CODE QUI SE CONNECTE AU BACKEND :

Étape 1 : PAUSE - N'écrivez PAS de code encore

Vous êtes sur le point d'écrire du code qui appelle une API backend ou une méthode SDK (p. ex., SDK Medusa, API REST, GraphQL)
ARRÊTEZ - Ne procédez pas au code sans vérification

Étape 2 : INTERROGER la documentation ou le serveur MCP

Si le serveur MCP est disponible : L'interroger pour la méthode exacte (par exemple, Medusa MCP)
Si pas de serveur MCP : Rechercher la documentation officielle
Trouver : Nom exact de la méthode, paramètres, type de retour

Étape 3 : VÉRIFIER ce que vous avez trouvé

Énoncer à haute voix à l'utilisateur : « Je dois vérifier la méthode correcte pour [opération]. Laissez-moi vérifier [serveur MCP/documentation]. »
Montrer à l'utilisateur ce que vous avez trouvé : « Selon [source], la méthode est sdk.store.cart.methodName(params) »
Confirmer la signature de la méthode et les paramètres

Étape 4 : SEULEMENT ALORS écrire le code

Maintenant vous pouvez écrire du code en utilisant la méthode vérifiée
Utiliser la signature exacte que vous avez trouvée

Étape 5 : VÉRIFIER les erreurs TypeScript

Après avoir écrit le code, vérifier les erreurs TypeScript/type liées au SDK
Si vous voyez des erreurs de type sur les méthodes SDK, cela signifie que vous avez utilisé un nom de méthode incorrect ou des paramètres incorrects
Les erreurs de type sont un signe que vous n'avez pas vérifié correctement - Retourner à l'étape 2

CECI N'EST PAS OPTIONNEL - CECI EST UN FLUX OBLIGATOIRE DE PRÉVENTION DES ERREURS

C'est une ERREUR CRITIQUE de :

❌ Écrire du code qui appelle des APIs/SDKs backend sans interroger explicitement les docs/MCP en premier
❌ Deviner les noms ou paramètres de méthode
❌ Ignorer les erreurs TypeScript sur les méthodes SDK (les erreurs indiquent une utilisation incorrecte de la méthode)
❌ Copier les exemples de cette skill sans vérification (les exemples peuvent être obsolètes)
❌ Supposer que les méthodes SDK correspondent aux endpoints API REST

Pour Medusa spécifiquement :

Prix Medusa : Afficher les prix tels quels - NE PAS diviser par 100 (contrairement à Stripe, Medusa stocke les prix au format d'affichage)
Serveur Medusa MCP : https://docs.medusajs.com/mcp - Recommander la configuration si non installée
Charger reference/medusa.md pour les motifs spécifiques à Medusa (régions, prix, etc.)

Motifs de routage

TOUJOURS utiliser des routes dynamiques pour les produits et les catégories - NE JAMAIS créer de pages statiques pour les articles individuels
Pages produit : Utiliser des routes dynamiques comme /products/[handle] ou /products/$handle, PAS /products/shirt.tsx
Pages catégorie : Utiliser des routes dynamiques comme /categories/[handle] ou /categories/$handle, PAS /categories/women.tsx
Motifs spécifiques au framework :
- Next.js App Router : app/products/[handle]/page.tsx ou app/products/[id]/page.tsx
- Next.js Pages Router : pages/products/[handle].tsx
- SvelteKit : routes/products/[handle]/+page.svelte
- TanStack Start : routes/products/$handle.tsx
- Remix : routes/products.$handle.tsx
Pourquoi : Les routes dynamiques montent à n'importe quel nombre de produits/catégories sans créer de fichiers individuels
Les routes statiques ne sont pas maintenables et n'évoluent pas (imaginez créer 1000 fichiers produits)

Guides de sélection de motifs

Quand vous avez besoin de choisir entre les motifs d'implémentation, charger le fichier de référence pertinent :

Stratégie de paiement (une seule page vs multi-étapes) → Charger reference/layouts/checkout.md
Stratégie de navigation (dropdown vs megamenu) → Charger reference/components/navbar.md et reference/components/megamenu.md
Stratégie de liste produits (pagination vs défilement infini vs charger plus) → Charger reference/layouts/product-listing.md
Stratégie de recherche (autocomplétion vs filtres vs langage naturel) → Charger reference/components/search.md
Priorités mobile vs desktop → Charger reference/mobile-responsiveness.md
Sélection de variante (texte vs nuanciers vs configurateur) → Charger reference/layouts/product-details.md
Motif panier (popup vs tiroir vs navigation page) → Charger reference/components/cart-popup.md et reference/layouts/cart.md
Stratégie des signaux de confiance → Charger reference/layouts/product-details.md et reference/layouts/checkout.md

Chaque fichier de référence contient des cadres de décision avec des critères spécifiques pour vous aider à choisir le bon motif pour votre contexte.

Référence rapide

Général

reference/connecting-to-backend.md    - Détection de framework, configuration API, motifs d'intégration backend
reference/medusa.md                    - Intégration SDK Medusa, prix, régions, types TypeScript
reference/design.md                    - Préférences utilisateur, identité de marque, systèmes de design
reference/seo.md                       - Balises meta, données structurées, Core Web Vitals
reference/mobile-responsiveness.md     - Design mobile-first, points d'arrêt réactifs, interactions tactiles

Composants

reference/components/navbar.md         - Navigation desktop/mobile, logo, menu, icône panier, charger pour TOUTES les pages
reference/components/megamenu.md       - Organisation de catégories, produits en vedette, alternatives mobiles
reference/components/cart-popup.md     - Feedback ajout au panier, affichage mini panier
reference/components/country-selector.md - Sélection de pays/région, devise, prix, régions Medusa
reference/components/breadcrumbs.md    - Hiérarchie de catégories, balisage de données structurées
reference/components/search.md         - Entrée de recherche, autocomplétion, résultats, filtres
reference/components/product-reviews.md - Affichage d'avis, agrégation de notes, soumission
reference/components/hero.md           - Mises en page hero, placement CTA, optimisation image
reference/components/popups.md         - Inscription newsletter, popups remise, exit-intent
reference/components/footer.md         - Organisation du contenu, navigation, réseaux sociaux, charger pour TOUTES les pages
reference/components/product-card.md   - Images produit, prix, ajout au panier, badges
reference/components/product-slider.md - Implémentation carrousel, balayage mobile, accessibilité

Mises en page

reference/layouts/home-page.md         - Hero, catégories en vedette, listes produits
reference/layouts/product-listing.md   - Vues grille/liste, filtres, tri, pagination
reference/layouts/product-details.md   - Galerie d'images, sélection de variantes, produits associés
reference/layouts/cart.md              - Éléments panier, mises à jour de quantité, codes promo
reference/layouts/checkout.md          - Multi-étapes/une seule page, formulaires d'adresse, paiement
reference/layouts/order-confirmation.md - Numéro de commande, résumé, informations de livraison
reference/layouts/account.md           - Tableau de bord, historique de commandes, carnet d'adresses
reference/layouts/static-pages.md      - FAQ, à propos, contact, politiques d'expédition/retours

Fonctionnalités

reference/features/wishlist.md         - Ajouter aux favoris, page favoris, déplacer au panier
reference/features/promotions.md       - Bannières promotionnelles, codes remise, badges solde

Motifs d'implémentation courants

Démarrer une nouvelle vitrine

IMPORTANT : Pour chaque étape ci-dessous, charger les fichiers référencés AVANT d'implémenter cette étape.

1. Phase de découverte → Lire design.md pour les préférences utilisateur
2. Configuration de base → Lire connecting-to-backend.md (ou medusa.md pour Medusa), mobile-responsiveness.md, seo.md
3. Composants principaux → Implémenter navbar.md, footer.md
4. Page d'accueil → Lire home-page.md
5. Navigation produit → Lire product-listing.md, product-card.md, search.md
6. Détails produit → Lire product-details.md, product-reviews.md
7. Panier et paiement → Lire cart-popup.md, cart.md, checkout.md, order-confirmation.md
8. Compte utilisateur → Lire account.md
9. Fonctionnalités supplémentaires → Lire wishlist.md, promotions.md
10. Optimisation → Audit SEO (seo.md), test mobile (mobile-responsiveness.md)

Même si vous créez un plan d'implémentation, faire référence à la skill et charger les fichiers de référence pertinents lors de l'implémentation de chaque étape.

Motif de flux d'achat

Parcourir → Afficher → Panier → Paiement

Parcourir :   home-page.md → product-listing.md
Afficher :    product-details.md + product-reviews.md
Panier :      cart-popup.md → cart.md
Paiement :    checkout.md → order-confirmation.md

Guide de sélection de composants

Pour les grilles de produits et le filtrage → product-listing.md et product-card.md Pour les cartes produit → product-card.md Pour la navigation → navbar.md et megamenu.md Pour la fonctionnalité de recherche → search.md Pour le flux de paiement → checkout.md Pour les promotions et les soldes → promotions.md

Considérations de conception

Avant d'implémenter, considérer :

Préférences utilisateur - Lire design.md pour découvrir les préférences de style de conception
Identité de marque - Couleurs, typographie, ton qui correspondent à la marque
Public cible - B2C vs B2B, démographie, utilisation d'appareils
Type de produit - La mode vs l'électronique vs les épiceries affectent les choix de mise en page
Exigences commerciales - Multi-devise, multi-langue, spécifique à la région
Système backend - La structure API affecte l'implémentation des composants

Intégration avec Medusa

Medusa est un backend e-commerce moderne et flexible. Considérer Medusa quand :

Construire une nouvelle vitrine e-commerce
Besoin d'une solution de commerce sans tête
Support intégré pour multi-région, multi-devise souhaité
Moteur de promotion et de remise puissant nécessaire
Modélisation de produits flexible requise

Pour des conseils d'intégration Medusa détaillés, voir reference/medusa.md. Pour les motifs backend généraux, voir reference/connecting-to-backend.md.

Agnostique au framework

Tous les conseils sont agnostiques au framework. Les exemples utilisent React/TypeScript où les démonstrations de code sont utiles, mais les motifs s'appliquent à :

Next.js
SvelteKit
TanStack Start
Tout framework frontend moderne

Fonctionnalités minimales viables

Obligatoire pour le lancement (flux d'achat principal) :

Navbar avec panier, catégories, recherche
Liste produits avec filtrage et pagination
Détails produit avec sélection de variantes
Fonctionnalité d'ajout au panier
Page panier avec gestion des articles
Flux de paiement (livraison, paiement, révision)
Page de confirmation de commande

Bonus (ajouter si le temps le permet) :

Recommandations de produits associés
Avis et évaluations produit
Fonctionnalité favoris
Zoom image sur les pages produit
Navigation en bas sur mobile
Mega-menu pour la navigation
Inscription newsletter
Comparaison de produits
Modales d'aperçu rapide

Dépendant de l'utilisateur (demander avant d'implémenter) :

Paiement invité vs connexion obligatoire
Fonctionnalités du tableau de bord du compte
Support multi-langue
Support multi-devise
Support chat en direct

Top des erreurs e-commerce à éviter

Avant d'implémenter, surveillez ces pièges courants spécifiques à l'e-commerce :

1. Erreurs de panier et de navigation

❌ Masquer l'indicateur de panier dans le menu hamburger mobile (tenir toujours visible)
❌ Ne pas afficher les mises à jour en temps réel du nombre d'articles du panier
❌ CRITIQUE : aria-live="polite" manquant sur le nombre d'articles du panier - Les lecteurs d'écran n'annonceront pas les mises à jour du panier sans cela
❌ Ne pas afficher les détails de variante (taille, couleur, etc.) dans la popup panier - afficher seulement le titre produit
❌ Megamenu se ferme au survol du contenu dropdown (doit rester ouvert au survol du déclencheur OU du dropdown)
❌ CRITIQUE : Erreurs de positionnement du megamenu - Trois erreurs communes :
- ❌ Navbar n'a pas position: relative (le megamenu ne se positionnera pas correctement)
- ❌ Megamenu positionné relativement au bouton de déclenchement au lieu de la navbar (utiliser absolute left-0 sur megamenu)
- ❌ Megamenu ne s'étend pas sur toute la largeur (doit utiliser right-0 ou w-full, pas seulement w-auto)
❌ Coder en dur les catégories, les produits en vedette ou tout contenu dynamique au lieu de récupérer du backend
❌ Aucune indication claire de la page actuelle dans la navigation de catégories

2. Erreurs de navigation produit

❌ Créer des routes statiques pour les produits/catégories (utiliser des routes dynamiques comme /products/[handle] au lieu de /products/shirt.tsx)
❌ État vide « aucun produit trouvé » manquant avec suggestions utiles
❌ Pas d'indicateurs de chargement lors de la récupération des produits
❌ Pagination sans URLs SEO-friendly (pour les moteurs de recherche)
❌ Sélections de filtre qui ne persistent pas au rechargement de la page

3. Erreurs de détails produit

❌ Activer « Ajouter au panier » avant la sélection de variante (taille, couleur, etc.)
❌ Optimisation des images produit manquante (grandes images non compressées)
❌ Quitter la page produit après ajout au panier (rester sur la page)
❌ Utiliser des emojis dans l'UI au lieu d'icônes ou d'images (non professionnel, problèmes d'accessibilité)

4. Erreurs de conception et de cohérence

❌ CRITIQUE : Ne pas charger reference/design.md avant de créer UN composant UI - Mène à des couleurs, polices et styles incohérents
❌ Introduire de nouvelles couleurs sans vérifier le thème existant
❌ Ajouter de nouvelles polices sans vérifier ce qui est déjà utilisé
❌ Utiliser des valeurs Tailwind arbitraires quand les tokens de thème existent
❌ Ne pas détecter la version Tailwind (v3 vs v4) - Cause des erreurs de syntaxe

5. Erreurs de paiement et de conversion

❌ Exiger la création de compte pour le paiement (offrir le paiement invité si le backend le supporte)
❌ Ne pas récupérer les méthodes de paiement du backend - supposer les options de paiement disponibles ou ignorer la sélection de méthode de paiement
❌ Paiement multi-étapes trop complexe (4+ étapes tuent la conversion) - Optimal est 3 étapes : Infos livraison, Méthode livraison + Paiement, Révision
❌ Signaux de confiance manquants (badge paiement sécurisé, lien politique de retour)
❌ Ne pas gérer les erreurs de rupture de stock gracieusement pendant le paiement

6. Erreurs d'expérience mobile

❌ Cibles tactiles plus petites que 44x44px (boutons, liens, champs de formulaire)
❌ Menus au survol style desktop sur mobile (utiliser le tap/clic à la place)
❌ Ne pas optimiser les images pour mobile (charger d'énormes images desktop)
❌ Motifs mobiles manquants (nav en bas, filtres tiroir)

7. Erreurs de performance et de SEO

❌ Données structurées manquantes (schéma Produit) pour le SEO
❌ Pas de chargement explicite d'images lazy (ne pas supposer les valeurs par défaut du navigateur) - Toujours ajouter loading="lazy" aux images en bas de page
❌ Balises meta et Open Graph manquantes pour le partage sur réseaux sociaux
❌ Ne pas optimiser les Core Web Vitals (LCP, FID, CLS) - Utiliser PageSpeed Insights ou Lighthouse pour mesurer

8. Erreurs d'intégration backend

❌ ERREUR : Écrire du code qui appelle des APIs/SDKs backend sans suivre le flux de travail de vérification en 5 étapes - Vous DEVEZ : 1) PAUSE, 2) INTERROGER docs/MCP, 3) VÉRIFIER avec l'utilisateur, 4) Écrire du code, 5) VÉRIFIER les erreurs de type
❌ ERREUR : Ignorer les erreurs TypeScript sur les méthodes SDK - Les erreurs de type signifient que vous avez utilisé des noms de méthode incorrects ou des paramètres incorrects. Retourner et vérifier avec docs/MCP
❌ ERREUR : Deviner les noms de méthode API, les méthodes SDK ou les paramètres - Toujours vérifier les signatures exactes de méthode avant utilisation
❌ ERREUR : Ne pas utiliser le serveur Medusa MCP quand disponible - Si utiliser le backend Medusa, toujours interroger le serveur MCP pour les méthodes
❌ ERREUR : Copier les exemples de code sans vérifier qu'ils sont actuels - Les exemples peuvent être obsolètes, toujours vérifier en premier
❌ Ne pas détecter quel backend est utilisé (vérifier le monorepo, demander à l'utilisateur si incertain)
❌ Supposer la structure API sans vérifier la documentation backend ou le serveur MCP
❌ Coder en dur du contenu dynamique (catégories, régions, produits, etc.) au lieu de récupérer du backend
❌ Définir des types personnalisés pour les entités Medusa au lieu d'utiliser le package @medusajs/types
❌ Initialiser le SDK Medusa sans clé API publiable (requis pour les magasins multi-régions et les prix produit)
❌ Récupérer les produits Medusa sans passer le paramètre de requête region_id (cause des prix manquants ou incorrects)
❌ Afficher tous les pays au paiement Medusa - doit afficher seulement les pays de la région du panier
❌ Diviser les prix Medusa par 100 (Medusa stocke les prix tels quels, pas en centimes comme Stripe)
❌ Configuration Vite SSR manquante pour SDK Medusa (ajouter ssr.noExternal: ['@medusajs/js-sdk'] à vite.config.ts)
❌ Exécuter la vitrine Medusa sur un port autre que 8000 (cause des erreurs CORS - le backend Medusa s'attend au port 8000 par défaut)
❌ Ne pas gérer les états de chargement, d'erreur et vide pour les appels API
❌ Effectuer des appels API côté client qui devraient être côté serveur (SEO, sécurité)
❌ Pas de messages d'erreur appropriés (« Une erreur s'est produite » vs « Produit en rupture de stock »)
❌ Invalidation de cache manquante (données produit obsolètes, prix, inventaire)
❌ Ne pas effacer l'état du panier après la passation de commande - La popup panier affiche les anciens articles parce que le panier n'a pas été réinitialisé depuis Context/localStorage/cache

storefront-best-practices