How to Create Custom UI Templates for Different Image Categories: A Complete Guide

To create custom UI templates for different image categories in awesome-gpt-image-2, define a JSON prompt in docs/templates.md, register the template key in the uiPromptMap object inside src/main.jsx, and the existing src/apimartClient.js client automatically forwards the constructed prompt to the backend image generation API.

The awesome-gpt-image-2 repository by freestylefly structures its image generation prompts as reusable templates organized by category. When you need to generate specialized UI screenshots—such as mobile app interfaces, dashboard mockups, or social media layouts—you create custom UI templates for different image categories using a three-file architecture that separates template storage, frontend registration, and API transmission.

Understanding the UI Template Architecture

The repository decouples prompt definition from frontend logic using three core components. Template definitions reside in docs/templates.md under the UI与界面 (UI & Interfaces) section as structured JSON objects. The frontend mapping in src/main.jsx exposes these templates to users through the uiPromptMap object, which links category identifiers to template placeholders. Finally, src/apimartClient.js transmits the assembled prompt string to the backend via POST /api/generate-image without requiring modification for new templates.

Follow this architecture to add any custom UI category, from smartwatch faces to desktop application settings panels.

Step-by-Step Implementation Guide

Step 1 – Define the JSON Template in docs/templates.md

Create your template as a JSON object in the UI section of docs/templates.md. This structure describes the layout, platform, visual style, content slots, and generation constraints.

Include these required fields:

• type: Classification such as "UI Screenshot"
• platform: Target device (e.g., "Smartwatch", "iOS", "Desktop")
• product: Functional description of the interface
• layout: Spatial arrangement of elements
• style: Nested object containing theme, primary colors, and typography
• content: Widgets, headers, and data placeholders
• constraints: Aspect ratio, fidelity requirements, and readability rules

{
  "type": "UI Screenshot",
  "platform": "Smartwatch",
  "product": "Health Tracker",
  "layout": "Circular face with stacked widgets",
  "style": {
    "theme": "Dark Mode",
    "primary_color": "Deep Blue",
    "typography": "Rounded sans-serif"
  },
  "content": {
    "header": "Today's Stats",
    "widgets": [
      {"title": "Steps", "value": "8 342"},
      {"title": "Heart Rate", "value": "76 bpm"},
      {"title": "Sleep", "value": "7 h 12 m"}
    ]
  },
  "constraints": "High fidelity, 9:16 aspect ratio, readable numbers"
}

Step 2 – Register the Template in src/main.jsx

Make the frontend aware of your new category by adding an entry to the uiPromptMap object in src/main.jsx. This mapping connects the user-facing category identifier to the template reference.

const uiPromptMap = {
  // existing entries …
  "smartwatch-dashboard": `{{template:ui-smartwatch-dashboard}}`,
};

When a user selects "smartwatch-dashboard" from the UI category selector, the frontend retrieves this placeholder and prepares to inject the corresponding JSON template from docs/templates.md.

Step 3 – Configure Style Defaults in data/style-library.json (Optional)

To auto-populate the generation controls with specific defaults for your new category, add a configuration object to data/style-library.json. This step is optional but improves the user experience by pre-setting colors, themes, and aspect ratios.

"smartwatch-dashboard": {
  "primary_color": "Deep Blue",
  "theme": "Dark",
  "aspect_ratio": "9:16"
}

Step 4 – Generate Images via the API Client

The src/apimartClient.js file requires no modification when adding new templates. It forwards the finalized prompt string—which the frontend builds by merging the template with user inputs—to the backend generation endpoint.

import { apimartClient } from './apimartClient';

async function generateSmartwatchUI(prompt) {
  // prompt contains the JSON template after user substitution
  const response = await apimartClient.generateImage({ prompt });
  return response.url; // URL of the generated image
}

Complete Code Example: Adding a Smartwatch Dashboard Template

Here is the full implementation for adding a "Smartwatch Dashboard" category to awesome-gpt-image-2.

First, append the template to the UI section of docs/templates.md:

{
  "type": "UI Screenshot",
  "platform": "Smartwatch",
  "product": "Health Tracker",
  "layout": "Circular face with stacked widgets",
  "style": {
    "theme": "Dark Mode",
    "primary_color": "Deep Blue",
    "typography": "Rounded sans-serif"
  },
  "content": {
    "header": "Today's Stats",
    "widgets": [
      {"title": "Steps", "value": "8 342"},
      {"title": "Heart Rate", "value": "76 bpm"},
      {"title": "Sleep", "value": "7 h 12 m"}
    ]
  },
  "constraints": "High fidelity, 9:16 aspect ratio, readable numbers"
}

Next, update src/main.jsx to register the category:

const uiPromptMap = {
  // existing entries …
  "smartwatch-dashboard": `{{template:ui-smartwatch-dashboard}}`,
};

After restarting the development server, the UI displays a new "Smartwatch Dashboard" option. Selecting it loads the default values from data/style-library.json (if configured) and presents a generation form. Upon submission, src/apimartClient.js transmits the prompt to the backend, which processes it through the LLM-based image generator.

Summary

• Template storage: Define UI layouts as JSON objects in the UI & Interfaces section of docs/templates.md, specifying platform, style, content, and constraints.
• Frontend registration: Map category identifiers to template placeholders in the uiPromptMap object within src/main.jsx.
• API transmission: The existing client in src/apimartClient.js automatically forwards constructed prompts to POST /api/generate-image without code changes.
• Optional styling: Pre-configure UI controls by adding default values to data/style-library.json for your custom category.

Frequently Asked Questions

Where are UI templates stored in awesome-gpt-image-2?

UI templates are stored in docs/templates.md under the UI与界面 (UI & Interfaces) section. Each template is a JSON object describing the interface layout, visual style, and content structure. The frontend references these templates indirectly through the uiPromptMap mapping in src/main.jsx.

Do I need to modify the API client to add a new UI template?

No. The src/apimartClient.js file requires no changes when adding custom UI templates for different image categories. This file contains a generic generateImage method that forwards any prompt string to the backend endpoint. Once you register your template in src/main.jsx and define it in docs/templates.md, the existing client handles transmission automatically.

What JSON structure is required for UI templates?

UI templates must be valid JSON objects containing specific keys: type (e.g., "UI Screenshot"), platform (target device), product (interface purpose), layout (spatial description), style (nested object with theme and colors), content (widgets and data), and constraints (generation rules like aspect ratio). This structure ensures the LLM receives consistent formatting instructions.

Can I define default styles for my custom UI templates?

Yes. Add a corresponding entry to data/style-library.json using your template key (e.g., "smartwatch-dashboard"). Include properties such as primary_color, theme, and aspect_ratio. These values populate the frontend controls when users select your category, ensuring consistent styling across generations.

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