---
name: anima-upgrade-migration
description: 'Analyze and execute @animaapp/anima-sdk upgrades with rollback evidence.

  Use when upgrading SDK versions, migrating from the Figma plugin workflow

  to SDK-based automation, or adapting to new Anima API features.

  Trigger with: "anima upgrade", "anima migration", "anima SDK update".'
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 2.0.0
argument-hint: "[target-sdk-version]"
model: inherit
effort: high
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
  - saas
  - design
  - figma
  - anima
  - migration
compatibility: Requires Node.js 20+, approved Anima API access, current Anima SDK documentation, and authorized Figma or website source access
title: anima-upgrade-migration
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/anima-upgrade-migration
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/official-docs.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/anima-upgrade-migration/references/official-docs.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/anima-upgrade-migration`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/anima-upgrade-migration`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/anima-upgrade-migration) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/anima-upgrade-migration`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/anima-upgrade-migration --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/anima-upgrade-migration --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Anima Upgrade & Migration

## Overview

This workflow moves an Anima integration between SDK versions or from manual
Figma exports to automation while preserving a reviewable, reversible design
source of truth. It uses a pinned dependency and a staging canary so API or
generated-code changes are detected before production output is replaced.

## Prerequisites

- A clean working tree, committed lockfile, current SDK version, and a
  reviewed changelog or release note for the proposed target version.
- A fixture registry containing synthetic or approved design nodes, expected
  output paths, and a baseline artifact digest for the current workflow.
- Separate staging credentials with read-only design access, an owner for
  generated-code review, and a rollback revision that can restore the prior
  SDK and generated output.
- CI gates for install, lint, type checking, tests, and secret scanning; do
  not test an upgrade against customer designs or live production writes.

## Migration Paths

| From | To | Complexity |
|------|----|-----------|
| Figma plugin (manual) | SDK automation | Medium |
| Older pinned SDK | Explicit reviewed target | Depends on release/type/generated-output diff |
| Anima Playground | SDK API | Low |

## Instructions

### Step 1: Upgrade SDK

```bash
# Check current version
npm list @animaapp/anima-sdk

# Select and record a concrete target; 0.27.0 was current on 2026-09-12.
export APPROVED_ANIMA_VERSION="0.27.0"
npm install --save-exact "@animaapp/anima-sdk@${APPROVED_ANIMA_VERSION}"

# Check for breaking changes
npm view "@animaapp/anima-sdk@${APPROVED_ANIMA_VERSION}" version dist.integrity
```

### Step 2: Migrate from Manual Plugin to SDK

```typescript
// BEFORE: Manual Figma plugin workflow
// 1. Open Figma → Plugins → Anima
// 2. Select component → Export → React
// 3. Copy-paste generated code into project
// 4. Manually repeat for each component change

// AFTER: Automated SDK workflow
import { Anima } from '@animaapp/anima-sdk';
import fs from 'node:fs';
import path from 'node:path';

const anima = new Anima({ auth: { token: process.env.ANIMA_TOKEN! } });

// Automated: runs in CI on Figma file version change
async function syncDesignToCode() {
  const { files } = await anima.generateCode({
    fileKey: process.env.FIGMA_FILE_KEY!,
    figmaToken: process.env.FIGMA_TOKEN!,
    nodesId: ['1:2', '3:4', '5:6'],  // All design system components
    settings: { language: 'typescript', framework: 'react', styling: 'tailwind' },
  });

  // Write to project, run through linter, create PR
  const root = path.resolve('src/components/generated');
  for (const [fileName, file] of Object.entries(files)) {
    if (file.isBinary) throw new Error(`Review binary output separately: ${fileName}`);
    const target = path.resolve(root, fileName);
    if (!target.startsWith(`${root}${path.sep}`)) throw new Error('Unsafe output path');
    fs.mkdirSync(path.dirname(target), { recursive: true });
    fs.writeFileSync(target, file.content);
  }
}
```

### Step 3: API Changes Checklist

```typescript
// Common API changes between versions:
// - New settings options (e.g., uiLibrary: 'shadcn' added later)
// - Supported framework, styling, and UI-library unions
// - Response record shape and binary-file handling
// - Authentication, Figma access, streaming, and error types

// Test after upgrade:
async function testUpgrade() {
  const anima = new Anima({ auth: { token: process.env.ANIMA_TOKEN! } });
  const { files } = await anima.generateCode({
    fileKey: process.env.FIGMA_FILE_KEY!,
    figmaToken: process.env.FIGMA_TOKEN!,
    nodesId: ['1:2'],
    settings: { language: 'typescript', framework: 'react', styling: 'tailwind' },
  });
  console.log(`Upgrade test: ${Object.keys(files).length} files generated`);
}
```

## Error Handling

| Failure | Required response |
|---------|-------------------|
| Dependency resolution or lockfile changes are unexpected | Stop the migration, inspect the dependency tree, and restore the approved lockfile before retrying. |
| Authentication, file access, or API schema changes fail | Keep the old revision active; verify credentials and supported request fields without widening access. |
| Generated files move, disappear, or contain an unexpected diff | Quarantine the output, compare against the baseline fixture, and require owner review before any merge. |
| Lint, type, visual, or accessibility checks fail | Do not promote the SDK; retain the sanitized test receipt and return the failure to the design/code owner. |
| Staging canary fails or rollback is unavailable | Disable automated generation and restore the last known-good package and generated artifact. |

Never log tokens, full Figma payloads, or design content while comparing
versions. A migration is complete only after the pinned package, source
version, artifact digest, test result, and rollback reference are recorded.

## Tool Discipline

Use Read and Grep to inspect the existing integration and generated diff before changing anything. Use Write or Edit only inside the approved generated-code, test, or configuration paths. Use the declared Bash commands only for the explicit install, validation, or diagnostic steps in this workflow; never print tokens, source designs, generated source, or private website captures.

## Output

- SDK upgraded to the explicitly approved pinned version
- Migrated from manual plugin to automated SDK
- All generation tests passing after upgrade

## Examples

Use an approved version and one synthetic, allowlisted component for a staged
canary; keep the lockfile and generated diff in the review boundary:

```bash
export APPROVED_ANIMA_VERSION="2.x.y"
npm install "@animaapp/anima-sdk@${APPROVED_ANIMA_VERSION}"
npm test
npm run lint
npm run generate:staging -- \
  --file-key synthetic-staging-file \
  --node-id 1:2 \
  --output-dir .tmp/anima-upgrade \
  --no-production-write
```

Compare the staged artifact with the baseline, review the source-version and
path changes, and promote only after owner approval. If the canary changes an
unexpected file or fails a quality gate, delete the temporary output and
restore the prior lockfile/package before rerunning.

## Resources

- [Anima SDK npm](https://www.npmjs.com/package/@animaapp/anima-sdk)
- [Anima SDK GitHub](https://github.com/AnimaApp/anima-sdk)
