zhaodi-Wen/design-agent-skills

Exhibición de productos con desplazamiento y arrastre

Entrega una página web funcional y archivos fuente editables. Primero, confirma si esta vez será solo desplazamiento, solo arrastre, o ambos; al agregar una interacción a una página existente, conserva la otra interacción ya autorizada. El video de referencia se utiliza para identificar relaciones visuales y de movimiento, no para afirmar que el sitio original utiliza un framework específico. Indica el estado de finalización por separado para la página de exhibición y el sistema real de pedidos de comercio electrónico.

Extraer de la referencia

Para el video local, lee la duración y el tamaño del encuadre, extrae las imágenes del inicio, los puntos de transición media y el final; si es necesario, aumenta el muestreo para confirmar el movimiento continuo. Registra: posición y tamaño del sujeto, cambios de perspectiva, fondo y accesorios, tamaño de fuente, orden de oclusión, dirección de desplazamiento y comportamiento de rebobinado. No confundas el marco de la grabación de pantalla, los subtítulos explicativos o el cursor del mouse con el diseño web.

Organiza la referencia en una tabla de acciones ordenadas por progreso de desplazamiento. Marca respectivamente lo que es directamente visible en la imagen, lo inferido y el método de implementación elegido esta vez. Consulta el caso del café y el criterio de ruta en references/motion-design.md.

Elegir el método de presentación

• Si se necesitan cambios de perspectiva realistas, rotación interactiva o cambio de material: modelo 3D de Three.js con GSAP. Reutiliza GLB existente si es adecuado; para objetos simples como tazas, botellas o latas, se puede usar geometría paramétrica, indicando claramente que es un modelo esquemático original.
• Si el encuadre es fijo, la iluminación es compleja o ya hay recursos renderizados: secuencia de fotogramas en Canvas. El número de fotograma se determina por el progreso del desplazamiento; maneja fotogramas no cargados y el uso de memoria, no se puede asumir que saltar a cualquier fotograma de un video arbitrario sea fluido.
• Si solo se necesita desplazamiento, transparencia e inclinación plana: capas DOM/CSS. Una sola imagen no puede producir una rotación real de frente a atrás.

Una vez determinada la ruta de los assets, construye la lógica de desplazamiento. Cuando el usuario no especifique una marca, se pueden usar datos de marca y producto de demostración claros; no inventes certificaciones, ventas, reseñas ni resultados de transacciones reales.

Plantilla de inicio

Hay dos plantillas autónomas de Vite + Three.js + GSAP, elige según el producto y la tarea; para una nueva marca aún se necesita rediseñar la apariencia.

• assets/starter/ (coffee, predeterminada): narrativa de desplazamiento de café con arrastre superpuesto, cambio de color de sabor y bolsa de compras local; mini.html es un H5 estilo miniaplicación que comparte el producto y la bolsa.
• assets/gallery/ (gallery): tres temas visuales: perfume, auriculares y reloj. Los auriculares admiten desplazamiento con expansión, tres textos y arrastre coexistente; perfume y reloj usan arrastre y botones de estructura. Se puede usar para crear casos que no sean de café.

Crea un nuevo proyecto en un directorio que aún no exista (el script no sobrescribe proyectos existentes):

python3 /path/to/scroll-product-showcase/scripts/create_project.py /absolute/path/to/new-project
cd /absolute/path/to/new-project
npm ci
npm run dev -- --port 5197

Reemplaza /path/to/scroll-product-showcase con la ruta real de instalación del skill. Si el puerto está ocupado, usa uno disponible y entrega la dirección real.

Para generar un caso que no sea de café, agrega --template gallery. La entrada para auriculares es /?case=headphones, también hay /?case=perfume y /?case=watch. Al modificar un proyecto existente, modifícalo directamente, no uses el generador para sobrescribirlo.

Ubicaciones de modificación:

• src/scene.js: cámara, luces, postura de desplazamiento y ángulos de arrastre independientes; el modelo de café está aquí, los modelos de la galería están en src/models.js.
• src/scroll-story.js: etapas de desplazamiento, texto sincronizado y barra de progreso.
• src/main.js: entrada y estado de interacción; los gestos del puntero del café están en src/drag.js, la bolsa en src/bag.js.
• Café src/products.js, galería src/content.js: texto del producto y esquema de colores.
• src/style.css e index.html: formato, diseño responsive, texto y estructura semántica.
• Café mini.html, src/mini.js, src/mini.css, src/cup-viewer.js: interfaz estilo miniaplicación; vite.config.js conserva las dos entradas de compilación.

La plantilla usa CSS sticky para fijar la escena y ScrollTrigger para impulsar el progreso; no agregues pin en la misma capa. Otros proyectos también pueden cambiar a ScrollTrigger pin, pero deben eliminar el diseño sticky conflictivo.

Combinaciones de interacción y restricciones de implementación

Cuando se trata de arrastre, desplazamiento coexistente, botones de estructura o interfaz de miniaplicación, lee references/interaction-modes.md, donde se encuentran la superposición de posturas, la división de entrada y los puntos de aceptación.

• Usa un solo progreso de 0 a 1 para controlar el modelo, la cámara y el texto orquestados por el desplazamiento; bajo el mismo ángulo manual, avanzar y retroceder al mismo progreso debe dar la misma postura. El ángulo de arrastre se almacena de forma independiente y luego se superpone a la postura de desplazamiento; no permitas que dos controladores se sobrescriban la rotación.
• Cuando el desplazamiento y el arrastre coexisten, el restablecimiento solo borra el ángulo manual por defecto, conservando el progreso del desplazamiento y el esquema de colores. Si los botones de estructura controlan la misma acción, deben saltar a la posición correspondiente en la línea de tiempo, evitando iniciar otra animación que compita por escribir el progreso; sigue la solicitud del usuario si especifica explícitamente otro significado de restablecimiento.
• Primero determina el área segura del sujeto, luego coloca el texto; en dispositivos móviles, reajusta el tamaño y la trayectoria del sujeto, no solo reduzcas la versión de escritorio proporcionalmente.
• El título, la descripción, los botones de selección y el precio deben estar en HTML accesible; Canvas se encarga de la representación visual.
• Al cambiar una textura, libera la textura antigua; al desmontar, limpia observadores, animaciones, eventos y recursos de GPU. Limita la relación de píxeles y evita que las escenas no visibles sigan renderizando.
• Para la preferencia de reducir el movimiento, proporciona una composición estática e información del producto directamente accesible. Cuando WebGL falle, conserva la selección de productos y la bolsa de compras.
• La bolsa de compras local puede incluir selección, suma/resta, eliminación y persistencia. Cuando no esté conectado a un backend, indica claramente que es una demostración, no muestres que el pedido ha sido enviado o el pago exitoso.

Verificación y entrega

Primero construye, luego verifica el renderizado real en el navegador. Realiza pruebas de interacción que cubran el inicio, la mitad, el final, el rebobinado, pantalla estrecha, preferencia de movimiento reducido y selección de productos; en modo coexistente, prueba también arrastre en la sección media, continuar desplazamiento y restablecimiento. Después de cambiar de caso, verifica el texto, la altura del escenario y el esquema de colores. Si hay una bolsa de compras, verifica la cantidad, el total y el estado después de actualizar. Revisa la página en busca de anomalías, carga de recursos y desbordamiento horizontal.

El scripts/verify-browser.mjs de la plantilla de café es un script de regresión opcional, se puede usar PLAYWRIGHT_MODULE para apuntar a un módulo Playwright existente, y BASE_URL para apuntar al servidor real. Si el entorno actual especifica el uso de una herramienta de navegador, usa esa herramienta para realizar la misma verificación interactiva, no inicies otro controlador de navegador. Para la galería, verifica con la herramienta de navegador según los escenarios anteriores. Solo informa de las comprobaciones realmente realizadas, aún se necesitan capturas de pantalla para juzgar si lo visual es aceptable; una compilación exitosa o un HTTP 200 no reemplazan la inspección visual.

Al finalizar, proporciona la URL de vista previa, el directorio del código fuente y las capturas de pantalla clave. Explica la ruta de implementación real y los servicios aún no conectados. Solo graba una grabación de pantalla o video si el usuario lo solicita explícitamente; no informes una captura de pantalla estática como verificación interactiva o grabación.

Consulta técnica según sea necesario: GSAP ScrollTrigger, Three.js GLTFLoader.