how-to-guide

How to Generate and Save UI Designs to the .superdesign Folder in Secure‑Design

March 3, 2026 hbmartin/secure-design ↗

The Secure‑Design extension automatically routes all AI‑generated UI components, wireframes, and design iterations into a dedicated .superdesign/design_iterations folder through a controlled workflow involving workspace initialization, system prompt constraints, and VS Code file system APIs.

The Secure‑Design VS Code extension (hbmartin/secure-design) creates a sandboxed workspace for AI‑generated design artefacts. Understanding the process for generating and saving UI designs to the .superdesign folder is essential for managing versioned iterations and ensuring safe file operations within your repository.

Initializing the .superdesign Workspace

When the extension activates, it establishes a dedicated workspace structure to isolate all design files from your source code.

Creating the Directory Structure

In src/extension.ts (lines 13‑31), the extension checks for the active workspace and creates three directories:

// src/extension.ts
const workspaceFolder = vscode.workspace.workspaceFolders?.[0];
if (workspaceFolder) {
  const superdesignUri = vscode.Uri.joinPath(workspaceFolder.uri, '.superdesign');
  await vscode.workspace.fs.createDirectory(superdesignUri);          // .superdesign
  await vscode.workspace.fs.createDirectory(
    vscode.Uri.joinPath(superdesignUri, 'moodboard')
  );                                                             // .superdesign/moodboard
  await vscode.workspace.fs.createDirectory(
    vscode.Uri.joinPath(superdesignUri, 'design_iterations')
  );                                                             // .superdesign/design_iterations
}

The .superdesign directory serves as the root sandbox, containing:

  • moodboard/ — stores uploaded reference images
  • design_iterations/ — houses all HTML, SVG, and CSS output files

This initialization occurs once per activation; subsequent runs verify existing directories without overwriting content.

Configuring the AI Agent for Controlled Output

The extension constrains the LLM's file operations through strict system prompts and tool definitions, ensuring all designs save exclusively to the designated folder.

System Prompt Constraints

In src/services/customAgentService.ts (lines 40‑45), the system prompt explicitly mandates the output location and naming convention:

// src/services/customAgentService.ts (excerpt)
return `# Role

You are superdesign, a senior frontend designer …

# Instructions

- You ALWAYS output design files in 'design_iterations' folder as {design_name}_{n}.html (or .svg) …
- You MUST use tools for write/edit actions …
`;

This prompt engineering forces the model to:

  • Use the write tool for all file creation
  • Target only the design_iterations subfolder
  • Follow the {design_name}_{n}.html or .svg naming pattern for versioned iterations

The Design Generation and Saving Workflow

The end-to-end process converts user requests into persisted design files through four coordinated steps.

Step 1: User Request Processing

When a user submits a design request through the Chat sidebar, the CustomAgentService.query method processes the message. The extension forwards the request to the configured LLM along with the constrained system prompt.

Step 2: LLM Tool Invocation

Guided by the system instructions, the model emits structured tool calls rather than raw text. For example, when generating a chat interface:

{
  "tool": "write",
  "arguments": {
    "file_path": "design_iterations/chat_ui.html",
    "content": "<!DOCTYPE html>…"
  }
}

Step 3: Path Resolution and File Writing

The createWriteTool function (registered in CustomAgentService at lines 30‑34) resolves relative paths against the working directory (executionContext.workingDirectory), which points to the absolute path of .superdesign:

function createWriteTool(context: ExecutionContext) {
  return async ({ file_path, content }: { file_path: string; content: string }) => {
    const fullPath = path.join(context.workingDirectory, file_path);
    const uri = vscode.Uri.file(fullPath);
    await vscode.workspace.fs.writeFile(uri, Buffer.from(content, 'utf8'));
    return { success: true, path: fullPath };
  };
}

The tool automatically prefixes .superdesign/ to all file paths, ensuring writes occur only within the sandboxed directory. The implementation uses vscode.workspace.fs.writeFile with a Buffer of UTF‑8 content for atomic file operations.

Real-Time Canvas Synchronization

After saving, the Superdesign Canvas automatically detects and renders new designs without manual refresh.

File System Watching

In src/SuperdesignCanvasPanel.ts (lines 282‑284), the panel registers a file system watcher using a glob pattern:

// src/SuperdesignCanvasPanel.ts
const pattern = '.superdesign/design_iterations/**/*.{html,svg,css}';
this.fileWatcher = vscode.workspace.createFileSystemWatcher(pattern);
this.fileWatcher.onDidCreate(uri => this.refreshCanvas(uri));

This watcher monitors design_iterations for new HTML, SVG, and CSS files. When the write tool creates a new iteration (e.g., chat_ui_1.html → chat_ui_2.html), the Canvas immediately refreshes to display the latest version.

Summary

  • Workspace isolation: The extension creates .superdesign/, moodboard/, and design_iterations/ folders during activation in src/extension.ts (lines 13‑31).
  • Prompt engineering: The system prompt in src/services/customAgentService.ts (lines 40‑45) forces the LLM to use the write tool and follow the {name}_{n}.html naming convention.
  • Sandboxed writes: The createWriteTool resolves all paths against the .superdesign working directory, preventing file system escape.
  • Automatic preview: The Canvas panel watches .superdesign/design_iterations/**/*.{html,svg,css} and reloads when new designs appear.

Frequently Asked Questions

What is the purpose of the .superdesign folder?

The .superdesign folder acts as a sandboxed workspace that isolates all AI‑generated design artefacts from your repository's source code. It contains subfolders for moodboard images (moodboard/) and design iterations (design_iterations/), ensuring that automated file operations cannot accidentally modify production files outside this directory.

How does the AI know to save files in design_iterations?

The CustomAgentService injects explicit instructions into the LLM's system prompt (defined in src/services/customAgentService.ts) that state: "You ALWAYS output design files in 'design_iterations' folder." This prompt engineering, combined with the write tool schema, constrains the model to emit only valid, relative paths within that subfolder.

What naming convention does Secure‑Design enforce for design files?

According to the system prompt in src/services/customAgentService.ts, the LLM must use the format {design_name}_{n}.html or .svg, where {n} represents an incremental iteration number. This versioning scheme prevents overwrites and allows the Canvas panel to track design evolution through sequentially numbered files.

How does the Canvas panel display new designs immediately?

The SuperdesignCanvasPanel.ts file creates a FileSystemWatcher using the glob pattern .superdesign/design_iterations/**/*.{html,svg,css} (lines 282‑284). When the write tool creates or modifies a file matching this pattern, the watcher triggers refreshCanvas(), which loads the new content into the webview without requiring manual intervention.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →