name: magicui-optimizer description: Audit and optimize Magic UI (copy-paste component library, magicui.design) usage in a codebase — heavy components (globe canvas/WebGL, particles, meteors) mounted above the fold, static motion/framer-motion imports inflating route bundles, canvas components that never pause offscreen, marquees and infinite animations without reduced-motion handling, unused copied components, and ownership/update discipline for pasted code. Report with evidence and a fix plan the user approves before edits. Use when the user mentions Magic UI, magicui.design components (marquee, particles, globe, border-beam, animated-beam, meteors, shimmer text...), or is pasting magicui components into shadcn/Tailwind apps -- even if they don't say the word "optimize".

Magic UI Optimizer

Audit how a site uses Magic UI components and report what is slow or wasteful. Magic UI ships copy-paste source (shadcn-style, built on motion/framer-motion + Tailwind), so nothing is tree-shaken by npm — performance depends on which components got pasted where. Heavy canvas/WebGL pieces in hero sections, motion statically imported into route files, canvases that never stop rendering when scrolled away, and a drawer full of unused copies are the usual finds. Report first, plan approved, then edit.

Workflow

1. Scope (quick)

• Project root. Detect Magic UI usage: a components/magicui (or magicui) directory, or imports via @/components/magicui. There's no npm package — the pasted source files themselves are the "app".
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — inventories the copies, flags heavy ones (globe/particles/meteors...), checks where they're imported (route/hero files vs leaf sections), checks canvas RAF loops for offscreen pause, unused copies, motion import placement, and reduced-motion coverage.

2. Audit

The script gives the lead list; you confirm by reading the biggest copies and their usage sites. Load references as needed:

Runtime spot-checks the script can't do:

• Which components are above the fold on the important route (home/landing): everything there loads/animates before content is seen.
• Do canvases keep running when scrolled away / when the tab is hidden? Record a Performance trace: idle page should be near-zero work; a busy RAF loop with nothing visible is a hit.
• Reduced motion: the motion library can honor it automatically (link to components-catalog.md). Verify with browser emulation what of the pasted effects actually relaxes.

Mark findings Confirmed or Suspected.

3. Report

Fill in assets/report-template.md, save as MAGICUI_REPORT.md in the project root. Group: hero/route bundle, runtime cost (canvas loops), a11y (reduced motion), hygiene (unused copies).

4. Plan — stop for approval

1. Quick wins — delete unused copies, useInView with once: true (or amount limits) on below-fold pieces, cap marquee/dot loops with reduced-motion styles, move motion imports into dynamic/loading sections.
2. Structural — lazy-load heavy components (globe, particles) with dynamic import + IntersectionObserver mount gating; pause canvases when hidden; offload continuous animations to CSS where possible.
3. Optional / design calls — reduce the number of animated components on one route; replace canvas-only effects with cheaper CSS equivalents; replace globe on mobile with a cheaper variant. Each item: files touched, expected effect, verification, rollback. Let the user drop or reorder.

5. Fix

Only approved items. When editing pasted components, keep on their component structure (they may need to be re-pasteable later); add comments at local deviations. After each group: build/typecheck, exercise animations on the affected route, and check reduced-motion emulation.

6. Verify and wrap up

• Bundle/first-load JS on the affected routes before/after (route build output or the nextjs skill's tooling if the site is Next.js).
• Performance traces: idle page steady-state, scrolling away should drop wiggle; tab hidden should pause RAF loops.
• Reduced-motion emulation walkthrough.
• Report what shrank/paused; list deltas, leftovers, and a suggested next step.

Principles

• You own pasted code. Magic UI copies become part of your codebase; the npm layer can't fix them. Maintain them like any other component.
• Above-the-fold pays for everything. A hero with a globe + particles + shimmer is all pre-first-paint needs; below-fold animation is cheap, above-fold is not.
• Canvases that canvas should sleep. Any requestAnimationFrame loop must stop when offscreen or tab-hidden; a cooling cost you pay for nothing visible is waste, not polish.
• One motion import, placed carefully. Don't statically import motion/framer-motion into route files; the components that need it should import it from their own (dynamically/lazily loaded) files below the fold.
• Reduced motion isn't optional. The motion library can honor it automatically; any continuous CSS/DOM animation pasted in by hand must be gated by a prefers-reduced-motion check.
• Measurement over vibes. Before recommending a swap or a deletion, measure route bundle/trace impact; state it in the report.