# How the Design Iteration Workflow Manages Versioning and Naming in .superdesign

> Learn how the Secure Design extension manages versioning and naming in the .superdesign folder. Discover the hierarchical integer-based convention for traceable design iterations.

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

---

**The Secure Design extension uses a hierarchical integer-based naming convention within the `.superdesign/design_iterations` folder to ensure every generated UI mock-up has a unique, traceable version history.**

The **hbmartin/secure-design** repository implements a deterministic file versioning system that prevents naming collisions while maintaining clear iteration lineage. This workflow governs how AI-generated design files are created, updated, and organized within the VS Code workspace.

## The .superdesign/design_iterations Directory Structure

The extension establishes a dedicated workspace folder for all design artifacts. During activation, it creates the `.superdesign/design_iterations` path relative to the workspace root to isolate generated files from source code.

In [`src/extension.ts`](https://github.com/hbmartin/secure-design/blob/main/src/extension.ts), the initialization logic sets up this directory structure:

```typescript
// src/extension.ts
const superdesignFolder = vscode.Uri.joinPath(workspaceRoot, '.superdesign');
const designIterationsFolder = vscode.Uri.joinPath(superdesignFolder, 'design_iterations');
await vscode.workspace.fs.createDirectory(designIterationsFolder);

```

This folder serves as the canonical location for all HTML and SVG design outputs, ensuring the LLM always writes files to a predictable location.

## Naming Convention Rules

The workflow enforces strict naming patterns that encode version history directly into filenames. The convention varies based on whether the file represents a new component or an iteration of an existing design.

### First Design Creation

When generating an initial design for a component, the pattern follows `{design_name}_{n}.html`, where **n** represents the first available integer. For example, the first table design becomes [`table_1.html`](https://github.com/hbmartin/secure-design/blob/main/table_1.html).

### Subsequent Iterations

Creating new versions of the same component increments the integer while preserving the base name. The sequence progresses as [`table_2.html`](https://github.com/hbmartin/secure-design/blob/main/table_2.html), [`table_3.html`](https://github.com/hbmartin/secure-design/blob/main/table_3.html), and so forth, creating a linear version history.

### Hierarchical Versioning

When iterating on an already-generated file, the system appends an additional integer to the **current filename** rather than replacing it. A file named [`ui_1.html`](https://github.com/hbmartin/secure-design/blob/main/ui_1.html) spawns children like [`ui_1_1.html`](https://github.com/hbmartin/secure-design/blob/main/ui_1_1.html), [`ui_1_2.html`](https://github.com/hbmartin/secure-design/blob/main/ui_1_2.html), establishing a branching tree structure that preserves the parent-child relationship.

### SVG Asset Support

The same rules apply to SVG files, using the `.svg` extension instead of `.html`. Icons follow patterns like `icon_1.svg` or `icon_1_2.svg` depending on their position in the iteration chain.

## Implementation Across the Codebase

The versioning policy is enforced through three coordinated mechanisms that guide both the extension logic and the AI agent's behavior.

### Extension Activation and Prompt Injection

The extension embeds naming rules directly into the LLM's system prompt. In [`src/extension.ts`](https://github.com/hbmartin/secure-design/blob/main/src/extension.ts) (lines 210-212), the `designRuleContent` variable injects the following instruction:

```typescript
// src/extension.ts – design rule inserted into the agent prompt
// You ALWAYS output design files in '.superdesign/design_iterations' folder as
// {design_name}_{n}.html (where n is a unique integer, e.g. table_1.html, table_2.html)
// If iterating on an existing file, use {current_file_name}_{n}.html,
// e.g. ui_1.html → ui_1_1.html, ui_1_2.html, …

```

This ensures the AI model understands the versioning requirements before generating any files.

### Agent Instruction Set

The `CustomAgentService` reinforces these rules through dedicated instructions. According to [`src/services/customAgentService.ts`](https://github.com/hbmartin/secure-design/blob/main/src/services/customAgentService.ts) (lines 140-144), the agent receives explicit guidance:

```typescript
// src/services/customAgentService.ts
// You ALWAYS output design files in 'design_iterations' folder as
// {design_name}_{n}.html (Where n needs to be unique like table_1.html, table_2.html, etc.) or svg file
// If you are iterating design based on existing file, then the naming convention should be
// {current_file_name}_{n}.html, e.g. ui_1.html → ui_1_1.html, ui_1_2.html, etc.

```

This dual-layer enforcement (extension setup plus agent instructions) minimizes the risk of naming collisions.

### File Writing Operations

The actual disk operations occur through the write-tool utility. When the LLM selects a filename, [`src/tools/write-tool.ts`](https://github.com/hbmartin/secure-design/blob/main/src/tools/write-tool.ts) (line 86) executes the write operation:

```typescript
// src/tools/write-tool.ts (simplified)
const absolutePath = path.join(workspaceRoot, '.superdesign', 'design_iterations', 'button_3.html');
fs.writeFileSync(absolutePath, htmlContent, 'utf8');

```

The tool assumes the agent has already selected an unused numeric suffix, guaranteeing unique filenames on disk.

### Filename Parsing for UI Display

The webview interface uses utility functions to interpret versioned filenames. In [`src/webview/utils/gridLayout.ts`](https://github.com/hbmartin/secure-design/blob/main/src/webview/utils/gridLayout.ts) (line 372), the `parseFileName` function decomposes hierarchical names:

```typescript
// src/webview/utils/gridLayout.ts
// "text_1_3_1.html" → ["text", "1", "3", "1"]
function parseFileName(fileName: string): string[] {
  return fileName.replace(/\.(html|svg)$/, '').split('_');
}

```

This parsing enables the Canvas view to display version trees and track lineage across multiple iteration branches.

## Practical Workflow Example

Consider a scenario where a developer generates a button component and iterates twice:

1. **Initial creation**: The agent writes [`button_1.html`](https://github.com/hbmartin/secure-design/blob/main/button_1.html) to `.superdesign/design_iterations/`
2. **First iteration**: The agent creates [`button_1_1.html`](https://github.com/hbmartin/secure-design/blob/main/button_1_1.html) based on feedback
3. **Second iteration**: The agent generates [`button_1_2.html`](https://github.com/hbmartin/secure-design/blob/main/button_1_2.html) preserving the branch

If the developer instead requests a completely new button design unrelated to the first, the agent would create [`button_2.html`](https://github.com/hbmartin/secure-design/blob/main/button_2.html), maintaining parallel version histories.

## Summary

- **The `.superdesign/design_iterations` folder** serves as the isolated workspace for all generated design artifacts.
- **Integer-based naming** (`{name}_{n}.html`) ensures collision-free file creation while encoding version sequence.
- **Hierarchical iteration** supports branching workflows by appending additional integers to existing filenames.
- **Dual enforcement** through [`src/extension.ts`](https://github.com/hbmartin/secure-design/blob/main/src/extension.ts) prompt injection and [`src/services/customAgentService.ts`](https://github.com/hbmartin/secure-design/blob/main/src/services/customAgentService.ts) instructions ensures AI compliance.
- **Utility parsing** in [`src/webview/utils/gridLayout.ts`](https://github.com/hbmartin/secure-design/blob/main/src/webview/utils/gridLayout.ts) enables the UI to reconstruct version trees from filenames.

## Frequently Asked Questions

### How does the extension prevent filename collisions when multiple designs are created?

The extension relies on the LLM to select unused integer suffixes based on existing files in `.superdesign/design_iterations`. The naming convention rules embedded in [`src/extension.ts`](https://github.com/hbmartin/secure-design/blob/main/src/extension.ts) and [`src/services/customAgentService.ts`](https://github.com/hbmartin/secure-design/blob/main/src/services/customAgentService.ts) instruct the AI to scan the directory and choose the next available number, ensuring each file has a unique identifier.

### Can the versioning system handle branching design iterations?

Yes, the hierarchical naming convention supports complex branching. When iterating on [`design_1.html`](https://github.com/hbmartin/secure-design/blob/main/design_1.html), the system creates [`design_1_1.html`](https://github.com/hbmartin/secure-design/blob/main/design_1_1.html), and further iterations on that branch produce [`design_1_1_1.html`](https://github.com/hbmartin/secure-design/blob/main/design_1_1_1.html). The `parseFileName` function in [`src/webview/utils/gridLayout.ts`](https://github.com/hbmartin/secure-design/blob/main/src/webview/utils/gridLayout.ts) splits these underscore-delimited names to reconstruct the entire version tree for display.

### What file types does the Secure Design extension support?

The workflow supports both **HTML** and **SVG** file formats. While HTML files typically contain UI mock-ups and component layouts, SVG files store icon and graphic assets. Both use identical versioning conventions, differing only in their file extensions (`.html` vs `.svg`).

### Where is the physical file writing operation implemented?

The actual disk write occurs in [`src/tools/write-tool.ts`](https://github.com/hbmartin/secure-design/blob/main/src/tools/write-tool.ts) at line 86. This tool receives the target path constructed by the agent and executes `fs.writeFileSync` to create the file within the `.superdesign/design_iterations` directory, completing the workflow initiated by the extension's prompt rules.