# Understanding the style-library.json Structure in awesome-gpt-image-2

> Explore the style-library.json structure in awesome-gpt-image-2. Discover how this JSON file defines metadata, tags, categories, styles, scenes, and templates for your image generation pipeline.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: api-reference
- Published: 2026-09-10

---

**The [`style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json) file in the awesome-gpt-image-2 repository defines a strict JSON schema with six top-level sections—metadata, tag labels, categories, styles, scenes, and templates—that serves as the single source of truth for the entire image generation pipeline.**

The [`style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json) file located at [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) controls every visual element and prompt template used by the Awesome-GPT-Image-2 system. This centralized configuration ensures consistency across the React front-end, the agent skill documentation, and the static site generation by establishing a hierarchical data structure that cross-references categories, styles, and scenes with individual templates.

## Top-Level Schema Architecture

The JSON file organizes data into a predictable hierarchy beginning with repository metadata and extending through localized translations and template definitions. At the root level, the schema contains version information, followed by arrays and objects that define the visual language of the system.

The hierarchy follows this structure:

```json
{
  "version": "string",
  "repository": "string", 
  "templateDocument": "string",
  "tagLabels": { ... },
  "categories": [ ... ],
  "styles": [ ... ],
  "scenes": [ ... ],
  "templates": [ ... ]
}

```

This structure enables the front-end to fetch the file directly at runtime, while build scripts consume it to generate documentation and skill definitions.

## The Six Core Sections

### Metadata

The metadata section occupies the first few lines of the file and establishes basic repository information. It includes three key fields:

- `version` — Tracks the schema version (line 2)
- `repository` — Points to the source repository URL (line 3)  
- `templateDocument` — References the documentation source (line 4)

These fields ensure that consuming applications can validate compatibility before processing the template data.

### Tag Labels

Tag labels provide human-readable translations for tag identifiers, supporting internationalization for English (`en`) and Chinese (`zh`) audiences. Stored as an object starting at line 5, each key maps a tag identifier (e.g., `Art`, `Campaign`) to localized strings:

```json
{
  "Art": { "en": "Art", "zh": "艺术" },
  "Campaign": { "en": "Campaign", "zh": "活动" }
}

```

This localization layer allows the UI to display appropriate labels based on the user's language preference without modifying the underlying tag identifiers used in template logic.

### Categories

Categories represent logical groupings of prompt templates, such as "UI & Interfaces" or "Charts & Infographics." Defined in an array spanning lines 32-88, each category object contains:

- `id` — Unique identifier
- `value` — Machine-readable key
- `anchor` — URL hash for direct linking
- `templateAnchor` — Reference point for template navigation
- `cover` — Image asset path
- `title` — Localized display names (`en`/`zh`)
- `description` — Localized explanatory text

Categories act as high-level buckets that organize the template library into browsable segments.

### Styles

The styles array (lines 90-109) defines individual visual styles that can be attached to templates, such as `3d`, `brand`, or `poster`. Each style object includes:

- `id` — Unique style identifier
- `value` — Machine-readable key
- `title` — Localized display names
- `keywords` — Optional array of search shortcuts

Styles function as an orthogonal dimension to categories, enabling fine-grained control over visual appearance regardless of the template's subject matter.

### Scenes

Scenes provide high-level usage contexts like `Tech`, `Commerce`, or `Education` (lines 111-126). Similar to styles, each scene contains `id`, `value`, `title`, and optional `keywords` fields. These contexts help users filter templates by narrative purpose or industry vertical, independent of the visual style or category classification.

### Templates

The templates array forms the core of the library, beginning at line 124 with the `ui-screenshot-system` template and continuing through line 818. Each template object declares:

- `id` — Unique template identifier
- `anchor` — UI routing anchor
- `cover` — Preview image path
- `title` and `description` — Localized content
- `category` — Human-readable category name (cross-reference)
- `styles` — Array of style identifiers (must exist in styles section)
- `scenes` — Array of scene identifiers (must exist in scenes section)
- `tags` — Array of tag references
- `guidance` — Usage instructions
- `pitfalls` — Common mistakes to avoid
- `examples` — Reference case IDs

This cross-referencing system ensures that every template maintains valid relationships to existing categories, styles, and scenes, preventing orphaned references across the ecosystem.

## Repository Integration Points

The [`style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json) file is consumed in three critical locations within the awesome-gpt-image-2 repository, ensuring synchronization between the data definition and its various presentations.

**Front-End Runtime**: The React application fetches [`/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main//style-library.json) directly at line 3623 in [`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx), using the data to render the interactive template browser and search interface.

**Skill Generation**: The `scripts/generate-style-skill.mjs` script reads the JSON at line 6 to automatically generate the Agent skill reference documentation located at [`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md).

**Site Generation**: The `scripts/generate-site-data.mjs` script processes the file at line 8 to produce static pages, ensuring the documentation website reflects the current template library state.

Because all three systems read from the same source file, updates to categories, styles, or templates propagate instantly across the UI, skill documentation, and generated site.

## Working with the JSON: Practical Examples

### Loading and Listing Categories

To fetch the library and extract all English category titles:

```javascript
fetch('/style-library.json')
  .then(response => response.json())
  .then(lib => {
    const titles = lib.categories.map(c => c.title.en);
    console.log('Available categories:', titles);
  });

```

### Filtering Templates by Style

To retrieve all templates that utilize the `Poster` style:

```javascript
fetch('/style-library.json')
  .then(response => response.json())
  .then(lib => {
    const posterTemplates = lib.templates.filter(t =>
      t.styles.includes('Poster')
    );
    console.log('Poster templates:', posterTemplates);
  });

```

### Resolving Scene Localized Titles

To map a scene ID to its localized display name:

```javascript
function sceneTitle(lib, sceneId, locale = 'en') {
  const scene = lib.scenes.find(s => s.id === sceneId);
  return scene ? scene.title[locale] : null;
}

```

These patterns demonstrate how the structured JSON enables efficient lookups for UI rendering, autocomplete functionality, and backend validation.

## Related Source Files

The following files interact directly with [`style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json) to maintain the system's single-source-of-truth architecture:

- **[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)** — The central configuration file containing all tags, categories, styles, scenes, and template definitions.
- **[`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)** — Front-end entry point that loads the JSON at line 3623 for the interactive React application.
- **`scripts/generate-style-skill.mjs`** — Node.js script that reads the JSON at line 6 to generate Agent skill documentation.
- **`scripts/generate-site-data.mjs`** — Build script that processes the JSON at line 8 to create static site pages.
- **[`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)** — Auto-generated documentation reflecting the current state of the style library.

## Summary

- The [`style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json) file uses a six-section schema: metadata, tag labels, categories, styles, scenes, and templates.
- Located at [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json), it serves as the single source of truth for the Awesome-GPT-Image-2 ecosystem.
- Templates cross-reference categories by name and styles/scenes by ID, ensuring data integrity across the pipeline.
- The file is consumed by the React front-end (line 3623 in [`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)), the skill generator (line 6 in `generate-style-skill.mjs`), and the site builder (line 8 in `generate-site-data.mjs`).
- Built-in localization support via `en` and `zh` fields enables internationalization without structural changes.

## Frequently Asked Questions

### What is the primary purpose of style-library.json in awesome-gpt-image-2?

The [`style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/style-library.json) file acts as the centralized configuration schema that defines every visual element, prompt template, and categorization rule used by the system. It enables consistent behavior across the web interface, agent skills, and documentation by providing a single JSON source that all components consume.

### How do templates reference categories, styles, and scenes?

Templates use string cross-references to maintain relationships: the `category` field contains the human-readable category name, while `styles` and `scenes` are arrays of identifiers that must match existing entries in the respective sections. This validation approach prevents orphaned references and ensures template metadata remains consistent with the defined taxonomy.

### Where is the style-library.json file actually used in the codebase?

The file is loaded in three specific locations: the React front-end fetches it at line 3623 in [`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx) for runtime rendering, the skill generator imports it at line 6 in `scripts/generate-style-skill.mjs` to create documentation, and the site builder reads it at line 8 in `scripts/generate-site-data.mjs` to generate static pages.

### Does the JSON structure support multiple languages?

Yes, the schema includes built-in internationalization through localized objects containing `en` (English) and `zh` (Chinese) fields. This pattern appears in tag labels (line 5 onwards), category titles and descriptions, style titles, scene titles, and template content, allowing the UI to switch languages without altering the underlying data structure.