Storefront Best Practices

• Construindo ou estendendo um storefront de ecommerce — qualquer framework (Next.js, SvelteKit, TanStack Start, React, Vue): páginas de produto, listagens de produtos, carrinho, checkout, navegação, página inicial, busca, páginas de conta ou confirmação de pedido.
• Integrando um backend (incluindo Medusa) — configuração do SDK, busca de produtos/categorias/regiões, exibição de preços, seleção de método de pagamento e gerenciamento de carrinho.
• Otimizando uma loja existente — melhorando taxas de conversão, corrigindo problemas de experiência mobile, adicionando dados estruturados de SEO ou melhorando a acessibilidade no fluxo de compras.
• Planejando uma implementação de storefront — gerando um plano de construção passo a passo que referencia os arquivos de referência corretos e evita armadilhas conhecidas antes de escrever qualquer código.

• Projetos não relacionados a e-commerce — painéis administrativos, aplicações SaaS, blogs ou qualquer site sem um fluxo de compras não têm utilidade para os padrões desta skill.
• Trabalho puramente de backend ou API — se você está trabalhando apenas na lógica de comércio do lado do servidor sem nenhum componente de storefront frontend envolvido, esta skill agrega pouco valor.

Antes de escrever qualquer código que chame uma API ou SDK de backend, a skill impõe um fluxo de trabalho de 5 etapas: pausar, consultar a documentação ou o servidor MCP, verificar o método com o usuário, escrever o código e, em seguida, verificar erros de TypeScript. Isso evita nomes de métodos inventados, exemplos desatualizados e falhas silenciosas em tempo de execução.

A skill mapeia cada tarefa do storefront — checkout, listagem de produtos, navegação, SEO, mobile, integração com Medusa e muito mais — para um arquivo de referência específico (ex.: reference/layouts/checkout.md, reference/medusa.md). Ela especifica exatamente quais arquivos carregar antes de implementar cada funcionalidade, garantindo que os padrões sejam aplicados de forma consistente.

Abrange regras de alto impacto exclusivas de storefronts: aria-live="polite" em contadores de carrinho para leitores de tela, env(safe-area-inset-bottom) para botões fixos no iOS, mínimo de 44px para alvos de toque, loading="lazy" obrigatório em imagens de produtos abaixo da dobra, e proibição de emojis na interface do storefront.

Fornece padrões corretos de rotas dinâmicas para Next.js (App Router e Pages Router), SvelteKit, TanStack Start e Remix para páginas de produtos e categorias. Alerta explicitamente contra rotas estáticas por item que não escalam.

Aborda a inicialização do SDK do Medusa (chave de API publicável obrigatória), exibição correta de preços (não dividir por 100), requisito de region_id ao buscar produtos, convenções de porta CORS (8000), configuração de SSR com Vite, uso de @medusajs/types em vez de tipos personalizados, e limpeza do estado do carrinho após a realização do pedido.

Uma lista categorizada com mais de 30 antipadrões nomeados abrangendo carrinho/navegação, navegação de produtos, checkout, mobile, SEO, performance, consistência de design e integração de backend — cada um formulado como uma regra concreta ❌ para verificar antes e durante a implementação.

A skill fornece um fluxo de trabalho sequencial de 10 etapas, desde a descoberta (carregando design.md) até a fundação, componentes principais, fluxo de compra e otimização. Cada etapa referencia o arquivo exato a ser carregado antes da implementação, garantindo que nada seja esquecido e os estilos permaneçam consistentes.

Orienta decisões de arquitetura do checkout (página única vs. múltiplas etapas), garante a busca de métodos de pagamento pelo backend em vez de codificá-los diretamente, sinaliza o requisito de checkout como convidado e fornece as etapas de integração de pagamento específicas do Medusa por meio de reference/layouts/checkout.md e reference/medusa.md.

Abrange configuração do SDK, padrões de região e precificação, busca de produtos com region_id, listas de países com escopo para a região do carrinho, configuração do Vite SSR e uso do servidor Medusa MCP para verificação de métodos — prevenindo os erros mais comuns de integração de storefront com Medusa.

Direciona os desenvolvedores para reference/mobile-responsiveness.md para tamanhos de áreas de toque, inserções de área segura e otimização de imagens, e para reference/seo.md para esquema JSON-LD de Produto, meta tags, Open Graph e medição de Core Web Vitals via PageSpeed Insights.