Svg Character

Workflow

Step 1: Read Style Config

Look for svg-style.json in the project root. If it exists, use its settings. If not, use these defaults:

{
  "recraft": {
    "model": "recraft-v4",
    "style": "vector_illustration",
    "substyle": "bold_stroke"
  },
  "prompt": {
    "prefix": "cute kawaii vector character, round shapes, big expressive eyes, simple features, thick outlines, ",
    "suffix": ", flat colors, transparent background, centered composition, clean SVG paths"
  },
  "svg": {
    "viewBox": "0 0 200 200"
  }
}

If --ref PATH is provided, read the reference image and prepend a description of its style to the prompt prefix.

Step 2: Generate SVG Frames

For each frame, call the Recraft V4 API through Vercel AI Gateway. Use the generate-frames.ts script or call directly:

import { generateImage } from 'ai';
import { gateway } from '@ai-sdk/gateway';

const result = await generateImage({
  model: gateway.imageModel('recraft/recraft-v4'),
  prompt: `${config.prompt.prefix}${userPrompt}, ${poseInstruction}${config.prompt.suffix}`,
  providerOptions: {
    recraft: {
      style: 'vector_illustration',
      // NOTE: substyles are NOT supported for V4 via the gateway — use prompt wording instead
    },
  },
});

// Decode base64 SVG (mediaType incorrectly reports image/png — content is SVG)
const svg = Buffer.from(result.image.base64, 'base64').toString('utf-8');

Multi-frame pose instructions: Generate each frame with an explicit pose description. Keep the character description identical — only change the pose:

• Frame 1 (idle): "standing relaxed, arms at sides"
• Frame 2 (mid): "right arm raised halfway"
• Frame 3 (peak): "right arm fully raised, waving"

Save raw SVGs to a temporary location (e.g., /tmp/svg-frames/ or the project's asset directory).

Step 3: Optimize SVGs

Run the optimization pipeline on each frame. This is critical for GSAP morph compatibility:

npx tsx scripts/optimize-svg.ts --input /path/to/frame-1.svg --output /path/to/optimized/

The optimizer:

1. Converts all shapes (<rect>, <circle>, <ellipse>, <polygon>) to <path> elements
2. Flattens all transform attributes into path data
3. Standardizes the viewBox across all frames
4. Removes metadata, comments, and unnecessary attributes
5. Extracts path data as JSON for embedding in components

If you don't have the script available, perform these steps manually using SVGO configuration or by hand-editing the SVG.

Step 4: Validate Morph Compatibility

Check that all frames can morph smoothly:

npx tsx scripts/validate-morph.ts --frames /path/to/optimized/*.svg

Validation checks:

• All frames have the same number of top-level <path> elements
• ViewBoxes match
• No embedded raster images
• Paths use compatible command types

If frames have different path counts, add invisible placeholder paths (d="M0,0" with opacity="0") to the frame with fewer paths.

Step 5: Generate Animated React Component

Create a React component that:

1. Embeds the SVG path data directly (no external file loads)
2. Uses useGSAP hook for animation lifecycle
3. Uses useRef for SVG element references
4. Respects prefers-reduced-motion (show static first frame)
5. Supports lazy initialization via IntersectionObserver
6. Accepts a fallback prop for loading/error states
7. Accepts theme colors via props and applies with gsap.set()

Component structure — follow this pattern:

"use client";

import { useRef } from "react";
import gsap from "gsap";
import { useGSAP } from "@gsap/react";
import { MorphSVGPlugin } from "gsap/MorphSVGPlugin";

gsap.registerPlugin(MorphSVGPlugin);

// Embedded path data from optimized SVGs
const FRAMES = {
  idle: { body: "M...", head: "M...", armLeft: "M...", armRight: "M..." },
  mid:  { body: "M...", head: "M...", armLeft: "M...", armRight: "M..." },
  peak: { body: "M...", head: "M...", armLeft: "M...", armRight: "M..." },
};

interface Props {
  className?: string;
  fallback?: React.ReactNode;
  ariaLabel?: string;
  /** Theme accent color (updates fill/stroke dynamically) */
  accentColor?: string;
}

export default function WavingCharacter({ className, fallback, ariaLabel, accentColor }: Props) {
  const svgRef = useRef<SVGSVGElement>(null);
  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;

  useGSAP(() => {
    if (reducedMotion || !svgRef.current) return;

    const tl = gsap.timeline({ repeat: -1, yoyo: true, defaults: { duration: 0.6, ease: "power2.inOut" } });

    // Morph each part from idle → mid → peak and back
    Object.keys(FRAMES.idle).forEach((part) => {
      tl.to(`#${part}`, { morphSVG: FRAMES.mid[part] }, 0)
        .to(`#${part}`, { morphSVG: FRAMES.peak[part] }, 0.6);
    });

    return () => tl.kill();
  }, { scope: svgRef });

  // Apply accent color
  useGSAP(() => {
    if (!accentColor || !svgRef.current) return;
    gsap.set(svgRef.current.querySelectorAll("[data-accent]"), { fill: accentColor });
  }, { scope: svgRef, dependencies: [accentColor] });

  return (
    <div className={className} role="img" aria-label={ariaLabel}>
      <svg ref={svgRef} viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
        {/* Render idle frame paths with semantic IDs */}
        <path id="body" d={FRAMES.idle.body} fill="..." />
        <path id="head" d={FRAMES.idle.head} fill="..." />
        <path id="armLeft" d={FRAMES.idle.armLeft} fill="..." />
        <path id="armRight" d={FRAMES.idle.armRight} fill="..." />
      </svg>
      {reducedMotion && fallback}
    </div>
  );
}

Step 6: Place Component

1. Write the component to the specified output path
2. Add any necessary imports to the consumer file
3. If replacing an existing animation (e.g., Rive), swap the import

Animation Presets

Read references/presets.md for the full preset library. Quick reference:

Guidelines

• Always embed path data — never reference external SVG files at runtime
• Keep components self-contained — one file per animation, all data inline
• Test morph compatibility before generating the component
• Use semantic IDs for path elements (body, head, armLeft, etc.) so they're maintainable
• Provide fallback — every component should gracefully degrade
• Respect reduced motion — check prefers-reduced-motion and show static frame
• Theme-aware — accept color props and apply with gsap.set(), not inline styles
• No dangerouslySetInnerHTML — render SVG paths as JSX elements with d attribute

Reference Docs

Read these before generating:

• references/recraft-api.md — Recraft V4 API, styles, sub-styles, prompt engineering
• references/gsap-patterns.md — MorphSVG, DrawSVG, MotionPath exact APIs
• references/frame-strategy.md — Multi-frame consistency techniques
• references/presets.md — Animation preset implementations