visionagent: Instructions file for Claude Code

VisionAgent — Claude Code Guide

Project Overview

VisionAgent is a TypeScript framework for AI-driven design-to-code automation. It provides:

• Multi-provider AI support: OpenAI, Anthropic, Google Gemini
• Figma design system conversion: Screenshots → React + Tailwind CSS
• Google Stitch integration: UI generation via MCP
• Agent framework: Tool calling loop with maxIterations control
• MCP support: Model Context Protocol client

Stack: TypeScript 5.7, Vercel AI SDK, Zod, tsup, Vitest, ESLint, Prettier, Husky

---

Architecture

src/
├── index.ts                  # Public API surface — export everything from here
├── lib/                      # Core framework (provider-agnostic)
│   ├── agents/               # runAgent() — the central agent executor
│   ├── models/               # createModel() factory + 3 provider adapters
│   ├── tools/                # Tool definition, execution, toolset helpers
│   ├── subagents/            # Orchestrating nested agents
│   ├── mcp/                  # MCP client + transport
│   ├── types/                # Shared TypeScript interfaces
│   └── utils/                # Logger, errors, misc helpers
└── modules/                  # Feature modules (domain-specific)
    ├── figma/                # 15 Figma tools + converter + 2 agents
    │   ├── agents/           # runFigmaAgent, runFigmaToCodeAgent
    │   ├── client.ts         # FigmaClient (REST wrapper)
    │   ├── converter/        # Figma → HTML → JSX → React+Tailwind pipeline
    │   └── tools/            # One file per tool
    ├── stitch/               # 8 Stitch tools + agents
    │   ├── agents/           # runStitchAgent, runDesignRequirementsAgent
    │   ├── client.ts         # StitchClient (MCP-based)
    │   └── tools/            # One file per tool
    └── hello-world/          # Minimal example module

Key Abstractions

// Model — unified LLM interface
interface Model {
  provider: 'openai' | 'anthropic' | 'google';
  modelName: string;
  invoke(messages, options?): Promise<ModelResponse>;
  generateVision(prompt, images, options?): Promise<ModelResponse>;
}

// Tool — Zod-validated tool definition
interface ToolConfig<T extends ZodSchema> {
  name: string;
  description: string;
  input: T;
  handler: (input: z.infer<T>) => Promise<unknown>;
}

// Agent — autonomous execution loop
interface AgentConfig {
  model: Model;
  tools: Tool[] | ToolSet;
  systemPrompt: string;
  input: string;
  maxIterations?: number; // default: 10
  onStep?: (step: AgentStep) => void;
}