dee0917/commercecraft-agent-skill

Motor de Criação de Loja Virtual Front-End Autônomo de Alto Padrão (Auto E-Commerce Frontend Engine)

Núcleo: Estética visual máxima, arquitetura de engenharia robusta, experiência 100% front-end, zero dependências externas.

Esta skill integra o modelo maduro de DTC (Direct-to-Consumer) com práticas modernas de engenharia front-end, focada em fornecer uma experiência de e-commerce de nível comercial, sem placeholders, com máquina de estados real de compra e checkout, tudo no front-end.

Regras de idioma na execução:

• Nomes de marca, títulos de produtos, parâmetros de especificação, textos de UI → Inglês Apenas (English Only), transmitindo qualidade de marca internacional.
• Log de desenvolvimento, relatórios de progresso, explicações técnicas e interação com o usuário → Português (Brasileiro).
• Variáveis, funções, definições de interface no código → camelCase / PascalCase, absolutamente proibido usar romanização.

---

🤖 Cinco Papéis Virtuais e Matriz de Habilidades (Agent Team Architecture)

Ao executar o fluxo de construção do site, o agente de IA alternará entre 5 papéis profissionais, progredindo sequencialmente e realizando verificações cruzadas:

Papel (Role)	Responsabilidade Principal	Tags de Habilidade (Skills)
1. Project Orchestrator	Posicionamento da marca, seleção de categoria, agendamento do plano de execução e coordenação entre etapas	prd, brainstorming, executing-plans, writing-plans
2. Chief Creative Director	Definição do Vibe da marca, contraste de cores, sistema tipográfico e layout de alta qualidade	ui-ux-pro-max, brand-guidelines, canvas-design, frontend-design
3. Lead Full-Stack Architect	Interface estrita em TypeScript, máquina de estados Zustand, componentes RWD e implementação de rotas	web-artifacts-builder, frontend-design, react-best-practices, tailwindcss
4. Content Strategist	Descrições profissionais de produtos, storytelling, SEO keywords e design de avaliações de clientes	content-research-writer, internal-comms, brand-guidelines, doc-coauthoring
5. QA & Compliance	Auditoria de zero placeholders, depuração de erros no Console, aceitação de Build e verificação de 7 camadas	verification-before-completion, webapp-testing, systematic-debugging, audit

---

🚀 Fluxo de Execução do Ciclo de Vida Completo (Lifecycle Phases)

Usuário inicia: "Me gere um site de e-commerce [categoria/estilo]"

┌─ Fase 0: Carregamento das Regras de Tolerância Zero e Princípios Psicológicos (P0)
│  ├─ 📖 Ler references/anti-patterns.md (18 regras de tolerância zero)
│  └─ 📖 Ler references/ux-psychology-ecommerce.md (Princípios de psicologia CRO)
│
├─ Fase 1: Geração da Semente Criativa e do Sistema de Design (Creative & System Generation)
│  ├─ 🎲 Definir tema da marca (Ex.: Minimal Desk Aesthetics, Luxe Aromatherapy, Tech Gear)
│  ├─ 🎨 Executar Creative Director: Decidir paleta de cores (regra 60-30-10) e fontes (Display / Body)
│  ├─ ✍️ Executar Content Strategist: Gerar slogan central da marca e 8~12 itens de dados realistas de especificações de produto
│  └─ 📝 Gerar resumo do PRD do projeto e decisões de design em docs/DESIGN_DECISIONS.md
│
├─ Fase 2: Configuração da Engenharia Front-End (Vite + React + TS + Tailwind)
│  ├─ 🏗️ Inicializar esqueleto do projeto (Vite React-TS)
│  ├─ 📦 Instalar dependências principais: zustand, react-router-dom, lucide-react, clsx, tailwind-merge, framer-motion, canvas-confetti
│  ├─ 📐 Importar templates/ecommerce-types.ts para garantir restrições de tipos fortes
│  └─ 🛒 Implementar camada de estado (src/store/useCartStore.ts) com persistência em LocalStorage
│
├─ Fase 3: Implementação de Rotas Completas de E-commerce (11 páginas) (100% Complete Routes)
│  ├─ 🏠 Camada A (Ciclo principal de compras): Home, Shop, ProductDetail, CartDrawer, Checkout, OrderSuccess
│  ├─ 👤 Camada B (Centro de confiança do usuário): Profile, OrderHistory
│  └─ 📜 Camada C (Páginas de conformidade e confiança): FAQ, ShippingPolicy, ReturnsRefunds, About
│
├─ Fase 4: Reforço Psicológico CRO e Elevação Visual
│  ├─ ⏳ Injetar etiquetas de escassez (Scarcity: "Only 3 units left!")
│  ├─ 🚚 Implementar barra de progresso do valor restante para frete grátis ("Adicione mais R$ X para ganhar Frete Grátis")
│  ├─ ⭐ Incorporar avaliações reais com estrelas e dinâmica de compra (Social Proof)
│  ├─ 🏷️ Injetar dados estruturados Schema.org (Product, Offer) JSON-LD
│  └─ 🖼️ Configurar imagens profissionais de alta resolução do Unsplash (proibido placeholders borrados)
│
└─ Fase 5: Aceitação de Qualidade e Entrega com Um Clique (Quality & Delivery Gate)
   ├─ 🔨 Executar npm run build (garantir 0 erros TypeScript, 0 avisos de build)
   ├─ 🔍 Executar verificação da porta de qualidade de 7 camadas (Zero Mock, Zero Broken Links)
   └─ 🚀 Entregar preview front-end e guia de deploy em um clique no Vercel

---

📋 Especificação de Rotas de 11 Páginas Completas (Page Requirements)

Todo site gerado deve ter as 11 rotas completas abaixo, absolutamente nenhuma página vazia ou 404:

1. Página Inicial (/):

   • Banner visual Hero (imagem grande de alto impacto, CTA forte "Shop The Collection").
   • Selos de confiança autoritários (Free Shipping, 30-Day Guarantee, 256-Bit SSL, Ethical Craft).
   • Grid de produtos recomendados em destaque (Featured Products Grid).
   • Entrada rápida por categoria (Shop by Categories).
   • Bloco de história da marca (Brand Ethos).
   • Depoimentos reais de clientes (Social Proof Testimonials).
   • Área de inscrição na newsletter (Newsletter Signup com incentivo de desconto).

2. Catálogo de Produtos (/shop):

   • Filtro multidimensional: Filtro por categoria, Slider de faixa de preço, filtro por tags.
   • Função de classificação em tempo real: Popularidade, Preço: menor para maior, Preço: maior para menor, Mais recentes.
   • Caixa de pesquisa por palavra-chave instantânea (Instant Client Search).
   • Estado de defesa para pesquisa vazia (Empty State com botão de redefinir filtros).

3. Página de Detalhes do Produto (/product/:id):

   • Galeria de imagens com pré-visualização de múltiplos ângulos (Image Gallery).
   • Seletor de especificações: Tamanho (Size), Cor (Color), Variação (Variant).
   • Alerta de urgência de estoque (ex.: exibir aviso âmbar quando estoque < 5).
   • Regulador de quantidade (aumentar/diminuir).
   • Botões duplos: "Add to Cart" (desliza gaveta do carrinho) e "Buy Now" (vai direto ao checkout).
   • Abas: Especificações detalhadas (Specifications), Informações de envio e devolução (Shipping), Avaliações reais de clientes (Reviews).
   • Recomendações de produtos relacionados (Recommended Products).
   • Injeção de Schema.org JSON-LD.

4. Gaveta Lateral do Carrinho de Compras (CartDrawer):

   • Desliza suavemente ao clicar no ícone do carrinho no cabeçalho ou ao clicar em "Add to Cart" (Framer Motion / Transition).
   • Barra de progresso do valor restante para frete grátis em tempo real (ex.: "Faltam R$ X para frete grátis").
   • Lista de itens: miniatura, nome do produto, especificação selecionada, aumento/diminuição de quantidade, exclusão em tempo real.
   • Campo de resgate de cupom de desconto (Promo Code) (ex.: WELCOME10 com desconto imediato de 10%).
   • Resumo de preços: Subtotal, Desconto (Discount), Frete estimado (Shipping), Total.
   • Botão para ir ao checkout (Proceed to Checkout).

5. Central de Checkout (/checkout):

   • UI de checkout em 3 etapas:
     1. Informações de Contato e Envio (Shipping Details): Nome, Email, Endereço, Telefone.
     2. Escolha do Método de Envio (Shipping Method): Standard (R$ 0 ~ R$ 25), Express (R$ 75).
     3. Simulação do Método de Pagamento (Payment Method): Cartão de crédito simulado (com formatação automática, ícones de segurança), opções de checkout rápido Apple Pay / PayPal.
   • Cartão de resumo do pedido fixo à direita/abaixo (Order Summary Sticky Card).
   • Prevenção de clique duplicado, validação em tempo real dos campos do formulário.

6. Página de Pedido Concluído (/order-success):

   • Animação de sucesso verde com efeito de confetes (canvas-confetti).
   • Número de pedido único gerado aleatoriamente (ex.: #ORD-2026-89412).
   • Lista completa do resumo do pedido, dados do destinatário e previsão de entrega.
   • Botão "Continue Shopping" para retornar.

7. Histórico e Rastreamento de Pedidos (/orders):

   • Campo para consultar barra de progresso simulada do pedido (Confirmed → Processing → Shipped → Delivered) inserindo número do pedido ou email.

8. Perfil e Favoritos (/profile):

   • Visualização rápida de dados básicos simulados do usuário e lista de desejos (Wishlist).

9. Perguntas Frequentes (/faq):

   • Componente de acordeão sanfonado, contendo perguntas comuns sobre pedidos, envio, devoluções, cuidados com materiais, etc.

10. Política de Envio (/shipping):

    • Inclui tabela de taxas de frete nacional e internacional, prazos de entrega por país, explicação sobre impostos alfandegários.

11. Política de Devolução e História da Marca (/returns & /about):

    • Declaração clara dos termos de garantia de devolução de 30 dias, processo de 3 etapas para devolução e a história de fundação da marca.

---

🧠 Guia de Implementação Obrigatória de Psicologia de E-commerce e CRO

Todo site gerado deve incorporar os seguintes mecanismos psicológicos (consulte references/ux-psychology-ecommerce.md para definições detalhadas):

1. Lei de Hick (Hick's Law):
   • Formulários de checkout devem ser simplificados por padrão, com o mínimo de campos não obrigatórios.
   • Navegação principal deve ter no máximo 5 itens de primeiro nível.
2. Efeito de Ancoragem (Anchoring Effect):
   • Exibir produtos em promoção com o preço original riscado ao lado (ex.: ~~R$ 600,00~~ R$ 445,00) e etiqueta de valor economizado Economize R$ 155.
3. Escassez e Urgência (Scarcity & Urgency):
   • Na página de detalhes, exibir dinamicamente e aleatoriamente "Restam apenas 2 unidades neste preço".
   • Na página de checkout, marcar "Reservado para seu carrinho por 10:00 minutos" (temporizador opcional).
4. Prova Social (Social Proof):
   • Marcar selo de "Comprador Verificado" (Verified Buyer) na página inicial e de detalhes.
   • Exibir avaliação média com estrelas no card da lista de produtos (ex.: ★ 4,9 (128 avaliações)).
5. Aversão à Perda (Loss Aversion):
   • Na barra de progresso do frete grátis no carrinho, notificar dinamicamente: "Faltam apenas R$ 60,00 para garantir frete grátis em todo o site!".

---

🛠️ Especificação da Arquitetura de Gerenciamento de Estado (Zustand + LocalStorage)

Usar uma Zustand Store desacoplada e com debounce para garantir que os dados do carrinho não sejam perdidos ao atualizar a página:

// Modelo de especificação src/store/useCartStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { CartItem, Product } from '../types';

interface CartState {
  items: CartItem[];
  isOpen: boolean;
  promoCode: string | null;
  discountRate: number;
  openCart: () => void;
  closeCart: () => void;
  addItem: (product: Product, quantity?: number, selectedVariant?: string) => void;
  removeItem: (itemId: string) => void;
  updateQuantity: (itemId: string, quantity: number) => void;
  applyPromoCode: (code: string) => { success: boolean; message: string };
  clearCart: () => void;
  getSubtotal: () => number;
  getTotal: () => number;
}

---

🛡️ Barreira de Qualidade de Entrega (7 Camadas de Verificação de Aceitação)

Antes de submeter o resultado ao usuário, o papel de QA deve verificar item por item:

1. 0 Imagens Quebradas (Zero Broken Images): Todas as URLs de imagem devem carregar corretamente, ter tamanho adequado e possuir atributos loading="lazy" e alt.
2. 0 Links Quebrados (Zero Broken Links): Todos os links de navegação, rodapé e botões do site devem ser clicáveis e redirecionar para a rota correta entre as 11 páginas.
3. 0 Placeholders (Zero Placeholders): É terminantemente proibido usar textos como Lorem Ipsum, Produto 1, R$ 0,00. Todos os textos devem ser coerentes com o tom da marca.
4. Ciclo Completo do Carrinho (Cart Loop Completed): Adicionar ao carrinho → gaveta desliza → alterar quantidade e preço sincronizado → inserir cupom de desconto → finalizar checkout → redirecionar para Order Success com número do pedido.
5. Garantia de Design Responsivo (RWD): Sem overflow horizontal ou quebra de layout em celular (375px), tablet (768px) e desktop (1280px+).
6. SEO Estruturado: Páginas de detalhes do produto devem gerar application/ld+json (Schema.org Product) correto.
7. Validação de Build de Produção (Production Build): Executar npm run build sem nenhum erro e gerar diretório dist/.