# What Is the GPU-Only Rule for Animation Properties? A Complete Guide to the Skills Performance Standard

> Understand the GPU-only rule for animation properties. Learn how animating transform and opacity on the GPU boosts UI performance and avoids layout recalculations.

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: deep-dive
- Published: 2026-08-07

---

**Only `transform` and `opacity` may be animated in UI elements because they are composited on the GPU, avoiding costly layout, paint, and style recalculations.**

The **GPU-only rule for animation properties** is a strict performance standard enforced throughout the `emilkowalski/skills` knowledge-base. This rule mandates that all animations must be limited to CSS properties that can be handled entirely on the GPU's compositor thread. According to the source code in [[`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md)](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md) (lines 35-36) and [[`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md) (lines 112-113), animating any layout-related property triggers performance regressions that must be flagged during code review.

## Why the GPU-Only Rule Exists

Browser rendering pipelines have distinct phases: style calculation, layout, paint, and compositing. The GPU-only rule exists because **different properties trigger different pipeline costs**:

- **`transform`** and **`opacity`** — Skip layout and paint phases entirely. The GPU simply moves, scales, rotates, or fades existing layers.
- **`width`**, **`height`**, **`margin`**, **`padding`**, **`top`**, **`left`** — Force complete layout recalculation, then paint, then composite. Frame times spike significantly.
- **Framer Motion shorthands like `x`, `y`, `scale`** — Under load, these may still trigger layout thrashing if not properly optimized to `transform` equivalents.

The rule is codified as the **7th non-negotiable standard** in the review-animation skill. It appears in performance checklists across audit files as a hard requirement, not a suggestion.

## Which Properties Are GPU-Safe vs. Performance-Killing

### Permitted: GPU-Composited Properties

| Property | Use Case | Example |
|----------|----------|---------|
| `transform` | Movement, scaling, rotation | `translateX()`, `scale()`, `rotate()` |
| `opacity` | Fade effects | `0` to `1` transitions |
| `clip-path` | Reveals, masks | `inset()`, `circle()` via special exception |

The [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) file notes `clip-path` as a permissible fourth property in specific contexts, though `transform` and `opacity` remain the primary duo.

### Forbidden: Layout-Triggering Properties

- `width` and `height`
- `margin` and `padding`
- `top`, `left`, `right`, `bottom`
- `border-width`
- Inherits via `transition: all`

Using `transition: all` is explicitly flagged in [[`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md)](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md) because it inadvertently animates non-GPU properties.

## Correct Implementation: GPU-Only Animation Examples

### CSS Transition (Recommended)

```css
/* ✅ GPU-only: translateY for movement, opacity for fade */
.card {
  opacity: 0;
  transform: translateY(20px);
  transition: opacity 150ms ease-out, transform 150ms ease-out;
}

.card.visible {
  opacity: 1;
  transform: translateY(0);
}

```

This implementation stays on the compositor thread throughout the animation. No layout recalculation occurs.

### Web Animations API (WAAPI)

```javascript
// ✅ GPU-only keyframes guarantee compositor-only work
const panel = document.querySelector('.panel');

panel.animate(
  [
    { opacity: 0, transform: 'translateX(-10px)' },
    { opacity: 1, transform: 'translateX(0)' }
  ],
  {
    duration: 200,
    easing: 'cubic-bezier(0.23, 1, 0.32, 1)', // strong ease-out
    fill: 'forwards'
  }
);

```

WAAPI with restricted property sets provides programmatic control while maintaining the GPU-only rule.

## Common Violations to Avoid

```css
/* ❌ VIOLATION: width triggers layout + paint */
.drawer {
  width: 0;
  transition: width 300ms ease-out;
}

.drawer.open {
  width: 320px;
}

```

**Replace with transform-based approach:**

```css
/* ✅ FIXED: scaleX or translateX on GPU */
.drawer {
  transform: scaleX(0);
  transform-origin: left;
  transition: transform 300ms cubic-bezier(0.4, 0, 0.2, 1);
}

.drawer.open {
  transform: scaleX(1);
}

```

## Where the GPU-Only Rule Is Enforced

The `emilkowalski/skills` repository implements this rule across multiple files that form a complete performance governance system:

- **[`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md)** — Defines standard #7 as the GPU-only requirement; lists escalation triggers for violations.
- **[`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)** — Provides the theoretical foundation: "only animate `transform` and `opacity`" with performance benchmarks.
- **[`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md)** — Expands the vocabulary with `clip-path` exceptions and advanced easing patterns.
- **[`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md)** — Documents real-world violations like `transition: all` and their remediation paths.

## Summary

- **The GPU-only rule permits only `transform` and `opacity`** for animations in the Skills repository, with `clip-path` as a narrow exception.
- **Layout properties (`width`, `height`, `margin`, etc.) are strictly prohibited** because they force main-thread work and frame drops.
- **The rule is the 7th non-negotiable standard** in [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) and appears across audit and standards documents.
- **Replace dimension animations with `transform` equivalents**: use `scale` instead of `width`, `translate` instead of `top`/`left`.

## Frequently Asked Questions

### What happens if I animate width or height instead of using transform?

Animating `width` or `height` forces the browser to recalculate layout for the element and potentially its entire subtree, then repaint, then composite. This main-thread work causes **frame drops and jank**, especially on complex pages or low-end devices. The Skills repository explicitly flags this as a performance regression requiring remediation.

### Why does Framer Motion's x/y/scale shorthand matter for the GPU-only rule?

Framer Motion's `x`, `y`, and `scale` props are convenient abstractions, but **under load they can degrade to layout-triggering behavior** if not carefully optimized. The GPU-only rule in Skills treats these shorthands as suspect unless verified to compile to pure `transform` operations. Always verify the generated CSS or use explicit `transform` styles.

### Is clip-path really allowed as a third GPU-safe property?

Yes, `clip-path` is noted in [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) as a **permissible fourth property** for specific reveal and mask effects. However, it carries higher compositor cost than `transform` and `opacity`, so it should be used sparingly and never alongside layout animations.

### How do I audit my codebase for GPU-only rule violations?

Search for `transition` declarations containing properties beyond `transform` and `opacity`, or any `animate` calls with `width`, `height`, `margin`, `padding`, or positioning properties. The [`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md) file provides a checklist-based audit process specifically designed to catch these violations during code review.