dee0917/commercecraft-agent-skill

Motor de Creación de Tiendas Online de Alto Nivel 100% Frontend (Auto E-Commerce Frontend Engine)

Núcleo conceptual: Estética visual extrema, arquitectura de ingeniería sólida, experiencia 100% frontend, cero dependencias externas.

Esta habilidad integra el modelo maduro de comercio electrónico DTC con las mejores prácticas modernas de frontend, centrándose en ofrecer una experiencia de comercio electrónico moderna, de nivel comercial, sin placeholders y con una máquina de estados de compra y pago real.

Normas de idioma de ejecución:

• Nombres de marca, títulos de productos, parámetros de especificaciones, textos de UI → Solo en inglés (English Only), mostrando una calidad de marca internacional.
• Registros de desarrollo, informes de progreso, explicaciones técnicas e interacción con el usuario → Chino tradicional (Traditional Chinese).
• Variables, funciones, definiciones de interfaz en el código → camelCase / PascalCase en inglés, absolutamente prohibido usar nombres en pinyin.

---

🤖 Cinco Roles Virtuales y Matriz de Habilidades (Agent Team Architecture)

Durante el proceso de creación del sitio, el agente de IA cambiará a 5 roles profesionales, impulsando y verificando mutuamente en secuencia:

Rol (Role)	Responsabilidades principales	Etiquetas de habilidades principales (Skills)
1. Project Orchestrator	Posicionamiento de marca, selección de categorías, programación del plan de ejecución y coordinación entre fases	prd, brainstorming, executing-plans, writing-plans
2. Chief Creative Director	Definición de la atmósfera (Vibe) de la marca, contraste de color, sistema tipográfico y maquetación de alta calidad	ui-ux-pro-max, brand-guidelines, canvas-design, frontend-design
3. Lead Full-Stack Architect	Interfaces estrictas de TypeScript, máquina de estado de Zustand, componentes RWD e implementación de rutas	web-artifacts-builder, frontend-design, react-best-practices, tailwindcss
4. Content Strategist	Descripciones profesionales de productos, textos de historia, palabras clave SEO y diseño de reseñas de clientes	content-research-writer, internal-comms, brand-guidelines, doc-coauthoring
5. QA & Compliance	Auditoría de cero placeholders, depuración de errores de consola, aceptación de compilación y verificación de 7 niveles	verification-before-completion, webapp-testing, systematic-debugging, audit

---

🚀 Flujo de Ejecución del Ciclo de Vida Completo (Lifecycle Phases)

Usuario inicia: "Ayúdame a generar un sitio de comercio electrónico de [categoría/estilo]"

┌─ Fase 0: Carga de reglas de tolerancia cero y principios psicológicos (P0)
│  ├─ 📖 Leer references/anti-patterns.md (18 normas de tolerancia cero)
│  └─ 📖 Leer references/ux-psychology-ecommerce.md (principios psicológicos CRO)
│
├─ Fase 1: Generación de semillas creativas y sistemas de diseño (Creative & System Generation)
│  ├─ 🎲 Determinar el tema de la marca (ej: Minimal Desk Aesthetics, Luxe Aromatherapy, Tech Gear)
│  ├─ 🎨 Ejecutar Director Creativo: decidir paleta de colores (regla 60-30-10) y tipografía (Display / Body)
│  ├─ ✍️ Ejecutar Estratega de Contenido: generar eslogan principal de la marca y datos de especificaciones de 8~12 productos de alta fidelidad
│  └─ 📝 Exportar resumen del PRD del proyecto y decisiones de diseño a docs/DESIGN_DECISIONS.md
│
├─ Fase 2: Configuración de ingeniería frontend puro (Vite + React + TS + Tailwind)
│  ├─ 🏗️ Inicializar esqueleto del proyecto (Vite React-TS)
│  ├─ 📦 Instalar dependencias principales: zustand, react-router-dom, lucide-react, clsx, tailwind-merge, framer-motion, canvas-confetti
│  ├─ 📐 Importar templates/ecommerce-types.ts para garantizar restricciones de tipo fuerte
│  └─ 🛒 Implementar capa de estado (src/store/useCartStore.ts) con persistencia en LocalStorage
│
├─ Fase 3: Implementación de 11 rutas completas de comercio electrónico (100% Complete Routes)
│  ├─ 🏠 Capa A (Bucle principal de compra): Home, Shop, ProductDetail, CartDrawer, Checkout, OrderSuccess
│  ├─ 👤 Capa B (Centro de confianza del usuario): Profile, OrderHistory
│  └─ 📜 Capa C (Páginas de cumplimiento y confianza): FAQ, ShippingPolicy, ReturnsRefunds, About
│
├─ Fase 4: Refuerzo psicológico CRO y elevación visual
│  ├─ ⏳ Inyectar etiquetas de escasez (Scarcity: "¡Solo quedan 3 unidades!")
│  ├─ 🚚 Implementar barra de progreso de umbral de envío gratuito ("Añade $X más para desbloquear Envío Gratis")
│  ├─ ⭐ Insertar reseñas reales con estrellas de clientes y dinámicas de compra (Social Proof)
│  ├─ 🏷️ Inyectar datos estructurados JSON-LD de Schema.org (Product, Offer)
│  └─ 🖼️ Configurar imágenes comerciales de alta definición de Unsplash (prohibidos placeholders borrosos)
│
└─ Fase 5: Aceptación de calidad y entrega con un clic (Quality & Delivery Gate)
   ├─ 🔨 Ejecutar npm run build (garantizar 0 errores de TypeScript, 0 advertencias de compilación)
   ├─ 🔍 Ejecutar verificación de calidad de 7 niveles (Zero Mock, Zero Broken Links)
   └─ 🚀 Entregar vista previa del frontend y guía de implementación con un clic en Vercel

---

📋 Especificaciones de Rutas de 11 Páginas Completas (Page Requirements)

Cada sitio generado debe tener las siguientes 11 rutas completas, absolutamente no se permiten páginas vacías o 404:

1. Página de inicio (/):

   • Banner visual Hero (imagen grande de alto impacto, llamada a la acción potente "Shop The Collection").
   • Sellos de confianza (Free Shipping, 30-Day Guarantee, 256-Bit SSL, Ethical Craft).
   • Cuadrícula de productos destacados (Featured Products Grid).
   • Entrada rápida por categoría (Shop by Categories).
   • Bloque de historia de marca (Brand Ethos).
   • Testimonios reales de clientes (Social Proof Testimonials).
   • Sección de suscripción al boletín (Newsletter Signup con incentivo de descuento).

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

   • Filtro multidimensional: Filtro por categoría, Deslizador de rango de precios, Filtro por etiqueta.
   • Función de ordenación instantánea: Popularidad, Precio de menor a mayor, Precio de mayor a menor, Recién llegados.
   • Cuadro de búsqueda por palabra clave instantánea (Instant Client Search).
   • Estado de defensa de búsqueda vacía (Estado vacío con botón de restablecer filtros).

3. Página de detalle del producto (/product/:id):

   • Conmutación de vista previa de miniaturas de múltiples ángulos (Image Gallery).
   • Selector de especificaciones: Tamaño (Size), Color (Color), Variante (Variant).
   • Indicación de urgencia de stock (ej: mostrar advertencia ámbar cuando el stock sea < 5).
   • Regulador de aumento/disminución de cantidad.
   • Botón doble: "Add to Cart" (desliza el cajón del carrito) y "Buy Now" (va directamente al pago).
   • Pestañas: Especificaciones detalladas (Specifications), Envío y devoluciones (Shipping), Reseñas reales de clientes (Reviews).
   • Recomendación de productos relacionados (Recommended Products).
   • Inyección de Schema.org JSON-LD.

4. Cajón lateral del carrito (CartDrawer):

   • Deslizamiento suave (Framer Motion / Transition) al hacer clic en el icono del carrito en el encabezado del sitio o al hacer clic en "Add to Cart".
   • Barra de progreso de cálculo instantáneo del umbral de envío gratuito (ej: "Envío gratis por compras superiores a $100").
   • Lista de productos: miniatura, nombre del producto, especificación seleccionada, aumento/disminución de cantidad, eliminación instantánea.
   • Cuadro de canje de código promocional (con código incorporado como WELCOME10 para un descuento instantáneo del 10%).
   • Resumen de precios: Subtotal, Descuento (Discount), Envío estimado (Shipping), Total (Total).
   • Botón de pago directo (Proceed to Checkout).

5. Centro de pago (/checkout):

   • Interfaz de pago en 3 pasos:
     1. Información de contacto y envío (Shipping Details): Nombre, Email, Dirección de envío, Teléfono.
     2. Selección de método de envío (Shipping Method): Estándar ($0 ~ $5), Express ($15).
     3. Simulación de método de pago (Payment Method): Entrada simulada de tarjeta de crédito (con formato automático, icono de seguridad), opciones de pago rápido (Apple Pay / PayPal).
   • Tarjeta de resumen de pedido instantáneo en el lado derecho/abajo (Order Summary Sticky Card).
   • Prevención de clics repetidos, validación instantánea de campos del formulario.

6. Página de pedido completado (/order-success):

   • Animación de marca de verificación verde de éxito y efecto de confeti de celebración (canvas-confetti).
   • Número de pedido único generado aleatoriamente (ej: #ORD-2026-89412).
   • Lista completa del resumen del pedido, datos del destinatario y fecha de entrega estimada.
   • Botón de retorno "Continue Shopping".

7. Seguimiento e historial de pedidos (/orders):

   • Barra de progreso de pedido simulada (Confirmed → Processing → Shipped → Delivered) tras introducir el número de pedido o Email.

8. Perfil y favoritos (/profile):

   • Visualización rápida de datos básicos del usuario simulado y lista de deseos (Wishlist).

9. Preguntas frecuentes (/faq):

   • Componente de acordeón plegable (Accordion) que incluye preguntas populares sobre pedidos, envíos, devoluciones, cuidado de materiales, etc.

10. Política de envío (/shipping):

    • Incluye tabla de tarifas de envío nacional e internacional, días laborables de entrega por país, explicación de aranceles.

11. Política de devoluciones e historia de la marca (/returns y /about):

    • Declaración clara de los términos de garantía de devolución de 30 días, proceso de devolución en 3 pasos y la historia del fundador de la marca.

---

🧠 Guía de Implementación Obligatoria de Psicología del Consumidor y Tasa de Conversión (CRO)

Cada sitio generado debe incorporar los siguientes mecanismos psicológicos (consulte references/ux-psychology-ecommerce.md para definiciones detalladas):

1. Ley de Hick (Hick's Law):
   • El formulario de pago debe ser conciso por defecto, reduciendo campos no obligatorios innecesarios.
   • El menú principal de navegación no debe tener más de 5 elementos de primer nivel.
2. Efecto de anclaje (Anchoring Effect):
   • Los productos en oferta deben mostrar el precio original tachado (ej: ~~$120.00~~ $89.00) y una etiqueta de ahorro Ahorra $31.
3. Escasez y urgencia (Scarcity & Urgency):
   • En la página de detalle, mostrar dinámicamente y al azar "¡Solo quedan 2 artículos a este precio!".
   • En la página de pago, indicar "Reservado para tu carrito durante 10:00 minutos" (temporizador opcional).
4. Prueba social (Social Proof):
   • Marcar insignias de comprador verificado (Verified Buyer) en la página de inicio y en la página de detalle.
   • Mostrar la calificación promedio en la tarjeta de la lista de productos (ej: ★ 4.9 (128 reseñas)).
5. Aversión a la pérdida (Loss Aversion):
   • La barra de progreso de envío gratuito en el carrito debe recordar dinámicamente: "¡Solo te faltan $12 para disfrutar del envío gratuito en todo el sitio!".

---

🛠️ Especificaciones de la Arquitectura de Gestión de Estado (Zustand + LocalStorage)

Utilice un Zustand Store desacoplado y a prueba de rebotes, asegurando que los datos del carrito no se pierdan al actualizar la página:

// src/store/useCartStore.ts plantilla de especificación
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;
}

---

🛡️ Línea de Defensa de la Calidad de Entrega (7 Niveles de Verificación)

Antes de presentar los resultados al usuario, el rol de QA debe verificar cada elemento:

1. 0 Imágenes rotas (Zero Broken Images): Todas las URL de imágenes deben cargarse correctamente y tener el tamaño adecuado, con atributos loading="lazy" y alt.
2. 0 Enlaces muertos (Zero Broken Links): Todos los enlaces de navegación, enlaces de pie de página y botones del sitio deben ser clicables y redirigir a las 11 rutas correspondientes.
3. 0 Placeholders (Zero Placeholders): Prohibido terminantemente el uso de textos de relleno como Lorem Ipsum, Product 1, $0.00. Todos los textos deben coincidir con la personalidad de la marca.
4. Bucle completo del carrito (Cart Loop Completed): Añadir al carrito → deslizar el cajón → modificar la cantidad y el precio se actualiza → introducir cupón de descuento → enviar pedido → redirigir a Order Success y obtener el número de pedido.
5. Garantía de diseño responsivo (RWD): Sin desbordamiento horizontal en móvil (375px), tableta (768px) y escritorio (1280px+).
6. SEO estructurado: La página de detalle del producto debe generar correctamente application/ld+json (Schema.org Product).
7. Verificación de compilación de producción (Production Build): Ejecutar npm run build sin errores, generando el directorio dist/.