Theme Architecture & Directory Structure

Detailed technical documentation and implementation guide for Theme Architecture & Directory Structure.

Overview & Theme Philosophy #

Official Theme Directory Structure #

Every JoonWeb theme follows a standardized file and folder hierarchy:

```text
your-theme/
├── layout.jw                  # Master HTML shell & global document wrapper
├── theme_config.json          # Theme metadata, color palette & typography presets
├── theme_structure.json       # Page templates layout & default section hierarchy
├── sections/                  # Dynamic storefront sections (.jw)
│   ├── header.jw              # Store navigation bar & announcements
│   ├── hero.jw                # Hero banners & sliders
│   ├── product-grid.jw        # Product catalogue listings
│   ├── cart.jw                # Shopping cart page & slide-over drawer
│   ├── card-slider.jw         # Featured collection carousel
│   ├── blog.jw                # Article feeds & news
│   ├── breadcrumb.jw          # Hierarchical page navigation
│   └── footer.jw              # Multi-column footer & copyright
├── components/                # Reusable template components (.jw)
│   ├── pagination.jw          # Reusable page navigation
│   ├── product-list.jw        # Product item card snippet
│   ├── product-filters.jw     # Faceted sidebar collection filters
│   ├── product-review.jw      # Customer reviews & ratings
│   └── wishlist.jw            # Wishlist trigger & counter
├── blocks/                    # Atomic nested block components (.jw)
│   ├── group.jw               # Layout wrapper & flex container block
│   └── myheading.jw           # Configurable typography block
├── assets/                    # Static theme assets (CDN-hosted)
│   ├── style.css              # Custom theme stylesheet
│   ├── index.js               # Theme interaction JavaScript
│   ├── apiClient.js           # Ajax API client helper
│   ├── slick.min.js           # Slider library
│   ├── aos.css                # Scroll animations CSS
│   └── fonts/                 # Custom web fonts (.ttf, .woff2)
└── apps/                      # Installed Theme App Extensions
    └── {app_id}/              # App-injected blocks and embeds (.jw & .json)
```

### Directory & File Roles

| Folder / File | Purpose |
|---|---|
| `layout.jw` | The root master layout wrapping every page (`<head>`, meta tags, header/footer inclusions, and main content outlet). |
| `theme_config.json` | Stores global theme metadata (`name`, `type`, `engine`), default typography, color palette, and presets. |
| `theme_structure.json` | Defines default section order and presets across templates (`home`, `product`, `collection`, `cart`). |
| `sections/` | Modular `.jw` sections that merchants can add, reorder, remove, and customize in the Site Builder. |
| `components/` | Reusable `.jw` snippets imported into sections (e.g. `product-list.jw`, `pagination.jw`). |
| `blocks/` | Atomic block elements that can be nested inside sections via the Site Builder. |
| `assets/` | Static CSS, JS, fonts, and images uploaded directly to CDN storage. |
| `apps/` | Dedicated directory where JoonWeb App Extensions automatically place app blocks and theme embeds. |

> 🔒 **Ignored Directories**: The folders `trash/`, `cache/`, and `rules/` are internal system folders. Theme developers and AI tools must never create or modify files inside these paths.

theme_config.json Architecture & Rules #

The `theme_config.json` file controls the global design tokens, typography, and color schemes across the entire storefront.

### Strict Schema Structure

```json
{
  "info": {
    "name": "Sporty Store",
    "type": "store",
    "author": "JoonWeb Design Team",
    "engine": 2
  },
  "default": {
    "fontStyle": {
      "heading": { "family": "Inter", "weight": "700" },
      "body": { "family": "Inter", "weight": "400" }
    },
    "colors": {
      "color1": "#0f172a",
      "color2": "#1e293b",
      "color3": "#2563eb",
      "color4": "#f8fafc",
      "color5": "#ffffff",
      "color6": "#64748b"
    }
  },
  "presets": [
    {
      "label": "Ocean Modern",
      "set": {
        "fontUnit": "px",
        "fontStyle": {
          "heading": { "family": "Outfit", "weight": "700" },
          "body": { "family": "Plus Jakarta Sans", "weight": "400" }
        },
        "colors": {
          "color1": "#0c4a6e",
          "color2": "#0284c7",
          "color3": "#38bdf8",
          "color4": "#f0f9ff",
          "color5": "#ffffff",
          "color6": "#475569"
        }
      }
    }
  ]
}
```

### Key Architectural Guidelines
1. **Mandatory Root Keys**:
   - `"info"`: Contains `"name"`, `"type"` (must strictly be either `"site"` or `"store"`), `"author"`, and `"engine"` (`1` or `2`, where `2` is latest).
   - `"default"`: Contains default typography (`fontStyle`) and base color palette (`colors`).
   - `"presets"`: Array of merchant-selectable color combinations and font pairings.
2. **Protected Keys**:
   - `"blocks"` and `"settings"` are protected system structures. Custom themes must not inject ad-hoc objects into these keys.
3. **Pure Valid JSON**: No trailing commas or unquoted keys are allowed; `theme_config.json` is validated upon every upload.

Last modified: Oct 08, 2026

Theme Architecture & Directory Structure

Overview & Theme Philosophy #

Official Theme Directory Structure #

theme_config.json Architecture & Rules #

Endpoint Title