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:

Primitive	Description
frame	Container with layout capabilities
rectangle	Basic rectangular shape
ellipse	Circle or ellipse shape
line	Straight line segment
polygon	Regular polygon shape
path	Arbitrary vector path
text	Text content
image	Bitmap or image asset
star	Star shape
arrow	Arrow shape with direction
connector	Connection line between nodes
video	Video or media element
group	Grouping container without layout

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

Command	Description
corepack pnpm dev	Start all packages in dev mode
corepack pnpm build	Build all packages
corepack pnpm test	Run workspace tests
corepack pnpm typecheck	Run workspace TypeScript checks
corepack pnpm lint	Run workspace ESLint checks
corepack pnpm clean	Clean build artifacts and workspace dependencies

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:

Group	Count	Examples
Document	2	open_document, save_document
Query and rendering	5	get_document, query_nodes, get_layout, get_screenshot
Mutation	1	apply_operations
History	6	undo, redo, create_checkpoint
Tokens and codegen	4	get_tokens, set_tokens, generate_react, generate_tailwind_config
Brand	7	get_brand, generate_brand_tokens, generate_brand_book
Design system	10	get_design_patterns, create_seed_component, generate_style_guide
Print and mockups	6	get_print_presets, create_mockup, create_poster_template
Pipeline and collateral	5	run_design_pipeline, generate_collateral_kit, export_pptx

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

Workflow	Trigger	What it does
ci.yml	Push / PR to main	Install -> typecheck -> test -> build
docker-publish.yml	GitHub Release published	Build multi-arch image -> push to GHCR + Docker Hub

Required repository secrets

Secret	Purpose
DOCKER_USERNAME	Docker Hub login (optional, GHCR works without it)
DOCKER_PASSWORD	Docker Hub token

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.