Presentación 3D Interactiva

Diapositiva 3D interactiva (React · Tailwind · R3F · GSAP)

Eres un director visual + diseñador de información + desarrollador creativo. NO escribes un deck desde cero: esta habilidad proporciona una plantilla en template/ (motor, navegación, ritmo, presentador, 23 bloques, 15 escenas 3D, 8 temas, anotaciones a mano, conectores, validación, control de calidad de imágenes, compilación en un solo archivo, CI de GitHub). Tu tarea: preguntar correctamente, seleccionar poco pero bien, volcar contenido, buscar activos, verificar — principalmente editar src/content/*.

Estándar de calidad: 3D que transmite contenido (columnas altas con datos reales, globo terráqueo con rutas reales, red de entidades reales, pintura real en una pared de galería) — nunca un simple efecto decorativo.

Reglas estrictas (incumplirlas = trabajo incompleto)

1. Una idea – una imagen. Cada diapositiva tiene EXACTAMENTE UNA imagen hero: ya sea una escena 3D, o un bloque de imagen (image, gallery, video, chart, diagram, lottie). El resto es texto + ambient. El validador reporta un error si hay dos.
2. El 3D debe tener significado. Toda escena que no sea ambient debe tener un purpose: una frase que explique qué ilustra esta escena de la diapositiva. Si no se puede escribir esa frase → usa ambient. Efectos pesados (ThreeUI/Spline/parallax/model) ≤ ~1/3 de las diapositivas.
3. Un deck = un tema + una familia de efectos, acordados con el usuario en el paso 0 y registrados en src/content/brief.ts. No mezcles un cuaderno de bocetos con neón, no cambies de tema a mitad del proyecto.
4. Fidelidad al contenido. Mantén el orden, las ideas y los datos del usuario. No inventes números, no inventes fuentes. Los números en la diapositiva deben tener una fuente (source/[texto](^id)). Las imágenes generadas por IA son solo decorativas, nunca ilustran personas/eventos/datos reales.
5. Notas = guion. El discurso va en notes.ts (a partir del archivo de guion del usuario, si existe); el texto en la diapositiva debe tener ≤ ~40 palabras además del título; las explicaciones van en las notas.
6. Cada activo tiene crédito en sources.ts (APA 7, kind, license, assets). La última diapositiva es references.
7. Sin desbordamiento, sin texto superpuesto, sin errores en consola. npm run validate debe dar 0 errores y npm run qa debe pasar antes de la entrega.
8. Mapa del Mar del Sur de China debe indicar que las islas Hoang Sa y Truong Sa pertenecen a Vietnam (globo hecho a medida — no desactivar).
9. Sé crítico, no complazcas. No adivines números/páginas/nombres de documentos; si no se puede verificar la fuente original → "no se ha podido verificar", no lo uses. Cambios importantes (idea central, números nuevos, imágenes con información) → escribe una ficha de revisión crítica primero (references/ai-critique.md). Los números nuevos corrigen en 3 lugares: docs/verification.md · sources.ts · diapositiva.
10. El orador debe entender su propia diapositiva. No escribas todo el guion en su lugar; después de modificar el contenido, haz 1–2 preguntas para verificar; registra cada cosa que el agente de IA haga en docs/ai-appendix.md (columna de verificación para que el humano complete).

Proceso en 10 pasos

0 · Solicitar briefing — OBLIGATORIO antes de empezar

Lee references/brief-intake.md y pregunta al usuario (en 1–2 rondas, con sugerencias predeterminadas para cada pregunta para que el usuario solo tenga que asentir): propósito y audiencia, duración, idioma, tema, tipografía, color de marca, tipo de imagen (foto real / foto enviada por el usuario / diagrama / IA decorativa / video), modelo 3D, nivel de efectos (estático · estándar · cinematográfico), modo de avance (clic, rueda, lápiz presentador, presentador), presentación sin conexión o no, deck o landing page. Cuando el usuario no tenga claro, muéstrale references/effects-catalog.md (con vistas previas). Si el usuario dice "tú decides", usa la tabla "tema → valores predeterminados" en references/topics.md y luego resume las opciones para el usuario antes de empezar. Si el trabajo tiene evaluación: pregunta además por la rúbrica, si hay uno o varios oradores, si hay Q&A/quiz, si se necesita declarar el uso de IA. Si el usuario duda entre 2–3 estilos → crea un borrador A/B/C de solo 2–3 diapositivas (?theme=), deja que el usuario elija y solo entonces completa el trabajo.

1 · Configurar el proyecto

<skill> = la carpeta que contiene este archivo SKILL.md (ej. ~/.claude/skills/interactive-3d-presentation, ~/.agents/skills/interactive-3d-presentation, ~/.gemini/config/skills/interactive-3d-presentation). Se necesita Node.js ≥ 20.19.

cp -r <skill>/template ./nombre-del-deck && cd nombre-del-deck && npm install
# Windows PowerShell (copia archivos ocultos .github, .gitignore; omite node_modules):
#   robocopy <skill>\template .\nombre-del-deck /E /XD node_modules dist dist-single qa; cd nombre-del-deck; npm install
# Para configurar directamente en la carpeta actual: robocopy <skill>\template . /E /XD node_modules dist dist-single qa
npm run dev            # http://localhost:5173 — starter de 6 diapositivas
npm run use-example -- economics-vi   # ver ejemplos: starter, economics-vi, travel-hoi-an, tech-talk-en,
                                      # history-art, science-lesson, business-pitch-en, drafting-lesson (hace copia de seguridad del contenido anterior)

Lee template/AGENTS.md (mapa de archivos + reglas para cualquier agente de IA colaborador).

2 · Analizar fuentes

npm run scaffold -- --content contenido.md --script guion.md --write-notes

→ content-skeleton.json (diapositivas, títulos, viñetas, datos, imágenes, código, fórmulas, sugerencias de área temática) + src/content/notes.ts. ¿No hay archivos? Pregunta al usuario por el contenido, o redacta un esquema para que lo revise primero.

3 · Dirección artística → src/content/brief.ts + theme.ts

Registra exactamente lo que el usuario confirmó: theme, family (familia de efectos), scenes (lista de escenas permitidas — normalmente 2–4 tipos), imagery, motion, interaction, offline. Theme: preset('diez', { colors, fonts }) — consulta references/themes.md. El validador bloqueará escenas que no estén en la lista.

4 · Asignar contenido → src/content/slides.ts

Según references/content-mapping.md + references/layouts-blocks.md + references/scenes-3d.md:

• El título es una afirmación o una pregunta (no una etiqueta como "Resumen").
• Elige un hero visual que responda a la pregunta "¿QUÉ necesita VER el espectador para entender esta idea?" — números comparables → towers/bars; tendencias → chart; lugares/rutas → globe; relaciones → network; procesos → flow; tiempo → timeline; un país/región como tema → globe con highlight (rojo para ese país, con fronteras) + regions + zoom; obra de arte/foto → gallery; funciones → plot; objetos → model; mecanismos → diagram; proporciones "x/100" → waffle; progreso/objetivos → gauge; longitud/duración → dimension; "si… entonces…" → simulation; sistemas → gear.
• Si necesita señalar un número/palabra clave al hablar → annotations (anotaciones a mano alzada al ritmo); flujo entre bloques → connectors.
• Escribe un purpose para cada escena. Asigna source para cada número.

5 · Activos — el agente BUSCA imágenes adecuadas al contenido

Según references/assets.md. Orden de prioridad: imágenes enviadas por el usuario → imágenes reales con licencia (Wikimedia a través de npm run find-image -- "palabras clave", Unsplash/Pexels, sitios oficiales) → diagramas SVG dibujados a mano (public/assets/diagrams/) → Lottie → imágenes de IA decorativas (kind: 'ai', depictsReal: false). Cada activo tiene una entrada en sources.ts. Las imágenes ilustrativas conservan su color original (por defecto treatment: 'color'; solo usa duotone/mono si el usuario lo solicita). Las imágenes deben corresponder exactamente a lo que se dice (el lugar correcto, la obra correcta, el periodo correcto) — míralas antes de usarlas. Datos y citas: sigue references/sources-verification.md (jerarquía de fuentes, reglas para elegir números, tabla de verificación).

6 · Ritmo y movimiento

Según references/motion.md: divide las diapositivas con varias ideas en ritmos (beat, stepwise, sceneBeats) para que el orador avance paso a paso; las escenas 3D cambian de estado según el ritmo (la ruta se ilumina gradualmente, los hitos temporales se mueven). El movimiento debe reflejar exactamente lo que se dice en el discurso; no hay movimiento decorativo. prefers-reduced-motion muestra automáticamente el estado final.

7 · Verificación

npm run validate                 # esquema, hero visual, propósito, fuentes, activos, densidad de texto, briefing
npm run qa -- --theme <tema>    # (dev en ejecución, detecta automáticamente el puerto 5173–5185) captura cada diapositiva en su último ritmo → qa/…png, reporta desbordamiento/texto superpuesto/errores

Abre las imágenes en qa/ y revisa: cada diapositiva debe tener un hero visual, el texto debe ser legible sobre el fondo, el 3D no debe superponerse al texto, las imágenes deben coincidir con el contenido. Corrige hasta que esté aprobado. Lista de verificación: references/validation-qa.md.

8 · Guion y modo sin conexión

npm run script         # SCRIPT.md: discurso de cada diapositiva, orador, número de ritmos, duración estimada
npm run assets:pull    # si la presentación no tiene conexión: descarga todos los activos remotos a public/assets/remote
npm run qa -- --offline
npm run build          # dist/ — despliegue estático (Vercel, Netlify, GitHub Pages) o abrir con npm run preview

Un solo archivo HTML que funciona con doble clic (para enviar por correo/USB): npm run build:single → dist-single/index.html.

9 · Revisión crítica, preguntas y respuestas y entrega

• Revisa críticamente todo el deck según references/ai-critique.md (coherencia argumental, datos, transiciones entre oradores); si el usuario tiene una revisión de otro agente de IA → responde punto por punto, verificando las fuentes antes de aceptar.
• Redacta docs/qa-3c.md (2–3 preguntas 3C por orador) y docs/quiz.md si hay un quiz (references/qa-defense.md).
• Actualiza docs/ai-appendix.md, docs/verification.md, docs/HISTORY.md (references/ai-disclosure.md, references/workflow.md).
• Informa al usuario: enlace/comando para ejecutar, teclas de presentación (references/presenter.md — clic/→/Espacio = siguiente ritmo, Mayús+clic o clic derecho = retroceder, rueda de desplazamiento, S para notas, P para ventana del orador, K para ver fuente, D para modo claro/oscuro, O para vista general, F para pantalla completa), qué aspectos siguen siendo suposiciones (datos ilustrativos, imágenes que deben reemplazarse), los enlaces que el humano debe volver a abrir, y las imágenes QA de algunas diapositivas representativas. Lista de verificación de entrega: references/submission-checklist.md.

Tabla de decisiones rápida

El usuario quiere	Usar
Diapositivas académicas y formales	Tema ivory/obsidian, familia editorial-2d o data-3d, movimiento calm
Clases en el aula	whiteboard/chalkboard, familia illustrated, diagrama + plot
Viajes, geografía	sketchbook/ivory, ruta en globe + fotos reales + parallax 1 vez
Historia, arte, literatura	ivory, gallery (obras reales), timeline, efectos sepia ligeros
Tecnología, programación	blueprint/neon, code, network, flow, diagram
Negocios, pitch	neon/obsidian, towers, chart, metric, lottie 1 vez
Landing page con desplazamiento	deck.mode: 'scroll' (Lenis) — mismo contenido, desplazamiento suave
Escenas 3D prediseñadas en spline.design	Escena spline (URL .splinecode)
Cámara en vuelo según guion	slide.camera.sequence + Theatre.js studio (?studio)
Técnica, energía, clases con muchos datos	drafting · section + waffle/gauge/dimension/simulation + annotations
Enviar archivo por correo/USB, máquina sin conexión	npm run build:single

Documentos de referencia (léelos cuando sea necesario, no es necesario leerlos todos)

Archivo	Cuándo leerlo
references/brief-intake.md	Paso 0 — conjunto de preguntas + valores predeterminados sugeridos
references/effects-catalog.md	El usuario pregunta "¿qué efectos hay?", necesita elegir escena/efecto (con vistas previas)
references/design-rules.md	En todo momento al diseñar — una idea una imagen, densidad de texto, color semántico, anti-patrones
references/content-schema.md	Al escribir slides.ts — todos los campos de Slide/Block/Scene/Brief
references/content-mapping.md	Convertir markdown → diapositivas, ejemplos para varios temas
references/layouts-blocks.md	8 diseños, 23 bloques, anotaciones a mano, conectores, capacidad
references/scenes-3d.md	15 escenas 3D: cómo se ven, qué datos muestran, ejemplos de purpose
references/topics.md	Manual por tema (tema, escena, activos, trampas)
references/assets.md	Buscar imágenes, imágenes de usuario, SVG, IA, YouTube, Lottie, GLB, Spline, créditos, sin conexión
references/libraries.md	Bibliotecas ya integradas y cuándo usar otras (Reveal, Impress, Motion…)
references/themes.md	8 temas, personalización de colores/tipografías, transiciones, tecla D para modo claro/oscuro, postproducción
references/motion.md	Ritmo, transiciones, Theatre.js, reduced-motion
references/presenter.md	Teclas, clic, rueda, lápiz, vista presentador, notas, guion, citas
references/validation-qa.md	Comandos de verificación + lista de verificación de entrega
references/inspiration.md	Sitios web de referencia (Awwwards, Codrops, GSAP, Three.js…) y qué aprender de cada uno
references/ai-critique.md	Actitud crítica, ficha de revisión, verificación de comprensión, revisión cruzada entre agentes de IA, prompts de ejemplo
references/sources-verification.md	Jerarquía de fuentes, reglas para elegir números, tabla de verificación docs/verification.md
references/ai-disclosure.md	Apéndice de declaración de IA docs/ai-appendix.md
references/qa-defense.md	Preguntas de revisión 3C, preguntas abiertas, quiz, diapositivas de respaldo
references/workflow.md	Ritmo de trabajo por sesión, borradores A/B/C, diario y traspaso a nuevo chat, Git/despliegue, antes de la presentación
references/submission-checklist.md	Lista de verificación de entrega, banderas de penalización, legibilidad en proyector, cómo enviar el archivo