# Fixing Motion Performance

> Audita y corrige problemas de rendimiento en animaciones: layout thrashing, propiedades del compositor, movimiento ligado al scroll y desenfoques. Úsalo si las animaciones van a tirones o revisas el rendimiento de animaciones CSS/JS.

Fuente: https://skillsagentes.com/skills/ibelick/ui-skills/fixing-motion-performance
Markdown: https://skillsagentes.com/skills/ibelick/ui-skills/fixing-motion-performance.md

Repositorio: https://github.com/ibelick/ui-skills
Autor: ibelick
Licencia: MIT
Actualizado: hace 6 meses
Coste de contexto: 56 tok instalada, 1.4k tok al activarse, 1.4k tok con todos los archivos del bundle
Bundle: 1 archivo, 5 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ibelick/ui-skills --skill fixing-motion-performance --agent claude-code
# Cursor
npx -y skills add ibelick/ui-skills --skill fixing-motion-performance --agent cursor
# Codex
npx -y skills add ibelick/ui-skills --skill fixing-motion-performance --agent codex
# Gemini CLI
npx -y skills add ibelick/ui-skills --skill fixing-motion-performance --agent gemini
# Windsurf
npx -y skills add ibelick/ui-skills --skill fixing-motion-performance --agent windsurf
# Cline
npx -y skills add ibelick/ui-skills --skill fixing-motion-performance --agent cline
```

## Qué hace

- Audita y corrige el rendimiento de animaciones CSS/JS: layout thrashing, propiedades del compositor, movimiento ligado a scroll y desenfoques.
- Prioriza transform y opacity para el movimiento y evita animar layout o pintura en superficies grandes.
- Mide el DOM una sola vez y aplica patrones como FLIP para evitar lecturas y escrituras encadenadas.
- Usa Scroll Timelines, view() e IntersectionObserver para el movimiento ligado a scroll.
- Mantiene la librería de animación existente; solo migra si se pide explícitamente.

## Cuándo usarla

- Al añadir o cambiar animaciones de UI con CSS, WAAPI, Motion, rAF o GSAP.
- Al refactorizar interacciones o transiciones con tirones.
- Al implementar movimiento ligado al scroll o reveal-on-scroll.
- Al revisar componentes que usan will-change, transform o mediciones del DOM.

## Qué la activa

- "Esta animación va a tirones, ¿cómo la arreglo?"
- "Revisa este archivo y dime qué violaciones de rendimiento de animación tiene."
- "Aplica las reglas de rendimiento de animación a esta conversación."
- "Ayúdame a hacer un reveal-on-scroll sin causar tirones."
- "¿Por qué mi transición de ancho da tirones y cómo la paso a transform?"

## Archivos

- SKILL.md — 5 KB

## SKILL.md

Reproducido tal cual desde ibelick/ui-skills bajo MIT. Esta sección es el documento original y está en inglés.

# fixing-motion-performance

Fix animation performance issues.

## how to use

- `/fixing-motion-performance`
  Apply these constraints to any UI animation work in this conversation.

- `/fixing-motion-performance <file>`
  Review the file against all rules below and report:
  - violations (quote the exact line or snippet)
  - why it matters (one short sentence)
  - a concrete fix (code-level suggestion)

Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack.

## when to apply

Reference these guidelines when:
- adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP)
- refactoring janky interactions or transitions
- implementing scroll-linked motion or reveal-on-scroll
- animating layout, filters, masks, gradients, or CSS variables
- reviewing components that use will-change, transforms, or measurement

## rendering steps glossary

- composite: transform, opacity
- paint: color, borders, gradients, masks, images, filters
- layout: size, position, flow, grid, flex

## rule categories by priority

| priority | category | impact |
|----------|----------|--------|
| 1 | never patterns | critical |
| 2 | choose the mechanism | critical |
| 3 | measurement | high |
| 4 | scroll | high |
| 5 | paint | medium-high |
| 6 | layers | medium |
| 7 | blur and filters | medium |
| 8 | view transitions | low |
| 9 | tool boundaries | critical |

## quick reference

### 1. never patterns (critical)

- do not interleave layout reads and writes in the same frame
- do not animate layout continuously on large or meaningful surfaces
- do not drive animation from scrollTop, scrollY, or scroll events
- no requestAnimationFrame loops without a stop condition
- do not mix multiple animation systems that each measure or mutate layout

### 2. choose the mechanism (critical)

- default to transform and opacity for motion
- use JS-driven animation only when interaction requires it
- paint or layout animation is acceptable only on small, isolated surfaces
- one-shot effects are acceptable more often than continuous motion
- prefer downgrading technique over removing motion entirely

### 3. measurement (high)

- measure once, then animate via transform or opacity
- batch all DOM reads before writes
- do not read layout repeatedly during an animation
- prefer FLIP-style transitions for layout-like effects
- prefer approaches that batch measurement and writes

### 4. scroll (high)

- prefer Scroll or View Timelines for scroll-linked motion when available
- use IntersectionObserver for visibility and pausing
- do not poll scroll position for animation
- pause or stop animations when off-screen
- scroll-linked motion must not trigger continuous layout or paint on large surfaces

### 5. paint (medium-high)

- paint-triggering animation is allowed only on small, isolated elements
- do not animate paint-heavy properties on large containers
- do not animate CSS variables for transform, opacity, or position
- do not animate inherited CSS variables
- scope animated CSS variables locally and avoid inheritance

### 6. layers (medium)

- compositor motion requires layer promotion, never assume it
- use will-change temporarily and surgically
- avoid many or large promoted layers
- validate layer behavior with tooling when performance matters

### 7. blur and filters (medium)

- keep blur animation small (<=8px)
- use blur only for short, one-time effects
- never animate blur continuously
- never animate blur on large surfaces
- prefer opacity and translate before blur

### 8. view transitions (low)

- use view transitions only for navigation-level changes
- avoid view transitions for interaction-heavy UI
- avoid view transitions when interruption or cancellation is required
- treat size changes as potentially layout-triggering

### 9. tool boundaries (critical)

- do not migrate or rewrite animation libraries unless explicitly requested
- apply these rules within the existing animation system
- never partially migrate APIs or mix styles within the same component

## common fixes

```css
/* layout thrashing: animate transform instead of width */
/* before */ .panel { transition: width 0.3s; }
/* after */  .panel { transition: transform 0.3s; }

/* scroll-linked: use scroll-timeline instead of JS */
/* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500)
/* after */  .reveal { animation: fade-in linear; animation-timeline: view(); }
```

```js
// measurement: batch reads before writes (FLIP)
// before — layout thrash
el.style.left = el.getBoundingClientRect().left + 10 + 'px';
// after — measure once, animate via transform
const first = el.getBoundingClientRect();
el.classList.add('moved');
const last = el.getBoundingClientRect();
el.style.transform = `translateX(${first.left - last.left}px)`;
requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; });
```

## review guidance

- enforce critical rules first (never patterns, tool boundaries)
- choose the least expensive rendering work that matches the intent
- for any non-default choice, state the constraint that justifies it (surface size, duration, or interaction requirement)
- when reviewing, prefer actionable notes and concrete alternatives over theory

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [ibelick](https://skillsagentes.com/creators/ibelick.md) — 7 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Create Design Md](https://skillsagentes.com/skills/ibelick/ui-skills/create-design-md.md): Crea o actualiza un DESIGN.md desde un repositorio o web pública: documenta el lenguaje de diseño, reconstruye el sistema visual y extrae tokens y pautas de evidencia. No modifica código fuente ni convierte patrones accidentales en diseño.
- [Improve Ui](https://skillsagentes.com/skills/ibelick/ui-skills/improve-ui.md): Audita una interfaz contra su diseño, detecta problemas de UI verificados y escribe planes autocontenidos sin tocar código. Útil para revisar, refinar o limpiar sin cambiar la identidad, ver deriva del design system o preparar un handoff.
- [Ui Skills Root](https://skillsagentes.com/skills/ibelick/ui-skills/ui-skills-root.md): Úsalo antes de trabajo relacionado con UI para seleccionar el contexto de UI Skills más pequeño y útil a través de la CLI ui-skills.
- [Baseline Ui](https://skillsagentes.com/skills/ibelick/ui-skills/baseline-ui.md): Pule rápido el código de interfaz corrigiendo espaciado, jerarquía, tipografía y pequeños problemas de layout. Úsalo cuando la interfaz necesite una limpieza o un pulido rápido.
- [Fixing Accessibility](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-accessibility.md): Audita y corrige problemas de accesibilidad HTML: ARIA, navegación por teclado, gestión del foco, contraste de color y errores de formulario. Úsalo al añadir controles interactivos, formularios, diálogos o revisar WCAG.

## Skills relacionadas

- [Create Design Md](https://skillsagentes.com/skills/ibelick/ui-skills/create-design-md.md): Crea o actualiza un DESIGN.md desde un repositorio o web pública: documenta el lenguaje de diseño, reconstruye el sistema visual y extrae tokens y pautas de evidencia. No modifica código fuente ni convierte patrones accidentales en diseño.
- [Fixing Accessibility](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-accessibility.md): Audita y corrige problemas de accesibilidad HTML: ARIA, navegación por teclado, gestión del foco, contraste de color y errores de formulario. Úsalo al añadir controles interactivos, formularios, diálogos o revisar WCAG.
- [Baseline Ui](https://skillsagentes.com/skills/ibelick/ui-skills/baseline-ui.md): Pule rápido el código de interfaz corrigiendo espaciado, jerarquía, tipografía y pequeños problemas de layout. Úsalo cuando la interfaz necesite una limpieza o un pulido rápido.
- [Fixing Metadata](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-metadata.md): Audita y corrige metadatos HTML: títulos, descripciones, canónicas, Open Graph, Twitter cards, favicons, JSON-LD y robots. Úsalo al añadir SEO, arreglar vistas previas, revisar Open Graph, configurar canónicas o publicar páginas nuevas.
- [Improve Ui](https://skillsagentes.com/skills/ibelick/ui-skills/improve-ui.md): Audita una interfaz contra su diseño, detecta problemas de UI verificados y escribe planes autocontenidos sin tocar código. Útil para revisar, refinar o limpiar sin cambiar la identidad, ver deriva del design system o preparar un handoff.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)