¿Qué hace Motion Lexicon?
Motion Lexicon es un sistema de diseño para el movimiento en productos. Conecta dos colecciones equivalentes: las Primitivas de Movimiento describen un comportamiento preciso; los Componentes convierten uno o más comportamientos en una interacción de producto completa y lista para copiar. La composición de página sitúa esas interacciones dentro de una superficie de producto coherente.
Diseña a partir del evento de producto del usuario. Produce código solo cuando este respalda un cambio de estado claro, un actor enfocado y una transición accesible.
Elige un modo
| Señal en la solicitud | Modo | Entregable |
|---|---|---|
| Una página completa, pantalla, página de inicio, dashboard o superficie de configuración | Construir Página | Plan de página, composición exacta del Registro, página funcional y evidencia de aceptación |
| Una sensación, término o pregunta "qué animación" | Recomendar | Candidatos clasificados y una recomendación |
| Un flujo de trabajo, transición o escena de varios pasos | Componer | Blueprint de Movimiento y plan de tiempos |
| Una solicitud de código de producción o adaptación a un framework | Implementar | HTML, CSS, JS portátiles o código del framework solicitado |
| Código existente, una grabación o un informe de jank | Revisar | Diagnóstico priorizado y correcciones concretas |
| Un nuevo patrón, ejemplo o adición propuesta a la librería | Contribuir | Registro candidato listo para revisión del mantenedor |
Aplica la prioridad de modo de manera determinista: una página completa o superficie de varias regiones usa Construir Página; una solicitud explícita de código o implementación de un framework para una interacción usa Implementar; una solicitud solo de un plan de diseño, plan de tiempos o Blueprint usa Componer. Implementar puede crear un Blueprint internamente y aún así entrega el formato ejecutable que el usuario solicitó. Una solicitud de Revisar puede devolver un Blueprint revisado cuando la interacción actual necesita un cambio mayor.
Comienza cada solicitud
- Conserva el idioma del usuario. Usa Español para solicitudes en español e Inglés para solicitudes en inglés.
- Identifica el trabajo del producto, la acción principal, el estado visible para el usuario antes y después de ella, el actor principal y la sensación prevista.
- Usa la tabla de modo × referencia a continuación. Carga solo los archivos seleccionados para la tarea actual.
- Carga interior-principles.md cuando la solicitud necesite profundidad material, fisicalidad o el perfil visual Interior.
- Declara las suposiciones brevemente cuando la solicitud deje abierto el contexto del producto. Haz una pregunta enfocada solo cuando una restricción faltante cambie el diseño.
- Mantén un actor visual principal y como máximo dos actores de apoyo en un tiempo. Dale a cada actor un tipo semántico: desencadenante, héroe, estado, registro o entorno. Dale a cada tiempo un propósito de producto: orientar, confirmar, preservar la continuidad, revelar o recuperar.
- Incluye un plan de movimiento reducido y comportamiento de teclado/enfoque en cada interacción compuesta, implementada o revisada.
- Para una solicitud de página, inspecciona el proyecto anfitrión antes de elegir una pila. Conserva su enrutamiento, sistema de componentes, tokens de diseño e idioma del contenido. Usa React y TypeScript para una página desde cero a menos que el usuario solicite otra pila.
Enrutamiento de modo × referencia
| Modo o tarea | Leer | Añadir solo cuando sea relevante |
|---|---|---|
| Construir Página | page-composition.md, page-system.md y components.md | motion-lexicon-page.css cuando el anfitrión no tenga un sistema visual establecido; una referencia de momento o primitiva para el cambio de estado principal de la página |
| Recomendar un componente publicado | components.md | Una familia de primitivas a continuación cuando el usuario pregunte cómo funciona el movimiento |
| Recomendar un comportamiento | motion-language.md | entradas, retroalimentación, transiciones o secuenciación |
| Componer un Momento de Producto | composition.md y contract.md | momento de retroalimentación, momento de elección, momento de cambio o momento de flujo de trabajo |
| Implementar | implementation-css.md | contract.md al consumir o producir un Blueprint; components.md para un componente publicado exacto |
| Revisar | review-rubric.md | La referencia de primitiva o momento que coincida con el comportamiento observado |
| Contribuir | contribution.md y candidate-template.md | contract.md para el Blueprint requerido y components.md para descartar un componente existente |
Lenguaje de movimiento
Usa el perfil informado por Interior en toda la habilidad:
- Modela un estado de producto real con un bisel, un panel elevado y un hueco empotrado cuando la profundidad material ayude a la orientación.
- Inicia el movimiento desde un evento: una pulsación, selección, cambio de ruta, actualización de estado o manipulación directa.
- Reserva espacio para los cambios de estado para que las etiquetas, botones y registros mantengan su geometría.
- Usa movimiento de llegada para nuevo contexto:
cubic-bezier(.23, 1, .32, 1)durante aproximadamente 200–280 ms. Usa movimiento de salida para contexto eliminado:cubic-bezier(.23, 1, .32, 1)durante aproximadamente 110–180 ms. - Usa transform y opacity para el trabajo en movimiento. Usa transiciones cortas de color o enfoque cuando la retroalimentación necesite una respuesta inmediata.
- Permite que una segunda acción del usuario interrumpa, revierta o estabilice la primera acción.
- En movimiento reducido, conserva el estado, la jerarquía, el enfoque y la retroalimentación a través de un estado estático o una transición de opacidad corta.
Lee las reglas detalladas en interior-principles.md.
Construir Página
Construye una superficie de producto completa y ejecutable en el proyecto del usuario. Lee page-composition.md, page-system.md y components.md antes de planificar la página.
- Inspecciona el repositorio de destino, el framework, las rutas, los tokens existentes y las dependencias instaladas. Reutiliza el sistema anfitrión donde sea coherente.
- Antes de editar cualquier archivo, muestra la tabla de inspección del anfitrión y el Plan de Página
compacto que se muestra a continuación. Incluye el trabajo y arquetipo de la página, cada región importante,
el ID exacto del componente publicado o
none, el límite de estado principal y las decisiones de diseño responsivo y tema. Cada valor de inspección del anfitrión cita la ruta del archivo inspeccionado. Una intención de implementación en prosa no satisface este punto de control. - Usa la fuente en
https://motion-lexicon.pages.dev/r/<id>.jsonpara un componente publicado. Lee susfiles,dependenciesy runtime antes de editar. Instala la fuente y dependencias entregadas; adapta solo sus props, etiquetas, datos, callbacks y ubicación en el anfitrión. No regeneres una aproximación del mismo componente. - Completa el punto de control de integración del Registro antes de seleccionar un ID: cada
fuente actual del Registro usa clases de utilidad Tailwind. Confirma que el anfitrión
ya compile Tailwind, o añade su configuración Tailwind compatible cuando cambiar el toolchain del anfitrión
esté dentro del alcance. Si no se puede añadir esa configuración, selecciona
nonepara la región y construye una UI semántica simple; nunca pegues en silencio una reimplementación CSS de un componente del Registro. Registra la URL JSON, el archivo de destino, la lista de dependencias y cualquier runtime requerido en el Plan de Página. - Audita el nodo interactivo renderizado después de la integración. El estándar de página es
al menos 44 por 44 px CSS incluso cuando la altura visual predeterminada de un componente del Registro
sea menor. Pasa una clase del anfitrión a través de una prop
classNamedocumentada y establecemin-widthymin-heighten ese nodo. Si la fuente no ofrece un hook de estilo seguro, elige un componente que lo haga o deja la región simple. - Dale a la página una superficie de trabajo dominante, un momento de movimiento principal y como máximo dos momentos de movimiento de apoyo. Mantén el contenido estático tranquilo.
- Usa el sistema de diseño del anfitrión. Para una superficie desde cero, copia y adapta motion-lexicon-page.css, luego aplica la jerarquía exacta y las reglas responsivas de page-system.md.
- Entrega toda la ruta o página, incluyendo contenido realista, estados de carga, vacío, éxito, error y recuperación que pertenezcan a su trabajo.
- Verifica los diseños de 320, 390, 768 y 1440 px; temas claro y oscuro; orden de teclado
y enfoque; movimiento reducido; objetivos interactivos de 44 px; desbordamiento; y errores de
consola o hidratación. El éxito de construcción solo no satisface la aceptación de la página. Inicia la aplicación local
o la vista previa de producción y usa la automatización del navegador disponible para ejercitar la acción principal e inspeccionar la geometría
renderizada en cada viewport requerido. La falta de un script de prueba de navegador en el proyecto no es
un bloqueo: usa una herramienta de navegador disponible contra la vista previa local.
En cada viewport, enumera cada
button, enlace, input, select, textarea y nodo interactivo personalizado visible; registra el ancho y alto mínimo renderizado más una lista deoffenderspara nodos por debajo de 44 px en cualquier dimensión. Arregla cada infractor y vuelve a ejecutar las cuatro auditorías de viewport antes de informar la aceptación. Informa los comandos, interacciones, mediciones y resultados observables.
Mantén el Plan de Página conciso:
## Inspección del anfitrión
| Aspecto | Evidencia observada del anfitrión |
| --- | --- |
| Framework | nombre/versión — `package.json` |
| Ruta | ruta actual y archivo de destino — `src/router.tsx` |
| Sistema de componentes | componentes reutilizados o ninguno — `src/components/...` |
| Tokens / tema | mecanismo de tokens y tema — `src/styles.css` |
| Tailwind | instalado/compilado o ausente — `package.json`, `vite.config.ts` |
| Dependencias | paquetes y versiones reutilizados — `package.json` |
## Plan de Página
Trabajo: …
Arquetipo: …
Acción principal: …
Estado principal: inactivo → pendiente → éxito/error
| Región | Propósito del producto | Componente publicado | Estado o movimiento |
| --- | --- | --- | --- |
| … | … | `component-id` o `none` | … |
Registro:
- `component-id` — https://motion-lexicon.pages.dev/r/component-id.json —
`target/file.tsx` — dependencias: `package` / ninguna
Responsivo: 320/390 …; 768 …; 1440 …
Tema: claro …; oscuro …; movimiento reducido …
No comiences la implementación hasta que cada línea de este plan sea concreta.
La entrega final debe permanecer auditable de forma independiente después de que los mensajes intermedios se colapsen. Repite la tabla completa de Inspección del anfitrión y el Plan de Página, incluyendo la tabla de regiones y las líneas de Registro, luego añade una tabla de Aceptación con una fila observada para cada elemento a continuación:
| Verificación | Evidencia observada |
| --- | --- |
| Construcción | comando y resultado de salida |
| 320 | ancho de viewport/documento, ancho/alto mínimo del objetivo, número de infractores |
| 390 | ancho de viewport/documento, ancho/alto mínimo del objetivo, número de infractores |
| 768 | ancho de viewport/documento, ancho/alto mínimo del objetivo, número de infractores |
| 1440 | ancho de viewport/documento, ancho/alto mínimo del objetivo, número de infractores |
| Claro / oscuro | cómo se activó e inspeccionó cada tema |
| Teclado / enfoque | ruta de tecla exacta, entrada de enfoque y retorno de enfoque |
| Movimiento reducido | preferencia emulada y resultado estático o de transición de opacidad observado |
| Objetivos | ancho y alto mínimo medidos de los nodos interactivos visibles |
| Estado principal | estados de pendiente, éxito, error/reintento e interrupción ejercitados |
| Runtime | recuento de errores de consola, página, solicitud e hidratación |
Nombra los IDs de componentes instalados y los archivos modificados. Usa Incompleto para una
fila no observada y declara la capacidad faltante. No describas una verificación no observada como
compatible o superada.
Cuando el usuario solicite el aspecto de Motion Lexicon, conserva el perfil visual y la calidad de interacción mientras adaptas el contenido y la arquitectura de información al producto real. Evita llenar una página con demos de la librería.
Recomendar
Devuelve una decisión compacta que el usuario pueda aplicar de inmediato.
- Asigna la solicitud a hasta tres candidatos publicados de components.md, o de la referencia de primitiva relevante seleccionada anteriormente. Comienza cada celda de candidato con su ID exacto de componente o primitiva publicado entre comillas invertidas, seguido de una etiqueta humana cuando sea útil. Una etiqueta descriptiva sola está incompleta. Nunca presentes un ID desconocido o inventado como publicado.
- Explica la diferencia visual en términos de producto: continuidad espacial, peso, ritmo, atención o confianza en el estado.
- Elige un candidato, repite su ID publicado exacto en la línea de Elección y declara el tiempo predeterminado, easing, disparador y tratamiento de movimiento reducido.
- Ofrece un Blueprint de Movimiento cuando la solicitud describa varios estados.
Usa este formato:
## Sugerencia / Recommendation
| Candidato / Candidate | Ajuste / Fit | Diferencia / Difference |
| --- | --- | --- |
| `published-id` / … | … | … |
**Elección / Pick:** `published-id` / …
- Disparador / Trigger: …
- Tiempo / Timing: …
- Accesibilidad / Accessibility: …
Componer
Crea un Blueprint de Movimiento antes de expandirte en detalles de implementación. Usa assets/motion-blueprint.schema.json como contrato. Cada respuesta de Componer incluye un objeto JSON válido según el esquema entre comillas invertidas; no sustituyas una tabla en prosa o un diagrama de texto por el Blueprint. Mantén los valores de cadena compactos en el chat, luego escribe el mismo JSON en un archivo cuando el usuario solicite un artefacto reutilizable.
Cada valor de beats[].primitive y cada valor de provenance.foundations[] debe ser un
ID de primitiva publicado exacto copiado de las referencias seleccionadas. Las etiquetas humanas
y los pseudo IDs no publicados no cumplen con el contrato del Blueprint.
Antes de responder, escribe el JSON final en un archivo temporal y ejecuta:
node "$CODEX_HOME/skills/motion-lexicon/scripts/validate-motion-blueprint.mjs" /tmp/blueprint.json
Arregla cada fallo de validación y vuelve a ejecutar hasta que el comando salga con 0. Copia
el JSON entre comillas invertidas byte a byte en tu respuesta.
Implementar
- Carga implementation-css.md. Carga el contract.md cuando la solicitud consuma o produzca uno o más Blueprints.
- Para un componente publicado de la tabla de enrutamiento, carga la fuente desde
https://motion-lexicon.pages.dev/r/<id>.json. Instala las dependencias declaradas, copia los archivos de la fuente y adapta solo las props, la ranura de contenido, las etiquetas y los callbacks. No reescribas la lógica de animación del componente; cualquier anulación debe pasar por props comoclassName,durationoeasing. - Cuando la solicitud describa una nueva interacción, primero escribe un Blueprint que cumpla con el esquema, luego escribe código usando la lógica de Blueprint como guía.
- Incluye el plan de movimiento reducido, el orden de teclado y el comportamiento de enfoque en cada interacción implementada.
- Entrega el código como bloques de código independientes. Para un archivo, escribe el nombre de la ruta relativa en una línea de información del bloque de código y luego todo el contenido del archivo dentro de las comillas invertidas. Una solicitud de "página" o "aplicación" completa es una solicitud de Construir Página, no de Implementar.
Revisar
Carga review-rubric.md. Cualquier otra referencia agregada debe coincidir con la interacción que el usuario describe, no la presunta solución.
- Declara la puntuación de revisión y la calificación (Pasa / Advierte / Falla).
- Enumera los hallazgos en orden de prioridad. Empareja cada hallazgo con un estándar de la rúbrica.
- Para cada hallazgo fallido, da el arreglo exacto: una línea de CSS, un cambio de prop, una alternativa de componente publicado o un nuevo Blueprint.
- Cuando la interacción necesite un cambio estructural mayor, devuelve un Blueprint revisado junto con el informe.
Contribuir
Carga contribution.md, candidate-template.md, contract.md y components.md para descartar un componente existente.
- Rellena la plantilla candidata.
- Valida contra el esquema del Blueprint. Ejecuta el script de validación del esquema.
- Prepara las integraciones de demostración: como mínimo, un HTML independiente con CSS y JS en línea.
- Incluye un snippet de código para cada framework solicitado.
Registro de componentes
Cada componente listado en components.md
tiene una fuente publicada en https://motion-lexicon.pages.dev/r/<id>.json.
Obtén el JSON de la fuente del componente, instala las dependencias enumeradas y escribe los
archivos del campo files. No regeneres una versión independiente del mismo componente;
no pierdas la fidelidad de la fuente. Cuando la integración necesite un ajuste, usa solo las
props documentadas.
Primitivas de movimiento
| Familia | Propósito | Referencia |
|---|---|---|
| Entradas | Un nuevo elemento aparece, se desliza o se revela en la página | entrances.md |
| Retroalimentación | Un elemento responde a una interacción del usuario | feedback.md |
| Transiciones | Un elemento cambia de estado o de lugar | transitions.md |
| Secuenciación | Varios elementos se mueven en una coreografía | sequencing.md |
Comandos de validación
# Validar un Blueprint contra el esquema JSON
node "$CODEX_HOME/skills/motion-lexicon/scripts/validate-motion-blueprint.mjs" /tmp/blueprint.json
# Obtener la fuente de un componente publicado
curl https://motion-lexicon.pages.dev/r/<id>.json
Gestión de tokens y temas
El CSS de Motion Lexicon usa tokens para color, espaciado y easing. El conjunto de tokens se especifica en page-system.md. Para una integración de página, prefiere los tokens y variables CSS del anfitrión. En una superficie desde cero, copia la hoja de tokens de motion-lexicon-page.css.
Los temas claro y oscuro se manejan mediante una clase .dark en el elemento html o
body. Cuando el anfitrión use prefers-color-scheme, envuelve las reglas oscuras en
una consulta de medios. Para movimiento reducido, usa la consulta de medios
@media (prefers-reduced-motion: reduce) o una clase .reduced-motion.
Página de ejemplo
Una vez completada, la página debe:
- Superar las cuatro verificaciones de viewport.
- Pasar la verificación de objetivo interactivo de 44 px.
- No tener errores de consola o hidratación.
- Soportar los estados claro, oscuro y movimiento reducido.
- Tener orden de teclado y gestión de enfoque.
Convenciones de código
- Usa
transformyopacitypara animaciones de movimiento. - El easing predeterminado es
cubic-bezier(.23, 1, .32, 1). - La duración predeterminada es de 200-280 ms para llegadas y 110-180 ms para salidas.
- Para movimiento reducido, usa transiciones de opacidad cortas o estados estáticos.