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:
| Words the user might say |
Seed |
| bouncy, springy, playful, energetic, alive |
Spring |
| smooth, silky, fluid, elegant, composed, continuous |
Silk |
| snappy, quick, instant, decisive, sharp, precise |
Snap |
| floaty, gentle, weightless, dreamy, ambient, drifting |
Float |
| rhythmic, punchy, pulsing, heartbeat, beat |
Pulse |
| "Toss style", "Arc style" |
Spring (per brand default) |
| "Stripe style", "Notion style" |
Silk |
| "Linear style", "Raycast style", "Vercel style" |
Snap |
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):
| Use case |
Reach for |
Why |
| Primary button / CTA press |
spring · press |
tactile, confident — the press should "give" |
| Modal / dialog / sheet enter |
silk · entrance |
smooth; never bounce serious/destructive content |
| Dropdown / popover / menu |
snap · entrance |
instant, precise — frequent UI shouldn't wait |
| Toast / inline notification |
spring · entrance |
small friendly arrival, non-blocking |
| List / feed items appearing |
stagger-cascade |
choreograph order, gently |
| Feature / marketing card hover |
tilt-3d |
depth/flair OK on content-light marketing |
| Dashboard / data card hover |
snap · hover |
a subtle lift only — keep dense UI calm |
| Like / favorite / reaction |
like-burst |
a celebratory one-shot; reward the tap |
| Live / online / recording dot |
pulse-beat |
looping heartbeat = "alive" |
| Loading / skeleton |
shimmer |
calm directional progress |
| Success / confirmation |
pop-in |
positive little "done" |
| Toggle / tab / segment switch |
toggle-flip |
distinctive, recognizable switch |
| Page / route transition |
silk · entrance |
smooth, minimal, get out of the way |
| Number / balance / KPI / price reveal |
none |
don't animate the payload — it must read instantly |
Two anti-rules override the table (state them if you deviate):
- One seed per product. If the project already uses a seed, match it — don't introduce a second personality.
- 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.
| Keyword |
Move |
Say it when the user wants… |
toggle-flip |
3D Y-axis card flip |
a switch/toggle to flip between two faces |
toggle-slide |
slide-stack swap |
a value to slide out and the next to slide in |
toggle-morph |
pill ⇄ circle morph |
a control to change shape on toggle |
toggle-curtain |
top→bottom clip-path wipe |
a panel to reveal like a curtain |
reveal-blur |
blur(12px)→0 focus-in |
content to focus-pull into place |
reveal-rise |
masked clip-path text rise |
a headline/text to climb into view |
reveal-unfold |
scaleY from top edge |
an accordion/panel to unfold |
pop-in |
spring overshoot from 0 |
a badge/checkmark to pop in bouncily |
press-squish |
scale-down + skew |
a button to feel jelly/tactile on tap |
tap-ripple |
radial ripple from tap |
Material-style press feedback |
pulse-beat |
looping scale pulse |
a live/recording/heartbeat indicator |
wiggle |
quick horizontal shake |
error / invalid-input feedback |
shimmer |
skeleton loading sweep |
a loading placeholder |
stagger-cascade |
children fade-up in sequence |
a list to animate in one-by-one |
Applying a keyword:
- Read the exact recipe from
engine/motion/library.ts — find the entry whose
key matches, copy its snippet verbatim (it is calibrated and runnable).
- Adapt only the element/content to the user's JSX; keep the transition values.
- 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.
- 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
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.
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
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)
<motion.div {...snap.layout}>...</motion.div>
Do NOT inline the params. The whole point of the seed is that the values come from one source. Never expand { type: "spring", stiffness: 300, damping: 18 } into the JSX — always spread the recipe.
Respect prefers-reduced-motion in long-running surfaces. For one-off interactions (hover/press), framer-motion already throttles. For mount/exit/layout sequences in a long-lived page, import usePrefersReducedMotion and REDUCED_TRANSITION from @engine/motion and override the transition when reduced motion is on.
Validate by re-reading the file and confirming the JSX still parses (matching brackets, motion tag closed, AnimatePresence in place if exit was used).
Tell the user which seed and context you applied, and offer one related context they might want next ("Want press too so it feels clickable?").
Defaults if the user is vague
- No file given → ask "which file?"
- No vibe word → ask "any vibe word, brand, or seed name?"
- Vibe is "natural" or "feel like a real app" → default to Silk (the safest of the five)
- Element is a CTA button → also apply
press
Forbidden
- Do not invent new seed names. There are exactly five.
- Do not edit
engine/motion/seeds/*.ts from this skill — those are calibrated by hand. Add a new seed only via a separate, explicit ask.
- Do not introduce a third-party animation lib (gsap, anime.js). StyleSeed targets framer-motion exclusively.
- Do not add scroll-linked, parallax, or infinite animations via this skill — it does
per-component seeds/moves. (Scroll-linked/parallax/3D ARE allowed on a marketing/landing/brand
page per DESIGN-LANGUAGE §43 Cinematic tier — build those directly with a scroll lib; on
app/data surfaces they stay forbidden.) Infinite loops remain banned everywhere except skeleton pulse.
1---
2name: ss-motion
3description: Apply a named StyleSeed motion to a component — either one of the 5 personality seeds (Spring/Silk/Snap/Float/Pulse × entrance/exit/hover/press/layout) or a distinctive keyword move from the motion library (toggle-flip, toggle-curtain, reveal-blur, pop-in, shimmer, …). Translates vibe words into framer-motion code from one source of truth.
4argument-hint: "[vibe-seed-or-keyword] [context] [file-path]"
5allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6metadata:
7 source: https://skillmd.com/skills/bitjaru/ss-motion
8---
9
10# Motion Seed Applier
11## Registry-first artifact boundary
12
13When `.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.
14
15## When NOT to use
16
17- For general framer-motion docs or learning → use the framer-motion site
18- For non-React motion (CSS-only transitions, GSAP) — this skill targets `motion.X` JSX only
19- For full scroll-linked timelines or parallax — out of scope for *this* skill (it does per-component
20 seeds/moves). Note these ARE allowed on a marketing/landing/brand page (DESIGN-LANGUAGE §43
21 Cinematic tier); just build them with a scroll library, not this skill. On app/data surfaces they
22 stay banned.
23- For tweaking the existing FadeIn/FadeUp/Stagger wrappers — edit `engine/components/ui/motion.tsx` directly
24
25## Vibe → Seed mapping
26
27Translate the user's prompt to one of the five seeds before applying. Use this lookup table from `engine/motion/index.ts`:
28
29| Words the user might say | Seed |
30|---|---|
31| bouncy, springy, playful, energetic, alive | **Spring** |
32| smooth, silky, fluid, elegant, composed, continuous | **Silk** |
33| snappy, quick, instant, decisive, sharp, precise | **Snap** |
34| floaty, gentle, weightless, dreamy, ambient, drifting | **Float** |
35| rhythmic, punchy, pulsing, heartbeat, beat | **Pulse** |
36| "Toss style", "Arc style" | **Spring** (per brand default) |
37| "Stripe style", "Notion style" | **Silk** |
38| "Linear style", "Raycast style", "Vercel style" | **Snap** |
39
40If 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.
41
42## Recommend mode — use-case → motion (when the user describes the *moment*, not the vibe)
43
44If the user describes **what the thing is** ("a like button", "a modal", "the loading
45state", "items in a feed") rather than a feeling, recommend from the use-case map
46(`MOTION_BY_USECASE` in `engine/motion/library.ts`, exported from `@engine/motion`):
47
48| Use case | Reach for | Why |
49|---|---|---|
50| Primary button / CTA press | `spring · press` | tactile, confident — the press should "give" |
51| Modal / dialog / sheet enter | `silk · entrance` | smooth; never bounce serious/destructive content |
52| Dropdown / popover / menu | `snap · entrance` | instant, precise — frequent UI shouldn't wait |
53| Toast / inline notification | `spring · entrance` | small friendly arrival, non-blocking |
54| List / feed items appearing | `stagger-cascade` | choreograph order, gently |
55| Feature / marketing card hover | `tilt-3d` | depth/flair OK on content-light marketing |
56| Dashboard / data card hover | `snap · hover` | a subtle lift only — keep dense UI calm |
57| Like / favorite / reaction | `like-burst` | a celebratory one-shot; reward the tap |
58| Live / online / recording dot | `pulse-beat` | looping heartbeat = "alive" |
59| Loading / skeleton | `shimmer` | calm directional progress |
60| Success / confirmation | `pop-in` | positive little "done" |
61| Toggle / tab / segment switch | `toggle-flip` | distinctive, recognizable switch |
62| Page / route transition | `silk · entrance` | smooth, minimal, get out of the way |
63| Number / balance / KPI / price reveal | **none** | don't animate the payload — it must read instantly |
64
65**Two anti-rules override the table** (state them if you deviate):
661. **One seed per product.** If the project already uses a seed, match it — don't introduce a second personality.
672. **Never delay the payload.** Don't animate a balance, price, or search result into view; motion is for affordance, not content.
68
69## Named motion keywords (distinctive moves)
70
71Seeds set a *personality* (how a fade/scale feels). The **motion library** in
72`engine/motion/library.ts` adds *distinctive moves* — a flip, a curtain wipe, a
73morph — each behind a unique keyword. Prefer a keyword when the user wants a
74specific, recognizable motion rather than a generic feel.
75
76`engine/motion/library.ts` (exported as `MOTION_LIBRARY` / `MOTION_BY_KEY` from
77`@engine/motion`) is the **single source of truth** — every keyword carries its
78own runnable `snippet`. Pull the snippet from there; never hand-write the params.
79
80| Keyword | Move | Say it when the user wants… |
81|---|---|---|
82| `toggle-flip` | 3D Y-axis card flip | a switch/toggle to flip between two faces |
83| `toggle-slide` | slide-stack swap | a value to slide out and the next to slide in |
84| `toggle-morph` | pill ⇄ circle morph | a control to change shape on toggle |
85| `toggle-curtain` | top→bottom clip-path wipe | a panel to reveal like a curtain |
86| `reveal-blur` | blur(12px)→0 focus-in | content to focus-pull into place |
87| `reveal-rise` | masked clip-path text rise | a headline/text to climb into view |
88| `reveal-unfold` | scaleY from top edge | an accordion/panel to unfold |
89| `pop-in` | spring overshoot from 0 | a badge/checkmark to pop in bouncily |
90| `press-squish` | scale-down + skew | a button to feel jelly/tactile on tap |
91| `tap-ripple` | radial ripple from tap | Material-style press feedback |
92| `pulse-beat` | looping scale pulse | a live/recording/heartbeat indicator |
93| `wiggle` | quick horizontal shake | error / invalid-input feedback |
94| `shimmer` | skeleton loading sweep | a loading placeholder |
95| `stagger-cascade` | children fade-up in sequence | a list to animate in one-by-one |
96
97**Applying a keyword:**
98
991. Read the exact recipe from `engine/motion/library.ts` — find the entry whose
100 `key` matches, copy its `snippet` verbatim (it is calibrated and runnable).
1012. Adapt only the element/content to the user's JSX; keep the transition values.
1023. If the keyword is stateful (toggles, ripple), wire the `useState` shown in the
103 snippet. If it's a one-shot reveal, a `key` bump replays it.
1044. Tell the user the keyword you applied so they can reuse it elsewhere for
105 consistency, and point them at `/motion` to preview/Copy others.
106
107If the user describes a move but no exact keyword fits, fall back to a seed +
108context. If they say a keyword that doesn't exist, suggest the closest real one
109from the table — never invent a keyword.
110
111## Context detection
112
113Infer one of the five contexts from the prompt:
114
115- "on hover" / "when hovered" → `hover`
116- "on press" / "on tap" / "on click" → `press`
117- "when it appears" / "on mount" / "entering" → `entrance`
118- "when it leaves" / "on close" / "exiting" → `exit` (requires `<AnimatePresence>`)
119- "when layout changes" / "FLIP" / "rearranging" → `layout`
120
121If ambiguous, default to `entrance`. If multiple contexts are reasonable (e.g., a button needs both `hover` and `press`), apply both.
122
123## Application steps
124
125Apply seed: **$0** · Context: **$1** · Target: **$ARGUMENTS**
126
1271. **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.
128
1292. **Confirm the import paths**. The component file must be able to import:
130 - `motion` (and `AnimatePresence` for `exit`) from `"framer-motion"`
131 - the chosen seed from `"@engine/motion"` — in a project that doesn't use the `@engine/*` alias, use a relative path to `engine/motion`
132
1333. **Replace the target tag with a `<motion.X>` and spread the seed's recipe**:
134
135 ```tsx
136 // hover example
137 <motion.button {...spring.hover}>Save</motion.button>
138
139 // press + hover combined
140 <motion.button {...spring.press} {...spring.hover}>Save</motion.button>
141
142 // entrance (mount)
143 <motion.div {...silk.entrance}>...</motion.div>
144
145 // exit (requires AnimatePresence wrapper somewhere up the tree)
146 <AnimatePresence>
147 {open && <motion.div {...silk.entrance} {...silk.exit} />}
148 </AnimatePresence>
149
150 // layout (FLIP)
151 <motion.div {...snap.layout}>...</motion.div>
152 ```
153
1544. **Do NOT inline the params**. The whole point of the seed is that the values come from one source. Never expand `{ type: "spring", stiffness: 300, damping: 18 }` into the JSX — always spread the recipe.
155
1565. **Respect `prefers-reduced-motion`** in long-running surfaces. For one-off interactions (hover/press), framer-motion already throttles. For mount/exit/layout sequences in a long-lived page, import `usePrefersReducedMotion` and `REDUCED_TRANSITION` from `@engine/motion` and override the transition when reduced motion is on.
157
1586. **Validate** by re-reading the file and confirming the JSX still parses (matching brackets, motion tag closed, AnimatePresence in place if `exit` was used).
159
1607. **Tell the user which seed and context you applied**, and offer one related context they might want next ("Want `press` too so it feels clickable?").
161
162## Defaults if the user is vague
163
164- No file given → ask "which file?"
165- No vibe word → ask "any vibe word, brand, or seed name?"
166- Vibe is "natural" or "feel like a real app" → default to **Silk** (the safest of the five)
167- Element is a CTA button → also apply `press`
168
169## Forbidden
170
171- Do not invent new seed names. There are exactly five.
172- Do not edit `engine/motion/seeds/*.ts` from this skill — those are calibrated by hand. Add a new seed only via a separate, explicit ask.
173- Do not introduce a third-party animation lib (gsap, anime.js). StyleSeed targets framer-motion exclusively.
174- Do not add scroll-linked, parallax, or infinite animations *via this skill* — it does
175 per-component seeds/moves. (Scroll-linked/parallax/3D ARE allowed on a marketing/landing/brand
176 page per DESIGN-LANGUAGE §43 Cinematic tier — build those directly with a scroll lib; on
177 app/data surfaces they stay forbidden.) Infinite loops remain banned everywhere except skeleton pulse.