Anima Reference Architecture
Overview
This architecture separates design-source intake, authenticated code generation, deterministic post-processing, and reviewed delivery. It is intended for repeatable Figma-to-code pipelines where each run is bounded to approved files and nodes, produces inspectable artifacts, and can be stopped or rolled back without exposing design content or credentials.
Prerequisites
- Define the target framework, repository layout, supported Anima/Figma SDK versions, and the owner who approves generated changes. Pin dependencies and create a sandbox Figma file with synthetic components for pipeline tests.
- Obtain Figma and Anima credentials through the deployment secret manager, using least-privilege scopes and short-lived credentials where supported. Verify webhook signatures before accepting events; never commit, print, or place tokens in generated code, cache files, pull requests, or receipts.
- Establish allowlists for Figma file IDs, node IDs, webhook sources, output repositories, and branch names. Define retention and deletion rules for source snapshots, generated output, and logs before enabling automation.
- Prepare a dry-run mode, an artifact-diff gate, a staged canary environment, and a rollback reference to the last approved generated revision. Do not allow a webhook to publish directly to production.
System Architecture
┌────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Figma Design │────▶│ Figma API │────▶│ Anima SDK │
│ (Components) │ │ (Webhooks) │ │ (Code Gen) │
└────────────────┘ └──────────────┘ └────────┬────────┘
│
┌─────────▼────────┐
│ Post-Processing │
│ - Token mapping │
│ - Normalization │
│ - Lint/format │
└─────────┬────────┘
│
┌─────────▼────────┐
│ Output │
│ - React/Vue/HTML │
│ - PR creation │
│ - Storybook sync │
└──────────────────┘
Instructions
- Ingest and authorize. Use
Readto inspect the existing repository conventions and the signed event payload. Check the file/node allowlist, event freshness, source revision, and suppression/deletion rules before requesting any generation. - Generate in isolation. Run the pinned SDK in a sandbox worker with bounded concurrency and an explicit output directory. Record a request fingerprint and source revision; keep source snapshots and generated files out of logs and clean temporary material after the run.
- Normalize and verify. Use the token mapper and normalizer deterministically, then run formatting, type checks, dependency policy checks, secret scanning, and a generated-file diff. Reject output that writes outside the allowlisted tree or contains credentials, unexpected network calls, or unapproved source data.
- Review and deliver. Use
Write/Editonly within the approved workspace, create a draft change or pull request, and require an owner review before merge. Storybook or preview publishing must target a sandbox first and must not expose private design assets. - Promote and recover. Promote one canary component or sandbox project, compare aggregate health and visual/regression results, and then roll out in batches. On failure, stop event consumption, restore the prior generated revision, revoke temporary credentials, delete staged artifacts according to retention policy, and record a redacted receipt.
Error Handling
- Reject unauthenticated, stale, duplicate, or out-of-scope webhook events before any API call. Return a generic status to the sender and keep detailed diagnostics restricted to the operator channel.
- Treat Figma/Anima 401 and 403 responses as configuration or authorization failures; do not retry them automatically. Treat 429 and transient 5xx/network failures with the bounded retry and rate-limit policy, using an idempotency key or request fingerprint to prevent duplicate generation.
- If post-processing, linting, type checking, or secret scanning fails, quarantine the generated tree and do not open or update a production change. Preserve only hashes, rule IDs, counts, and the rollback reference in the receipt.
- If a worker or webhook delivery fails after generation, resume from the last durable stage rather than rerunning the whole pipeline. A rollback must be tested in the sandbox and must restore both repository state and event-consumer state.
- Alert on repeated failures, scope drift, unexpected output paths, retention violations, or canary regressions. A human owner decides whether to retry, repair configuration, or disable the pipeline.
Examples
For a controlled component update, an event for file=synthetic-design-system; revision=r42; node=button-primary passes the allowlist, generates into generated/canary/, and produces a draft change containing only normalized component files. The receipt can record source_revision=r42; output_digest=sha256:opaque; checks=lint,type,secret-scan; canary=pass; production_promoted=false without storing the design payload or generated source.
For a failed canary, the pipeline records stage=storybook; reason=visual-regression; rollback=generated/r41; production_promoted=false, restores revision r41, stops further webhook consumption, and removes the staged directory after the retention check. The same sequence is the acceptance test for enabling production promotion.
Project Structure
design-to-code/
├── src/
│ ├── anima/
│ │ ├── client.ts # Singleton SDK client
│ │ ├── cache.ts # Generation cache
│ │ ├── retry.ts # Error recovery
│ │ └── presets.ts # Framework/styling presets
│ ├── pipeline/
│ │ ├── scanner.ts # Figma component discovery
│ │ ├── generator.ts # Batch code generation
│ │ ├── change-detector.ts # Figma version tracking
│ │ └── runner.ts # Pipeline orchestrator
│ ├── post-process/
│ │ ├── normalizer.ts # Output normalization
│ │ ├── token-mapper.ts # Design token mapping
│ │ └── organizer.ts # File organization + barrel exports
│ ├── webhooks/
│ │ └── figma-handler.ts # Figma webhook receiver
│ └── server.ts # Express API (optional)
├── scripts/
│ ├── generate-components.ts # CLI generation script
│ └── compare-presets.ts # Side-by-side preset comparison
├── fixtures/
│ └── component-map.json # Figma node ID → component name mapping
├── generated/ # Output directory (gitignored or committed)
├── .anima-cache/ # Generation cache (gitignored)
└── package.json
Key Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| SDK | @animaapp/anima-sdk |
Official, server-side, typed |
| Change detection | Figma Webhooks v2 | Event-driven, no polling waste |
| Caching | File-based with MD5 keys | Simple, no external dependencies |
| Post-processing | Custom normalizer | Match project conventions |
| CI integration | GitHub Actions scheduled | Avoid real-time generation costs |
| Output framework | React + Tailwind + shadcn | Most production-ready output |
Output
- Complete design-to-code pipeline architecture
- Project structure with all components
- Design decision rationale documented
Resources
Next Steps
Start with anima-install-auth, then follow skills through production deployment.