SKILL.md

Premium Motion UI

Restraint is what reads as luxury. One or two signature animated moments per page, timed well, beat effect soup every time. Magic UI and Aceternity ship copy-paste components with explicit props; Motion (motion, imported from motion/react, formerly framer-motion) drives them.

Workflow

Pick the single moment per section. Decide what each viewport section's one signature effect is before installing anything. A hero with an aurora background plus text-generate plus a marquee plus a beam reads as a demo reel: choose the strongest.
Install via the shadcn registry so components land as owned source in components/:

bunx shadcn@latest add "https://magicui.design/r/marquee"
bunx shadcn@latest add "https://ui.aceternity.com/registry/spotlight.json"

Shared deps: motion, clsx, tailwind-merge, Tailwind.

Read the added file before wiring it. Props are explicit in the source. Never guess a prop.
Orchestrate entrances with variants and stagger, viewport-triggered, once:

import { motion, useReducedMotion } from "motion/react";
const container = { hidden: {}, show: { transition: { staggerChildren: 0.08 } } };
const item = { hidden: { opacity: 0, y: 16 }, show: { opacity: 1, y: 0 } };
<motion.ul variants={container} initial="hidden" whileInView="show" viewport={{ once: true, margin: "-80px" }}>

Gestures: whileHover, whileTap. Scroll linking: useScroll + useTransform for parallax. Shared element: matching layoutId. Exits: wrap in AnimatePresence with an exit variant.

Gate for reduced motion. Required, not optional:

const reduce = useReducedMotion();
<motion.div initial={reduce ? false : { opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} transition={{ duration: reduce ? 0 : 0.5 }} />

CSS effects get a scoped @media (prefers-reduced-motion: reduce) that neutralizes animation and transitions.

Component menu, by intent

Fewest components that deliver the moment:

Ambient backgrounds (one per section, max): Aurora Background, Spotlight, Background Beams, Retro Grid, Dot/Grid Pattern, Ripple
Hero text: Text Generate Effect, Animated Shiny Text, Hyper Text, Flip Words
Proof/logos: Marquee, Animated Beam (integration diagrams), Icon Cloud
Feature layout: Bento Grid, Magic Card, 3D Card Effect, Wobble Card
Numbers: Number Ticker, Animated Circular Progress Bar
Buttons: Shimmer Button, Interactive Hover Button, Moving Border
Scroll: Sticky Scroll Reveal, Hero Parallax, Container Scroll, Tracing Beam, Scroll Progress
Device mockups: iPhone, Android, Safari, Macbook Scroll, Terminal

Taste rules

Motion serves meaning: entrances draw the eye to hierarchy, scroll motion paces a narrative. Random floating blobs do neither.
Expressive easing over linear: [0.16, 1, 0.3, 1]. Durations 0.3-0.6s for UI, longer only for ambient.
Animate transform and opacity only. Never width, top, or box-shadow. will-change sparingly.
Lazy-mount heavy background canvases below the fold, never block first paint.

Verification

Open the page with DevTools performance recording while scrolling the full length. Expect steady 60fps with no long tasks from animation and no layout thrash entries. Then enable the OS reduced-motion setting and reload. Expect all non-essential motion gone, content fully readable. Either check fails: fix before shipping (move to transform/opacity, add the reduced-motion gate).

Good vs Bad

Bad: Hero with aurora background, sparkles text, a marquee, three shimmer buttons, and parallax on every card. Reads as a template demo, janks on mid-range phones.

Good: Hero with one spotlight background and a single text reveal; features in a static bento grid where only the flagship card gets a hover tilt; one number ticker in the proof section. Feels engineered, runs at 60fps.

Completion checklist

[ ] At most one signature animated element per viewport section
[ ] Reduced motion respected everywhere, verified with the OS setting on
[ ] Only transform/opacity animated, 60fps confirmed in a trace
[ ] Heavy backgrounds lazy-mounted below the fold
[ ] Component source read from components/, props real not guessed
[ ] Contrast survives overlays in both light and dark

Any box unchecked: not done. Fix or say so.

Footguns

Effect soup. Every additional simultaneous effect cheapens the page. Fix: one moment per section, cut the second-best.
Animating layout properties. width/top/box-shadow trigger layout and paint, killing frame rate on real devices. Fix: transform and opacity equivalents (scale, translate, pseudo-element shadows).
Guessed props. Registry components vary between sources and versions. Fix: read the installed file in components/ before use.
Entrance animations replaying on every scroll. Feels broken. Fix: viewport={{ once: true }} unless repetition is the point.

premium-motion-ui

SKILL.md