tellmotion

TellMotion — idea → tema → animación

Un flujo repetible, económico en tokens. Funciona para cualquier tema que quepa en 2D: diagramas, procesos, arquitecturas, algoritmos, cronologías, conceptos. (No sirve para 3D ni video con actores reales.)

Estructura de esta habilidad: themes/ (catálogo theme.json) · tools/ (Node, sin dependencias) · assets/base (plantilla de Motion Canvas, con recetas de escenas) · assets/packs/ (paquetes de componentes opcionales) · scripts/new-project.sh · references/.

1. Brief (una ronda, pregunta solo lo que falta)

Si el usuario ya proporcionó contenido/estructura, no vuelvas a preguntar. Usa AskUserQuestion (máximo 4 preguntas) para lo que falte:

1. Tema y contenido (si falta: propón uno inventado y dilo).
2. Duración / ritmo (por defecto: ritmo tranquilo, escenas de 20-60 s) y fps (por defecto 30 previsualización / 60 renderizado).
3. Diseño — ofrece siempre estas tres opciones:
   • Plantilla: usa un tema del catálogo. Ejecuta node tools/list-themes.mjs (lista compacta) y pide el id; para verlos visualmente ejecuta node tools/build-catalog.mjs <tmpdir> y abre gallery.html (sirve con node tools/serve.mjs <tmpdir>).
   • Diseño personalizado: escribe 3 propuestas contrastadas de theme.json (consulta references/theme-format.md), genera previsualizaciones y deja que el usuario elija (paso 2).
   • Trae el tuyo: el usuario proporciona colores/tipografías de marca o un archivo de Figma → deriva un theme.json a partir de ello.
4. Paquetes: infiérelos del tema, no preguntes a menos que no esté claro, y añade solo los que usarán las escenas personalizadas: cloud (arquitecturas), algorithms (ordenamiento, árboles), charts (datos), flowchart (procesos), timeline (historia/hojas de ruta), code (programación, CLI), typography (intros, citas, A vs B), science (ciclos, capas, ondas), math (ecuaciones, funciones), ui (demostraciones de producto, flujos de usuario), maps (lugares, viajes). Combínalos libremente; references/packs.md lista cada componente.

2. Diseño personalizado (saltar cuando se haya elegido una plantilla)

1. Escribe 3 propuestas como archivos theme.json en una carpeta temporal (copia el tema del catálogo más cercano y cambia los tokens; familias diferentes, p. ej. técnico / divertido / editorial).
2. node tools/validate.mjs <archivo> para cada uno, luego node tools/build-catalog.mjs <salida> --themes <carpeta>.
3. Muestra las previsualizaciones: abre <salida>/gallery.html en el panel del navegador (serve.mjs) o envía los SVG. Espera la elección del usuario.
4. Ruta opcional de alta fidelidad con Figma (solo si el usuario la quiere y existe el conector de Figma): references/figma.md.
5. Guarda el tema elegido como <proyecto>/theme.custom.json (y ofrece contribuirlo al catálogo).

3. Storyboard (el usuario lo aprueba antes de animar nada)

Reescribir una animación es caro; reescribir una lista de escenas no lo es. Omite este paso solo para una única escena o si el usuario lo pide.

1. Lee references/storyboard.md y references/recipes.md, luego escribe storyboard.json: una entrada por escena, con su receta (o custom), lo que muestra, sus segundos y su texto real.
2. node tools/storyboard.mjs validate <archivo>, luego node tools/storyboard.mjs preview <archivo> --theme <id|archivo> --out <tmpdir>. Muestra la página con el panel del navegador (serve.mjs), y también lista las escenas en el chat.
3. Espera la aprobación del usuario. Cambia el storyboard, no el código, hasta que esté de acuerdo. Detén el servidor de previsualización después.

Después de la aprobación, trabaja de forma autónoma hasta la entrega.

4. Proyecto

bash <habilidad>/scripts/new-project.sh <nombre> --theme <id|ruta.json> [--pack a,b|all] [--demos]

(--demos copia la escena de demostración de cada paquete: útil para aprender la API, luego borra las demos.) Ejecútalo desde la carpeta que debe contener el proyecto. Un proyecto por tema; añade escenas para nuevos videos. Copia la plantilla, aplica el tema (src/theme.ts, src/fonts.ts), instala dependencias y registra el proyecto en .claude/launch.json. Cambia el tema después: node <habilidad>/tools/apply-theme.mjs <tema> <proyecto> luego npm install.

5. Escenas

node tools/storyboard.mjs generate <archivo> <proyecto> escribe cada escena y src/project.ts. Las escenas con receta están terminadas. Cada escena custom es un marcador de posición funcional con su título, subtítulos y duración: escribe su animación, manteniéndolos. Para esas, lee references/motion-guide.md (API principal, receta de diseño, errores comunes) y references/packs.md (componentes de paquetes). Volver a ejecutar generate conserva las escenas que editaste. Reglas fijas:

• Una escena por bloque en src/scenes/, registrada en src/project.ts (+ un archivo .meta por escena).
• Usa prepareScene(view, title); llama a enter() primero y leave() al final; subtítulos mediante sub.say(text).
• Texto ≥ 28 px en 1920x1080; subtítulos ≤ 85 caracteres; un color de categoría por tipo de elemento + leyenda en src/config.ts (LEGEND).
• Muestra solo lo necesario por escena; glow() el elemento activo y dim() el resto.
• Texto editable, temporizaciones y colores como constantes al inicio de cada escena (comentario EDITABLE TEXT); velocidad global en PACE.
• Une piezas con connect(root, a, b). Las solicitudes y eventos viajan con send(root, arrow.points, {shape: 'dot' | 'diamond', to: piece}), así la forma los distingue y la pieza reacciona al llegar.
• Nunca uses colores o fuentes fijas en las escenas: usa C, S, FONT, fs() de config.ts para que los temas sean intercambiables.

6. Verificar (económico)

1. npm run typecheck en el proyecto, luego node tools/storyboard.mjs duration <proyecto>: si una escena se aleja del plan aprobado, arréglala o informa al usuario.
2. preview_start (nombre del proyecto desde .claude/launch.json), resize_window 1700x950, luego haz clic en la línea de tiempo y zoom en [215,0,800,330]; agrupa varios clics+zoom en un browser_batch. scroll right en la línea de tiempo para llegar a escenas posteriores.
3. Al terminar: resize_window preset desktop, preview_stop. No renderices mp4 a menos que te lo pidan.

7. Renderizar (cuando se pida)

npm run render en el proyecto escribe output/<nombre>/<nombre>.mp4 y render.json (duración por escena, tamaños de archivo), sin abrir el editor. Opciones (después de npm run render --):

• --format mp4,webm,gif · --thumb o --thumb-at <segundos> · --fps <n> · --scale <n>. La codificación WebM es lenta (minutos): solicítala solo cuando sea necesario.
• --aspect 9:16,1:1: ajusta el video dentro con barras del fondo del tema (--pad-color sobreescribe); no reorganiza la escena, por lo que el texto se reduce aproximadamente al 56%. Dilo al usuario.
• --draft: 30 fps a la mitad de tamaño, en output/<nombre>-draft/. Úsalo para revisar.
• --info: duración de cada escena, no renderiza nada. Económico: prefierelo a renderizar para comprobar el ritmo.
• --dry-run: rango de tamaño por archivo a partir de muestras renderizadas, no guarda nada. Úsalo antes de un render grande o cuando el usuario se preocupe por el tamaño.

Necesita Chrome, Edge o Chromium (CHROME sobreescribe la ruta). Proyectos creados antes de que existiera este script: node <habilidad>/tools/render.mjs <proyecto>. La fuente es tools/render.mjs.

8. Entregar

Lista las escenas (nombre → lo que muestra), cómo ejecutar (npm start), cómo renderizar (npm run render), cómo cambiar el ritmo (PACE), textos (constantes por escena), tema (apply-theme.mjs). Indica lo que no se verificó. Si el espacio de trabajo tiene un CLAUDE.md, añade el nuevo proyecto.

Ahorro de tokens

• No vuelvas a leer archivos que acabas de escribir; usa Edit.
• Usa list-themes.mjs en lugar de leer archivos JSON de temas; lee un solo tema solo cuando lo personalices.
• Agrupa capturas de pantalla/zooms; evita capturas de página completa.
• Reutiliza assets/ en lugar de regenerar componentes.