React Native Skia v2

When to use this skill

Use this skill for React Native or Expo work that depends on @shopify/react-native-skia, especially when the user wants a custom animated element, canvas-driven interaction, shader effect, exported graphic, or performance-sensitive motion system.

Reach for it when the request mentions:

• Skia, Canvas, shaders, RuntimeEffect, RuntimeShader, paths, pictures, atlas, Paragraph, snapshots, Skottie, video, CanvasKit, or headless rendering
• visual language such as glass, glow, blob, liquid, particle, shimmer, parallax, neon, morph, premium loader, hero background, or "make this feel expensive"
• frame-rate or interaction concerns such as 60 fps, 120 fps, GPU-friendly, stutter, jank, gesture-driven, or "keep this off the JS thread"

Do not use this skill for ordinary layout, forms, lists, settings screens, or standard view animation unless the user clearly wants a Skia or canvas-based solution.

Default workflow

1. Audit the repo first in existing projects.

   • Run:

     python3 scripts/audit_skia_repo.py --root . --format markdown
     

   • Read the findings before editing code.

2. Lock the real constraints up front.

   • Platforms: iOS / Android / Web
   • Desired feel: ambient, tactile, energetic, technical, playful, premium
   • Interaction model: passive loop, tap, drag, pinch, scrub, scroll-linked
   • Performance expectations: decorative only, hero element, many instances, always-on animation
   • Asset needs: custom fonts, images, video, Lottie JSON, captured React Native views
   • Accessibility: reduced motion, readable text, tappable overlays

3. If the aesthetic is underspecified, propose 2-3 directions before coding.

   • Give distinct options with trade-offs such as:
     • Retained polish: gradients, blur, layered shapes, safest and simplest
     • Shader-led: most distinctive, best for backgrounds and procedural effects
     • High-instance field: Atlas or Picture driven, best for particles / sprites / trails
   • Then implement the best fit.

4. Choose the simplest architecture that satisfies the effect.

   • Use references/decision-tree.md.
   • Default to retained mode.
   • Escalate to Picture, Atlas, textures, shaders, or headless only when the workload actually needs it.

5. Implement a complete patch, not fragments.

   • Update imports, assets, bootstrap code, and fallbacks together.
   • Include null guards for async fonts, images, and video frames.
   • If web matters, include CanvasKit bootstrapping as part of the change.

6. Review both polish and performance before finishing.

   • Run the review checklist in references/performance-playbook.md and references/motion-design-playbook.md.
   • Mention platform caveats, reduced-motion behaviour, and testing steps.

Hard rules for expert Skia work

• Keep animation state on the UI thread with Reanimated shared or derived values whenever practical.
• Pass shared or derived values directly to Skia props. Do not wrap Skia nodes with createAnimatedComponent or useAnimatedProps just to animate them.
• Avoid reading shared values on the JS thread during normal rendering logic.
• Prefer animating transform, opacity, shader uniforms, and other non-layout properties over layout-affecting view changes.
• Memoise gesture objects and frame callbacks in component code.
• Use retained mode by default. Use Picture when the number of draw commands changes frame to frame. Use Atlas when many instances share the same texture. Use texture hooks when a pre-rendered result is reused often.
• Keep business data, theme context, and layout decisions outside the canvas tree unless you explicitly re-inject context.
• Use Paragraph for wrapped or multi-style text. Load fonts explicitly when custom families matter.
• Treat Paragraph, Picture, Skottie, and SVG as special cases for effects: use layer when you need blur, filters, or other paint effects on them.
• Treat useImage() returning null as normal. Never assume the image is synchronously ready.
• When capturing React Native content with makeImageFromView, keep collapsable={false} on the captured root view.
• When using RuntimeShader as an image filter, account for pixel density and supersample if the result looks soft.
• On web, gate rendering until CanvasKit has loaded. In Expo web, rerun setup-skia-web after Skia upgrades unless CanvasKit comes from a CDN.
• Only use androidWarmup for static, fully opaque canvases. Avoid it for animated or translucent scenes.
• Respect reduced motion. Offer a static or lighter fallback when the effect is decorative.

Motion-design heuristics

Use these rules unless the user asks for a very specific visual style:

• Anchor each scene with one stable focal layer. Let one hero motion lead, one secondary motion support, and keep the rest quiet.
• Put soft, large, low-frequency motion in the background and small, sharp highlights in the foreground.
• Phase-offset loops so everything does not crest at the same time.
• Keep blur and transparency doing compositional work, not hiding weak geometry.
• Place the brightest contrast near the point of action or label, not the canvas edge.
• Clamp gesture-driven motion and spring back to rest states.
• Prefer visuals that can degrade gracefully to a static frame.

See references/motion-design-playbook.md for deeper guidance and pattern recipes.

Deliverable expectations

When you produce code with this skill:

• provide a full runnable TSX component or a coherent repository patch
• explain why the chosen primitives and rendering mode fit the task
• call out the likely performance profile and any trade-offs
• mention web/native setup needs if relevant
• include reduced-motion behaviour for decorative or always-on motion
• when the request is broad, provide 2-3 concept options first and then implement the best one

Bundled resources

• Official doc distillation: references/official-doc-notes.md
• Architecture and primitive selection: references/decision-tree.md
• Motion direction and polish heuristics: references/motion-design-playbook.md
• Performance rules and anti-patterns: references/performance-playbook.md
• Symptom-to-fix guide: references/debugging-matrix.md
• Pattern cookbook: references/animated-element-recipes.md
• Eval workflow notes: references/eval-strategy.md
• Ready-to-adapt TSX templates: assets/templates/
• Repo audit script: scripts/audit_skia_repo.py
• Trigger and output-quality evals: evals/

Quick path by task

New animated decorative element

1. Read references/animated-element-recipes.md.
2. Pick a concept lane from references/motion-design-playbook.md.
3. Start from the closest file in assets/templates/.
4. Keep the structure retained-mode unless the workload clearly needs Picture, Atlas, or a shader.

Gesture-driven surface

1. Confirm react-native-gesture-handler and Reanimated are correctly installed.
2. Prefer shared values for transforms and memoised gestures.
3. If per-element hit-testing is needed, use overlay views that mirror the canvas transforms.

Performance tuning

1. Run scripts/audit_skia_repo.py.
2. Read references/performance-playbook.md.
3. Decide whether the real problem is JS-thread churn, too many draw nodes, wrong render mode, missing web bootstrap, or expensive filters.
4. Only escalate complexity when there is clear evidence.

Text or badge UI

1. Prefer Paragraph.
2. Load fonts explicitly if typography matters.
3. Keep text crisp; do not bury active text inside broad blur/filter layers.

Web blank screen or setup problems

1. Check web bootstrap and CanvasKit loading first.
2. Check setup-skia-web, Babel/worklets config, and version compatibility before rewriting components.

Sprite or particle fields

1. Use retained mode only if the structure is fixed and modest.
2. Use Atlas for many instances of the same texture.
3. Use Picture for dynamic command lists such as trails, generative art, or changing entity counts.
4. Use texture hooks if pre-rendering saves repeated work.