Skip to main content

Design JSON

Design JSON is Pixello's file format for storing designs. It's human-readable, version-controllable, and serves as the bridge between your visual canvas and generated code.

What Is Design JSON?​

Design JSON is a structured JSON file that describes:

  • Components: What elements make up your design
  • Layout: How components are arranged
  • Styles: Colors, typography, spacing, and other visual properties
  • Content: Text, images, and other data
  • Structure: Hierarchy and relationships between elements

Example​

Here's a simplified example of what a design JSON file looks like:

{
  "version": "1.0",
  "name": "Landing Page",
  "components": [
    {
      "type": "Hero",
      "props": {
        "title": "Welcome to Pixello",
        "subtitle": "AI-native design ↔ code collaboration",
        "cta": "Get Started"
      },
      "styles": {
        "backgroundColor": "#ffffff",
        "padding": "4rem 2rem"
      }
    },
    {
      "type": "Features",
      "props": {
        "items": [
          {
            "title": "Local-First",
            "description": "All files live in your repo"
          }
        ]
      }
    }
  ]
}

Why Design JSON?​

Human-Readable​

Unlike binary formats (like Figma files), Design JSON is plain text. You can:

  • Read it in any text editor
  • Understand what it represents
  • Edit it directly if needed
  • Review changes in Git diffs

Version-Controllable​

Since it's text-based, Design JSON works perfectly with Git:

  • See exactly what changed between versions
  • Review design changes in pull requests
  • Roll back to previous designs
  • Merge design changes from different branches

No Vendor Lock-In​

Design JSON is just JSON. You're not locked into Pixello:

  • Export your designs to other tools
  • Build custom tooling around the format
  • Use the data in other contexts
  • Own your designs completely

Enables Sync​

Design JSON is the single source of truth that:

  • The web canvas reads to render designs
  • The code generator reads to create components
  • Both update when you make changes
  • Keeps everything in sync automatically

File Location​

Design JSON files are typically stored in:

  • designs/ directory in your project root
  • pixello/ directory (alternative)
  • Or a custom location you configure

Each design typically has its own JSON file, named after the design (e.g., landing-page.json).

Structure​

While the exact structure may evolve, Design JSON generally includes:

  • Metadata: Version, name, created date, etc.
  • Components: Array of component definitions
  • Styles: Global styles and theme settings
  • Assets: References to images, fonts, etc.
  • Pages: For multi-page designs (see Multi-Page Apps)

Editing Design JSON​

Via Canvas​

The easiest way to edit Design JSON is through the web canvas. Visual edits automatically update the JSON file.

Directly​

You can also edit Design JSON files directly in your editor. Changes will:

  • Be reflected in the canvas (after refresh)
  • Trigger code regeneration
  • Work with Git normally

Programmatically​

Since it's JSON, you can:

  • Write scripts to modify designs
  • Generate designs from data
  • Transform designs between formats
  • Integrate with other tools

Multi-Page Support​

Design JSON supports multiple pages in a single file:

{
  "pages": [
    {
      "name": "Home",
      "components": [...]
    },
    {
      "name": "About",
      "components": [...]
    }
  ]
}

👉 Learn more: Multi-Page Apps

Future Possibilities​

Design JSON enables future features:

  • Collaboration: Multiple developers can work on the same design
  • Templates: Share and reuse design patterns
  • Versioning: Track design evolution over time
  • Integration: Connect with other design and development tools

Best Practices​

  1. Commit to Git: Version control your design files
  2. Keep it readable: Don't minify or obfuscate the JSON
  3. Use meaningful names: Name your designs and components clearly
  4. Organize by feature: Group related designs together

What's Next?​

Now that you understand Design JSON, learn about: