AI-Canvas

AI-native design system and UI tooling for semantic, type-safe, reversible design documents.

AI-Canvas combines a document model, renderer, code generators, and an MCP server so AI assistants can inspect, modify, export, and validate design work inside one TypeScript monorepo.

Quick Start

# Enable pnpm from Corepack if pnpm is not already on your PATH
corepack enable

# Install dependencies
corepack pnpm install

# Start development
corepack pnpm dev

# Run tests
corepack pnpm test

# Build all packages
corepack pnpm build

# Type check
corepack pnpm typecheck

Documentation

• CONTRIBUTING.md - contribution workflow and PR expectations

• CHANGELOG.md - notable unreleased and released changes

• CLAUDE.md - detailed development workflow and architecture notes

• Gemini.md - Gemini-oriented development guide aligned with CLAUDE.md

• TASKS.md - roadmap, milestones, and status tracking

• docs/product-design-strategy.md - product strategy and expansion plan

• packages/core/README.md - core engine package guide

• packages/renderer/README.md - renderer package guide

• packages/mcp-server/README.md - MCP server package guide

• packages/codegen/README.md - code generation package guide

• packages/vscode-extension/README.md - VSCode editor package guide

Architecture

packages/
├── core/              # @ai-canvas/core - Document model, operations, history, tokens (PenDocument dual mode)
├── mcp-server/        # @ai-canvas/mcp-server - 47 MCP tools (stdio + SSE transport)
├── renderer/          # @ai-canvas/renderer - IRenderBackend abstraction (Canvas2D + CanvasKit)
├── codegen/           # @ai-canvas/codegen - React/Vue/HTML/Tailwind generation
├── web-app/           # @ai-canvas/web-app - Standalone web app (React + multi-AI proxy)
└── vscode-extension/  # @ai-canvas/vscode-extension - Visual editor in VSCode

Core Concepts

Document Model

Document > Pages > Nodes

• Document: Metadata, design tokens, reusable components, pages, history

• Page: Root canvas surface containing the node tree

• Node: A typed design element categorized by primitive and optionally semantic

Node Primitives

AI-Canvas currently supports 13 primitive node types:

Operations

Atomic, reversible operations for document modification:

• insert - add a node

• update - modify node properties

• delete - remove a node

• move - change parent or index

• replace - replace a node entirely

• duplicate - copy an existing node

• set - smart insert or update based on target existence

Feature Highlights

• Immutable document updates with rollback, inverse operations, undo/redo, and checkpoints

• Semantic node search plus component discovery for AI-driven editing workflows

• Layout engines for auto-layout and CSS grid-style composition via GridLayout

• Rendering and interaction support for screenshots, hit testing, snapping, transforms, and viewport control

• Presentation export via PPTXExporter

• Motion primitives through AnimationEngine and TransitionManager

• Brand and design-system generation including DesignPipeline and BrandCollateralGenerator

Development

Prerequisites

• Node.js >= 20.0.0

• pnpm >= 9.15.0 via Corepack

Scripts

Testing

Tests use Vitest. Current test suites live under package-local src/__tests__ directories.

# Run all tests
corepack pnpm test

# Run a specific package
corepack pnpm --filter @ai-canvas/core test

# Watch mode
corepack pnpm --filter @ai-canvas/core test:watch

# Coverage
corepack pnpm --filter @ai-canvas/core test:coverage

VSCode Extension Development

# Build the extension
corepack pnpm --filter @ai-canvas/vscode-extension build

# Debug from VSCode
# Open the repository in VSCode and press F5

开发经验

以下经验已同步到 README.md、CLAUDE.md、Gemini.md，后续调整时应同时更新这三份文档。

• 命令写法统一使用 corepack pnpm ...；包级验证统一使用 corepack pnpm --filter <package> ...

• 包级 typecheck / test 如果依赖其他包生成的 dist/*.d.ts，先构建依赖包，再验证目标包

• 文档中的数量、能力清单和工具列表必须以代码为准，避免手填数字长期漂移

• 调整 CI 质量门禁前，先本地跑受影响包的 lint、typecheck、test，确认当前基线

• 多 Registry 发布流程必须显式覆盖所有目标仓库，且登录失败不能静默跳过

• 测试修复优先通过类型收窄和真实接口对齐解决，避免扩散 as any

• 功能、命令、流程、工具数量有变化时，同时同步 README.md、CLAUDE.md、Gemini.md

• 每次问题修复成功后，都要把可复用的经验补充到开发文档，至少同步 CLAUDE.md 和 Gemini.md

推荐验证顺序

# 1. 安装依赖
corepack pnpm install --frozen-lockfile

# 2. 如目标包依赖其他包的声明产物，先构建依赖包
corepack pnpm --filter @ai-canvas/renderer build

# 3. 再验证目标包
corepack pnpm --filter @ai-canvas/mcp-server typecheck
corepack pnpm --filter @ai-canvas/mcp-server test

# 4. 最后执行仓库级验证
corepack pnpm build
corepack pnpm test

MCP Server

The MCP server exposes the design document, rendering, codegen, brand, print, mockup, collateral, and export workflows to AI assistants.

open_document and save_document support both native .canvas documents and Pencil-compatible .pen files.

# Build and start the server
corepack pnpm --filter @ai-canvas/mcp-server build
corepack pnpm --filter @ai-canvas/mcp-server start

Tool Coverage

The current server ships 47 MCP tools grouped by workflow:

See packages/mcp-server/README.md for the package-level workflow overview.

Deployment

MCP Server — Docker (Recommended)

The MCP server ships as a multi-stage Docker image targeting linux/amd64 and linux/arm64.

Pull from GitHub Container Registry

docker pull ghcr.io/laoluojuhai/ai-canvas-mcp:latest

Run

# stdio mode (used by Claude Desktop / Cursor)
docker run -i --rm \
  -v $(pwd)/documents:/data \
  ghcr.io/laoluojuhai/ai-canvas-mcp:latest

# Pass a specific document directory
docker run -i --rm \
  -v /absolute/path/to/designs:/data \
  ghcr.io/laoluojuhai/ai-canvas-mcp:latest

Build locally

docker build -t ai-canvas-mcp -f Dockerfile.mcp .
docker run -i --rm -v $(pwd)/documents:/data ai-canvas-mcp

MCP Server — Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ai-canvas": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/absolute/path/to/designs:/data",
        "ghcr.io/laoluojuhai/ai-canvas-mcp:latest"
      ]
    }
  }
}

Or run from source (requires the repo cloned and built):

{
  "mcpServers": {
    "ai-canvas": {
      "command": "node",
      "args": ["/absolute/path/to/ai-canvas/packages/mcp-server/dist/cli.js"]
    }
  }
}

After saving, restart Claude Desktop. The 47 design tools will appear in the tool panel.

MCP Server — Connect to Cursor

Open Cursor Settings → MCP → Add Server:

{
  "name": "ai-canvas",
  "command": "docker run -i --rm -v /absolute/path/to/designs:/data ghcr.io/laoluojuhai/ai-canvas-mcp:latest"
}

MCP Server — SSE Transport (HTTP)

The server also supports HTTP + Server-Sent Events for web-based clients:

# Build and start with SSE enabled
corepack pnpm --filter @ai-canvas/mcp-server build
MCP_TRANSPORT=sse MCP_PORT=3001 corepack pnpm --filter @ai-canvas/mcp-server start

Connect from any MCP-compatible client at http://localhost:3001/sse.

Web App — Static Hosting

The web app builds to a static bundle and can be deployed to any CDN.

# Build
corepack pnpm --filter @ai-canvas/web-app build
# Output: packages/web-app/dist/

# Preview locally
corepack pnpm --filter @ai-canvas/web-app preview

Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy from packages/web-app
cd packages/web-app && vercel --prod

Or add a vercel.json at the repo root:

{
  "buildCommand": "corepack pnpm --filter @ai-canvas/web-app build",
  "outputDirectory": "packages/web-app/dist",
  "installCommand": "corepack pnpm install --frozen-lockfile"
}

Docker (web app)

docker build -t ai-canvas-web -f packages/web-app/Dockerfile .
docker run -p 3000:3000 ai-canvas-web

VSCode Extension

Install from VSIX (manual)

# Build the extension package
corepack pnpm --filter @ai-canvas/vscode-extension build
cd packages/vscode-extension
npx vsce package          # produces ai-canvas-*.vsix

# Install into VSCode
code --install-extension ai-canvas-*.vsix

Development / Debug

1. Open the repo root in VSCode

2. Press F5 — launches an Extension Development Host with the extension loaded

3. Open any .canvas or .pen file to activate the visual editor

CI / CD

Required repository secrets

Create a release

# Tag a version and push — GitHub Actions handles the rest
git tag v1.0.0
git push origin v1.0.0

# Then create a GitHub Release from the tag to trigger docker-publish.yml
gh release create v1.0.0 --generate-notes

Troubleshooting

pnpm: command not found

Run corepack enable and retry with corepack pnpm ....

Workspace commands fail after pulling changes

Reinstall dependencies from the repository root:

rm -rf node_modules
corepack pnpm install --frozen-lockfile

Clean rebuild

corepack pnpm clean
corepack pnpm install
corepack pnpm build

License

Released under the MIT License. See LICENSE.