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

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, the initialization logic sets up this directory structure:

// 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.

Subsequent Iterations

Creating new versions of the same component increments the integer while preserving the base name. The sequence progresses as table_2.html, 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 spawns children like ui_1_1.html, 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 (lines 210-212), the designRuleContent variable injects the following instruction:

// 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 (lines 140-144), the agent receives explicit guidance:

// 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 (line 86) executes the write operation:

// 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 (line 372), the parseFileName function decomposes hierarchical names:

// 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 to .superdesign/design_iterations/
2. First iteration: The agent creates button_1_1.html based on feedback
3. Second iteration: The agent generates 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, 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 prompt injection and src/services/customAgentService.ts instructions ensures AI compliance.
• Utility parsing in 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 and 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, the system creates design_1_1.html, and further iterations on that branch produce design_1_1_1.html. The parseFileName function in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}