@nerdev/skillset 0.2.1

package/skills/ui/animaxxing/references/text-stability.md

@@ -0,0 +1,68 @@
+# Text stability
+
+Technical requirements for split text on the project's existing typography. No particular font, palette, or layout is required.
+
+## Stable typography for character animation
+
+Read this before using any recipe that splits characters, especially `charsRiseIn`. [GSAP's Tips & Limitations](https://gsap.com/docs/v3/Plugins/SplitText/#tips--limitations) documents that character wrappers interrupt browser kerning. Splitting can change spacing; `split.revert()` restores natural kerning and can produce a horizontal snap even when heading height stays unchanged. `smartWrap` groups words to prevent mid-word breaks; character masks clip the reveal. Neither preserves kerning.
+
+Make stable typography part of the target's base CSS, present before first paint and retained during splitting, after cleanup, and under reduced motion:
+
+```html
+<h2 class="character-headline">Small idea. Big feeling.</h2>
+```
+
+```css
+/* Only headlines that use character animation, not all headings or body text. */
+.character-headline {
+  font-kerning: none;
+  text-rendering: optimizeSpeed;
+}
+```
+
+Tailwind equivalent: `[font-kerning:none] [text-rendering:optimizeSpeed]` on the same target. Use the project's own selector or CSS module name. This setting is permanent typography, not a tween or an animation-state class; do not toggle it in a builder, completion callback, or reduced-motion query. For `speakIn`, scope it to the persistent emphasis elements that receive inner character splits.
+
+Keep `split.revert()` and the framework controller's interruption/unmount cleanup. Keeping wrappers indefinitely is not the default spacing fix. If natural kerning is essential, choose whole-word or whole-line animation without character splitting (for example `wordsSlideIn` or `linesMaskIn`), then verify the result.
+
+### Diagnose the measured change
+
+Change one cause at a time; do not apply every workaround:
+
+| Evidence | Targeted response |
+|---|---|
+| Horizontal character-position changes across split/revert, with fonts ready and the same line breaks | Check computed kerning settings in both states; use the persistent CSS above. A stable heading box alone does not rule this out. |
+| Font face or metrics change after splitting | Have the framework controller wait for the required fonts (`document.fonts.ready`), or use supported `autoSplit`/`onSplit` handling. Check the installed GSAP version and docs; returning the animation from `onSplit` lets the plugin manage re-splits. |
+| Joined glyphs such as `fi`/`ffi` differ between states | Inspect ligatures separately. If confirmed, test persistent `font-variant-ligatures: none` on the affected target, or preserve shaping with words/lines. Do not disable ligatures globally or assume the rendering hint fixes every font/browser. |
+| Line membership or heading height changes | Inspect available width, white space, tracking, and word grouping. GSAP warns against `text-wrap: balance` on split targets: omit `text-wrap: balance` there and keep normal wrapping consistent across states. Use `smartWrap` for chars-only splits or words/lines grouping; re-split lines when width changes through the controller. |
+| Text appears heavier after revert, or letter edges/descenders are clipped while masked | Compare computed font properties and font readiness first, then inspect glyph ink against each mask. Stable boxes and unchanged weight do not rule out clipping. Use the targeted mask fix below when demonstrated. |
+| Weight effects jump when pinned character widths are removed | Compare pinned widths with the settled font's advances. Width pinning can stabilize the weight animation yet still change spacing on revert; verify that boundary separately. |
+
+### Apparent weight change from clipped glyph ink
+
+This is distinct from kerning: `mask: "chars"` with tight negative `letter-spacing` and `line-height` can clip letter edges and descenders. Removing masks exposes the complete glyph, making it look heavier without changing font weight or character positions. The kerning CSS above does not give masks extra room.
+
+Before diagnosing a weight change, compare computed `font-family`, `font-weight`, `font-size`, `font-style`, `font-variation-settings`, and `font-feature-settings` on the split characters and restored text. Record tracking and line-height too. Confirm the intended font face is loaded (font readiness plus the browser's rendered-font inspection), not just that its CSS family is declared. If these are stable, compare captured glyphs and inspect mask overflow before blaming GPU compositing or trying `force3D`, layer promotion, or font-smoothing changes.
+
+For confirmed mask clipping, add a class only to the affected split's masks immediately after creation, before building the reveal:
+
+```ts
+// split is the affected headline's existing character-masked SplitText instance.
+for (const mask of split.masks) mask.classList.add("title-char-mask");
+// With CSS Modules, pass the scoped token instead: styles.titleCharMask.
+```
+
+```css
+.title-char-mask {
+  /* Verified for the AI Film Camp headline; tune to the actual glyph ink. */
+  padding: 0.15em;
+  margin: -0.15em;
+}
+```
+
+Padding expands the clipping area; matching negative margins compensate for the added space to preserve the layout footprint. `0.15em` is a verified value for that typography, not a universal constant or a new design token. Use only enough room for the actual font, size, tracking, and line-height, and measure spacing, wrapping, and height again. Keep clipping enabled so the reveal still works. Do not apply this to all split wrappers, unmasked characters, or headings globally.
+
+Apply the class to each new affected split (inside `onSplit` if the controller uses auto re-splitting). In [split entrances](recipes/split-entrances.md), the optional `charMaskClass` passes this class to character masks only. Preserve durations, easing, stagger, `aria`, completion callbacks, and revert/unmount cleanup: the styled mask nodes disappear with revert. Unlike the permanent kerning CSS, this class belongs to temporary mask nodes.
+
+Expanded masks may expose characters at the hidden endpoint. Check both forward and backward reveals, including opposite travel directions; do not assume `yPercent: 115` or `-115` still hides all ink. If a frame shows leakage, adjust only the hidden travel distance enough to clear the expanded mask, retaining animation timing, then repeat the checks.
+
+See [cleanup verification](verification.md#splittext-cleanup-stability) for measurements and the observed regression.

package/skills/ui/animaxxing/references/verification.md

@@ -0,0 +1,44 @@
+# Verification
+
+Reference demo: [Animaxxing](https://github.com/johnpolacek/animaxxing). It exercises these recipes with `style-animaxxing`; it is not a required design. Until a motion suite exists in animaxxing-skills-test, verify changed recipes there or in the consuming app, alongside the framework skill's relevant checks.
+
+## Portability
+
+- An effect-only request preserves the app's fonts, palette, layout, and component styling. No style-specific tokens or fonts are needed to copy a recipe and its named helpers.
+- Particle color follows the canvas's computed `color`, including theme changes; its contrast works on the actual background.
+- Weight effects use a loaded variable face and its supported axis range. Confirm the configured resting weight matches the target. For a static face, choose a transform-only effect or omit weight moves.
+- Selected timing, spread, intensity, and stagger suit the actual surface and viewport. Layout boxes remain stable through the effect.
+
+## Motion
+
+- Entrance splits are reverted at settled. Only an active wave or speak-in finishes retain required markup; both release it at their documented cleanup boundary.
+- No inline `transform`, `will-change`, or `transition` remains on route items at settled.
+- If the controller uses `data-transition-state`, it reports `entering → idle` for intro and `exiting → waiting` for outro. It never reports completion while the relevant timeline still runs.
+- Particle canvases: one per treated element, positioned at `-bleed`, `pointer-events: none`, `aria-hidden`, colored from the consuming app's chosen canvas `color`. The GSAP ticker drops each field once its particles are gone and no emitter is attached.
+- Hover and focus produce the same state on treated elements.
+- Reduced motion (`prefers-reduced-motion: reduce`, or `data-motion="reduced"` on `<html>`): entrances reach the readable settled state immediately, exits reach their documented end state, no splits, no particles, no wave, and every completion callback still fires.
+- Off screen: scroll a treated element out of view and confirm its field stops ticking.
+
+## Effect failure and restoration
+
+- Throw before writes, after initial styles, and after a split or particle resource is created. Confirm partial setup rolls back even without a returned handle.
+- Stop owned timelines, delayed calls, tickers, observers, and listeners before restoration. Invoke teardown twice; it remains safe and cannot recreate motion.
+- Compare original nodes, text, links, ARIA, and application-owned inline styles after rollback. Check hidden ancestors and masks, not just opacity.
+- Resolve deferred font/media work after the framework recovers; no new split, hidden frame, or decorative completion may run.
+- Use the matching installed framework skill's `references/initialization.md` failure matrix for disabled JavaScript, blocked bundles, deadlines, navigation, and completion ownership. These checks also apply with another brand's fonts and CSS.
+
+## SplitText cleanup stability
+
+Use [stable typography diagnosis](text-stability.md#stable-typography-for-character-animation) with the actual font, tracking, text, and container width:
+
+1. Capture the unsplit baseline after fonts load and persistent target CSS is applied. Record computed font/variation/feature settings, tracking, leading, kerning, and ligatures.
+2. At the existing completion boundary, measure immediately before revert, immediately after it, and on the next frame. Capture both painted states at equal scale; temporarily holding at that boundary is acceptable, removing cleanup is not.
+3. Compare non-space character positions with DOM `Range` rectangles, re-querying text nodes after revert. Check heading height, line membership, and glyph edges/dots/descenders. Wrapper rectangles alone cannot distinguish mask padding from glyph movement.
+4. Repeat at desktop/mobile widths and near a line-break threshold, with reduced motion and interruption. Separate intended weight/tilt changes from cleanup-induced movement. Confirm accessible text and nested controls survive.
+5. If masks were expanded, inspect both hidden reveal endpoints and the exit endpoint for ink leakage. Keep timing fixed; adjust travel only when leakage is observed.
+
+Record viewport, browser, font readiness, maximum position deltas, height, wrapping, and visual observations. A repeatable multi-pixel snap fails even with stable height; tiny subpixel rounding without visible movement is not a universal failure. Do not round measurements to whole pixels.
+
+## Report
+
+Say which checks ran in a browser and which were static review. Do not claim animation behavior was verified from code alone.

package/skills/ui/ask-animation/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: ask-animation
+description: Pattern guide for transitions, springs, scroll animations, gestures, page transitions. Load via ui-engineering. Invokes pick-ui-library → recommends motion.dev (Framer Motion) → loads ask-motion for implementation. For showcase tier: GSAP + ScrollTrigger + Lenis.
+---
+# Ask Animation , Transitions, Springs, Scroll, Gestures
+
+**When to use:** Any motion , page transitions, layout animations, enter/exit, scroll-linked, drag, hover/tap feedback, morphing.
+
+
+## The Pattern (What Good Looks Like)
+
+| Animation Type | Use When | Library | Key Principles |
+|----------------|----------|---------|----------------|
+| **Page transitions** | Route changes | motion.dev / GSAP | Shared layout, exit before enter, 200ms |
+| **Layout animations** | Reorder, expand, collapse | motion.dev `layout` | `layoutId` for shared element, spring |
+| **Enter/Exit** | Modals, sheets, toasts, dropdowns | motion.dev `AnimatePresence` | Scale 0.97→1 + fade, exit before enter |
+| **Scroll-linked** | Parallax, reveal, progress, sticky | GSAP + ScrollTrigger | Scrub, pin, snap, velocity-based |
+| **Drag/Gesture** | Draggable cards, sliders, drawers | motion.dev `drag` / Lenis | Constraints, momentum, snap points |
+| **Hover/Tap** | Buttons, cards, interactive elements | motion.dev `whileHover`/`whileTap` | Scale 0.98, instant press, spring back |
+| **Morphing** | Icon state changes, shape shifts | motion.dev `keyframes` / GSAP | SVG path morph, crossfade |
+| **Stagger** | Lists, grids, onboarding | motion.dev `staggerChildren` | Rare moments only, 50-100ms delay |
+
+
+## Quality Checklist
+
+- [ ] **Fast, physical, quiet, purposeful** , Every motion answers "what changed?"
+- [ ] **State lands first** , Input responds same frame, motion is polish on top
+- [ ] **Transform + opacity only** , No layout property animations (width, height, top, left)
+- [ ] **Spring curves** , `cubic-bezier(0.16, 1, 0.3, 1)` (ease-out spring), not `ease-in-out`
+- [ ] **200ms in, 150ms out** , Micro means micro. >300ms = scene change, needs reason
+- [ ] **One motion per event** , Pick the element that carries the change
+- [ ] **Matched to element** , Checkbox does not slide. card does
+- [ ] **Exits exist** , Whatever appears animated leaves animated
+- [ ] **Reduced motion** , `prefers-reduced-motion: reduce` = instant, no springs
+- [ ] **Interruptible** , Next click cancels last spring. Nobody waits.
+- [ ] **Nothing loops forever** , No idle pulses, no infinite marquees (unless dial=3 justified)
+
+
+## Anti-Patterns
+
+- ❌ `transition: all 0.3s ease` , Lazy, animates layout properties
+- ❌ `animate.css` / `framer-motion` defaults without tuning , Generic feel
+- ❌ Stagger on every page load , Daily interactions get subtle/fast
+- ❌ Keyboard-initiated actions animate , Never
+- ❌ Scroll-jacking , User owns scroll
+- ❌ Parallax without purpose , Dial 3 only
+- ❌ No reduced-motion support , Accessibility fail
+- ❌ Exit animation missing , One-frame vanish = flicker
+- ❌ Competing springs , Two at once reads as glitch
+
+
+## Implementation Flow
+```
+User needs animation/motion
+    │
+    ├─► ui-engineering detects "transition/scroll/drag/hover/morph"
+    │
+    ├─► pick-ui-library → recommends motion.dev (or GSAP for showcase)
+    │
+    ├─► load ask-motion (library skill) or ask-gsap for showcase
+    │
+    └─► implement with motion.dev + house-style motion rules
+```
+
+**Reference:** [transitions.dev](http://transitions.dev) — curated CSS transitions & micro-interactions. Good for inspiration and copy-paste snippets that align with the quality checklist above.
+
+## motion.dev Primitives (Core)
+```tsx
+import { motion, AnimatePresence, LazyMotion, domAnimation, m } from 'motion/react'
+
+// Spring preset (house-style)
+const spring = { type: 'spring', stiffness: 500, damping: 30, mass: 0.8 }
+// = cubic-bezier(0.16, 1, 0.3, 1) ≈ 200ms in
+
+// Quick spring for press feedback
+const tapSpring = { type: 'spring', stiffness: 600, damping: 20 }
+
+// Page transition
+<AnimatePresence mode="wait">
+  <motion.div
+    key={pathname}
+    initial={{ opacity: 0, y: 20 }}
+    animate={{ opacity: 1, y: 0 }}
+    exit={{ opacity: 0, y: -20 }}
+    transition={spring}
+  />
+</AnimatePresence>
+
+// Layout animation (shared element)
+<motion.div layoutId="shared-card" className="card" />
+// In another route:
+<motion.div layoutId="shared-card" className="card-expanded" />
+
+// Scroll-linked (with GSAP - see ask-motion for GSAP)
+// motion.dev scroll: useScroll, useTransform
+```
+
+## Composition Examples
+
+### Page Transition (Linear-style)
+```tsx
+// app/layout.tsx
+import { AnimatePresence } from 'motion/react'
+
+export default function Layout({ children }) {
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.div
+        key={pathname}
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        exit={{ opacity: 0, y: -16 }}
+        transition={{ type: 'spring', stiffness: 500, damping: 30 }}
+        className="min-h-screen"
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}
+```
+### Button Press Feedback (Raycast-style)
+```tsx
+<motion.button
+  whileHover={{ scale: 1.02 }}
+  whileTap={{ scale: 0.97 }}
+  transition={tapSpring}
+  className="..."
+>
+  Action
+</motion.button>
+```
+### List Stagger (Onboarding only , rare moment)
+```tsx
+<ul>
+  <AnimatePresence>
+    {items.map((item, i) => (
+      <motion.li
+        key={item.id}
+        initial={{ opacity: 0, x: -20 }}
+        animate={{ opacity: 1, x: 0 }}
+        exit={{ opacity: 0, x: 20 }}
+        transition={{ ...spring, delay: i * 0.05 }}
+      >
+        {item.label}
+      </motion.li>
+    ))}
+  </AnimatePresence>
+</ul>
+```
+### Scroll Reveal (Stripe-style)
+```tsx
+// Use GSAP for this - see ask-motion
+// motion.dev alternative:
+const { scrollY } = useScroll()
+const y = useTransform(scrollY, [0, 500], [100, 0])
+
+<motion.div style={{ y }} className="sticky top-0" />
+```
+
+## Showcase Tier (Dial = 3) , GSAP + Lenis
+
+When animation dial = 3 (showcase/motion-heavy):
+- `npm i gsap @studio-freight/lenis`
+- Load `ask-gsap` library skill
+- Lenis for smooth scroll
+- GSAP ScrollTrigger for scrub, pin, snap
+- Rive for interactive vectors
+
+
+## When to Escalate
+
+| Need | Escalate To |
+|------|-------------|
+| Complex scroll animations | `ask-motion` (GSAP) |
+| Interactive vectors | Rive |
+| Canvas/WebGL | Custom + `ask-animation` |
+| Page transitions with data | `ask-animation` + TanStack Router loaders |