hirowyh/settle

¿Qué hace settle?

Convierte una solicitud como "un interruptor que se sienta realmente agradable al hacer clic" o "una animación corta en bucle que muestre mi aplicación de tareas pendientes" en una pieza viva con movimiento que se asienta como lo hacen las cosas físicas. La artesanía del movimiento es la misma en cada pieza; el aspecto se renueva para cada solicitud, o se hereda del proyecto de la persona.

Las rutas a continuación son relativas a la carpeta de este archivo. Ejecuta cada script desde la carpeta de trabajo (la raíz del proyecto, o la carpeta donde va la pieza) usando su ruta completa: node <esta carpeta>/scripts/deal.mjs …: los scripts escriben sus archivos donde los ejecutas.

Cómo se ejecuta una solicitud

1. Lee el contexto. Averigua si estás en un proyecto: un package.json que nombre un framework, o una carpeta de páginas HTML. En un proyecto, anota cómo escribe los estilos, el aspecto que definen sus tokens o tema, y cualquier librería de movimiento que ya use. Luego lee la solicitud: qué estructura en references/kinds/ es, si es una muestra o parte de un producto, y qué piden sus palabras de principiante, las cuales references/words.md traduce.
2. Negocia o hereda el aspecto.
   • Un proyecto con aspecto propio lo conserva: mapea ese aspecto a las variables de la hoja, y negocia solo lo que falte con --keep palette,type.
   • De lo contrario, negocia: node scripts/deal.mjs --brief "<la solicitud en una línea>" --kind <control, data-view, composite o flow>, con las banderas que references/words.md da para las palabras de la solicitud, y --project cuando estés en un proyecto, para que piezas posteriores allí hereden el aspecto. Construye el aspecto 1, el negociado: --pick 1. Toma el aspecto 2 o 3 solo cuando el aspecto 1 choque con el tema, y nombra el conflicto: --pick 2 --because "un fondo oscuro para un menú de desayuno". references/tokens.md tiene las reglas.
   • Un aspecto negociado tiene una dirección, que viste la pieza; la solicitud establece su forma. Lee su sección en references/directions.md, y cada dirección al principio, antes del resumen.
3. Escribe el resumen, o un storyboard.
   • Para un control, una vista de datos o un compuesto, indica el resumen en dos líneas y construye directamente: qué es, en qué se convierte la dirección para este tema, el aspecto, el momento característico y los valores predeterminados que elegiste. "Un temporizador Pomodoro para un sitio de estudio. Instrumento: el temporizador es la carátula de un temporizador de cocina, marcas de minutos alrededor de un bisel; aspecto 1, masilla y negro; momento característico: el botón de Inicio se convierte en la barra que se vacía; 25 minutos, descansos de 5 minutos."
   • Para un flujo a lo largo del tiempo, o una solicitud que podría significar dos cosas muy diferentes, muestra un storyboard (references/kinds/flow.md tiene el formato) y espera una confirmación.
   • Antes de construir, imagina qué recibiría cualquier solicitud similar. Cambia cada parte del resumen que coincida con esa imagen.
4. Constrúyelo donde va la pieza.
   • Sin proyecto: un archivo HTML construido sobre assets/page.html, o assets/reel.html para un carrete. Contiene la hoja, las reglas de página de la dirección, el kernel (assets/kernel.js) pegado completo en el script de módulo de la cabecera, y las recetas de references/motion.md que la pieza necesita.
   • Un proyecto: un componente en el framework y estilo del proyecto, el kernel copiado una vez como módulo, la hoja en la hoja de estilos global del proyecto. references/stacks/ tiene una nota por pila.
   • Movimiento para una pieza que ya existe: conserva su marcado y su aspecto, y da a cada uno de sus cambios el movimiento que la gramática nombra (references/craft.md, sección 3), a través de la puerta.
   • El archivo de la estructura en references/kinds/ dice qué recetas usar, según el tipo de cambio que hace cada parte.
5. Verifícalo. Lint el archivo y captura fotogramas con snap.mjs como describe references/review.md, en el archivo o en el servidor de desarrollo del proyecto. Arregla lo que se lea mal en la hoja de contactos y captura de nuevo, tres rondas como máximo. Una verificación que se comporte mal, como que un arrastre no pueda aterrizar o un servidor que no arranque, recibe dos intentos; luego entrégala nombrándola como no verificada.
6. Entrégalo (abajo).

Qué leer

Archivo	Leer cuando
references/craft.md	Cada construcción: las reglas que sigue cada movimiento, la lista prohibida y los problemas comunes
references/tokens.md	Cada construcción: cómo se negocia o hereda un aspecto, y cómo se usa
references/directions.md	Cada construcción sin proyecto: la sección de la dirección negociada
references/motion.md	Cada construcción: la hoja, la página base y las recetas, una por movimiento
references/kinds/control.md, data-view.md, composite.md, flow.md	La estructura de la pieza: su anatomía y las recetas desde las que empezar
references/stacks/html.md, react-next.md, vue.md, svelte.md, astro.md	Donde va la pieza: html.md para un archivo independiente, la pila del proyecto en caso contrario
references/words.md	La solicitud describe un sentimiento, como "que resalte"
references/review.md	El paso de verificación

Reglas estrictas

• La pieza va donde la persona trabaja. En un proyecto: el framework y estilo del proyecto, sin nuevo paquete, y la librería de movimiento del proyecto si tiene una, llevando el tiempo de settle. Sin proyecto: un archivo HTML autónomo con el kernel pegado, cuya única solicitud externa es el enlace de la fuente del aspecto; debe funcionar también con la fuente del sistema. Una foto obtenida por solicitud se coloca junto a él.
• La solicitud establece la forma. Un control mantiene su tamaño real, un widget se queda en una tarjeta o panel, y una pantalla completa solo llega cuando la solicitud pide una pantalla. Una solicitud para una página de aterrizaje o sitio web completo recibe solo la pieza móvil dentro de él, como la presentación de diapositivas de la aplicación, construida para insertarse en la página, y la entrega deja la página a una habilidad de diseño de páginas. El fondo alrededor de la pieza permanece simple.
• El aspecto proviene de la hoja y la dirección. Cada valor visual proviene de las variables de la hoja o sus matices, con un fondo, una tinta y uno o dos acentos. La dirección negociada viste la pieza, y un fondo oscuro es para un tema que ocurre en la oscuridad.
• Movimiento desde el kernel. Cada movimiento que responde a una persona, y cada cambio de estado, se ejecuta en settle.track, settle.stretch o settle.move con un preset del registro del aspecto, settle.register().
• Tiempo desde settle.now(). Los manejadores establecen objetivos; un bucle requestAnimationFrame dibuja cada estilo en movimiento desde el tiempo actual. snap.mjs detiene ese reloj para verificar fotogramas.
• La forma perdura. Cada nuevo estado se construye a partir de la forma ya en pantalla, el texto cambiado pasa por un breve desenfoque, y un nuevo contenedor se abre desde detrás de lo que permanece.
• La mano lidera. Los valores arrastrados se sitúan exactamente bajo el puntero; más allá de un límite siguen una goma elástica; las liberaciones mantienen la velocidad de la mano.
• Contenido real. Especificaciones plausibles, y una acción mantiene su nombre a lo largo de un flujo. Las fotos provienen de la persona, o, cuando pide una foto real y no tiene ninguna, de scripts/photo.mjs con su crédito en la pieza; de lo contrario, dibuja en código solo lo que el código dibuja nítidamente, nunca un paisaje (references/directions.md, Imágenes).
• Un momento característico, y todo lo demás a su alrededor tranquilo.
• Prohibido a menos que la solicitud lo nombre: todo en la lista prohibida de references/craft.md, que el lint marca.
• Para todos. Funciona con puntero, tacto y teclado, con foco visible y objetivos de 44 píxeles. Se adapta a una pantalla de 360 píxeles sin texto menor de 11 píxeles, y bajo movimiento reducido sus muelles aterrizan de inmediato.
• El costo cuenta. Cada llamada de herramienta gasta el uso de la persona. Construye una vez, verifica en tres rondas como máximo, da a una verificación que se comporte mal dos intentos, y deja los scripts mismos sin depurar: nombra lo que quedó sin verificar en la entrega.

Muestra o producto

Una muestra, como un carrete para una página de aterrizaje, recibe el movimiento completo. Un control dentro de un producto funcional se mueve menos cuanto más a menudo lo ve una persona: nada para algo usado cien veces al día, rápido y leve para algo usado decenas de veces. references/craft.md tiene la tabla (regla de frecuencia de Emil Kowalski).

Dónde va el archivo

Sin proyecto, escríbelo en la carpeta de trabajo con un nombre corto de su tema, como tea-timer.html, a menos que la persona nombre una ruta. En un proyecto, colócalo donde diga la nota de la pila, nombrado en el estilo del proyecto, y muéstralo en algún lugar donde la persona pueda abrirlo: una página o ruta propia cuando la solicitud no nombre ninguna. Mantén los números ajustables de la pieza juntos al principio de su script: los datos, y cualquier tiempo que el registro no establezca.

Entrega

Responde con:

• Dónde está la pieza, cómo abrirla (el archivo, o la ruta y el comando que inicia el servidor de desarrollo), y una línea sobre qué es y su momento característico.
• Dos o tres cosas para probar: "arrastra el pomo más allá del final", "presiona Tab, luego las teclas de flecha".
• Dos parámetros para ajustar, nombrados como aparecen al principio del script.
• Dónde va su foto, cuando un dibujo la reemplaza: el elemento a intercambiar por un <img> de ellos.
• Qué quedó sin verificar, si algo, como Safari en un teléfono real.
• Una oferta para renegociar una parte del aspecto (node scripts/deal.mjs --redeal palette), y para una solicitud vaga, tres variantes detrás de un conmutador.

Para un carrete, ofrece la exportación de video: node scripts/export.mjs reel.html --out reel.mp4 (o --gif) lo renderiza con ffmpeg, promediando cuatro subfotogramas por fotograma para desenfoque de movimiento.

Scripts

Script	Hace
scripts/deal.mjs --brief "…" [--tone …] [--register …] [--dark] [--project]	Negocia tres aspectos; --pick <n> imprime la hoja elegida (y la conserva como el aspecto del proyecto con --project); --redeal <part> negocia una parte de nuevo; --check verifica la librería
scripts/lint.mjs <file>	Verificaciones estáticas de un archivo independiente; sale con 1 en caso de FALLO
scripts/snap.mjs <file o url> --out <dir> --sheet [--size WxH] [--times …] [--do "…"] [--calm]	Fotogramas sobre un reloj detenido con entrada real y una hoja de contactos, luego las verificaciones de la página estabilizada que su encabezado lista
scripts/export.mjs <carrete> [--out carrete.mp4] [--gif]	Un carrete a MP4 o GIF con desenfoque de movimiento de cuatro subfotogramas
scripts/photo.mjs "<lo que muestra>" [--out foto.jpg]	Una foto con licencia abierta (CC0, dominio público o CC BY) guardada donde se ejecuta, con la línea de crédito para la pieza; solo cuando la persona pide una foto real

Necesitan Node 22 o posterior y un navegador Chromium: snap.mjs encuentra Chrome, Chromium, Edge o Brave en su lugar habitual, y cualquier otro a través de CHROME. Cuando no se encuentra ninguno, lo dice en una línea: revisa el código contra references/review.md y nombra los fotogramas como no verificados. Export también necesita ffmpeg, y photo.mjs una red. Nada que instalar.

Sin shell

Cuando los scripts no se pueden ejecutar, como en un chat sin shell: lee library/directions.json, library/palettes.json y library/type.json, conserva las entradas cuyos tipos y tonos se ajusten a la solicitud, y toma la entrada en la posición dada por la longitud de la solicitud en caracteres, contada alrededor de cada lista, para que diferentes solicitudes caigan en diferentes aspectos. Construye a partir de los mismos archivos, revisa el código contra la rúbrica en references/review.md, y di en la entrega que los fotogramas quedaron sin verificar.

Créditos

• [Las habilidades de Emil Kowalski](https://github.com/emil

…

[truncado para traducción]