170 lines
4.8 KiB
Markdown
170 lines
4.8 KiB
Markdown
# Performance Guardrails
|
|
|
|
Rules for maintaining smooth animation and rendering performance. These prevent the most common causes of mobile frame drops and layout thrashing.
|
|
|
|
---
|
|
|
|
## GPU-Safe Animations
|
|
|
|
**Only animate these properties:**
|
|
- `transform` (translate, scale, rotate)
|
|
- `opacity`
|
|
|
|
**Never animate:**
|
|
- `top`, `left`, `right`, `bottom` — triggers layout reflow
|
|
- `width`, `height` — triggers layout + paint
|
|
- `margin`, `padding` — triggers layout
|
|
- `background-color` — triggers paint (acceptable for color transitions, but avoid on frequently animating elements)
|
|
|
|
**Why:** CSS `transform` and `opacity` are composited on the GPU and don't trigger layout or paint. All other properties cause the browser to recalculate layout on every frame — catastrophic on mobile.
|
|
|
|
```css
|
|
/* Good */
|
|
.card { transform: translateY(0); transition: transform 300ms; }
|
|
.card:hover { transform: translateY(-4px); }
|
|
|
|
/* Bad */
|
|
.card { top: 0; transition: top 300ms; }
|
|
.card:hover { top: -4px; }
|
|
```
|
|
|
|
---
|
|
|
|
## Blur Constraints
|
|
|
|
**Apply `backdrop-blur` only to:**
|
|
- Fixed-position elements (sticky navbars, overlays)
|
|
- Modals and dialogs
|
|
- Elements that don't scroll with content
|
|
|
|
**Never apply blur to:**
|
|
- Scrolling containers
|
|
- Large content areas
|
|
- Elements inside `overflow: auto/scroll` parents
|
|
|
|
**Why:** `backdrop-blur` triggers continuous GPU compositing on every scroll frame. On a scrolling container with 20+ cards, this causes severe frame drops on mid-range and low-end mobile.
|
|
|
|
```css
|
|
/* Good — fixed nav */
|
|
.navbar { position: fixed; backdrop-filter: blur(12px); }
|
|
|
|
/* Bad — scrolling card list */
|
|
.card-list .card { backdrop-filter: blur(8px); } /* kills mobile perf */
|
|
```
|
|
|
|
---
|
|
|
|
## Grain and Noise Overlays
|
|
|
|
**Correct implementation:**
|
|
```css
|
|
/* Fixed, pointer-events-none pseudo-element only */
|
|
body::after {
|
|
content: '';
|
|
position: fixed;
|
|
inset: 0;
|
|
z-index: 50;
|
|
pointer-events: none;
|
|
background-image: url("data:image/svg+xml,..."); /* or CSS noise */
|
|
opacity: 0.03;
|
|
}
|
|
```
|
|
|
|
**Never attach grain/noise to:**
|
|
- Scrolling containers
|
|
- Individual cards or sections
|
|
- Any element with `position: relative` inside a scroll context
|
|
|
|
---
|
|
|
|
## Z-Index Discipline
|
|
|
|
**Use systemic layers only. Establish a scale in your theme/variables:**
|
|
|
|
```css
|
|
:root {
|
|
--z-base: 0;
|
|
--z-card: 10;
|
|
--z-sticky: 100;
|
|
--z-overlay: 200;
|
|
--z-modal: 300;
|
|
--z-tooltip: 400;
|
|
--z-notification: 500;
|
|
}
|
|
```
|
|
|
|
**Never:**
|
|
- Use arbitrary values like `z-[9999]` or `z-50` unprompted
|
|
- Stack z-indexes without a documented reason
|
|
- Use z-index to fix stacking without understanding the stacking context
|
|
|
|
---
|
|
|
|
## Framer Motion Performance
|
|
|
|
**Use `useMotionValue` + `useTransform` for continuous animations:**
|
|
```jsx
|
|
// Good — runs outside React render cycle
|
|
const mouseX = useMotionValue(0);
|
|
const rotateY = useTransform(mouseX, [-300, 300], [-15, 15]);
|
|
|
|
// Bad — triggers re-render on every mouse move
|
|
const [rotation, setRotation] = useState(0);
|
|
```
|
|
|
|
**For perpetual/infinite animations:**
|
|
- Wrap in `React.memo` to prevent parent re-renders
|
|
- Extract as isolated leaf client components
|
|
- Use `<AnimatePresence>` for enter/exit — don't conditionally render without it
|
|
|
|
**For scroll-driven reveals:**
|
|
- Use `whileInView` or `IntersectionObserver`
|
|
- Never use `window.addEventListener('scroll')` — causes continuous reflows
|
|
|
|
**For staggered children:**
|
|
- Parent `variants` and children MUST be in the same Client Component tree
|
|
- If data is async, pass it as props into a centralized parent motion wrapper
|
|
|
|
---
|
|
|
|
## RSC Safety (Next.js)
|
|
|
|
- Global state (Context, providers) works **only** in Client Components
|
|
- Wrap providers in a `"use client"` component
|
|
- If a section uses Framer Motion or any interactive hook, extract it as an isolated leaf component with `'use client'` at the top
|
|
- Server Components render static layout only
|
|
|
|
---
|
|
|
|
## Mobile Override Rules
|
|
|
|
For any asymmetric or complex layout, apply aggressive mobile fallback below 768px:
|
|
|
|
```jsx
|
|
// All asymmetric layouts collapse to single column
|
|
<div className="grid grid-cols-1 md:grid-cols-[2fr_1fr_1fr] gap-6">
|
|
```
|
|
|
|
- Remove all rotations, negative margins, and overlaps below `md:`
|
|
- Replace `h-screen` with `min-h-[100dvh]` — prevents iOS Safari viewport jumping
|
|
- Never use `overflow: hidden` on `html`/`body` without testing on actual mobile
|
|
- Test horizontal scroll — asymmetric layouts often cause unintentional x-overflow on small screens
|
|
|
|
---
|
|
|
|
## `will-change` Guidance
|
|
|
|
Use sparingly. `will-change: transform` tells the browser to promote the element to its own GPU layer:
|
|
|
|
- Apply only to elements that are **actively animating**
|
|
- Remove after animation completes (or use `:hover` scoping)
|
|
- Never apply globally — creates excessive GPU memory pressure
|
|
|
|
```css
|
|
/* Good — scoped to hover state */
|
|
.card:hover { will-change: transform; }
|
|
|
|
/* Bad — always promoted */
|
|
.card { will-change: transform; }
|
|
```
|