How superdesigndev/superdesign works
Project Type and Purpose
• This is a VS Code (and Cursor/Windsurf/Claude Code) extension, combining:
– A backend “extension host” component (Node/TypeScript)
– A frontend “webview” component (React + TypeScript)
– Integration with external AI services (Claude Code, Cursor, OpenAI, etc.)
• Purpose: let users generate UI mockups, components, and wireframes from prompts directly inside the IDE.
File Structure
• Top-level “src” directory is split into:
– extension.ts: entry point that initializes the VS Code extension
– providers/: e.g. chatSidebarProvider.ts registers the sidebar webview
– services/: encapsulate external-API calls and logging (chatMessageService, claudeCodeService, customAgentService, logger)
– templates/: HTML/JS template for the webview
– tools/: “agent” helper tools representing file-system operations (bash, ls, grep, read/write)
– types/: shared TypeScript interfaces
– webview/: React application (App.tsx, components, hooks, styles) that runs inside VS Code’s WebView
• Configuration files (tsconfig.json, eslint.config.mjs), build scripts (esbuild.js), and package manifests.
Readme Insights
• The extension stores generated designs in .superdesign/ locally
• Users interact via a sidebar panel that hosts the webview (Canvas, Chat UI, Mode toggles)
• Supports external subscriptions (Cursor, Claude Code)
1. IDE Host / Extension Host
– Responsibilities: activate extension, register sidebar provider, handle commands, forward messages
– Key file: src/extension.ts
2. Webview Client (React)
– Renders UI: chat interface, canvas preview, theme tools
– Key files: src/webview/index.tsx, App.tsx, components/…
3. Template Engine
– webviewTemplate.ts injects HTML + bundled React into the webview
4. Agent Services
– chatMessageService handles prompt formatting
– claudeCodeService, customAgentService call external AI APIs
5. Local Storage
– .superdesign/ folder for saving generated mockups
6. Tools Layer
– Helper scripts (bash-tool, read-tool, write-tool) the agent can invoke
7. External AI Platforms
– Cursor, Claude Code, OpenAI, Windsurf endpoints
Relationships & Data Flows
• User types a prompt in the Webview → React UI
• React UI posts a message to the Extension Host (via vscode.postMessage)
• Extension Host receives message → dispatches to appropriate Service
• Service formats prompt, calls external AI API → receives design data
• Extension Host saves to local storage (.superdesign/) and forwards result back to Webview
• Webview updates Canvas and Component previews
Architectural Patterns & Principles
• MVC-style separation:
– Model: Services + storage
– View: Webview React components
– Controller: Extension host routing messages
• Message-passing between host and webview
• Dependency inversion: Services abstract external API details
• Plugin architecture: VS Code activation hooks and providers
Technologies & Frameworks
• Node.js + TypeScript
• VS Code Extension API
• esbuild for bundling
• React + Hooks in the webview
• External AI APIs (Claude Code, OpenAI, Cursor)
• Local file I/O for design persistence