Skip to main content

How Pixello Works

Pixello's architecture is designed to keep design and code in sync while staying local-first and developer-friendly. Here's how the pieces fit together.

Architecture Overview​

Cursor / VS Code Extension
        ↓
      MCP Server
        ↓
  Design JSON (in repo)
        ↓
    Web Canvas

Components​

1. Extension (Cursor / VS Code)​

The Pixello extension runs inside your editor and provides:

  • Command palette integration: Access Pixello commands from anywhere
  • File watching: Monitors design JSON files for changes
  • Webview hosting: Opens and manages the web canvas
  • MCP client: Communicates with the MCP server for AI operations

The extension is lightweight and doesn't perform heavy computation—it orchestrates the other components.

2. MCP Server​

The Model Context Protocol (MCP) server is Pixello's AI brain. It:

  • Processes prompts: Takes your natural language descriptions and generates designs
  • Orchestrates AI tools: Coordinates multiple AI operations (generation, editing, syncing)
  • Manages file operations: Writes design JSON and code files to your repository
  • Handles sync: Keeps design JSON and generated code aligned

The MCP server runs locally and communicates with AI models to understand your intent and generate appropriate designs and code.

👉 Learn more: MCP Server

3. Design JSON​

The Design JSON file is the source of truth. It:

  • Stores design structure: Components, layouts, styles, and content
  • Lives in your repo: Version-controlled alongside your code
  • Is human-readable: You can edit it directly if needed
  • Enables sync: Both the canvas and code generator read from it

Design JSON files are typically stored in a designs/ or pixello/ directory in your project.

👉 Learn more: Design JSON

4. Web Canvas​

The web canvas is the visual editor. It:

  • Renders designs: Displays your design JSON as a visual interface
  • Enables editing: Lets you modify designs visually
  • Stays in sync: Reads from and writes to design JSON files
  • Runs in webview: Embedded in your editor, not a separate app

The canvas never writes directly to disk—it updates the design JSON, which triggers code generation.

👉 Learn more: Web Canvas

Data Flow​

Creating a Design​

  1. You enter a prompt in the extension
  2. Extension sends prompt to MCP server
  3. MCP server uses AI to generate design structure
  4. MCP server writes design JSON to your repo
  5. Extension opens web canvas with the design JSON
  6. MCP server generates code files based on the design JSON
  7. Canvas renders the design visually

Editing a Design​

  1. You edit the design in the canvas (or edit code directly)
  2. Canvas updates the design JSON file
  3. Extension detects the change
  4. MCP server regenerates code to match the updated design
  5. Your code files are updated automatically

Syncing Changes​

  • Design → Code: Canvas edits update design JSON → code regenerates
  • Code → Design: Code edits can update design JSON → canvas refreshes
  • Both ways: Changes in either place propagate to the other

Key Principles​

Filesystem as Source of Truth​

Everything lives in your repository. The design JSON file is the single source of truth that both the canvas and code generator read from.

Local-First​

No cloud dependency for core functionality. The MCP server runs locally, files are stored locally, and the canvas runs in your editor.

No Vendor Lock-In​

Design JSON is human-readable JSON. You can edit it directly, version control it, and even use it without Pixello if needed.

AI-Native​

Pixello is built for AI from the ground up. The MCP server orchestrates AI operations seamlessly, making design generation and editing feel natural.

What's Next?​

Now that you understand the architecture, dive deeper into: