page-load-animations

name	page-load-animations
description	Fix janky page-load animations, layout shift, or skeletons in a Sui dapp. Use when the user wants to fix loading animations or first paint.

Preamble (run first)

# Suiperpower telemetry. Routes through the CLI so projects.json + Convex stay in sync.
# Silent on failure so the skill never blocks. Opt out: SUIPERPOWER_TELEMETRY=off.
#
# AGENT NOTE: when this skill finishes, run the matching completion command:
#   suiperpower track page-load-animations build completed
# Or use "failed" / "aborted" if it ended that way.
command -v suiperpower >/dev/null 2>&1 && suiperpower track page-load-animations build started >/dev/null 2>&1 &
true

If TEL_PROMPTED is no, before doing real work, ask the user:

Help suiperpower get better. We track which skills get used and how long they take. No code, no file paths, no PII. Change anytime in ~/.suiperpower/config.json.

A) Sure, anonymous B) No thanks

Write the answer to ~/.suiperpower/config.json telemetryTier field and create ~/.suiperpower/.telemetry-prompted. Then continue.

What this skill does

Audits page-load and transition animations across the dapp and replaces janky patterns with a small set of calm defaults. Removes layout shift, replaces oversized fade-ins, and uses skeleton loaders that match the final content shape. The result is a UI that feels fast even when the network is slow.

When to use it

• Page load shows an empty white flash, then content snaps in.
• Generic spinners run for any duration, including sub-100ms operations.
• Content layout shifts on first paint (CLS issues).
• Animations are too long, too bouncy, or chained in a way that feels slow.
• Wallet-connect or transaction flows have animation that competes for attention with actual feedback.

When NOT to use it

• Performance issues are caused by network or JS execution, not animation timing. Profile first.
• The user wants brand-level animation (custom logo intro, marketing landing motion). Route to marketing-video or a custom design skill.
• There are no animations yet, route to frontend-design-guidelines for component-level state defaults.

If you activated this and the user actually wants something else, consult skills/SKILL_ROUTER.md and hand off.

Inputs

• The frontend code, especially layout components, route transitions, and async-data containers.
• The user's stated symptom (jank, layout shift, slow feel).
• Optional: a screen recording or a URL to inspect.

Outputs

• Concrete change list per file: which animation to remove, replace, or shorten.
• Skeleton loader components that match the final layout dimensions.
• Reduced-motion support across the board.

Workflow

1. Audit existing animations

   • Grep for transition, animate-, motion., framer-motion, keyframes, custom CSS animations.
   • Note timing values. Anything over 300ms for a UI transition is suspect.

2. Tighten timings

   • UI transitions: 150ms to 200ms.
   • Modal / dialog open: 150ms to 200ms.
   • Page transitions: 250ms to 300ms max.
   • Any value over 300ms is a redesign candidate, not a tweak.

3. Replace spinners with skeletons

   • For surfaces that load in 200ms or more: use a skeleton with the final layout dimensions.
   • For surfaces that load in under 100ms: no loading state at all (the user will not see it).
   • For surfaces that load in 100-200ms: a delayed spinner (only show after 100ms to avoid flash).

4. Eliminate layout shift

   • Reserve space for async content with explicit dimensions or skeletons.
   • Use aspect-ratio for images.
   • Set font-display: swap and pre-size containers, OR use font-display: optional to avoid swap-induced shift.

5. Add reduced-motion support

   • Wrap every animation in @media (prefers-reduced-motion: no-preference), or use the JS query.
   • For users who prefer reduced motion, fall back to instant transitions or simple cross-fades under 100ms.

6. First-paint pass

   • Inline critical CSS for above-the-fold content.
   • Defer non-critical fonts.
   • Avoid full-page fade-in on first load (it makes the page feel slower than it is).

7. Sui-specific surfaces

   • Wallet-connect modal: fast in, fast out. No bouncy spring.
   • Transaction-status surfaces: animate state changes (pending -> success), not the whole container.
   • Faucet response: a single in-out animation, not a chain.

8. Verification

   • Open Chrome DevTools Performance tab, record a page load. Look for layout-shift markers.
   • Throttle network to "Slow 3G". The page should still feel intentional, not broken.
   • Toggle prefers-reduced-motion on. Confirm the page is usable without animation.

Quality gate (anti-slop)

Before reporting done:

• Are all UI transitions at or under 200ms?
• Is there zero layout shift on first paint (CLS < 0.1 in Lighthouse)?
• Does prefers-reduced-motion: reduce produce a usable, non-jarring experience?
• Are spinners replaced with skeletons or removed where the load is sub-100ms?
• Do skeletons match the final content shape (not generic grey rectangles in random sizes)?

If any answer is no, the skill keeps working.

References

On-demand references (load when relevant to the user's question):

• references/timing-defaults.md: Recommended durations and easings per component class.
• references/skeleton-patterns.md: Skeleton shapes for common Sui dapp surfaces (balance, address list, transaction history, NFT grid).

Use in your agent

• Claude Code: claude "/suiper:page-load-animations <your message>"
• Codex: codex "/page-load-animations <your message>"
• Grok Build: run grok, then /page-load-animations <your message> in the session
• Cursor: paste a chat message that includes a phrase like "fix my loading animations", or load ~/.cursor/rules/page-load-animations.mdc and reference it.

If you activated this and the user actually wants something else, consult skills/SKILL_ROUTER.md and hand off.