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

> Learn how to generate and save UI designs to the .superdesign folder in Secure-Design using VS Code file system APIs. Follow this workflow for efficient design management.

- Repository: [Harold Martin/secure-design](https://github.com/hbmartin/secure-design)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/hbmartin/secure-design/blob/main/src/extension.ts) (lines 13‑31), the extension checks for the active workspace and creates three directories:

```typescript
// 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`](https://github.com/hbmartin/secure-design/blob/main/src/services/customAgentService.ts) (lines 40‑45), the **system prompt** explicitly mandates the output location and naming convention:

```typescript
// 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:

```json
{
  "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`:

```typescript
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`](https://github.com/hbmartin/secure-design/blob/main/src/SuperdesignCanvasPanel.ts) (lines 282‑284), the panel registers a file system watcher using a glob pattern:

```typescript
// 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`](https://github.com/hbmartin/secure-design/blob/main/chat_ui_1.html) → [`chat_ui_2.html`](https://github.com/hbmartin/secure-design/blob/main/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`](https://github.com/hbmartin/secure-design/blob/main/src/extension.ts) (lines 13‑31).
- **Prompt engineering**: The system prompt in [`src/services/customAgentService.ts`](https://github.com/hbmartin/secure-design/blob/main/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`](https://github.com/hbmartin/secure-design/blob/main/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`](https://github.com/hbmartin/secure-design/blob/main/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`](https://github.com/hbmartin/secure-design/blob/main/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.