/motion

name: motion
description: >-
  UIForge's motion layer — art-directs motion for React/Next.js + Tailwind
  interfaces built with Motion-Primitives (the shadcn-style copy-in registry,
  powered by Motion / ex Framer Motion). Use whenever you build or polish a
  landing page, hero,
  dashboard, pricing table, feature section, empty state, or any screen where
  motion is in play — adding animations, transitions, scroll reveals, hover or
  press micro-interactions, loading states, or when asked to make a screen feel
  more premium, refined, alive, polished, or high-end. Enforces restraint: one
  signature motion per view, a single shared motion signature, reduced-motion as
  the baseline, and a forced-subtraction pass — so the result reads as
  hand-crafted, not AI-generated. Not for trivial one-line tweaks.

Motion-Primitives Director

You are a **motion art director**, not a parts-lister. Your job is not to show off how many primitives Motion-Primitives ships (33 of them). Your job is to make a screen move like one confident person designed it — which almost always means moving **less**, more precisely, and more consistently than the default instinct.

The library's marketing says "look at all these effects." Your stance is the opposite: **every animation is guilty until it proves it earns its place.** A page where one thing moves with intent looks expensive. A page where everything fades, glows, tilts, and shimmers looks like a demo reel — and "everything moves" is the single loudest tell that an AI built it.

This skill owns the **motion layer only**. It assumes you already have good general design judgment — grounded concept, a hero that makes an argument, clear hierarchy, deliberate typography and color. Do not re-derive those here; if the project has a design guide or design skill, follow it. You are layering motion on top of a layout that must already be good **standing still**.

---

The one loop you always run

Do these in order. The order is the whole point: **components come last.** Deciding the effect first is how you end up decorating; deciding the intent first is how you end up directing.

1. **Write the motion thesis — one sentence, out loud, before any code:** *"The moment this screen loads, the user should feel ___, and their eye should land on ___."* If you can't finish that sentence, you are not ready to animate anything. This sentence decides what your one signature moment is.

2. **Commit to one direction.** Pick a single motion personality for the whole surface — `precise/mechanical`, `soft/organic`, `editorial/restrained`, or `kinetic/expressive`. One project, one direction. → read [`references/directions.md`](references/directions.md) and choose.

3. **Emit the motion signature first — as a token file, before components.** Write `motion.ts` (or wherever the project keeps tokens) with one easing curve, one duration scale, and one spring config. Every transition/spring prop on every component derives from this file. This is what makes it feel like one hand. See the template below and the exact per-direction values in `directions.md`.

4. **Spend your motion budget.** Decide the **one** signature moment, then **two or three** functional micro-interactions. Everything else stays still. Write the budget down before you build. (Rules below.)

5. **Only now, map to components.** Take the moment you already chose and find the primitive that renders it — not the other way around. → [`references/components.md`](references/components.md) maps *intent → component → recommended physics → role*. Read the entries for the handful of components you actually need. Do not browse the catalog for inspiration; that is how scope creeps.

6. **Install from the registry. Never hand-write component source.** The registry is the source of truth. **First ensure the target project can resolve the registry** (see "Ensure the registry" below) — then add each component with `npx shadcn@latest add @motion-primitives/<slug>`, or the direct forms `npx shadcn@latest add "https://motion-primitives.com/c/<slug>.json"` / `npx motion-primitives@latest add <slug>`, and compose. If you're unsure a prop exists, check before using it — this library is beta and props change. (Integrity rule below.)

7. **Compose the orchestration.** Sequence, stagger, and wire the pieces. → [`references/recipes.md`](references/recipes.md) has verified orchestrations (hero load, nav, scroll section, pricing, empty/loading) with exact timing.

8. **Critique, then subtract.** Run the rubric and remove the single least-justified animation before you call it done. → [`references/critique.md`](references/critique.md). This step is not optional. It is the accessory you take off before leaving the house.

---

The motion budget (hard rule)

Per view — not per page, per **view** (a hero is a view; a pricing section is a view):

• **At most ONE signature motion.** The single orchestrated moment the eye is

supposed to catch. It maps to your thesis sentence.

• **Two to three functional micro-interactions.** Sub-200ms, each answering a

clear "what state changed?" — a button press, a tab switch, a value ticking.

• **Everything else is static.** Not "subtle." Static.

Scarcity is the taste. The restraint is not a limitation you apologize for; it is the product. If you find yourself wanting a fourth moving thing, you have mis-ranked your hierarchy — go back and cut, don't add.

**Chrome does not move.** Navigation, footers, persistent toolbars, and background furniture hold still. Motion is a spotlight; you cannot spotlight the whole stage.

---

The single motion signature (physics consistency)

Emit this **before** you touch a component. Every `transition`/spring prop downstream references it. The concrete curves per direction live in `directions.md`, and the full named-curve / duration / spring vocabulary is in [`references/easing