Storefront Best Practices

• Создание или расширение витрины интернет-магазина — любой фреймворк (Next.js, SvelteKit, TanStack Start, React, Vue): страницы товаров, списки товаров, корзина, оформление заказа, навигация, главная страница, поиск, страницы аккаунта или подтверждение заказа.
• Интеграция бэкенда (включая Medusa) — настройка SDK, получение товаров/категорий/регионов, отображение цен, выбор способа оплаты и управление корзиной.
• Оптимизация существующего магазина — повышение конверсии, исправление проблем с мобильным опытом, добавление структурированных данных SEO или улучшение доступности в процессе оформления покупки.
• Планирование реализации витрины — создание пошагового плана разработки, который ссылается на правильные справочные файлы и позволяет избежать известных подводных камней перед написанием кода.

• Проекты без электронной коммерции — административные панели, SaaS-приложения, блоги или любые сайты без процесса покупок не нуждаются в паттернах этого навыка.
• Чисто серверная разработка или работа с API — если вы работаете исключительно над серверной логикой коммерции без какого-либо фронтендового компонента витрины, этот навык имеет небольшую ценность.

Перед написанием любого кода, обращающегося к бэкенд-API или SDK, навык предписывает соблюдение рабочего процесса из 5 шагов: остановиться, запросить документацию или MCP-сервер, согласовать метод с пользователем, написать код, затем проверить на ошибки TypeScript. Это предотвращает использование угаданных названий методов, устаревших примеров и скрытых сбоев во время выполнения.

Навык сопоставляет каждую задачу витрины — оформление заказа, листинг товаров, навигацию, SEO, мобильную адаптацию, интеграцию с Medusa и многое другое — с конкретным референсным файлом (например, reference/layouts/checkout.md, reference/medusa.md). Он точно определяет, какие файлы необходимо загрузить перед реализацией каждой функции, обеспечивая единообразное применение паттернов.

Охватывает высокоэффективные правила, уникальные для витрин магазинов: aria-live="polite" для счётчиков корзины в целях доступности для экранных дикторов, env(safe-area-inset-bottom) для фиксированных кнопок на iOS, минимальный размер сенсорных целей 44px, обязательный атрибут loading="lazy" для изображений товаров ниже линии сгиба, а также запрет на использование эмодзи в интерфейсе витрины Storefront Best Practices.

Предоставляет корректные шаблоны динамической маршрутизации для Next.js (App Router и Pages Router), SvelteKit, TanStack Start и Remix для страниц товаров и категорий. Явно предупреждает против использования статических маршрутов для отдельных элементов, которые не масштабируются.

Охватывает инициализацию Medusa SDK (требуется публикуемый API-ключ), корректное отображение цен (не делить на 100), требование region_id при получении продуктов, соглашения о портах CORS (8000), конфигурацию Vite SSR, использование @medusajs/types вместо пользовательских типов, а также очистку состояния корзины после оформления заказа.

Категоризированный список из более чем 30 именованных антипаттернов, охватывающих корзину/навигацию, просмотр товаров, оформление заказа, мобильные устройства, SEO, производительность, согласованность дизайна и интеграцию с бэкендом — каждый сформулирован в виде конкретного правила ❌ для проверки до и в процессе реализации.

Навык предоставляет последовательный рабочий процесс из 10 шагов: от обнаружения (загрузка design.md) через фундамент, основные компоненты, процесс покупок и оптимизацию. Каждый шаг указывает точный файл, который необходимо загрузить перед реализацией, гарантируя, что ничего не упущено, а стили остаются согласованными.

Руководит архитектурными решениями для оформления заказа (одностраничное или многошаговое), обеспечивает получение способов оплаты с бэкенда вместо их жёсткого кодирования, отмечает требование к гостевому оформлению заказа и предоставляет шаги интеграции платежей, специфичные для Medusa, через reference/layouts/checkout.md и reference/medusa.md.

Охватывает настройку SDK, паттерны работы с регионами и ценообразованием, получение товаров с region_id, списки стран в рамках региона корзины, конфигурацию Vite SSR, а также использование сервера Medusa MCP для проверки методов — предотвращая наиболее распространённые ошибки интеграции витрины Medusa.

Направляет разработчиков к reference/mobile-responsiveness.md для получения информации о размерах сенсорных целей, отступах безопасной зоны и оптимизации изображений, а также к reference/seo.md для работы со схемой Product JSON-LD, мета-тегами, Open Graph и измерением показателей Core Web Vitals с помощью PageSpeed Insights.