Storefront Best Practices

• Costruire o estendere uno storefront ecommerce — qualsiasi framework (Next.js, SvelteKit, TanStack Start, React, Vue): pagine prodotto, listini prodotti, carrello, checkout, navigazione, homepage, ricerca, pagine account o conferma ordine.
• Integrare un backend (incluso Medusa) — configurazione dell'SDK, recupero di prodotti/categorie/regioni, visualizzazione dei prezzi, selezione del metodo di pagamento e gestione del carrello.
• Ottimizzare uno store esistente — migliorare i tassi di conversione, risolvere problemi di esperienza mobile, aggiungere dati strutturati SEO o migliorare l'accessibilità nel flusso di acquisto.
• Pianificare l'implementazione di uno storefront — generare un piano di sviluppo passo dopo passo che faccia riferimento ai file di riferimento corretti ed eviti le insidie note prima di scrivere qualsiasi codice.

• Progetti non e-commerce — dashboard amministrative, applicazioni SaaS, blog o qualsiasi sito privo di un flusso di acquisto/pagamento non hanno alcun utilizzo per i pattern di questa skill.
• Lavoro puramente backend o API — se stai lavorando esclusivamente sulla logica commerce lato server senza alcun componente frontend di storefront coinvolto, questa skill aggiunge poco valore.

Prima di scrivere qualsiasi codice che chiami un'API backend o un SDK, la skill impone un flusso di lavoro in 5 fasi: pausa, consultazione della documentazione o del server MCP, verifica del metodo con l'utente, scrittura del codice, quindi controllo degli errori TypeScript. Questo previene nomi di metodi indovinati, esempi obsoleti e fallimenti silenziosi a runtime.

La skill mappa ogni attività dello storefront — checkout, schede prodotto, navigazione, SEO, mobile, integrazione con Medusa e altro ancora — a un file di riferimento specifico (ad es., reference/layouts/checkout.md, reference/medusa.md). Specifica esattamente quali file caricare prima di implementare ciascuna funzionalità, garantendo che i pattern vengano applicati in modo coerente.

Copre le regole ad alto impatto uniche per i negozi online: aria-live="polite" sul conteggio del carrello per gli screen reader, env(safe-area-inset-bottom) per i pulsanti fissi su iOS, target touch minimi di 44px, loading="lazy" obbligatorio sulle immagini dei prodotti sotto la piega, e il divieto di emoji nell'interfaccia utente del negozio.

Fornisce i pattern corretti per le route dinamiche in Next.js (App Router e Pages Router), SvelteKit, TanStack Start e Remix per le pagine di prodotto e categoria. Avverte esplicitamente contro l'uso di route statiche per singolo elemento che non scalano.

Tratta l'inizializzazione dell'SDK di Medusa (chiave API pubblicabile obbligatoria), la visualizzazione corretta dei prezzi (non dividere per 100), il requisito di region_id durante il recupero dei prodotti, le convenzioni sulle porte CORS (8000), la configurazione Vite SSR, l'utilizzo di @medusajs/types al posto di tipi personalizzati e la cancellazione dello stato del carrello dopo il completamento dell'ordine.

Un elenco categorizzato di oltre 30 anti-pattern denominati relativi a carrello/navigazione, esplorazione dei prodotti, checkout, mobile, SEO, prestazioni, coerenza del design e integrazione backend — ognuno formulato come una concreta regola ❌ da verificare prima e durante l'implementazione.

La skill fornisce un flusso di lavoro sequenziale in 10 passaggi che va dalla fase di scoperta (caricamento di design.md) fino a fondamenta, componenti principali, flusso d'acquisto e ottimizzazione. Ogni passaggio fa riferimento al file esatto da caricare prima dell'implementazione, garantendo che nulla venga tralasciato e che gli stili rimangano coerenti.

Guida le decisioni architetturali relative al checkout (pagina singola vs. multi-step), impone il recupero dei metodi di pagamento dal backend anziché definirli staticamente nel codice, segnala il requisito del checkout come ospite e fornisce i passaggi di integrazione dei pagamenti specifici per Medusa tramite reference/layouts/checkout.md e reference/medusa.md.

Copre la configurazione dell'SDK, i pattern di regione e pricing, il recupero dei prodotti con region_id, le liste di paesi limitate alla regione del carrello, la configurazione di Vite SSR e l'utilizzo del server Medusa MCP per la verifica dei metodi — prevenendo gli errori di integrazione più comuni nel frontend Medusa.

Indirizza gli sviluppatori a reference/mobile-responsiveness.md per le dimensioni dei target touch, gli inset delle aree sicure e l'ottimizzazione delle immagini, e a reference/seo.md per lo schema Product JSON-LD, i meta tag, Open Graph e la misurazione dei Core Web Vitals tramite PageSpeed Insights.