Open Design for Beginners: The Right Way to Use the Open-Source Claude Design

Project Overview

Open Design is an open-source alternative to Claude Design, developed and maintained by nexu-io/open-design.

Its core idea is very straightforward: don’t reinvent the wheel. The coding agents already installed on your computer (Claude Code, Codex, Cursor Agent, etc.—16 CLI tools) become the design engine directly. Combined with 31 composable design skills and 72 brand-grade design systems, it completes the entire design process locally.

Key features at a glance:

---

Target Audience

• Front-end / Full-stack developers: Want to use AI to generate design drafts, but don’t want to learn complex Figma workflows
• Indie developers: Need to ship landing pages, mobile prototypes, and product demos quickly
• Design teams: Prefer local-first, and want an automation solution that doesn’t depend on cloud design
• AI tooling enthusiasts: Want to explore the potential of existing coding agents in the design domain

---

Core Dependencies & Environment

Node.js ~24
pnpm 10.33.x (managed via Corepack)
Operating system: macOS / Windows / Linux

Open Design automatically scans your PATH for installed coding agents. If there are no CLIs installed on your machine, it will guide you to set up BYOK mode (requires an API key).

---

Full Project Directory Tree

open-design/
├── apps/
│   ├── daemon/                 # Local service (Express + SQLite)
│   │   └── src/
│   │       ├── agents.ts       # Agent detection and adapters
│   │       ├── skills.ts       # Skill loader
│   │       └── server.ts       # API routes
│   └── web/                    # Next.js 16 front-end
│       └── src/
│           ├── prompts/        # Prompt templates
│           ├── artifacts/      # Artifact parsing
│           └── components/     # UI components
├── skills/                     # 31 design skills
│   ├── web-prototype/          # Web prototype
│   ├── mobile-app/             # Mobile app
│   ├── dashboard/              # Dashboard
│   ├── guizang-ppt/            # Slide deck
│   └── ...
├── design-systems/             # 72 design systems
│   ├── linear-app/
│   ├── vercel/
│   ├── anthropic/
│   └── ...
├── assets/frames/              # Device frames (iPhone, Pixel, iPad, MacBook)
└── .od/                        # Runtime data (SQLite, project files)

---

Step-by-Step Guide

1) Clone the repository and install dependencies

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
pnpm install

corepack enable automatically reads the pnpm version locked in package.json (10.33.x), ensuring your team environments stay consistent.

2) Start the local development server

pnpm tools-dev run web

After startup succeeds, it prints two URLs:

✅ Daemon running at http://localhost:17456
✅ Web running at http://localhost:17573

Open the Web URL in your browser to begin.

3) Choose a coding agent

On your first visit to the Web interface, Open Design auto-detects the coding agents installed on your PATH.

Supported 16 CLIs:

The model selector in the top-right corner shows the detected agents. If no CLI is found, click the selection for BYOK mode and run it via the OpenAI/Anthropic/Azure/Gemini API using your API key.

4) Choose a design skill

The entry page lists 31 skills, grouped by use case:

• Design: web-prototype (default), mobile-app, mobile-onboarding, gamified-app, wireframe-sketch, critique, tweaks
• Marketing: saas-landing, pricing-page, blog-post, email-marketing, social-carousel, magazine-poster, motion-frames, sprite-animation
• Operation/Engineering/Product: dashboard, docs-page, pm-spec, team-okrs, meeting-notes, kanban-board, eng-runbook, finance-report, invoice, hr-onboarding
• Deck (slide decks): guizang-ppt (default), simple-deck, replit-deck, weekly-update

Click the skill you need. For example, choose mobile-app to generate a mobile prototype.

5) Choose a design system

After selecting a skill, you’ll see the design system panel. By default, it provides two starting systems: default (Neutral Modern) and warm-editorial (Warm Editorial).

The full library includes 72 brand design systems:

• AI & LLM: claude, cohere, mistral-ai, ollama, x-ai…
• Developer tools: cursor, vercel, linear-app, supabase, posthog, sentry…
• Products: notion, figma, airtable, intercom, raycast…
• E-commerce: shopify, airbnb, uber, nike, starbucks…
• Automotive: tesla, bmw, ferrari, lamborghini…
• Others: apple, ibm, nvidia, spotify…

You can also upload your own DESIGN.md file to define 9 design spec dimensions such as brand colors, fonts, and spacing.

6) Send design instructions

Type your design requirements in the input box, for example:

make me a mobile onboarding flow for a fitness app with dark theme

Submit after filling out the form. Then the agent will:

1. Generate a TodoWrite plan and stream updates in real time
2. Read the skill templates and design system
3. Run a 5-dimensional self-check (philosophy, hierarchy, execution, specificity, restraint)
4. Output <artifact> code
5. Render a preview in a sandbox iframe

7) Preview and export

After the design is rendered, you can:

• Edit in real time: Modify HTML/CSS directly in the file workspace on the right
• Download: Export as HTML (with inline assets), PDF, PPTX, ZIP, or Markdown
• Save to disk: Click “Save to disk”; artifacts are saved to .od/artifacts/
• Continue the conversation: Tell the agent “Make the buttons rounded” or “Change the color palette”. It will keep modifying based on the current draft

Other commonly used commands:

# Check runtime status
pnpm tools-dev status

# View logs
pnpm tools-dev logs

# Stop all services
pnpm tools-dev stop

# Restart (when changing ports)
pnpm tools-dev restart --daemon-port 17456 --web-port 17573

# Diagnose issues
pnpm tools-dev check

---

Modify an Existing Project

Many people’s first reaction to Open Design is: “Isn’t this just a tool for generating new pages?” In fact, you can use it to modify existing projects too—and you don’t need your project to contain a DESIGN.md file.

The core logic is simple: the agent has full file-system access—Read, Write, Bash, WebFetch, and more. If it analyzes your code, it can understand your design language, then output changes based on your existing style.

Use the direction selector to quickly establish a visual baseline

If you don’t have design specs yet, Turn 2 will pop up 5 preset directions. Each one is a deterministic OKLch color palette plus a font stack:

After choosing a direction, the agent uses this palette to override the skill template’s :root variables. From then on, all components follow this spec.

Upload screenshots so the agent can extract your design language

This is a more practical way that matches real projects. Open Design includes a built-in brand asset extraction protocol:

1. Locate  — Identify key color blocks in the screenshot
2. Download — Download the screenshot into the project directory
3. Grep hex — Extract hex color values
4. Codify   — Write to brand-spec.md
5. Vocalise — The agent outputs based on brand-spec.md, not guesses from memory

The workflow is simple:

"Here's our current app, I want you to match the styles"
# Then attach screenshots or paste the URL of the existing page

The agent parses main/secondary colors, font, and spacing traits from the screenshot to generate brand-spec.md. All subsequent modifications are based on this spec.

Read the code directly—more precise than screenshots

Instead of copying files? The agent’s default working directory is .od/projects/<id>/, but you can place your existing project there:

# Copy your project into Open Design’s working directory
cp -r ~/my-app/.   .od/projects/<projectID>/

Or use an MCP server to let the agent read across directories directly (see the next section).

Then send instructions like these:

"Read all .css files in ./src/styles and extract the color palette"

"Read the component library at ./components/. Generate a new
form component using the same spacing and border-radius tokens"

"I see you use Tailwind. Add a new button variant that matches
your existing primary/secondary button styles"

The agent will traverse files, parse CSS variables / Tailwind config, extract design tokens, and generate outputs that match your existing code style.

MCP Server: Read design files across projects

Don’t want to copy files? Open Design provides an MCP server so your coding agent can directly read files from Open Design projects.

On Open Design’s Settings → MCP Server page, there are configuration guides for different clients. After you configure it, Claude Code / Cursor agents running in other projects (e.g., ~/my-app) can directly query the design files in Open Design.

Recommended workflow for modification scenarios

1. Open Open Design and pick a skill close to your project style (e.g., web-prototype)

2. Turn 1 form:
   - Surface: Web
   - Audience: the existing user group
   - Tone: keep consistent with the current product

3. Turn 2 direction choice:
   - Want to stay consistent → upload screenshots of existing pages so the agent extracts brand-spec.md
   - Allow some redesign → choose a direction as the visual baseline

4. Send instruction:
   "Add a settings page to my existing project at ./src,
    match the color palette and typography from the attached screenshot"

The agent will:

1. Read the screenshot → extract brand-spec.md (or read CSS variables from the code)
2. Read your project’s existing files
3. Reuse the primary/secondary colors, fonts, etc. in the new page
4. Output runnable HTML with a style consistent with your existing project

---

Troubleshooting FAQ

Q1: Wrong Node version; error Requested version v24.x.x is not currently installed

Open Design requires Node 24. Install it with nvm or fnm:

nvm install 24 && nvm use 24
# or
fnm install 24 && fnm use 24

If you use fnm, make sure your shell config loads fnm env (refer to the fnm official docs).

Q2: Coding agents aren’t being detected

Open Design scans PATH on first startup. Confirm that the CLI is installed and globally available:

# Verify an agent
which claude     # macOS/Linux
where claude     # Windows

# If installed but still not detected, try restarting the service
pnpm tools-dev stop && pnpm tools-dev start web

Q3: Port is already in use

By default, ports 17456 (daemon) and 17573 (web) may already be taken:

# Switch to other ports
pnpm tools-dev run web --daemon-port 17457 --web-port 17574

Q4: Styles don’t change after switching design systems

Open Design’s design systems work by injecting CSS variables from DESIGN.md. After each switch, the agent uses the new variables in a new conversation, but existing old conversations won’t auto-refresh. Start a new conversation to apply the new system.

Q5: Preview iframe loads blank

The sandbox iframe uses srcdoc for rendering. If nothing shows up:

1. Check the browser console for CSP errors
2. Confirm an ad-blocking plugin isn’t blocking iframe loading
3. Click “Download HTML”, then open it directly on your machine to verify

Q6: BYOK mode returns API key errors

BYOK agents are located at /api/proxy/{anthropic,openai,azure,google}/stream. Confirm:

1. The baseUrl configured in the Settings page is correct (OpenAI-compatible format)
2. The API key is valid and has permission for the corresponding model
3. If the apiKey field isn’t filled in, the server will reject the request (SSRF protection)

---

Further Reading / Advanced Directions

Add custom design skills

Skills exist as an SKILL.md file plus assets/ and references/ folders, following Claude Code’s SKILL.md specification.

Create a new folder under skills/, add SKILL.md, and define od: frontmatter (e.g., mode, scenario, design_system.requires, etc.). After restarting the service, it will automatically appear in the skill selector.

Import Claude Design export bundles

Anthropic’s Claude Design supports ZIP exports. Drag the ZIP into Open Design’s welcome chat window. POST /api/import/claude-design will parse and rebuild the project, and the agent can continue editing seamlessly.

Integrate an MCP server

Open Design provides a stdio MCP server. Configure it in MCP clients such as Claude Code / Cursor / VS Code. Then the agent can directly read design files and assets from Open Design projects, without manually exporting ZIP files.

Build a desktop app

The Electron desktop build supports macOS (Apple Silicon) and Windows (x64):

# macOS
pnpm tools-pack mac build --to all
pnpm tools-pack mac install

# Windows
pnpm tools-pack win build --to nsis
pnpm tools-pack win install

The packaged app runs independently; data is stored in the system AppData directory.

Expand media generation capabilities

In addition to code artifacts, Open Design also integrates image (gpt-image-2), video (Seedance 2.0, HyperFrames), and audio (Suno, Udio) generation models. After configuring an API key, your design workflow can directly output media files like .mp4 and .png.

---

Project homepage: nexu-io/open-design