Communitygithub.com

escena-palo

Crea pequeñas escenas animadas de figuras de palo dibujadas a mano para páginas de aterrizaje y sitios web, donde una figura de palo opera una máquina o utilería que muestra lo que hace un producto.

¿Qué es escena-palo?

Esta habilidad permite generar widgets interactivos `<stick-scene>` que representan animaciones breves (5-8 segundos) de figuras de palo en el estilo de tinta y mantequilla de Kamran. Cada escena tiene un estado de inactividad (respiración, miradas, rascarse la barbilla) y reproduce una acción única al hacer clic, pasar el ratón o al hacerse visible al hacer scroll. Está diseñada para páginas de aterrizaje, explicadores animados o widgets tipo garabato que muestran visualmente una funcionalidad del producto (por ejemplo, tirar de una palanca, sellar un documento, fijar una nota). La habilidad incluye un runtime completo (`runtime/stick.js`) sin dependencias, plantillas para crear nuevas escenas, herramientas de verificación (hoja de contacto con fotogramas congelados y análisis de movimiento a 60 fps para detectar fallos) y un manual de referencia (`references/craft.md`) con catálogo de metáforas, recetas de utilería y temporización. El flujo de trabajo recomendado es: entender el producto, proponer 2-3 metáforas físicas (palanca, sello, correa, tablero, etc.), escribir la escena sobre la plantilla, verificar con la hoja de contacto y análisis de movimiento, y finalmente embeber el elemento en HTML (compatible con Astro). Las escenas existentes en `kamranahmed.info/story` (unas 90) sirven como referencia de estilo. Esta herramienta es ideal cuando un usuario solicita una animación de figura de palo, una escena de "trabajador" o "equipo", un explicador animado, o quiere mostrar una característica del producto como una pequeña escena animada que se entiende de un vistazo, sin necesidad de subtítulos extensos. Las reglas de estilo incluyen: tinta oscura, fondos blancos, un solo acento de color, la figura como protagonista (nunca oculta su cabeza o mano activa), una sola idea por escena, y mostrar el resultado final en lugar del proceso.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nilbuild/stick-scene/tree/HEAD

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Escena de palo

Una figura de palo al estilo tinta y mantequilla de Kamran realiza una tarea que muestra lo que hace un producto. La escena se mantiene en un estado de inactividad (respira, mira, se rasca la barbilla) y reproduce una acción de 5 a 8 segundos cuando se activa, para luego volver a la calma. Es un único <canvas> dentro de un elemento <stick-scene>, sin dependencias.

Todo lo que hay aquí ha sido probado en unas 90 escenas en kamranahmed.info/story. Comienza a partir de esos patrones; no inventes un nuevo estilo de dibujo.

Archivos

  • runtime/stick.js: el runtime completo. El esqueleto (figura, poses, easing, lápiz), un kit de utilería, el escenario y el elemento <stick-scene>. Cópialo sin cambios en la carpeta estática del proyecto.
  • templates/scene.js: el punto de partida para una nueva escena.
  • templates/preview.html + scripts/frames.mjs: renderiza una escena congelada en momentos elegidos como una hoja de contactos e informa errores.
  • scripts/motion.mjs: recorre la escena a 60 fps e informa problemas que un fotograma fijo no muestra: articulaciones que se rompen, un brazo atravesando la cara, una utilería dibujada sobre una cabeza, un codo doblado en dirección incorrecta o que sobresale por detrás, un giro aplastado, pies deslizantes, una mano que se queda corta, y un salto visual al inicio o final de la acción.
  • references/craft.md: hoja de trucos de la API, recetario de poses, receta de temporización, recetas de utilería, catálogo de metáforas y los errores que ya se han cometido una vez. Léelo antes de escribir una escena.
  • examples/: escenas reales. diffity-review.js (comentario → agente corrige → aprueba, dos figuras, un tablero y un escritorio) es el ejemplo completo más limpio. scenes-p3.js y scenes-p4.js contienen unas 30 más; el catálogo de metáforas en craft.md indica cuál es cuál.

Flujo de trabajo

  1. Comprende el producto. Una línea para cada uno: qué hace el usuario, qué obtiene. Lee la página de aterrizaje o el README si existe.
  2. Propón 2 o 3 metáforas y deja que el usuario elija, a menos que te haya pedido que continues directamente. Una línea por idea: la utilería, la acción, el resultado. Una buena metáfora es física (palanca, sello, transportador, tablero de chinchetas, carril de fotogramas, pila de cajas), se entiende de un vistazo sin necesidad del pie de foto, y termina con un resultado visible (una marca, un sello, algo que se eleva o se ilumina). Consulta el catálogo en craft.md.
  3. Escribe la escena a partir de templates/scene.js. Primero coloca la utilería en coordenadas mundiales fijas, luego la inactividad, luego la acción como una línea de tiempo en T segundos. Asigna a label una frase sencilla para lectores de pantalla.
  4. Compruébala con la hoja de contactos. Mira cada hoja antes de darla por terminada:
    # una vez, en un directorio temporal:  npm i [email protected]
    NODE_PATH=<temporal>/node_modules node <dir-habilidad>/scripts/frames.mjs \
      --scene <id> --src ruta/a/scene.js \
      --frames "idle:0,idle:2.5,s:0.8,s:1.6,s:2.4,s:3.2,s:4.0,s:5.0" --fw 400 --out /tmp/<id>.png
    
    <dir-habilidad> es la carpeta donde se encuentra este SKILL.md. Luego lee el PNG. idle:<seg> congela el bucle de reposo, s:<seg> un momento de la acción, u:<0..1> una fracción de la misma. Añade @<n> para renderizar la enésima reproducción (s:2.4@1), de modo que las escenas que varían con S.n tengan todas las variantes comprobadas. Corrige y vuelve a renderizar hasta que: nada esté recortado en los bordes, ninguna utilería cubra una cara o lo que se está explicando, cada momento se entienda por sí solo, el texto esté dentro de su caja con espacio arriba y abajo, las manos estén delante de lo que sostienen, los objetos sostenidos toquen el cuerpo donde lo haría uno real (un micrófono en la boca, un mango en la palma), las flechas sean cheurones dibujados a mano, no triángulos rellenos, y el último fotograma coincida con la inactividad (sin salto visual al volver al bucle). Dos o tres rondas es normal. Luego comprueba el movimiento, que la hoja no puede mostrar:
    NODE_PATH=<temporal>/node_modules node <dir-habilidad>/scripts/motion.mjs --scene <id> --src ruta/a/scene.js
    
    Corrige cada salto (fusiona la pose en lugar de cambiarla), brazo-atravesando-cara, cabeza-cubierta (una utilería, nota o burbuja dibujada sobre una cara), codo-doblado-hacia-atrás, codo-sobresale-por-detrás (un brazo de ala rota mantenido más de un momento), aplastamiento, salto-inicial y salto-final hasta que imprima "el movimiento está limpio". Un breve deslizamiento al principio o al final de una caminata es aceptable.
  5. Insértalo. Copia runtime/stick.js y el archivo de la escena en la carpeta estática del sitio y añade:
    <stick-scene scene="<id>" play="view" style="height:230px; max-width:560px"></stick-scene>
    <script src="/scenes/stick.js" defer></script>
    <script src="/scenes/<id>.js" defer></script>
    
    En Astro usa <script is:inline ... defer>. stick.js debe ir antes de cada script de escena en el orden del documento (los scripts diferidos se ejecutan en orden y las escenas leen window.RIG al cargar). En una página de aterrizaje con varias escenas, coloca cada una en un marco para que no flote sobre una línea de suelo desnuda: una tarjeta redondeada con borde de 1px, fondo blanco, una cuadrícula de puntos tenue (radial-gradient(#e6e6e6 1px, transparent 1.2px) a 14px) y la banda del suelo activada (sin no-floor); la línea de suelo entonces se extiende de borde a borde como un pequeño escenario. Dale a cada escena de la página el mismo marco y el ancho completo del contenido. Luego carga la página real en un navegador sin cabeza, desplázate hasta que el elemento esté visible, espera unos 3 segundos y captura la pantalla en tamaños de escritorio y móvil.

El elemento

  • scene: el id registrado como SCENES['<id>'].
  • play: view (se reproduce una vez cuando está medio visible, luego al hacer clic; el mejor valor por defecto para páginas de aterrizaje), click (al hacer clic), hover (se repite mientras el ratón está encima; al hacer clic en táctil), loop (siempre ejecutándose, usar con moderación), idle (nunca se reproduce).
  • no-floor: elimina la banda gris claro debajo de la línea de suelo. Úsalo en páginas blancas lisas. no-ground: también elimina la línea.
  • zoom: escala el dibujo hacia arriba o hacia abajo dentro del cuadro (por defecto 1).
  • label o aria-label: lo que muestra la escena. Por defecto es el label de la escena.
  • no-font: no carga Balsamiq Sans desde Google Fonts (cuando el sitio ya la aloja por sí mismo o no debe llamar a Google).
  • Dale tamaño con CSS. El dibujo se ajusta a la altura (230px es el tamaño nativo) y al ancho de la escena en unidades del mundo, centrado.
  • El movimiento reducido muestra un único fotograma fijo y nunca se reproduce. Las escenas fuera de pantalla no se dibujan.
  • STICK.theme({ butter: '#…', greenInk: '#…' }) intercambia los colores de la paleta para toda la página. Es preferible usar constantes de color locales en la escena (como los verdes de añadir/eliminar de GitHub en diffity-review.js) cuando solo una escena las necesita.

Reglas de estilo

  • Tinta #141414, rellenos de papel blanco, un único color mantequilla o acento, mucho espacio vacío. Balsamiq Sans a 8.5–11px para cualquier texto, y solo unas pocas palabras.
  • La figura es la heroína: nunca escondas su cabeza o la mano activa detrás de una utilería. Dibuja primero la utilería, luego las figuras, luego los objetos sostenidos o voladores.
  • Una idea por escena. Si necesitas un pie de foto para explicarlo, la metáfora es incorrecta.
  • Muestra el resultado, no el trabajo: termina con algo que ha cambiado de estado y se mantiene un instante.
  • Objetos físicos antes que animales dibujados o personajes detallados. Una segunda figura (un ayudante) recibe un solo color mediante ink/far. Un agente de IA es un robot: fig(..., { ink: '#d97757', far: '#e8b7a3', bot: { col: '#d97757', dark: '#a8553a', glow, blink, happy } }) dibuja una cabeza redondeada con una visera oscura y ojos brillantes, pernos de oreja, un bulbo de antena y una luz en el pecho. Un segundo agente va en verde azulado (#3d7a8c, dark #2a5866, far #a9c9d1). Un agente negro también funciona: un col oscuro obtiene automáticamente una visera blanca y ojos de tinta. Luz glow mientras trabaja, happy cuando termina, y coloca una pequeña etiqueta (tú, agente, claude) debajo de cada figura en y = 16.
  • Los agentes no deben reaccionar instantáneamente. Mantén una pausa después de que llegue una solicitud (una línea de pensando…, una burbuja de hmm…, una mano en la barbilla, un parpadeo lento de la antena) antes de que comience el trabajo.
  • No uses logotipos de otras empresas. Los nombres de productos como texto plano en una utilería están bien.

Skills relacionados