Ss Motion

Motion Seed Applier

Registry-first artifact boundary

When .styleseed/project.json and .styleseed/artifacts/index.json exist, resolve the requested artifact ID first, then read only .styleseed/bundles/<artifact-id>.md and .styleseed/manifests/<artifact-id>.json. Never fall back to the global legacy bundle for a registry project. Legacy projects may use .styleseed/effective-rules.md only when no registry exists.

When NOT to use

• For general framer-motion docs or learning → use the framer-motion site
• For non-React motion (CSS-only transitions, GSAP) — this skill targets motion.X JSX only
• For full scroll-linked timelines or parallax — out of scope for this skill (it does per-component seeds/moves). Note these ARE allowed on a marketing/landing/brand page (DESIGN-LANGUAGE §43 Cinematic tier); just build them with a scroll library, not this skill. On app/data surfaces they stay banned.
• For tweaking the existing FadeIn/FadeUp/Stagger wrappers — edit engine/components/ui/motion.tsx directly

Vibe → Seed mapping

Translate the user's prompt to one of the five seeds before applying. Use this lookup table from engine/motion/index.ts:

If the user says only a brand name, use that brand's default seed from BRAND_DEFAULT_SEED. If the user is explicit about a seed name (spring, silk, etc.), respect it verbatim.

Recommend mode — use-case → motion (when the user describes the moment, not the vibe)

If the user describes what the thing is ("a like button", "a modal", "the loading state", "items in a feed") rather than a feeling, recommend from the use-case map (MOTION_BY_USECASE in engine/motion/library.ts, exported from @engine/motion):

Two anti-rules override the table (state them if you deviate):

1. One seed per product. If the project already uses a seed, match it — don't introduce a second personality.
2. Never delay the payload. Don't animate a balance, price, or search result into view; motion is for affordance, not content.

Named motion keywords (distinctive moves)

Seeds set a personality (how a fade/scale feels). The motion library in engine/motion/library.ts adds distinctive moves — a flip, a curtain wipe, a morph — each behind a unique keyword. Prefer a keyword when the user wants a specific, recognizable motion rather than a generic feel.

engine/motion/library.ts (exported as MOTION_LIBRARY / MOTION_BY_KEY from @engine/motion) is the single source of truth — every keyword carries its own runnable snippet. Pull the snippet from there; never hand-write the params.

Applying a keyword:

1. Read the exact recipe from engine/motion/library.ts — find the entry whose key matches, copy its snippet verbatim (it is calibrated and runnable).
2. Adapt only the element/content to the user's JSX; keep the transition values.
3. If the keyword is stateful (toggles, ripple), wire the useState shown in the snippet. If it's a one-shot reveal, a key bump replays it.
4. Tell the user the keyword you applied so they can reuse it elsewhere for consistency, and point them at /motion to preview/Copy others.

If the user describes a move but no exact keyword fits, fall back to a seed + context. If they say a keyword that doesn't exist, suggest the closest real one from the table — never invent a keyword.

Context detection

Infer one of the five contexts from the prompt:

• "on hover" / "when hovered" → hover
• "on press" / "on tap" / "on click" → press
• "when it appears" / "on mount" / "entering" → entrance
• "when it leaves" / "on close" / "exiting" → exit (requires <AnimatePresence>)
• "when layout changes" / "FLIP" / "rearranging" → layout

If ambiguous, default to entrance. If multiple contexts are reasonable (e.g., a button needs both hover and press), apply both.

Application steps

Apply seed: $0 · Context: $1 · Target: $ARGUMENTS

1. Read the target file at the path given (or, if no path was given, ask the user which file). Locate the JSX element the user is talking about — usually a <button>, <div>, <Card>, or similar.

1. Confirm the import paths. The component file must be able to import:

• motion (and AnimatePresence for exit) from "framer-motion"
• the chosen seed from "@engine/motion" — in a project that doesn't use the @engine/* alias, use a relative path to engine/motion

1. Replace the target tag with a `<motion.X>` and spread the seed's recipe:

   // hover example
   <motion.button {...spring.hover}>Save</motion.button>

   // press + hover combined
   <motion.button {...spring.press} {...spring.hover}>Save</motion.button>

   // entrance (mount)
   <motion.div {...silk.entrance}>...</motion.div>

   // exit (requires AnimatePresence wrapper somewhere up the tree)
   <AnimatePresence>
     {open && <motion.div {...silk.entrance} {...silk.exit} />}
   </AnimatePresence>

   // layout (FLIP)