caceresfjulian/motion-figure

Figura de movimiento

Este skill crea figuras que se mueven o responden a la entrada. Tiene tres niveles. Usa este skill con Claude, Cursor, Codex, OpenClaw, Hermes o cualquier agente que lea SKILL.md.

Nivel	Qué crea	Dónde va
1. Figura de lección	Animación SMIL declarativa, o un control deslizante que redibuja un SVG. Ambos se montan desde un ```recuadro de figura.	Lecciones del curso
2. Figura de mecanismo	Un panel HTML que muestra las partes nombradas de un sistema. El lector maneja un control y lee un veredicto calculado.	Páginas independientes, READMEs, ensayos, el sitio del curso fuera de las lecciones
3. Campo de tramado	Una banda WebGL de puntos de tramado ordenado en los colores papel, acento y tinta, con cuatro movimientos inicializados por semilla.	Cabeceras de página y separaciones de sección

El nivel 1 tiene la mayoría de las reglas, porque el entorno de ejecución de la lección tiene límites estrictos. Los niveles 2 y 3 tienen sus propios archivos de referencia.

Cuándo usarlo

• Una lección explica un proceso que cambia con el tiempo: un token que avanza por etapas, una cola que se llena, un bucle que se repite.
• Una lección explica una fórmula donde una entrada cambia la salida: tasa de aprendizaje, temperatura, tamaño de fragmento, tamaño de lote.
• Un autor escribe "anima esta figura", "añade un control deslizante" o "haz el diagrama interactivo".
• Una página necesita una demostración donde el lector cambie una cosa y vea lo que hace el sistema: una caché, una cola, una ventana de contexto, un enrutador. Usa el nivel 2.
• Una página necesita una cabecera de movimiento lento en los colores del curso. Usa el nivel 3.

Cuándo no usarlo

• La idea es una estructura fija sin eje temporal ni entrada. Crea una figura SVG estática. El skill hermano blueprint-figure cubre las figuras estáticas.
• La página es una página explicativa completa con su propio modelo de estado y geometría de máquina. El skill hermano isometric-explainer cubre eso.
• Solo necesitas paleta, fuentes o reglas de prosa. El skill hermano course-style contiene eso. Este skill copia las partes que necesita en references/tokens.md.

Método

1. Escribe una frase que nombre el único cambio que muestra la figura. Si necesitas dos frases, haz dos figuras.

2. Elige el nivel. Dentro de una lección, usa el nivel 1. Para el nivel 2, lee references/mechanism-figures.md y comienza desde templates/mechanism.html. Para el nivel 3, lee references/dither-fields.md y copia templates/dither.js. Los pasos siguientes son para el nivel 1. En el nivel 1, usa una figura animada cuando el tiempo es la variable. Usa un control deslizante cuando un número es la variable.

3. Elige un nombre en kebab-case, por ejemplo request-path o context-budget. Busca primero ese nombre en el registro. Un módulo posterior que registre el mismo nombre reemplaza la figura anterior.

4. Coloca el código en un archivo de módulo llamado figures-<topic>.js. Envuélvelo en una IIFE, lee window.LF y retorna temprano si falta.

5. Escribe una función de figura function (host, cfg). Añade una tarjeta .lf a host y puede devolver una función de eliminación.

6. Construye la tarjeta: .lf-head con una .lf-label en mayúsculas y una pista corta, .lf-body y .lf-cap con el pie de figura.

7. Usa viewBox="0 0 520 H" para el SVG. La mayoría de las figuras del curso usan una H de 200 a 250. Una sola barra necesita menos.

8. Añade un <title> y un <desc> con ids que crees una vez, fuera de cualquier función de renderizado.

9. Para una figura animada, añade primero las entradas, luego un bucle lento. Sigue references/smil-rules.md línea por línea.

10. Para un control deslizante, define state._render antes de llamar a LF.slider o LF.select. Luego llama a state._render() una vez al final.

11. Llama a LF.register({ 'tu-nombre': fn }) al final del módulo.

12. En el Markdown de la lección, añade el recuadro. Pon el nombre en la primera línea y la configuración JSON opcional después:

    ```figure
    context-budget {"windowK": 32}
    ```
    

13. Ejecuta las comprobaciones en "Comprobar antes de terminar". Mira la figura en tema claro, tema oscuro, con 375 px de ancho y con movimiento reducido activado.

Cómo monta la página una figura

• El analizador Markdown convierte el recuadro en <div class="lesson-figure" data-figure="nombre {json}">.
• La compilación del sitio escanea el Markdown de la lección en busca de nombres de recuadro. Encuentra el archivo de módulo que contiene el nombre entrecomillado y escribe un manifiesto. Un nombre de recuadro sin proveedor detiene la compilación.
• La página carga solo los módulos que la lección necesita, en un orden fijo. Los nuevos archivos de módulo van después de los listados, en orden alfabético.
• La función de montaje lee la primera palabra como el nombre y analiza el resto como JSON. Un JSON incorrecto da un cfg vacío.
• Si la función de figura falla, el entorno de ejecución vacía el host y registra una advertencia. El resto de la lección aún se renderiza.
• Después del montaje, el entorno de ejecución añade un título, una descripción, role="img" y etiquetas de control si faltan. Añade un botón de Pausa cuando la figura tiene animación SMIL, y un botón de Reproducir cuando cualquier animación se reproduce una vez.
• El entorno de ejecución pausa la animación cuando la figura sale del viewport, cuando la pestaña está oculta y cuando el lector presiona Pausa. Con movimiento reducido o impresión, muestra el fotograma estático.

references/toolkit.md describe cada función del entorno de ejecución y tiene dos ejemplos completos de módulos.

Reglas

Figuras animadas:

1. Usa solo <animate>, <animateTransform> y <animateMotion>. No uses setInterval ni requestAnimationFrame en una figura.
2. Mantén cada figura en 55 elementos SVG o menos.
3. Las entradas van de opacidad 0 y escala 0.95 a opacidad 1 y escala 1. Nunca empieces una escala en 0.
4. Las entradas usan calcMode="spline" y keySplines="0.23 1 0.32 1". La duración de la entrada es de 0.5 a 0.6 s.
5. Escalonar los inicios de entrada de 0.05 a 0.4 s. Las salidas son más cortas que las entradas.
6. Los bucles duran de 2.5 a 6 s y usan repeatCount="indefinite". No establezcas fill="freeze" en un bucle, porque entonces el entorno de ejecución lo reproduce una vez.
7. Cada lista keyTimes tiene tantas entradas como values. Empieza en 0, termina en 1 y nunca disminuye.
8. Cada lista keySplines tiene una entrada menos que keyTimes. Úsala solo con calcMode="spline".
9. Un animateMotion con keyPoints usa calcMode="linear". Su número de keyPoints es igual a su número de keyTimes. No tiene values.
10. No pongas var() en un valor fill o stroke animado. Anima la opacidad de un segundo elemento que tenga el color objetivo.
11. Los bucles animan solo opacidad, transform, stroke-dashoffset o movimiento a lo largo de un camino. El entorno de ejecución hace que cualquier animación de x, y, x1, y1, x2, y2, width, height, r, cx, cy, rx o ry se reproduzca una vez.
12. El fotograma en data-static-time del host (por defecto 1.5 s) está completo y es legible. Establece el atributo en el host cuando un momento posterior muestre el estado completo.
13. Escala un elemento alrededor de su centro. Dibuja el contenido de un grupo alrededor de (0, 0) y mueve el grupo con translate. Añade la escala con additive="sum".

Controles deslizantes:

14. Escribe solo ES5: var, expresiones de función, concatenación de cadenas. Sin funciones flecha, let, const ni plantillas literales.
15. Define state._render antes de la primera llamada a LF.slider o LF.select. El control deslizante envuelve la función de renderizado cuando lo creas.
16. En state._render, elimina todos los hijos SVG y vuelve a añadirlos. No edites nodos en el lugar.
17. Crea ids una vez, fuera de state._render. El entorno de ejecución elimina los atributos que los nuevos nodos no tienen, incluidos los ids.
18. Haz crecer las barras por longitud o por stroke-dasharray en un camino. No hagas crecer las barras con escala, porque los nodos reconciliados escalan desde su centro.
19. Mantén cada etiqueta del control deslizante corta y en minúsculas con la unidad entre paréntesis, por ejemplo tamaño de fragmento (tokens).

Ambos tipos:

20. Toma cada color de una variable CSS con el valor del tema claro como su valor predeterminado, por ejemplo var(--blueprint,#3553ff). Usa hex literal solo cuando ninguna variable funcione.
21. Usa como máximo un color de acento (--blueprint) para el sujeto principal y --warn para un segundo estado. Usa tokens de tinta y regla para el resto.
22. Establece el texto SVG en 12 unidades o más, en var(--font-mono). Si las etiquetas deben ser más pequeñas, dale al SVG un ancho mínimo de 500 px y permite que se desplace lateralmente.
23. Mide el tamaño de la etiqueta en un teléfono. En una pantalla de 375 px, un SVG de 520 unidades dentro de la tarjeta dibujó 279 px de ancho. Una etiqueta de 12 unidades se dibujó entonces a aproximadamente 6.4 px.
24. Escribe el pie de figura en inglés técnico sencillo. Nombra lo que significa cada color. Mantén las frases en 25 palabras o menos.
25. Da la etiqueta en .lf-label en mayúsculas, de dos a cuatro palabras.

Figuras de mecanismo (nivel 2):

26. Muestra nombres reales y números reales: nombres de archivo, claves, recuentos de tokens. Nunca elemento 1 ni una barra gris sin nombre.
27. Dale al lector un control: paso, deslizante, alternar, reproducir o detener una parte.
28. Termina con una línea de veredicto en texto, calculada a partir de los números en el cuerpo. Nunca escribas un resultado fijo.
29. Ejecútala una vez cuando el 35 por ciento de la figura sea visible, añade un botón de Reproducir y nunca la repitas en bucle.
30. Anima solo transform y opacity, con cubic-bezier(0.23, 1, 0.32, 1). Presiona 120 a 160 ms, revela 200 a 300 ms, pliega 380 a 500 ms.
31. Escalona listas de 30 a 70 ms por elemento, solo para los primeros 8 elementos.
32. Mantén cada etiqueta completa en cada fotograma: sin puntos suspensivos, sin superposición, sin texto sobre puntos. Texto de 11 px o más, veredicto de 12.5 px o más.
33. A 320 px, apila los paneles en una columna y da a cada control un objetivo táctil de 40 px.
34. Usa un mecanismo que ninguna otra página del sitio use y añádelo a la tabla de mecanismos del sitio.

Campos de tramado (nivel 3):

35. Lee los colores de --bg, --blueprint y --ink, y redibuja cuando data-theme cambie.
36. Dibuja a 30 fotogramas por segundo como máximo, y solo mientras la banda sea visible.
37. Con movimiento reducido, dibuja un fotograma estático. Sin WebGL, muestra un sombreado estático.
38. Marca la banda aria-hidden="true" y no pongas texto en los puntos excepto la etiqueta del chip.

Comprobar antes de terminar

• El nombre del recuadro coincide exactamente con el nombre registrado, y ningún otro módulo lo registra.
• El módulo no tiene =>, let, const ni cadenas con comillas invertidas.
• El módulo no tiene setInterval ni requestAnimationFrame.
• El validador en references/smil-rules.md devuelve una lista vacía para el host montado.
• Cada figura animada tiene 55 elementos SVG o menos.
• Cada bucle tiene una duración de 2.5 a 6 s.
• Ningún bucle anima un atributo de geometría de la regla 11.
• Con movimiento reducido activado, la figura muestra una imagen completa y ningún elemento falta.
• En tema oscuro, cada línea y etiqueta es visible.
• Con un ancho de 375 px, cada etiqueta es legible y la página no tiene desplazamiento lateral fuera de la figura.
• Para un widget, mover cada control deslizante a su mínimo y máximo no produce NaN, anchos negativos ni errores en la consola.
• El SVG tiene un título y una descripción, y sus ids permanecen iguales después de que un control deslizante se mueva.
• El pie de figura nombra cada color que la figura usa.
• Nivel 2: cada elemento de la lista de verificación al final de references/mechanism-figures.md se cumple.
• Nivel 3: cada elemento de la lista de verificación al final de references/dither-fields.md se cumple.

Archivos

• references/smil-rules.md: las doce reglas SMIL completas, lo que previene cada regla y un validador que puedes ejecutar en la consola del navegador.
• references/toolkit.md: las funciones LF y la secuencia de montaje. También tiene un control deslizante completo, una figura SMIL completa y una página de vista previa para usar fuera del sitio del curso.
• references/tokens.md: tokens de color para temas claro y oscuro, fuentes y valores de sincronización de movimiento.
• references/mechanism-figures.md: nivel 2. Nombres reales, figuras rechazadas, formas de mecanismo, anatomía, veredicto, presupuesto de movimiento y comprobaciones.
• references/dither-fields.md: nivel 3. Cómo dibuja el sombreador, los cuatro movimientos, marcado, reglas, barras tramadas y comprobaciones.
• templates/mechanism.html: una figura de nivel 2 completa, una caché LRU con un control de tamaño, que se abre en cualquier navegador.
• templates/dither.js: un script de nivel 3 completo. Cárgalo y añade <div class="dither" data-seed="...">.

Dentro del repositorio AI Engineering from Scratch, consulta también site/lesson-figures.js para el entorno de ejecución y site/figures-*.js para más figuras.