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

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) (lines 35-36) and [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 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) because it inadvertently animates non-GPU properties.

Correct Implementation: GPU-Only Animation Examples

CSS Transition (Recommended)

/* ✅ 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)

// ✅ 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

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

.drawer.open {
  width: 320px;
}

Replace with transform-based approach:

/* ✅ 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 — Defines standard #7 as the GPU-only requirement; lists escalation triggers for violations.
• skills/review-animations/STANDARDS.md — Provides the theoretical foundation: "only animate transform and opacity" with performance benchmarks.
• skills/animate/SKILL.md — Expands the vocabulary with clip-path exceptions and advanced easing patterns.
• 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 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 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 file provides a checklist-based audit process specifically designed to catch these violations during code review.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}