diff --git a/.gitignore b/.gitignore
index 9f11b755a1..28e25b7665 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 .idea/
+.claude/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..d1ebb27aa1
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,74 @@
+# PrestaShop Developer Docs — Claude Context
+
+## Project
+
+Hugo static site. Source is Markdown with YAML front matter. Built with the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn/). Deployed at https://devdocs.prestashop-project.org/.
+
+Each major PrestaShop version has its own branch (`8.x`, `9.x`, …). This file lives on the `9.x` branch — all content paths are prefixed with `/9/`. If you are working on another branch, update the version prefix accordingly.
+
+## Hugo Conventions
+
+### Front matter (required on every page)
+
+```yaml
+---
+title: Page Title         # Required. Displayed as heading and in nav.
+menuTitle: Short Title    # Optional. Shorter title for the sidebar.
+weight: 10                # Required. Controls ordering (lower = higher).
+chapter: true             # Optional. Section landing pages only.
+showOnHomepage: true      # Optional. Shows on the docs home page.
+useMermaid: true          # Optional. Only when page uses Mermaid diagrams.
+aliases:                  # Optional. Hugo redirect aliases (see Redirects below).
+  - /9/old/path
+---
+```
+
+### Shortcodes
+
+```
+{{% notice note %}}        → Supplementary information
+{{% notice info %}}        → Important contextual information
+{{% notice tip %}}         → Best practice or recommendation
+{{% notice warning %}}     → Breaking change, deprecation, common pitfall
+{{% children /%}}          → Auto-list child pages (section landing pages)
+{{< relref "/9/..." >}}    → Internal cross-reference — always use relref, never raw paths
+{{< minver v="9.1" >}}     → Minimum version badge
+```
+
+### Images
+
+Stored in `img/` relative to the section. From a depth-1 page (e.g. `themes/concepts/page.md`) the path is `../../img/filename.png`. From depth-2 (e.g. `themes/concepts/templates/page.md`) it is `../../../img/filename.png`.
+
+### Internal links
+
+Always use `{{< relref "/9/section/page" >}}`. Never use relative paths.
+
+## Redirects
+
+When a page is moved or renamed, add an `aliases` key to the **new page's** front matter. Hugo generates a redirect HTML file at the old path automatically.
+
+```yaml
+aliases:
+  - /9/section/old/path/to/page
+```
+
+Multiple aliases are supported as a list. Use the full path from root including `/9/`.
+
+**Do not remove aliases once added** — external sites and search engines may link to old URLs.
+
+## Writing Style
+
+- Present tense, active voice, second person ("you").
+- "must" for requirements, "should" for recommendations, "can" for options.
+- No emojis. No marketing language. No merchant-facing guidance.
+- Lead with the most important information (inverted pyramid).
+- One concept per page when possible.
+- Audience: theme developers and module developers. Not merchants.
+
+## No Duplicate Content
+
+Each concept must live in exactly one place. If two pages need to cover the same information, the second page links to the first — it does not repeat the content.
+
+- Do not copy explanations, code examples, or configuration tables across pages
+- Do not summarize a page's content on another page — link to it instead
+- If you find duplicated content during an edit, remove it from the less authoritative page and add a link
diff --git a/basics/installation/_index.md b/basics/installation/_index.md
index 1db70d76d0..80fd873e1d 100644
--- a/basics/installation/_index.md
+++ b/basics/installation/_index.md
@@ -293,7 +293,7 @@ This problem may arise in case-insensitive file systems like MacOS due to a misc
 
 [getting-started-guide]: https://docs.prestashop-project.org/v.8-documentation/v/english/getting-started
 [system-requirements]: {{< relref "/9/basics/installation/system-requirements" >}}
-[clone-the-repository]: {{< relref "/9/themes/getting-started/setting-up-your-local-environment" >}}
+[clone-the-repository]: {{< relref "/9/themes/getting-started/environment-setup" >}}
 [compile-assets]: {{< relref "/9/development/compile-assets" >}}
 [webpack]: https://webpack.js.org/
 [composer]: https://getcomposer.org/download/
diff --git a/development/architecture/introduction.md b/development/architecture/introduction.md
index 6149ab20ec..5c8b5b8649 100644
--- a/development/architecture/introduction.md
+++ b/development/architecture/introduction.md
@@ -295,8 +295,8 @@ Remember the overview at the top of the article? Have a look at this more detail
 [MVC]: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
 [smarty]: https://www.smarty.net/
 [bootstrap]: https://getbootstrap.com/
-[child-theme]: {{< ref "/9/themes/reference/template-inheritance/parent-child-feature" >}}
-[theme-module-override]: {{< ref "/9/themes/reference/overriding-modules" >}}
+[child-theme]: {{< ref "/9/themes/create-a-theme/child-theme" >}}
+[theme-module-override]: {{< ref "/9/themes/concepts/overrides" >}}
 [twig]: https://twig.symfony.com/
 [github]: https://github.com/PrestaShop/prestashop-ui-kit/
 [autoupgrade]: https://github.com/PrestaShop/autoupgrade/
diff --git a/development/internationalization/rtl.md b/development/internationalization/rtl.md
index 746261c8e9..0bbcf348c1 100644
--- a/development/internationalization/rtl.md
+++ b/development/internationalization/rtl.md
@@ -32,4 +32,4 @@ If you changed something in your Back Office theme and you want your change to b
 
 {{< figure src="../img/rtl-edit-language.png" title="Toggling RTL for a language" >}}
 
-[rtl-support]: {{< ref "/9/themes/reference/rtl" >}}
+[rtl-support]: {{< ref "/9/themes/concepts/rtl" >}}
diff --git a/modules/core-updates/8.0.md b/modules/core-updates/8.0.md
index dcd61cddb8..a9cf166fcc 100644
--- a/modules/core-updates/8.0.md
+++ b/modules/core-updates/8.0.md
@@ -59,7 +59,7 @@ The `use_parent_assets` setting in `theme.yml`, when set to `true`, makes the ch
 
 To maintain the behavior of 1.7 and load the child theme's assets, `use_parent_assets` must be set to `false`.
 
-[More details in the theme.yml reference page]({{<relref "/9/themes/getting-started/theme-yml#parent--child-settings">}}).
+[More details in the theme.yml reference page]({{<relref "/9/themes/concepts/theme-structure#parentchild-settings">}}).
 
 #### Classic theme
 
diff --git a/modules/creation/displaying-content-in-front-office.md b/modules/creation/displaying-content-in-front-office.md
index 4e686f183d..a379d18f7b 100644
--- a/modules/creation/displaying-content-in-front-office.md
+++ b/modules/creation/displaying-content-in-front-office.md
@@ -416,7 +416,7 @@ name, or even your own name or initials, such as:
 
 ## List of Smarty variables
 
-You can find [a complete list of variables available in Smarty Templates on this page]({{< relref "/9/themes/reference/templates/variables" >}}).
+You can find [a complete list of variables available in Smarty Templates on this page]({{< relref "/9/themes/reference/template-variables" >}}).
 
 There are many other contextual hooks. If you need to display all of the
 current page's Smarty variables, add the following call:
diff --git a/themes/CLAUDE.md b/themes/CLAUDE.md
new file mode 100644
index 0000000000..d9ccb96a1b
--- /dev/null
+++ b/themes/CLAUDE.md
@@ -0,0 +1,47 @@
+# Themes Section — Claude Context
+
+This file is loaded in addition to the root `CLAUDE.md` when working inside `themes/`.
+
+## Section map
+
+| Directory | Purpose |
+|-----------|---------|
+| `getting-started/` | Fast path: requirements, quick start, environment setup |
+| `concepts/` | Generic PrestaShop theme system mechanics (any theme) |
+| `hummingbird/` | Reference theme implementation (self-contained) |
+| `create-a-theme/` | Step-by-step how-to guides |
+| `guidelines/` | Universal rules: coding standards, browser compat, accessibility |
+| `reference/` | Pure lookup tables: template variables, JS events, Smarty helpers |
+| `distribution/` | Validation and export |
+
+### concepts/ vs hummingbird/
+
+- `concepts/` = mechanics that apply to **any** PrestaShop theme
+- `hummingbird/` = Hummingbird-specific implementation details
+- Cross-reference between the two with "For Hummingbird specifics, see..." / "For how the API works, see..."
+
+## Documentation guidelines
+
+### Technology stack
+
+- **Hummingbird** is the reference theme. Always use it as the example implementation.
+- **Bootstrap 5.3** — not Bootstrap 4. Never document BS4 patterns as current.
+- **BEM** naming convention for CSS classes. Do not mention RSCSS.
+- **Smarty 4** template engine. Use `{extends}` / `{block}` inheritance, not `{include}` patterns.
+- **No jQuery** in theme code. jQuery is loaded by `core.js` for module backward compatibility only. New theme code must use vanilla JavaScript.
+- **`data-ps-*` attributes** for JavaScript DOM hooks — not `.js-` prefixed classes.
+- **Web Platform Baseline** as the browser compatibility reference — not fixed version numbers.
+- **Accessibility (EAA / WCAG 2.2 AA)** is a hard requirement, not optional.
+
+### What not to document
+
+- Classic theme directory structure or code examples
+- `_dev/` folder (Classic-specific build artifact)
+- Bourbon, RSCSS, or any deprecated CSS methodology
+- jQuery usage patterns for new code
+- Fixed browser version lists (e.g. "Chrome 90+")
+- PHP coding standards — those belong in core contribution docs
+- PrestaShop 1.6 or 1.7 patterns unless explaining a migration path
+- Merchant-facing guidance — audience is theme and module developers only
+
+`reference/` pages contain no narrative — pure lookup tables only. All explanatory content belongs in `concepts/` or `hummingbird/`.
diff --git a/themes/_index.md b/themes/_index.md
index 4a7e3b40dd..de79a1d551 100644
--- a/themes/_index.md
+++ b/themes/_index.md
@@ -11,12 +11,22 @@ icon: 'images/icons/themes.svg'
 
 # Themes
 
-The default PrestaShop installation offers the neutral "Classic theme", enabling merchants to quickly start their activity, whatever their business line.
+PrestaShop themes control the entire front-office experience: layout, templates, styles, and client-side behavior.
 
-Several marketplaces are available to get PrestaShop themes. As a graphic designer/front developer, you can put your themes up for sale on this marketplaces.
+Starting from PrestaShop 9.1, **[Hummingbird]({{< relref "/9/themes/hummingbird" >}})** is the default theme. It is built on Bootstrap 5.3, follows BEM conventions, and provides an accessibility-first, jQuery-free architecture.
 
-{{% notice note %}}
-A new theme, Hummingbird, is being developed by the maintainer team. While under develoment, [you can start to discover it here]({{<relref "/9/themes/hummingbird">}}).
+{{% notice warning %}}
+The **Classic theme is deprecated** for new development starting from PrestaShop 9.1. It remains available for backward compatibility but will not receive new features. For Classic-specific documentation, refer to the [v8 theme docs]({{< relref "/8/themes" >}}).
 {{% /notice %}}
 
-{{% children /%}}
+## Documentation structure
+
+| Section | What you'll find |
+|---------|-----------------|
+| **[Getting started]({{< relref "/9/themes/getting-started" >}})** | Requirements, quick start, environment setup |
+| **[Concepts]({{< relref "/9/themes/concepts" >}})** | How the PrestaShop theme system works, structure, templates, assets, hooks, overrides |
+| **[Hummingbird]({{< relref "/9/themes/hummingbird" >}})** | The reference theme, CSS architecture, JavaScript conventions, accessibility, workflow |
+| **[Create a theme]({{< relref "/9/themes/create-a-theme" >}})** | Step-by-step guides to build your own theme |
+| **[Guidelines]({{< relref "/9/themes/guidelines" >}})** | Coding standards, browser compatibility, accessibility requirements |
+| **[Reference]({{< relref "/9/themes/reference" >}})** | Lookup tables, template variables, JavaScript events, Smarty helpers |
+| **[Distribution]({{< relref "/9/themes/distribution" >}})** | Validation, testing, and exporting your theme |
diff --git a/themes/concepts/_index.md b/themes/concepts/_index.md
new file mode 100644
index 0000000000..3e5c249560
--- /dev/null
+++ b/themes/concepts/_index.md
@@ -0,0 +1,23 @@
+---
+title: Theme concepts
+menuTitle: Concepts
+weight: 10
+chapter: true
+showOnHomepage: true
+---
+
+# Theme concepts
+
+This section explains how the PrestaShop theme system works. These concepts apply to **any** PrestaShop theme — they are not specific to Hummingbird or any other theme implementation.
+
+| Page | Description |
+|------|-------------|
+| [Theme structure]({{< relref "/9/themes/concepts/theme-structure" >}}) | Directory layout, `theme.yml` reference, core assets |
+| [Templates]({{< relref "/9/themes/concepts/templates" >}}) | Layouts, inheritance, listing pages, head, notifications |
+| [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) | CSS/JS registration API, per-page assets, module integration |
+| [Hooks]({{< relref "/9/themes/concepts/hooks" >}}) | Extension points for modules in the front office |
+| [Overrides]({{< relref "/9/themes/concepts/overrides" >}}) | Module template/asset overrides and JS selector overrides |
+| [Translation]({{< relref "/9/themes/concepts/translation" >}}) | Internationalization for theme wordings |
+| [RTL support]({{< relref "/9/themes/concepts/rtl" >}}) | Right-to-left language stylesheet handling |
+
+For Hummingbird-specific architecture and conventions, see the [Hummingbird section]({{< relref "/9/themes/hummingbird" >}}).
diff --git a/themes/concepts/asset-management.md b/themes/concepts/asset-management.md
new file mode 100644
index 0000000000..2317f88c64
--- /dev/null
+++ b/themes/concepts/asset-management.md
@@ -0,0 +1,184 @@
+---
+title: Asset management
+weight: 3
+aliases:
+  - /9/themes/getting-started/asset-management
+  - /9/themes/getting-started/asset-management/webpack
+---
+
+# Asset management
+
+This page covers how PrestaShop registers, loads, and unregisters CSS and JavaScript assets in the front office.
+
+## Core assets
+
+PrestaShop automatically loads these files on every front-office page:
+
+| File | ID | Priority | Description |
+|------|----|----------|-------------|
+| `theme.css` | `theme-main` | 50 | Main theme stylesheet |
+| `rtl.css` | `theme-rtl` | 900 | Loaded only for RTL languages |
+| `custom.css` | `theme-custom` | 1000 | Empty override file, loaded last |
+| `core.js` | `corejs` | 0 | Event system, `prestashop` object, jQuery (for module compat) |
+| `theme.js` | `theme-main` | 50 | Main theme JavaScript |
+| `custom.js` | `theme-custom` | 1000 | Empty override file, loaded last |
+
+{{% notice tip %}}
+`custom.css` and `custom.js` are loaded last (priority 1000). Use them for quick overrides without modifying compiled theme files.
+{{% /notice %}}
+
+## Registering assets
+
+PrestaShop's `FrontController` provides `registerStylesheet()` and `registerJavascript()`. Both take three arguments:
+
+1. **ID** — Unique identifier. Registering an asset with an existing ID **replaces** the previous one (same array key). Prefix with your theme/module name to avoid collisions.
+2. **Relative path** — From the theme or PrestaShop root:
+   - `assets/css/product.css` for theme assets
+   - `modules/modulename/css/example.css` for module assets
+3. **Options** — Configuration array (see tables below).
+
+### Stylesheet options
+
+| Name | Values | Description |
+|------|--------|-------------|
+| media | `all` \| `screen` \| `print` \| … (default: `all`) | CSS media type |
+| priority | 0–999 (default: 50) | Lower number = loaded earlier in the HTML. Equal priorities keep registration order |
+| inline | `true` \| `false` (default: `false`) | Inline in `<style>` tag |
+| version | string (default: `null`) | Cache-busting query string |
+| needRtl | `true` \| `false` (default: `true`) | Automatically load the RTL variant if available |
+
+### JavaScript options
+
+| Name | Values | Description |
+|------|--------|-------------|
+| position | `head` \| `bottom` (default: `bottom`) | Load in `<head>` or before `</body>` |
+| priority | 0–999 (default: 50) | Lower number = loaded earlier in the HTML |
+| inline | `true` \| `false` (default: `false`) | Inline in `<script>` tag |
+| attributes | `async` \| `defer` (default: not set) | Loading attribute |
+| server | `local` \| `remote` (default: `local`) | Local path or remote URL |
+| version | string (default: `null`) | Cache-busting query string |
+
+## Registering in theme.yml
+
+Register per-page assets under the `assets` key. Page identifiers match the `php_self` property of each controller. Use `server: remote` for CDN or external URLs.
+
+{{% notice note %}}
+In `theme.yml`, the loading attribute key is `attribute` (singular), while the PHP API uses `attributes` (plural).
+{{% /notice %}}
+
+```yaml
+assets:
+  css:
+    # Page key matches the controller's php_self property
+    product:
+      - id: product-extra-style
+        path: assets/css/product.css
+        media: all
+        priority: 100
+  js:
+    # "all" loads the asset on every page
+    all:
+      - id: external-lib
+        path: assets/js/external-lib.js
+        priority: 30
+        position: bottom
+      # Remote asset (CDN, external URL)
+      - id: custom-cdn-js
+        path: //cdn-url.com/external-lib.js
+        priority: 200
+        server: remote
+    product:
+      - id: product-custom-lib
+        path: assets/js/product.js
+        priority: 200
+        attribute: async
+```
+
+## Registering in modules
+
+### Using the hook (most common)
+
+Modules without a front controller register assets via the `actionFrontControllerSetMedia` hook:
+
+```php
+public function hookActionFrontControllerSetMedia($params)
+{
+    // On a specific page
+    if ('product' === $this->context->controller->php_self) {
+        $this->context->controller->registerStylesheet(
+            'module-' . $this->name . '-style',
+            'modules/' . $this->name . '/css/style.css',
+            ['media' => 'all', 'priority' => 200]
+        );
+    }
+
+    // On every page
+    $this->context->controller->registerJavascript(
+        'module-' . $this->name . '-js',
+        'modules/' . $this->name . '/js/app.js',
+        ['position' => 'bottom', 'priority' => 200]
+    );
+}
+```
+
+### Using setMedia() (front controller modules)
+
+Modules that define their own front controller can extend `setMedia()` directly:
+
+```php
+public function setMedia()
+{
+    parent::setMedia();
+
+    $this->registerStylesheet(
+        'module-modulename-style',
+        'modules/' . $this->module->name . '/css/style.css',
+        ['media' => 'all', 'priority' => 200]
+    );
+
+    $this->registerJavascript(
+        'module-modulename-lib',
+        'modules/' . $this->module->name . '/js/lib.js',
+        ['priority' => 200, 'attributes' => 'async']
+    );
+}
+```
+
+## Unregistering assets
+
+### In themes
+
+Create an **empty file** at the override path inside your theme. PrestaShop resolves local assets by checking the theme directory first, so it loads the empty file instead of the module's original.
+
+```
+themes/mytheme/modules/modulename/views/css/style.css   # Empty file
+themes/mytheme/modules/modulename/views/js/file.js      # Empty file
+```
+
+{{% notice note %}}
+This only works for assets registered with a local relative path. Remote assets or inline scripts cannot be overridden this way — use `unregisterJavascript()` / `unregisterStylesheet()` instead.
+{{% /notice %}}
+
+### In modules
+
+Using the hook:
+
+```php
+public function hookActionFrontControllerSetMedia($params)
+{
+    $this->context->controller->unregisterStylesheet('module-example-style');
+    $this->context->controller->unregisterJavascript('module-example-js');
+}
+```
+
+Using `setMedia()` in a front controller module:
+
+```php
+public function setMedia()
+{
+    parent::setMedia();
+
+    $this->unregisterStylesheet('module-example-style');
+    $this->unregisterJavascript('module-example-js');
+}
+```
diff --git a/themes/concepts/hooks.md b/themes/concepts/hooks.md
new file mode 100644
index 0000000000..95ed78773a
--- /dev/null
+++ b/themes/concepts/hooks.md
@@ -0,0 +1,87 @@
+---
+title: Theme hooks
+weight: 4
+---
+
+# Theme hooks
+
+Hooks are extension points that allow modules to inject content or execute logic at specific locations in the front office. There are two types:
+
+- **Display hooks** — render HTML content in templates (e.g., `displayFooter`, `displayProductActions`)
+- **Action hooks** — trigger PHP logic without producing output (e.g., `actionFrontControllerSetMedia`, `actionProductOutOfStock`)
+
+As a theme developer, you mainly work with display hooks. For the full hook system, see [Hooks]({{< relref "/9/development/components/hook" >}}).
+
+## Using hooks in templates
+
+The `{hook}` Smarty function calls a hook and outputs the concatenated HTML returned by all modules attached to it:
+
+```smarty
+{hook h='displayFooter'}
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `h` | Hook name (required) |
+| `mod` | Restrict output to a single module by name |
+| `excl` | Exclude specific modules (comma-separated). Not recommended — prefer `modules_to_unhook` in `theme.yml` |
+
+Any additional parameters are passed through to the modules:
+
+```smarty
+{* Only output from the "mymodule" module *}
+{hook h='displayFooter' mod='mymodule'}
+
+{* Exclude specific modules *}
+{hook h='displayFooter' excl='blocknewsletter,ps_emailsubscription'}
+
+{* Pass custom variables to modules *}
+{hook h='displayFooterProduct' product=$product category=$category}
+```
+
+## Registering custom hooks
+
+Register hooks in your `config/theme.yml` so they appear in the Back Office and modules can attach to them:
+
+```yaml
+global_settings:
+  hooks:
+    custom_hooks:
+      - name: displayFooterBefore
+        title: displayFooterBefore
+        description: Add a widget area above the footer
+```
+
+Modules can also register hooks from PHP using `Hook::register('MyCustomHook')`.
+
+## Unhooking and hooking modules
+
+Remove modules from hooks using `modules_to_unhook`:
+
+```yaml
+global_settings:
+  hooks:
+    modules_to_unhook:
+      displayFooter:
+        - ps_socialfollow
+      displaySearch:
+        - ps_searchbar
+```
+
+Attach modules to hooks through `modules_to_hook`:
+
+```yaml
+global_settings:
+  hooks:
+    modules_to_hook:
+      displayHeaderTop:
+        - blocklanguages
+        - blockcurrencies
+        - blockuserinfo
+```
+
+See [Theme structure]({{< relref "/9/themes/concepts/theme-structure#hooks" >}}) for the full syntax including prepend, append, and page-specific hooks.
+
+For a visual map of all front-office hooks in the Hummingbird theme, see the [hook mapping]({{< relref "/9/themes/hummingbird/hooks" >}}).
diff --git a/themes/concepts/overrides.md b/themes/concepts/overrides.md
new file mode 100644
index 0000000000..dbf2ae3bb0
--- /dev/null
+++ b/themes/concepts/overrides.md
@@ -0,0 +1,110 @@
+---
+title: Overrides
+weight: 5
+aliases:
+  - /9/themes/reference/overriding-modules
+  - /9/themes/reference/overriding-selectors
+---
+
+# Overrides
+
+PrestaShop provides two override mechanisms for themes: **module overrides** (templates and assets) and **selector overrides** (JavaScript targeting).
+
+## Module overrides
+
+Themes can override a module's templates, CSS, and JavaScript by placing files at specific paths in the theme's `modules/` directory.
+
+### How it works
+
+Given a module `ps_featuredproducts` with this structure:
+
+```
+modules/ps_featuredproducts/
+├── css/
+│   └── style.css
+├── js/
+│   └── app.js
+└── views/
+    └── templates/
+        └── front/
+            └── ps_featuredproducts.tpl
+```
+
+Override it by mirroring the structure in your theme:
+
+```
+themes/mytheme/
+└── modules/
+    └── ps_featuredproducts/
+        ├── css/
+        │   └── style.css
+        ├── js/
+        │   └── app.js
+        └── views/
+            └── templates/
+                └── front/
+                    └── ps_featuredproducts.tpl
+```
+
+PrestaShop looks for overrides in this order:
+
+1. `/themes/THEME_NAME/modules/MODULE_NAME/...`
+2. `/modules/MODULE_NAME/...`
+
+{{% notice note %}}
+An empty override file tells PrestaShop to load nothing — neither the module's original nor the override. This is useful for removing a module's default styles when you handle them in your theme's compiled CSS.
+{{% /notice %}}
+
+### Template includes
+
+Module templates often include sub-templates (partials). How those includes are written determines whether your theme overrides apply to them.
+
+**The problem with relative paths:**
+
+If a module uses a relative path:
+
+```smarty
+{include file='./_partials/product-card.tpl'}
+```
+
+Smarty resolves this relative to the **original module directory**, not your theme's override directory. Even if you override the main template, the partial still loads from the module — your override of the partial is ignored.
+
+**The solution: `module:` resource prefix:**
+
+```smarty
+{include file='module:ps_featuredproducts/views/templates/front/_partials/product-card.tpl'}
+```
+
+The `module:` prefix tells PrestaShop to resolve the path through its override chain. It checks your theme's `modules/` directory first, then falls back to the original module path. This means theme overrides work for both the parent template and any included partials.
+
+{{% notice warning %}}
+If a module you need to override uses relative includes, you must override **every** included file alongside the main template. Contact the module developer to suggest switching to the `module:` prefix for better theme compatibility.
+{{% /notice %}}
+
+### Debugging overrides
+
+With Developer Mode enabled (`_PS_MODE_DEV_` set to `true` or activated in **"Advanced Parameters" > "Performance"**), HTML comments show the source path of each rendered template:
+
+```html
+<!-- begin /var/www/html/themes/mytheme/modules/ps_featuredproducts/... -->
+...
+<!-- end /var/www/html/themes/mytheme/modules/ps_featuredproducts/... -->
+```
+
+## Selector overrides
+
+PrestaShop's core JavaScript exposes a centralized **selector map** on `prestashop.selectors` for DOM targeting. Themes and modules can override these selectors to use custom markup without breaking core functionality.
+
+### Overriding core selectors
+
+The core emits a `selectorsInit` event after defining `prestashop.selectors`. Listen to it to modify selectors before they are used.
+
+Illustrative example:
+
+```js
+prestashop.on('selectorsInit', () => {
+  prestashop.selectors.cart.lineProductQuantity = '[data-ps-component="cart-quantity"]';
+});
+```
+
+If your script loads after `core.js`, you can modify the map directly without listening to the event.
\ No newline at end of file
diff --git a/themes/concepts/rtl.md b/themes/concepts/rtl.md
new file mode 100644
index 0000000000..81fecc07e3
--- /dev/null
+++ b/themes/concepts/rtl.md
@@ -0,0 +1,63 @@
+---
+title: RTL support
+weight: 7
+aliases:
+  - /9/themes/reference/rtl
+---
+
+# RTL support
+
+PrestaShop supports RTL (Right-to-Left) languages like Arabic, Hebrew, and Farsi. When an RTL language is active, PrestaShop adds a `lang-rtl` CSS class to the `<body>` tag and automatically loads RTL-specific stylesheets, allowing your theme to mirror its layout.
+
+## RTL stylesheets
+
+There are two approaches to providing RTL styles:
+
+### CSS override file
+
+PrestaShop loads `rtl.css` (ID: `theme-rtl`, priority: 900) after your theme's main stylesheets when an RTL language is active. Use this file for RTL-specific overrides.
+
+### RTL variant files
+
+When the shop displays an RTL language, PrestaShop automatically loads RTL variants of stylesheets if they exist. Variants are discovered by appending `_rtl` to the filename:
+
+| Original | RTL variant |
+|----------|-------------|
+| `theme.css` | `theme_rtl.css` |
+| `custom.css` | `custom_rtl.css` |
+
+## Automatic generation
+
+PrestaShop can generate RTL stylesheets from your original CSS:
+
+1. Go to **"Design" > "Theme & Logo"** in the Back Office.
+2. Go to **"Adaptation to right-to-left languages"** (visible only with an RTL language installed).
+3. Select your theme, toggle **"Generate RTL stylesheet"** to **Yes**, and save.
+
+This generates `_rtl.css` files for every `.css` file in the theme.
+
+{{% notice info %}}
+PrestaShop will not overwrite existing `_rtl.css` files. Delete them first to regenerate.
+{{% /notice %}}
+
+![RTL stylesheet generation in the Back Office](../../img/rtl-generate.png)
+
+## Fine-tuning with .rtlfix files
+
+The automatic RTL generation isn't always perfect — some CSS rules may not convert correctly. To fix these issues, **don't edit the generated `_rtl.css` files** because they will be overwritten next time you regenerate.
+
+Instead, create a `.rtlfix` file with the same name as your original stylesheet. PrestaShop will append its contents to the generated RTL file automatically.
+
+**Example:** your theme has `assets/css/theme.css`. After generation, you notice a spacing issue in `assets/css/theme_rtl.css`. To fix it:
+
+1. Create `assets/css/theme.rtlfix` with your corrections.
+2. Delete `assets/css/theme_rtl.css`.
+3. Regenerate from the Back Office.
+
+PrestaShop will generate a fresh `theme_rtl.css` from `theme.css`, then append the contents of `theme.rtlfix` at the end — your fixes are preserved across regenerations.
+
+## Best practices
+
+{{% notice tip %}}
+Use CSS logical properties (`margin-inline-start`, `padding-inline-end`, `inset-inline-start`, etc.) instead of physical ones (`margin-left`, `padding-right`, `left`). Logical properties automatically adapt to text direction, reducing the need for RTL-specific overrides.
+{{% /notice %}}
diff --git a/themes/concepts/templates/_index.md b/themes/concepts/templates/_index.md
new file mode 100644
index 0000000000..6c8cd9c91a
--- /dev/null
+++ b/themes/concepts/templates/_index.md
@@ -0,0 +1,22 @@
+---
+title: Templates
+weight: 2
+useMermaid: true
+disableToc: true
+aliases:
+  - /9/themes/reference/templates
+---
+
+# Templates
+
+This section covers how PrestaShop uses Smarty templates to render front-office pages — from directory structure and layouts to inheritance, listing pages, and the notification system.
+
+PrestaShop uses the [Smarty 4 template engine](https://smarty-php.github.io/smarty/). Templates define page content; layouts define page structure.
+
+| Page | Description |
+|------|-------------|
+| [Templates and layouts]({{< relref "/9/themes/concepts/templates/templates-and-layouts" >}}) | Directory structure, templates vs layouts, layout examples, template resolution |
+| [Template inheritance]({{< relref "/9/themes/concepts/templates/template-inheritance" >}}) | `{extends}`, `{block}`, building on parent templates |
+| [Listing pages]({{< relref "/9/themes/concepts/templates/listing-pages" >}}) | Shared product list template, `$listing` variable, AJAX updates |
+| [Head]({{< relref "/9/themes/concepts/templates/head" >}}) | Asset loading partials, SEO meta tags |
+| [Notifications]({{< relref "/9/themes/concepts/templates/notifications" >}}) | Notification types, customization, pushing from PHP |
diff --git a/themes/concepts/templates/head.md b/themes/concepts/templates/head.md
new file mode 100644
index 0000000000..b2c1c8f71d
--- /dev/null
+++ b/themes/concepts/templates/head.md
@@ -0,0 +1,58 @@
+---
+title: Head
+weight: 4
+aliases:
+  - /9/themes/reference/templates/head
+---
+
+# Head
+
+This page covers how PrestaShop themes handle asset loading and SEO meta tags in the `<head>` section.
+
+## Assets
+
+Two partial templates handle asset loading:
+
+- `_partials/stylesheets.tpl` — loops over registered stylesheets
+- `_partials/javascript.tpl` — loops over registered scripts, supports async loading
+
+```smarty
+{block name='stylesheets'}
+  {include file="_partials/stylesheets.tpl" stylesheets=$stylesheets}
+{/block}
+
+{block name='javascript_head'}
+  {include file="_partials/javascript.tpl" javascript=$javascript.head vars=$js_custom_vars}
+{/block}
+```
+
+`_partials/javascript.tpl` must also be included at the bottom of your layout for deferred scripts:
+
+```smarty
+{block name='javascript_bottom'}
+  {include file="_partials/javascript.tpl" javascript=$javascript.bottom}
+{/block}
+```
+
+The `$stylesheets` and `$javascript` variables are populated automatically by PrestaShop from all assets registered by the theme and modules. See [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) for the registration API.
+
+The `$js_custom_vars` variable is a key/value array of PHP variables exposed to JavaScript before any scripts run. It allows controllers and modules to pass server-side values (IDs, URLs, translated strings) into the front-end without inline `<script>` blocks in templates.
+
+## SEO
+
+SEO meta tags are grouped inside a `head_seo` block. Sub-blocks allow overriding individual tags without rewriting the entire block:
+
+```smarty
+{block name='head_seo'}
+  <title>{block name='head_seo_title'}{$page.meta.title}{/block}</title>
+  <meta name="description" content="{block name='head_seo_description'}{$page.meta.description}{/block}">
+  <meta name="robots" content="{block name='head_seo_robots'}{$page.meta.robots}{/block}">
+  <link rel="canonical" href="{block name='head_seo_canonical'}{$page.canonical}{/block}">
+{/block}
+```
+
+To override a single tag in a child template or a child theme, target the specific sub-block:
+
+```smarty
+{block name='head_seo_robots'}noindex,nofollow{/block}
+```
diff --git a/themes/concepts/templates/img/inheritance-schema.png b/themes/concepts/templates/img/inheritance-schema.png
new file mode 100644
index 0000000000..0ac0cd9e44
Binary files /dev/null and b/themes/concepts/templates/img/inheritance-schema.png differ
diff --git a/themes/concepts/templates/listing-pages.md b/themes/concepts/templates/listing-pages.md
new file mode 100644
index 0000000000..33b3334cf5
--- /dev/null
+++ b/themes/concepts/templates/listing-pages.md
@@ -0,0 +1,83 @@
+---
+title: Listing pages
+weight: 3
+aliases:
+  - /9/themes/reference/templates/listing
+---
+
+# Listing pages
+
+This page covers how PrestaShop handles product listing pages and how the product list updates dynamically via AJAX.
+
+Any page that displays a list of products — category, search results, new products, best sellers, etc. — uses the same listing system. They all share the same base template (`catalog/listing/product-list.tpl`) and receive the same `$listing` variable from their controller. Specific pages extend the base template and override only what differs.
+
+See [Template inheritance]({{< relref "/9/themes/concepts/templates/template-inheritance" >}}) for a real-world example.
+
+## The `$listing` variable
+
+All listing controllers provide the same `$listing` variable to the template. It contains everything needed to render the product list:
+
+| Key | Description |
+|-----|-------------|
+| `$listing.label` | Page title (e.g., category name, "Search results") |
+| `$listing.products` | Array of product data |
+| `$listing.pagination` | Pagination info (total, pages, current page) |
+| `$listing.sort_orders` | Available sort options |
+| `$listing.sort_selected` | Currently active sort option |
+| `$listing.facets` | Faceted search filters (when a filter module is active) |
+
+## Sub-templates
+
+The product list area is split into three sub-templates, each wrapped in a container with a specific ID:
+
+| Template | Container ID | Content |
+|----------|-------------|---------|
+| `catalog/_partials/products-top.tpl` | `#js-product-list-top` | Sort options, result count, display mode |
+| `catalog/_partials/products.tpl` | `#js-product-list` | The product grid/list itself |
+| `catalog/_partials/products-bottom.tpl` | `#js-product-list-bottom` | Pagination |
+
+This separation exists because of how AJAX updates work (see below).
+
+## AJAX page updates
+
+When customers change sort order or paginate, PrestaShop updates the product list **without a full page reload**. Filter modules (like `ps_facetedsearch`) also use this same system to refresh results dynamically.
+
+A key design decision: PrestaShop renders the updated HTML **server-side** and sends it back to the theme. The theme's JavaScript only needs to replace DOM placeholders — it does not need to parse JSON and reconstruct markup. This ensures no presentation logic is duplicated between Smarty and JavaScript.
+
+### How it works
+
+1. The customer interacts with a sort, pagination, or filter option.
+2. `core.js` intercepts the action and sends an AJAX request to the server.
+3. The server re-renders the sub-templates.
+4. PrestaShop emits the `updateProductList` event with the rendered HTML.
+5. Your theme replaces the corresponding DOM elements.
+
+### Handling the event
+
+```js
+if (typeof prestashop !== 'undefined') {
+  prestashop.on('updateProductList', (data) => {
+    updateProductListDOM(data);
+  });
+}
+
+function updateProductListDOM(data) {
+  document.querySelector('#js-product-list-top').replaceWith(data.rendered_products_top);
+  document.querySelector('#js-product-list').replaceWith(data.rendered_products);
+  document.querySelector('#js-product-list-bottom').replaceWith(data.rendered_products_bottom);
+}
+```
+
+| `data` property | Contains |
+|-----------------|----------|
+| `rendered_products_top` | Sort bar and result count HTML |
+| `rendered_products` | Product grid/list HTML |
+| `rendered_products_bottom` | Pagination HTML |
+| `rendered_facets` | Filter sidebar HTML (when a filter module is active) |
+| `rendered_active_filters` | Active filter tags HTML (when a filter module is active) |
+
+{{% notice warning %}}
+If you change the container IDs (`#js-product-list`, `#js-product-list-top`, `#js-product-list-bottom`) in your templates, make sure your JavaScript targets the new IDs — otherwise AJAX updates will silently fail.
+{{% /notice %}}
+
+See [JavaScript events]({{< relref "/9/themes/reference/javascript-events" >}}) for the full list of core events.
diff --git a/themes/concepts/templates/notifications.md b/themes/concepts/templates/notifications.md
new file mode 100644
index 0000000000..c37916f8b7
--- /dev/null
+++ b/themes/concepts/templates/notifications.md
@@ -0,0 +1,35 @@
+---
+title: Notifications
+weight: 5
+aliases:
+  - /9/themes/reference/templates/notifications
+---
+
+# Notifications
+
+PrestaShop provides a notification system to display feedback messages to the customer after actions like form submissions, cart updates, or account changes.
+
+Notifications are available in every template via the `$notifications` variable. They are rendered in a partial included from the layout:
+
+```smarty
+{block name='notifications'}
+  {include file='_partials/notifications.tpl'}
+{/block}
+```
+
+You can customize how notifications are displayed by editing `_partials/notifications.tpl`.
+
+## Notification types
+
+| Type | Variable | Typical use |
+|------|----------|-------------|
+| `success` | `{$notifications.success}` | Action completed |
+| `error` | `{$notifications.error}` | Validation failure, processing error |
+| `warning` | `{$notifications.warning}` | Non-blocking issue |
+| `info` | `{$notifications.info}` | Informational message |
+
+Each type is an array of message strings. If the array is empty, no notification of that type should be displayed.
+
+## Pushing notifications from PHP
+
+On the PHP side, front controllers can add messages to four arrays: `$this->success`, `$this->errors`, `$this->warning`, and `$this->info`. To display them after a redirect, use `$this->redirectWithNotifications()` which stores the messages in the session and clears them once they have been displayed — they are shown once and gone.
diff --git a/themes/concepts/templates/template-inheritance.md b/themes/concepts/templates/template-inheritance.md
new file mode 100644
index 0000000000..cb28ef8567
--- /dev/null
+++ b/themes/concepts/templates/template-inheritance.md
@@ -0,0 +1,119 @@
+---
+title: Template inheritance
+weight: 2
+aliases:
+  - /9/themes/reference/template-inheritance
+---
+
+# Template inheritance
+
+Template inheritance allows you to extend a parent template and only redefine the blocks you need. A parent template defines named `{block}` regions; a child template extends it with `{extends}` and overrides only the blocks it wants to change. Everything else is inherited as-is.
+
+The illustration below shows an illustrative example: `page.tpl` defines the global page structure, `product.tpl` extends it with product-specific content, and `product-pack.tpl` extends the product page to only override the description part — everything else is inherited.
+
+![Template inheritance schema](../../../img/inheritance-schema.png)
+
+The wrong way of doing this would be to extract header, footer, and reusable parts into fragments and `{include}` them in each file. This leads to duplication and makes changes harder to maintain.
+
+As the [official Smarty documentation](https://www.smarty.net/inheritance) puts it:
+
+> Template inheritance is an approach to managing templates that resembles object-oriented programming techniques. Instead of the traditional use of `{include …}` tags to manage parts of templates, you can inherit the contents of one template to another (like extending a class) and change blocks of content therein (like overriding methods of a class). This keeps template management minimal and efficient, since each template only contains the differences from the template it extends.
+
+## Real-world example: product listing pages
+
+Many pages display a list of products: categories, new products, search results, best sellers. They all extend `catalog/listing/product-list.tpl`:
+
+```smarty
+{* catalog/listing/product-list.tpl — shared base for all listing pages *}
+{extends file=$layout}
+
+{block name='content'}
+  {block name='product_list_header'}
+    {include file='components/page-title-section.tpl' title=$listing.label}
+  {/block}
+
+  {hook h='displayHeaderCategory'}
+
+  {if $listing.products|count}
+    {block name='product_list_top'}
+      {include file='catalog/_partials/products-top.tpl' listing=$listing}
+    {/block}
+
+    {block name='product_list_active_filters'}
+      {$listing.rendered_active_filters nofilter}
+    {/block}
+
+    {block name='product_list'}
+      {include file='catalog/_partials/products.tpl' listing=$listing}
+    {/block}
+
+    {block name='product_list_bottom'}
+      {include file='catalog/_partials/products-bottom.tpl' listing=$listing}
+    {/block}
+  {else}
+    {include file='errors/not-found.tpl'}
+  {/if}
+
+  {block name='product_list_footer'}{/block}
+{/block}
+```
+
+The base template handles the title, filters, product grid, pagination, and an empty state. For the category page, only the header and footer blocks are overridden to add category-specific content:
+
+```smarty
+{* catalog/listing/category.tpl — only overrides what differs *}
+{extends file='catalog/listing/product-list.tpl'}
+
+{block name='product_list_header'}
+  {include file='catalog/_partials/category-header.tpl' listing=$listing category=$category}
+{/block}
+
+{block name='product_list_footer'}
+  {include file='catalog/_partials/category-footer.tpl' listing=$listing category=$category}
+{/block}
+```
+
+Everything else — the product grid, pagination, filters, empty state — is inherited from the base template.
+
+## Block strategies
+
+Smarty provides three ways to override a block in a child template:
+
+| Strategy | Syntax | Behavior |
+|----------|--------|----------|
+| **Replace** | `{block name='foo'}...{/block}` | Completely replaces the parent block content |
+| **Prepend** | `{block name='foo' prepend}...{/block}` | Adds content **before** the parent block content |
+| **Append** | `{block name='foo' append}...{/block}` | Adds content **after** the parent block content |
+
+```smarty
+{* Keep the original header and add a promotional banner below it *}
+{block name='product_list_header' append}
+  <div class="promo-banner">Free shipping on orders over $50</div>
+{/block}
+```
+
+### Referencing parent and child content
+
+For more control than prepend/append, Smarty provides two special variables:
+
+`{$smarty.block.parent}` — used in a **child** template to insert the parent's block content at a specific position:
+
+```smarty
+{block name='product_list_header'}
+  <div class="custom-wrapper">
+    {$smarty.block.parent}
+  </div>
+{/block}
+```
+
+`{$smarty.block.child}` — used in a **parent** template to reference what the child will inject, useful for wrapping child content:
+
+```smarty
+{block name='page_title'}
+  <h1>{$smarty.block.child}</h1>
+{/block}
+```
+
+{{% notice tip %}}
+Define as many blocks as possible in your base templates. This gives child themes and overrides more granular control without needing to duplicate large sections.
+{{% /notice %}}
\ No newline at end of file
diff --git a/themes/concepts/templates/templates-and-layouts.md b/themes/concepts/templates/templates-and-layouts.md
new file mode 100644
index 0000000000..0a4749ff08
--- /dev/null
+++ b/themes/concepts/templates/templates-and-layouts.md
@@ -0,0 +1,154 @@
+---
+title: Templates and layouts
+weight: 1
+useMermaid: true
+aliases:
+  - /9/themes/concepts/templates-and-layouts
+  - /9/themes/reference/templates/templates-layouts
+---
+
+# Templates and layouts
+
+This page explains the directory structure, the difference between templates and layouts, and how PrestaShop resolves which template to use.
+
+## Template directory structure
+
+All template files live in the theme's `templates/` folder:
+
+| Directory | Content |
+|-----------|---------|
+| `_partials/` | Shared fragments — header, footer, breadcrumb, notifications |
+| `catalog/` | Product pages, listing pages, search results |
+| `checkout/` | Cart, checkout flow, order confirmation |
+| `cms/` | Static pages, sitemap, stores |
+| `components/` | Reusable UI components — introduced by [Hummingbird]({{< relref "/9/themes/hummingbird" >}}) |
+| `customer/` | Account pages, order history, addresses |
+| `errors/` | 404, forbidden, server error pages |
+| `layouts/` | Page layouts (full-width, columns, etc.) |
+
+## Templates vs layouts
+
+- A **layout** defines the global page structure: HTML shell, header, footer, and column arrangement. It never contains page-specific content.
+- A **template** fills in the content for a specific page by extending a layout and overriding its blocks.
+
+To illustrate, here is how the product page is built:
+
+1. `layout-both-columns.tpl` — the root layout, renders the HTML shell with header, footer, and sidebars
+2. `layout-full-width.tpl` — extends it and removes the sidebars
+3. `catalog/product.tpl` — the page template, extends the layout and fills in the product content
+
+Some pages add an extra step: `page.tpl` is a generic page wrapper (title, content area, footer) that also extends `$layout`. Simple pages like CMS or contact extend `page.tpl` instead of the layout directly, inheriting its common structure.
+
+See [Template inheritance]({{< relref "/9/themes/concepts/templates/template-inheritance" >}}) for a detailed guide on `{extends}`, `{block}`, and how to build on parent templates.
+
+## Layouts
+
+A layout is the top of the inheritance tree — it holds the `<html>`, `<head>`, and `<body>` tags. Users can choose a layout per page from the Back Office.
+
+The `$layout` variable is set by the front controller based on the layout assigned to the current page. Default assignments are defined in `theme.yml`, but can be overridden per page via _Design > Theme & Logo > Choose layouts_ in the Back Office.
+
+![Choose layouts](../../../img/choose-layouts.png)
+
+### A typical layout
+
+Here is a simplified version of a full-width layout, showing the main blocks that page templates can override:
+
+```smarty
+<!doctype html>
+<html lang="{$language.iso_code}">
+<head>
+  {block name='head'}
+    {* Loads stylesheets, meta tags, JS head *}
+    {include file='_partials/head.tpl'}
+  {/block}
+</head>
+
+{* classnames modifier converts the body_classes array into a CSS class string *}
+<body id="{$page.page_name}" class="{$page.body_classes|classnames}">
+  {hook h='displayAfterBodyOpeningTag'}
+
+  <main>
+    <header id="header">
+      {block name='header'}
+        {include file='_partials/header.tpl'}
+      {/block}
+    </header>
+
+    <section id="wrapper">
+      {block name='breadcrumb'}
+        {include file='_partials/breadcrumb.tpl'}
+      {/block}
+
+      {block name="content_wrapper"}
+        <div id="content-wrapper">
+          {block name="content"}
+            {* Page templates override this block with their content *}
+            <p>Default content placeholder.</p>
+          {/block}
+        </div>
+      {/block}
+    </section>
+
+    <footer id="footer">
+      {block name="footer"}
+        {include file="_partials/footer.tpl"}
+      {/block}
+    </footer>
+  </main>
+
+  {hook h='displayBeforeBodyClosingTag'}
+
+  {block name='javascript_bottom'}
+    {include file="_partials/javascript.tpl" javascript=$javascript.bottom}
+  {/block}
+</body>
+</html>
+```
+
+## Template resolution order
+
+PrestaShop resolves templates dynamically based on the **locale** and **entity ID**. This lets you create per-product, per-category, or per-locale templates without modifying the defaults — useful for stores with multiple languages or pages that need a unique layout.
+
+PrestaShop checks multiple locations and uses the **first match found**, from most specific to least specific.
+
+### Product page example
+
+For a product with ID 3 and locale `en-US`, PrestaShop looks for:
+
+1. `en-US/catalog/product-3.tpl` — locale + entity ID
+2. `catalog/product-3.tpl` — entity ID only
+3. `en-US/catalog/product.tpl` — locale only
+4. `catalog/product.tpl` — default
+
+<div class="mermaid">
+graph TD;
+    A(en-US/catalog/product-3.tpl)
+    A-->B(catalog/product-3.tpl);
+    B-->C(en-US/catalog/product.tpl);
+    C-->D(catalog/product.tpl);
+</div>
+
+### Category page example
+
+Listing pages have an additional fallback: if no category-specific template is found, PrestaShop falls back to the generic `product-list.tpl`. For category ID 9 with locale `en-US`:
+
+1. `en-US/catalog/listing/category-9.tpl`
+2. `catalog/listing/category-9.tpl`
+3. `en-US/catalog/listing/category.tpl`
+4. `catalog/listing/category.tpl`
+5. `en-US/catalog/listing/product-list.tpl`
+6. `catalog/listing/product-list.tpl` — final fallback
+
+<div class="mermaid">
+graph TD;
+    A(en-US/catalog/listing/category-9.tpl)
+    A-->B(catalog/listing/category-9.tpl);
+    B-->C(en-US/catalog/listing/category.tpl);
+    C-->D(catalog/listing/category.tpl);
+    D-->E(en-US/catalog/listing/product-list.tpl);
+    E-->F(catalog/listing/product-list.tpl);
+</div>
+
+This fallback chain applies to all listing pages (new products, best sellers, search results, etc.) — they all ultimately fall back to `product-list.tpl`.
+
+See [Listing pages]({{< relref "/9/themes/concepts/templates/listing-pages" >}}) for how listing templates work, including AJAX updates.
diff --git a/themes/concepts/theme-structure.md b/themes/concepts/theme-structure.md
new file mode 100644
index 0000000000..3ae348f4b0
--- /dev/null
+++ b/themes/concepts/theme-structure.md
@@ -0,0 +1,264 @@
+---
+title: Theme structure
+weight: 1
+aliases:
+  - /9/themes/getting-started/theme-organization
+  - /9/themes/getting-started/theme-yml
+---
+
+# Theme structure
+
+This page covers the directory structure every PrestaShop theme must follow and the full `config/theme.yml` reference.
+
+## Directory structure
+
+A PrestaShop theme is a self-contained set of files in a subdirectory of `/themes/`. Here is the typical directory structure of a theme:
+
+```bash
+mytheme/
+├── assets/
+│   ├── css/
+│   │   └── theme.css
+│   └── js/
+│       └── theme.js
+├── config/
+│   └── theme.yml
+├── modules/            # Module template/asset overrides
+├── plugins/            # Custom Smarty plugins
+├── templates/
+│   ├── _partials/      # Shared fragments (header, footer, etc.)
+│   ├── catalog/        # Product & listing pages
+│   ├── checkout/       # Cart & checkout flow
+│   ├── cms/            # Static content pages
+│   ├── customer/       # Account pages
+│   ├── errors/         # Error pages
+│   └── layouts/        # Page layouts
+└── preview.png
+```
+
+Most themes also include `assets/img/` for images and `assets/fonts/` for custom fonts. Source directories for pre-compilation (`src/`, `_dev/`, etc.) and build configuration are implementation details of the specific theme.
+
+{{% notice tip %}}
+For the Hummingbird directory layout specifically, see [Hummingbird architecture]({{< relref "/9/themes/hummingbird" >}}).
+{{% /notice %}}
+
+## Theme configuration (theme.yml)
+
+The `config/theme.yml` file is required for PrestaShop to recognize and configure your theme. It defines identity, compatibility, layouts, hooks, modules, image types, and more.
+
+### Identity
+
+The `name` field must match the theme's directory name exactly.
+
+```yaml
+name: mytheme               # Must match the theme's directory name
+display_name: My Theme      # Displayed in the Back Office
+version: 1.0.0
+author:
+  name: "Your Name"
+  email: "you@example.com"
+  url: "https://example.com"
+```
+
+### Compatibility and layouts
+
+```yaml
+meta:
+  compatibility:
+    from: 9.1.0                    # Minimum PrestaShop version required
+    to: ~9.1.0                     # Maximum tested version
+    framework: bootstrap-v5.3.3    # CSS framework used by the theme
+  available_layouts:
+    layout-full-width:
+      name: Full width layout
+      description: Ideal for product pages to maximize picture size
+    layout-left-side-column:
+      name: One small left column
+      description: Great for CMS pages to show advertisements on the side
+```
+
+{{% notice info %}}
+The `to` and `framework` fields are currently not enforced by PrestaShop. They serve as metadata indicating the version range and framework your theme has been tested with.
+{{% /notice %}}
+
+Layouts are parsed automatically from `/templates/layouts/`. The `available_layouts` key provides user-friendly names for the Back Office layout selector.
+
+### Parent/child settings
+
+To create a child theme, set the `parent` key:
+
+```yaml
+parent: hummingbird          # Name of the parent theme directory
+assets:
+  use_parent_assets: true    # Inherit parent's compiled assets
+```
+
+When `use_parent_assets` is `true`:
+- `theme_assets`, `img_url`, `css_url`, `js_url` point to the **parent** theme
+- `child_theme_assets`, `child_img_url`, `child_css_url`, `child_js_url` point to the **child** theme
+
+When `false`, all asset variables point to the child theme only.
+
+See [Creating a child theme]({{< relref "/9/themes/create-a-theme/child-theme" >}}) for a complete guide.
+
+### Global settings
+
+#### Configuration
+
+Set PrestaShop configuration values when the theme is activated:
+
+```yaml
+global_settings:
+  configuration:
+    # These values are set in the database when the theme is activated
+    PS_QUICK_VIEW: false
+    NEW_PRODUCTS_NBR: 4
+    PS_PNG_QUALITY: 8
+```
+
+#### Modules
+
+Enable, disable, or reset modules on theme activation:
+
+```yaml
+global_settings:
+  modules:
+    to_enable:
+      # Enabled when the theme is activated (installed if needed)
+      - my-custom-module
+    to_disable:
+      # Disabled when the theme is activated
+      - homeslider
+    to_reset:
+      # Reset to default settings when the theme is activated
+      - blockreassurance
+```
+
+#### Hooks
+
+Create custom hooks and attach modules to hooks:
+
+```yaml
+global_settings:
+  hooks:
+    custom_hooks:
+      # Register new hooks so modules can attach to them
+      - name: displayFooterBefore
+        title: displayFooterBefore
+        description: Add a widget area above the footer
+    modules_to_unhook:
+      # Detach modules from hooks on theme activation
+      displayFooter:
+        - ps_socialfollow
+      displaySearch:
+        - ps_searchbar
+    modules_to_hook:
+      # Attach modules to hooks on theme activation
+      displayHeaderTop:
+        - blocklanguages
+        - blockcurrencies
+        - blockuserinfo
+      displayFooter:
+        - blocknewsletter
+```
+
+The `~` symbol in a hook list means "keep whatever modules are currently hooked here":
+
+```yaml
+modules_to_hook:
+  displayHeaderMiddle:
+    - ~                    # Keep existing hooked modules
+    - blocksearch          # Append this module
+  displayHeaderBottom:
+    - blocktopmenu         # Prepend these modules
+    - blockcart
+    - ~                    # Then keep existing hooked modules
+```
+
+#### Image types
+
+Themes must declare their image types.
+
+{{% notice warning %}}
+Activating a theme **removes all existing image types** and replaces them with the theme's declaration. This is a destructive operation — make sure your image types are complete before activation.
+{{% /notice %}}
+
+```yaml
+global_settings:
+  image_types:
+    # Each key defines an image type name used by PrestaShop
+    # width/height in pixels, scope = which entities use this type
+    cart_default:
+      width: 80
+      height: 80
+      scope: [products]
+    small_default:
+      width: 125
+      height: 125
+      scope: [products, categories, manufacturers, suppliers]
+    medium_default:
+      width: 300
+      height: 300
+      scope: [products, categories, manufacturers, suppliers]
+    large_default:
+      width: 500
+      height: 500
+      scope: [products]
+    home_default:
+      width: 250
+      height: 250
+      scope: [products]
+    category_default:
+      width: 960
+      height: 350
+      scope: [categories]
+```
+
+### Theme settings
+
+Settings that can be changed per-shop through the Back Office:
+
+```yaml
+theme_settings:
+  # Used when no page-specific layout is set
+  default_layout: layout-full-width
+  layouts:
+    # Specific layout per page
+    identity: layout-left-side-column
+    order-confirmation: layout-left-side-column
+```
+
+When layout assignments are changed through the Back Office via _Design > Theme & Logo > Choose layouts_, they are stored in `settings_n.yml` (where `n` is the shop ID, relevant in multistore setups). The original `theme.yml` stays unchanged.
+
+#### Disable core.js
+
+You can disable `core.js` loading and provide your own implementation:
+
+```yaml
+theme_settings:
+  core_scripts: false   # Disables core.js loading entirely
+```
+
+{{% notice warning %}}
+Disabling `core.js` removes the `prestashop` event system and jQuery. Most modules depend on these — only disable if you provide a full replacement.
+{{% /notice %}}
+
+### Dependencies
+
+Declare module dependencies to include them in theme exports:
+
+```yaml
+dependencies:
+  modules:
+    # These modules are bundled when exporting the theme as a ZIP
+    - xx_customslider
+    - xx_customproductpage
+```
+
+## Required files for validation
+
+PrestaShop validates a theme before activation. See [Validation]({{< relref "/9/themes/distribution/validation" >}}) for the complete list of required files and configuration keys.
+
+## Core assets
+
+PrestaShop automatically loads a set of CSS and JavaScript files on every page. See [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) for the full list, their IDs, priorities, and how to register or unregister assets.
diff --git a/themes/concepts/translation.md b/themes/concepts/translation.md
new file mode 100644
index 0000000000..c0b24dea82
--- /dev/null
+++ b/themes/concepts/translation.md
@@ -0,0 +1,101 @@
+---
+title: Translation
+weight: 6
+aliases:
+  - /9/themes/reference/theme-translation
+---
+
+# Theme translation
+
+PrestaShop provides a built-in system for translating theme wordings into any language.
+
+## Adding translatable wordings
+
+In Smarty templates, use the `{l}` function with the `d` (domain) parameter. All wordings must be written in English:
+
+```smarty
+{l s='Read more' d='Shop.Mytheme'}
+```
+
+Replace `Mytheme` with your theme's name.
+
+{{% notice warning %}}
+The theme name in the domain must start with a capital letter and contain no other uppercase letters. `Shop.Mytheme` is correct; `Shop.MyTheme` is not.
+{{% /notice %}}
+
+### Using placeholders
+
+Use the `sprintf` parameter to insert dynamic values:
+
+```smarty
+{l s='%count% items in your cart' d='Shop.Mytheme' sprintf=['%count%' => $cart.products_count]}
+{l s='Welcome, %firstname% %lastname%!' d='Shop.Mytheme' sprintf=['%firstname%' => $customer.firstname, '%lastname%' => $customer.lastname]}
+```
+
+### Translation domains
+
+PrestaShop uses dot-separated domains to organize translations:
+
+| Domain | Purpose |
+|--------|---------|
+| `Shop.Mytheme` | Your theme's custom wordings |
+| `Shop.Theme.Global` | Shared theme wordings (core) |
+| `Shop.Theme.Catalog` | Catalog-related wordings (core) |
+| `Shop.Theme.Checkout` | Checkout-related wordings (core) |
+| `Shop.Theme.Actions` | Action labels like "Add to cart" (core) |
+| `Shop.Theme.CustomerAccount` | Account page wordings (core) |
+
+Use `Shop.Mytheme` for your own wordings. Core domains (`Shop.Theme.*`) are already translated in PrestaShop's language packs — reuse them when possible to get translations for free:
+
+```smarty
+{* Uses existing PrestaShop translations — no need to translate yourself *}
+{l s='Add to cart' d='Shop.Theme.Actions'}
+{l s='No products available yet' d='Shop.Theme.Catalog'}
+```
+
+## Translations in JavaScript
+
+To use translated strings in your theme's JavaScript, pass them from a Smarty template as JavaScript variables:
+
+```smarty
+<script>
+  var myThemeTranslations = {
+    addedToCart: '{l s="Product added to cart" d="Shop.Mytheme" js=1}',
+    confirmRemove: '{l s="Are you sure?" d="Shop.Mytheme" js=1}'
+  };
+</script>
+```
+
+The `js=1` parameter escapes quotes for safe embedding in JavaScript strings.
+
+## Translating wordings in the Back Office
+
+Translation involves two distinct steps in **"International" > "Translations"**:
+
+### Install languages
+
+Under **"Add / Update a language"**, install the languages you want to support. This downloads PrestaShop's official language packs, which include translations for all core domains (`Shop.Theme.*`).
+
+### Translate your theme's wordings
+
+Under **"Modify translations"**:
+
+1. Select **"Front office Translations"** as the type.
+2. Choose your theme and the target language.
+3. Click **"Modify"** — a form appears listing all wordings found in your `.tpl` files.
+4. Navigate to **"Shop" > "Your theme name"** in the left column to find your custom domain.
+5. Fill in translations and save.
+
+Repeat for each language you want to support.
+
+## Distributing translations
+
+To distribute your theme with translations pre-installed:
+
+1. In **"International" > "Translations"**, scroll to **"Export a language"**.
+2. Select your theme and the language to export, then download the ZIP.
+3. Extract it and place the `.xlf` files in your theme's `translations/` directory.
+
+When you [export your theme]({{< relref "/9/themes/distribution/exporting" >}}), the `translations/` folder is included automatically.
+
+See the [Smarty helpers reference]({{< relref "/9/themes/reference/smarty-helpers" >}}) for the full `{l}` parameter list.
diff --git a/themes/create-a-theme/_index.md b/themes/create-a-theme/_index.md
new file mode 100644
index 0000000000..3f51f251ea
--- /dev/null
+++ b/themes/create-a-theme/_index.md
@@ -0,0 +1,20 @@
+---
+title: Create a theme
+weight: 20
+chapter: true
+showOnHomepage: true
+---
+
+# Create a theme
+
+Choose your starting point based on how much you need to change and how much you want to maintain. Building from a rich base is faster but ties you more closely to its structure; starting from scratch gives you full control at the cost of more initial work.
+
+| Approach | Best for | What you get |
+|----------|----------|--------------|
+| **[From scratch]({{< relref "/9/themes/create-a-theme/from-scratch" >}})** | Learning the theme system internals | A minimal, valid theme with only the required files |
+| **[From Hummingbird]({{< relref "/9/themes/create-a-theme/from-hummingbird" >}})** {{< minver v="9.1" >}} | **Production themes** | A full-featured fork with Bootstrap 5.3, BEM, and accessibility built in |
+| **[Child theme]({{< relref "/9/themes/create-a-theme/child-theme" >}})** | Light customizations | Inherited templates and styles with selective overrides |
+
+{{% notice tip %}}
+Starting from Hummingbird is the recommended approach for most projects running PrestaShop 9.1 or later. On PrestaShop 9.0, start from scratch instead.
+{{% /notice %}}
diff --git a/themes/create-a-theme/child-theme.md b/themes/create-a-theme/child-theme.md
new file mode 100644
index 0000000000..297edc984d
--- /dev/null
+++ b/themes/create-a-theme/child-theme.md
@@ -0,0 +1,141 @@
+---
+title: Creating a child theme
+menuTitle: Child theme
+weight: 3
+aliases:
+  - /9/themes/reference/template-inheritance/parent-child-feature
+---
+
+# Creating a child theme
+
+A child theme inherits all templates, styles, and assets from a parent theme. You only override what you need to change, keeping the ability to update the parent independently.
+
+{{% notice note %}}
+For deep markup changes, [start from Hummingbird]({{< relref "/9/themes/create-a-theme/from-hummingbird" >}}) directly instead.
+{{% /notice %}}
+
+**Prerequisite:** The parent theme must be present in your PrestaShop `/themes/` directory before the child theme can be activated. Install the parent first.
+
+## Scaffold the directory
+
+A child theme requires only two files. Run the following from your PrestaShop `/themes/` directory:
+
+```bash
+cd /path/to/prestashop/themes
+
+mkdir -p my-child-theme/config
+
+touch my-child-theme/config/theme.yml \
+      my-child-theme/preview.png
+```
+
+This gives you the minimum structure PrestaShop requires:
+
+```
+my-child-theme/
+├── config/
+│   └── theme.yml
+└── preview.png
+```
+
+`preview.png` is displayed in the Back Office theme selector. Use a 500×746 PNG screenshot of your theme.
+
+## Minimal theme.yml
+
+```yaml
+parent: my-parent-theme-name
+name: my-child-theme          # Must match the directory name
+display_name: My Child Theme
+version: 1.0.0
+
+assets:
+  use_parent_assets: true     # Load the parent's registered CSS and JS in addition to your own
+```
+
+When `use_parent_assets` is `true`, the parent's CSS and JS files are loaded first, then any assets registered by your child theme are appended. Set it to `false` if you want to take full control of assets and provide your own stylesheet from scratch. See [Theme structure]({{< relref "/9/themes/concepts/theme-structure#parentchild-settings" >}}) for the full reference.
+
+## Overriding CSS
+
+To add or override styles, create a stylesheet in your child theme and register it via your theme's asset configuration. With `use_parent_assets: true`, your stylesheet is loaded after the parent's, so any rules you define will take precedence through standard CSS cascade:
+
+```
+my-child-theme/
+└── assets/
+    └── css/
+        └── custom.css
+```
+
+Register it in `config/theme.yml` under `global_settings`:
+
+```yaml
+global_settings:
+  assets:
+    css:
+      custom:
+        path: assets/css/custom.css
+        media: all
+```
+
+See [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) for the full registration syntax.
+
+## Overriding templates
+
+Without any template files, the child theme renders everything from the parent. See [Template inheritance]({{< relref "/9/themes/concepts/templates/template-inheritance" >}}) for the full reference.
+
+To override a template, create it at the same path in your child theme:
+
+```
+my-child-theme/
+└── templates/
+    └── catalog/
+        └── listing/
+            └── category.tpl
+```
+
+PrestaShop will use your file instead of the parent's. There are two ways to write it:
+
+### Replace a template completely
+
+You take full ownership of the template — but you don't have to start from zero. You can still extend a lower-level base template to keep shared logic and only redefine what you need to change. Here `category.tpl` extends `product-list.tpl` to reuse the shared listing logic while overriding only the header and footer blocks:
+
+```smarty
+{extends file='catalog/listing/product-list.tpl'}
+
+{block name='product_list_header'}
+  {include file='catalog/_partials/category-header.tpl' listing=$listing category=$category}
+{/block}
+
+{block name='product_list_footer'}
+  {include file='catalog/_partials/category-footer.tpl' listing=$listing category=$category}
+{/block}
+```
+
+### Override specific blocks using the `parent:` prefix
+
+If you only need to change one or two blocks within `category.tpl`, extend the parent theme's version of the same template directly using the `parent:` prefix. Without it, `{extends file='catalog/listing/category.tpl'}` would point back to itself and cause an infinite loop:
+
+```smarty
+{extends file='parent:catalog/listing/category.tpl'}
+
+{block name='product_list_header'}
+  {include file='catalog/_partials/category-header.tpl' listing=$listing category=$category}
+{/block}
+```
+
+## Activate the theme
+
+**Option A — Upload a zip**
+
+Zip your theme directory and upload it directly in the Back Office under _Design > Theme & Logo > Add new theme_:
+
+```bash
+# Run from the /themes/ directory — produces my-child-theme.zip containing the my-child-theme/ folder
+cd /path/to/prestashop/themes
+zip -r my-child-theme.zip my-child-theme/
+```
+
+**Option B — Copy manually**
+
+Copy your theme directory into `/themes/` inside your PrestaShop installation, then go to _Design > Theme & Logo_.
+
+In both cases, select the child theme and click _Use this theme_.
diff --git a/themes/create-a-theme/from-hummingbird.md b/themes/create-a-theme/from-hummingbird.md
new file mode 100644
index 0000000000..3e47e1e917
--- /dev/null
+++ b/themes/create-a-theme/from-hummingbird.md
@@ -0,0 +1,74 @@
+---
+title: Starting from Hummingbird
+menuTitle: From Hummingbird
+weight: 2
+---
+
+# Starting from Hummingbird
+
+The recommended way to create a new PrestaShop 9 theme is to start from [Hummingbird]({{< relref "/9/themes/hummingbird" >}}). This gives you a complete, production-ready foundation with modern architecture, accessibility compliance, and a structured codebase.
+
+## Clone and configure
+
+Run the following from your PrestaShop `/themes/` directory:
+
+```bash
+git clone https://github.com/PrestaShop/hummingbird.git mytheme
+cd mytheme
+rm -rf .git && git init  # Detach from Hummingbird's history and start your own
+git add -A && git commit -m "Initial commit from Hummingbird"
+```
+
+{{% notice warning %}}
+`rm -rf .git` permanently discards the full Hummingbird commit history. This is the right choice when you want a clean project history. If you want to keep the ability to pull future Hummingbird changes (e.g., bug fixes), set a new remote instead: `git remote set-url origin <your-repo-url>`.
+{{% /notice %}}
+
+Edit `config/theme.yml`:
+
+```yaml
+name: mytheme          # Must match the directory name
+display_name: My Theme
+version: 1.0.0
+author:
+  name: "Your Name"
+  email: "you@example.com"  # Optional
+  url: "https://example.com"  # Optional
+
+meta:
+  compatibility:
+    from: 9.1
+    to: ~9.1     # Supports all 9.1.x patch releases; update when you've tested against a new minor version
+```
+
+## Build and activate
+
+See [Requirements]({{< relref "/9/themes/getting-started/requirements" >}}) for the required Node and npm versions.
+
+```bash
+npm ci           # Installs exact versions from the lockfile — use this instead of npm install for reproducible builds
+npm run build
+```
+
+Then in the Back Office: _Design > Theme & Logo_ → select your theme → _Use this theme_.
+
+{{% notice tip %}}
+Replace `preview.png` with a 500×746 PNG screenshot of your theme before activating. The cloned Hummingbird image will otherwise appear in the Back Office theme selector.
+{{% /notice %}}
+
+For development with live recompilation:
+
+```bash
+npm run watch
+```
+
+## Customization approach
+
+Before customizing, take time to assess what your design actually requires. Many changes can be achieved by overriding Bootstrap variables or restyling existing components — no new code needed. Custom components should only come when the existing system genuinely cannot cover your need. See [CSS architecture]({{< relref "/9/themes/hummingbird/css-architecture" >}}) for the full structure.
+
+- **Templates:** Override Smarty templates using [template inheritance]({{< relref "/9/themes/concepts/templates/template-inheritance" >}}) — extend and redefine blocks rather than copying entire files.
+- **JavaScript:** Use `data-ps-*` attributes for behavior hooks. Listen to [PrestaShop events]({{< relref "/9/themes/reference/javascript-events" >}}) for dynamic updates. See [JavaScript conventions]({{< relref "/9/themes/hummingbird/javascript" >}}).
+- **Module overrides:** Place template and asset overrides in `modules/`. See [Overrides]({{< relref "/9/themes/concepts/overrides" >}}).
+
+{{% notice tip %}}
+If you only need small changes (add a block, adjust a style), consider a [child theme]({{< relref "/9/themes/create-a-theme/child-theme" >}}) instead. This makes it easier to pull in updates from Hummingbird.
+{{% /notice %}}
diff --git a/themes/create-a-theme/from-scratch.md b/themes/create-a-theme/from-scratch.md
new file mode 100644
index 0000000000..f2f86db811
--- /dev/null
+++ b/themes/create-a-theme/from-scratch.md
@@ -0,0 +1,177 @@
+---
+title: Creating a theme from scratch
+menuTitle: From scratch
+weight: 1
+---
+
+# Creating a theme from scratch
+
+This page walks through creating a minimal, valid PrestaShop 9 theme from scratch — no base theme required.
+
+## Scaffold the directory
+
+Run the following from your PrestaShop `/themes/` directory to create all required files. The commands use bash brace expansion — run them in bash, not sh.
+
+```bash
+cd /path/to/prestashop/themes
+
+mkdir -p minimal-theme/{config,assets/{css,js},templates/{_partials,catalog/listing,checkout,cms,customer,errors,layouts}}
+
+touch minimal-theme/config/theme.yml \
+      minimal-theme/assets/css/theme.css \
+      minimal-theme/assets/js/theme.js \
+      minimal-theme/preview.png \
+      minimal-theme/templates/_partials/form-fields.tpl \
+      minimal-theme/templates/catalog/product.tpl \
+      minimal-theme/templates/catalog/listing/product-list.tpl \
+      minimal-theme/templates/checkout/{cart,cart-empty,checkout,order-confirmation}.tpl \
+      minimal-theme/templates/cms/{category,page,sitemap,stores}.tpl \
+      minimal-theme/templates/contact.tpl \
+      minimal-theme/templates/customer/{address,addresses,authentication,guest-login,guest-tracking,history,identity,my-account,order-detail,order-follow,order-return,order-slip,registration}.tpl \
+      minimal-theme/templates/errors/{404,forbidden}.tpl \
+      minimal-theme/templates/layouts/layout-custom.tpl \
+      minimal-theme/templates/index.tpl
+```
+
+This gives you the minimum structure PrestaShop requires:
+
+```
+minimal-theme/
+├── config/
+│   └── theme.yml
+├── assets/
+│   ├── css/
+│   │   └── theme.css
+│   └── js/
+│       └── theme.js
+├── templates/
+│   ├── _partials/
+│   │   └── form-fields.tpl
+│   ├── catalog/
+│   │   ├── product.tpl
+│   │   └── listing/
+│   │       └── product-list.tpl
+│   ├── checkout/
+│   │   ├── cart-empty.tpl
+│   │   ├── cart.tpl
+│   │   ├── checkout.tpl
+│   │   └── order-confirmation.tpl
+│   ├── cms/
+│   │   ├── category.tpl
+│   │   ├── page.tpl
+│   │   ├── sitemap.tpl
+│   │   └── stores.tpl
+│   ├── customer/
+│   │   ├── address.tpl
+│   │   ├── addresses.tpl
+│   │   ├── authentication.tpl
+│   │   ├── guest-login.tpl
+│   │   ├── guest-tracking.tpl
+│   │   ├── history.tpl
+│   │   ├── identity.tpl
+│   │   ├── my-account.tpl
+│   │   ├── order-detail.tpl
+│   │   ├── order-follow.tpl
+│   │   ├── order-return.tpl
+│   │   ├── order-slip.tpl
+│   │   └── registration.tpl
+│   ├── errors/
+│   │   ├── 404.tpl
+│   │   └── forbidden.tpl
+│   ├── layouts/
+│   │   └── layout-custom.tpl
+│   ├── contact.tpl
+│   └── index.tpl
+└── preview.png
+```
+
+{{% notice note %}}
+Template files can be empty, but they must exist for PrestaShop to consider the theme valid.
+{{% /notice %}}
+
+`preview.png` is displayed in the Back Office theme selector. Use a 500×746 PNG screenshot of your theme.
+
+{{% notice warning %}}
+`touch` creates an empty file. An empty `preview.png` will break the theme thumbnail in the Back Office. Replace it with a real PNG before sharing or distributing the theme. The theme will still activate with an empty file, but the selector will show a broken image.
+{{% /notice %}}
+
+## Minimal theme.yml
+
+```yaml
+name: minimal-theme          # Must match the directory name
+display_name: Minimal Theme
+version: 1.0.0
+author:
+  name: "Your Name"
+
+meta:
+  compatibility:
+    from: 9.0.0
+    to: ~9.0          # Supports all 9.x patch releases; increment minor when testing a new minor version
+
+  available_layouts:
+    layout-custom:
+      name: Custom Layout
+      description: Your custom layout.
+
+global_settings:
+  # Image types are registered when the theme is activated and replace any existing ones in the shop.
+  # Each entry defines an image preset: its pixel dimensions and which entity types (scope) it applies to.
+  # Declare every preset your templates reference — missing types will cause broken images.
+  image_types:
+    cart_default:
+      width: 125
+      height: 125
+      scope: [products]
+    small_default:
+      width: 98
+      height: 98
+      scope: [products, categories, manufacturers, suppliers]
+    medium_default:
+      width: 452
+      height: 452
+      scope: [products, manufacturers, suppliers]
+    large_default:
+      width: 800
+      height: 800
+      scope: [products, manufacturers, suppliers]
+    home_default:
+      width: 250
+      height: 250
+      scope: [products]
+    category_default:
+      width: 180
+      height: 180
+      scope: [categories]
+
+theme_settings:
+  # default_layout must match a key under available_layouts above.
+  # It maps to templates/layouts/layout-<key>.tpl and is used as the page wrapper when no layout is specified.
+  default_layout: layout-custom
+```
+
+## Activate the theme
+
+**Option A — Upload a zip**
+
+Zip your theme directory and upload it directly in the Back Office under _Design > Theme & Logo > Add new theme_:
+
+```bash
+# Run from the /themes/ directory — produces minimal-theme.zip containing the minimal-theme/ folder
+cd /path/to/prestashop/themes
+zip -r minimal-theme.zip minimal-theme/
+```
+
+**Option B — Copy manually**
+
+Copy your theme directory into `/themes/` inside your PrestaShop installation, then go to _Design > Theme & Logo_.
+
+In both cases, select your theme and click _Use this theme_.
+
+{{% notice warning %}}
+Activating a theme replaces all image types with the ones declared in your `theme.yml`. Make sure your image type configuration is complete before activating.
+{{% /notice %}}
+
+Since all template files are empty, every page will render blank. This is expected — you now have a valid skeleton to build on.
+
+From here, read [Templates and layouts]({{< relref "/9/themes/concepts/templates/templates-and-layouts" >}}) to understand how PrestaShop renders pages, and [Asset management]({{< relref "/9/themes/concepts/asset-management" >}}) to learn how to register CSS and JavaScript files.
diff --git a/themes/distribution/_index.md b/themes/distribution/_index.md
index ccd3e054ad..8a9a8ed67b 100644
--- a/themes/distribution/_index.md
+++ b/themes/distribution/_index.md
@@ -1,14 +1,15 @@
 ---
 title: Distribution
+weight: 40
 chapter: true
 showOnHomepage: true
 ---
 
 # Distribution
 
-Now that you created an amazing theme, you probably want to release it. The following documentation
-will walk you through creating a ZIP archive that you can provide to users that want to install this amazing creation.
+Before a theme can be activated in the Back Office, it must pass validation. Once valid, it can be exported as a ZIP for sharing or distribution.
 
-But first, you need to test your theme!
-
-{{% children /%}}
+| Page | Description |
+|------|-------------|
+| [Validation]({{< relref "/9/themes/distribution/validation" >}}) | Required files and configuration keys — a theme that does not pass validation cannot be activated |
+| [Exporting]({{< relref "/9/themes/distribution/exporting" >}}) | Creating a ZIP, what gets exported, and how to prepare for distribution |
diff --git a/themes/distribution/exporting.md b/themes/distribution/exporting.md
index 63404a3180..541380406a 100644
--- a/themes/distribution/exporting.md
+++ b/themes/distribution/exporting.md
@@ -1,31 +1,63 @@
 ---
 title: Exporting your theme
+menuTitle: Exporting
+weight: 20
 ---
 
 # Exporting your theme
 
-## Creating a valid ZIP file
+## How themes become available
 
-A theme is installed as soon as it is on the disk.
+A theme becomes visible in the Back Office as soon as it is placed on disk in the `/themes/` directory with a `config/theme.yml` file. To be selectable as the active theme, it must pass [validation]({{< relref "/9/themes/distribution/validation" >}}).
 
-If you want the theme to appears in the backoffice, it only needs to contain a `config/theme.yml` file.
-This will only display it, if you want to select it as your active theme, it has to be valid. Read ["What
-makes a valid theme"]({{< relref "/9/themes/distribution/testing" >}}).
+## Exporting from the Back Office
 
+In _Design > Theme & Logo_, click **Export current theme** in the top right. The ZIP downloads directly in your browser.
 
-![Export current theme](../img/export-current-theme.png)
+![Export current theme](../../img/export-current-theme.png)
 
-Once it is active you can export your theme using the _"Export current theme"_ button or use the command
-from your terminal.
+## Exporting from the command line
 
 ```bash
-php bin/console prestashop:theme:export THEME_DIRECTORY_NAME
+php bin/console prestashop:theme:export theme_name
 ```
 
-### What is exported
+The command prints the path of the generated ZIP on success.
 
-Exporting your theme using the button or the command line will export the following data:
+## What gets exported
 
-* All theme files in directory
-* Dependencies specified in `theme.yml` ([See theme.yml doc]({{< relref "/9/themes/getting-started/theme-yml" >}}))
-* Theme translations
+Both methods produce a ZIP file containing:
+
+| Content | Source |
+|---------|--------|
+| All files in the theme directory | `/themes/theme_name/` |
+| Module dependencies | Modules listed under `dependencies.modules` in `theme.yml` |
+| Theme translations | Files in the theme's `translations/` folder |
+
+See [Theme structure]({{< relref "/9/themes/concepts/theme-structure" >}}) for the `dependencies` and `translations` configuration.
+
+## What to exclude before exporting
+
+The export includes **everything** in the theme directory. Clean up before exporting:
+
+| Exclude | Why |
+|---------|-----|
+| `node_modules/` | Build dependency, large, not needed at runtime |
+| `.git/` | Version control history, not relevant for distribution |
+| Source files (e.g. `src/scss/`, `src/js/`) | Only compiled assets in `assets/` are needed at runtime |
+| IDE and OS files (`.idea/`, `.vscode/`, `.DS_Store`) | Development artifacts |
+| Docker and CI files (`docker/`, `.github/`) | Development infrastructure |
+| AI context files (`.claude/`, `.cursor/`, `CLAUDE.md`) | Development tooling, not relevant for distribution |
+
+{{% notice tip %}}
+Add a `.gitignore` and keep your working directory clean. The export command packages the directory as-is — there is no built-in exclude mechanism.
+{{% /notice %}}
+
+## Preparing for distribution
+
+Before distributing your theme:
+
+1. Compile production-ready assets — for Hummingbird run `npm run build`; adapt to your own build pipeline if using a custom theme
+2. Verify the theme passes [validation]({{< relref "/9/themes/distribution/validation" >}})
+3. Test activation on a clean PrestaShop installation
+4. Ensure `preview.png` is present and up to date — required dimensions are 500×746px
diff --git a/themes/distribution/img/export-current-theme.png b/themes/distribution/img/export-current-theme.png
deleted file mode 100644
index 3b4d5c8b5d..0000000000
Binary files a/themes/distribution/img/export-current-theme.png and /dev/null differ
diff --git a/themes/distribution/testing.md b/themes/distribution/testing.md
deleted file mode 100644
index eeb8b9ddb9..0000000000
--- a/themes/distribution/testing.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: Testing
-weight: 10
----
-
-# Testing
-
-## What makes a theme valid
-
-When you're trying to select a theme in the backoffice, PrestaShop will test if your theme is valid. It
-won't install if the theme isn't valid.
-
-A theme is valid if it contains some files and some configuration keys.
-
-### Required files
-
-Here is the complete list of required files:
-
-* preview.png
-* config/theme.yml
-* assets/js/theme.js
-* assets/css/theme.css
-* templates/_partials/form-field.tpl
-* templates/catalog/product.tpl
-* templates/catalog/listing/product-list.tpl
-* templates/checkout/cart.tpl
-* templates/checkout/checkout.tpl
-* templates/cms/category.tpl
-* templates/cms/page.tpl
-* templates/customer/address.tpl
-* templates/customer/addresses.tpl
-* templates/customer/guest-tracking.tpl
-* templates/customer/guest-login.tpl
-* templates/customer/history.tpl
-* templates/customer/identity.tpl
-* templates/index.tpl
-* templates/customer/my-account.tpl
-* templates/checkout/order-confirmation.tpl
-* templates/customer/order-detail.tpl
-* templates/customer/order-follow.tpl
-* templates/customer/order-return.tpl
-* templates/customer/order-slip.tpl
-* templates/errors/404.tpl
-* templates/errors/forbidden.tpl
-* templates/checkout/cart-empty.tpl
-* templates/cms/sitemap.tpl
-* templates/cms/stores.tpl
-* templates/customer/authentication.tpl
-* templates/customer/registration.tpl
-* templates/contact.tpl
-
-### Required configuration keys
-
-Your configuration file `config/theme.yml` ([read more about this file]({{< relref "/9/themes/getting-started/theme-yml" >}}))
-must details some configuration keys.
-
-Here is the list of keys PrestaShop will look for. The dot represent the nesting.
-
-* name
-* display_name
-* version
-* author.name
-* meta.compatibility.from
-* meta.available_layouts
-* global_settings.image_types.cart_default
-* global_settings.image_types.small_default
-* global_settings.image_types.medium_default
-* global_settings.image_types.large_default
-* global_settings.image_types.home_default
-* global_settings.image_types.category_default
-* theme_settings.default_layout
diff --git a/themes/distribution/validation.md b/themes/distribution/validation.md
new file mode 100644
index 0000000000..322de01a14
--- /dev/null
+++ b/themes/distribution/validation.md
@@ -0,0 +1,73 @@
+---
+title: Validation
+weight: 10
+aliases:
+  - /9/themes/distribution/testing
+---
+
+# Validation
+
+## What makes a theme valid
+
+When you select a theme in the Back Office, PrestaShop validates it before activation. A theme that does not pass validation cannot be installed.
+
+A theme is valid if it contains the required files and a complete `config/theme.yml`.
+
+For child themes, each required file is checked in the child theme directory first, then in the parent theme directory. A file only triggers a validation error if it is missing from both.
+
+### Required files
+
+| File |
+|------|
+| `preview.png` |
+| `config/theme.yml` |
+| `assets/css/theme.css` |
+| `assets/js/theme.js` |
+| `templates/index.tpl` |
+| `templates/contact.tpl` |
+| `templates/_partials/form-fields.tpl` |
+| `templates/catalog/product.tpl` |
+| `templates/catalog/listing/product-list.tpl` |
+| `templates/checkout/cart.tpl` |
+| `templates/checkout/cart-empty.tpl` |
+| `templates/checkout/checkout.tpl` |
+| `templates/checkout/order-confirmation.tpl` |
+| `templates/cms/category.tpl` |
+| `templates/cms/page.tpl` |
+| `templates/cms/sitemap.tpl` |
+| `templates/cms/stores.tpl` |
+| `templates/customer/address.tpl` |
+| `templates/customer/addresses.tpl` |
+| `templates/customer/authentication.tpl` |
+| `templates/customer/guest-login.tpl` |
+| `templates/customer/guest-tracking.tpl` |
+| `templates/customer/history.tpl` |
+| `templates/customer/identity.tpl` |
+| `templates/customer/my-account.tpl` |
+| `templates/customer/order-detail.tpl` |
+| `templates/customer/order-follow.tpl` |
+| `templates/customer/order-return.tpl` |
+| `templates/customer/order-slip.tpl` |
+| `templates/customer/registration.tpl` |
+| `templates/errors/404.tpl` |
+| `templates/errors/forbidden.tpl` |
+
+### Required configuration keys
+
+The following keys must be present in `config/theme.yml`. Dots represent YAML nesting. See [Theme structure]({{< relref "/9/themes/concepts/theme-structure" >}}) for the full reference or [Creating a theme from scratch]({{< relref "/9/themes/create-a-theme/from-scratch" >}}) for a minimal working example.
+
+| Key |
+|-----|
+| `name` |
+| `display_name` |
+| `version` |
+| `author.name` |
+| `meta.compatibility.from` |
+| `meta.available_layouts` |
+| `global_settings.image_types.cart_default` |
+| `global_settings.image_types.small_default` |
+| `global_settings.image_types.medium_default` |
+| `global_settings.image_types.large_default` |
+| `global_settings.image_types.home_default` |
+| `global_settings.image_types.category_default` |
+| `theme_settings.default_layout` |
diff --git a/themes/getting-started/_index.md b/themes/getting-started/_index.md
index f2572beb74..95a8c5404a 100644
--- a/themes/getting-started/_index.md
+++ b/themes/getting-started/_index.md
@@ -1,6 +1,5 @@
 ---
-title: Getting started with theme development
-menuTitle: Getting started
+title: Getting started
 weight: 1
 chapter: true
 showOnHomepage: true
@@ -8,4 +7,10 @@ showOnHomepage: true
 
 # Getting started
 
-{{% children /%}}
+Get from zero to a working PrestaShop theme in minutes.
+
+| Page | Description |
+|------|-------------|
+| [Requirements]({{< relref "/9/themes/getting-started/requirements" >}}) | Tools you need: Node.js, Git, Docker |
+| [Quick start]({{< relref "/9/themes/getting-started/quick-start" >}}) | Clone Hummingbird, build, and activate in 5 minutes |
+| [Environment setup]({{< relref "/9/themes/getting-started/environment-setup" >}}) | Docker, local PHP stack, developer mode configuration |
diff --git a/themes/getting-started/asset-management/_index.md b/themes/getting-started/asset-management/_index.md
deleted file mode 100644
index bc4b4bf8a7..0000000000
--- a/themes/getting-started/asset-management/_index.md
+++ /dev/null
@@ -1,368 +0,0 @@
----
-title: Asset management
----
-
-# Asset Management
-
-We advise theme developers to compile most of their style and JavaScript code into a single concatenated/minified file (see the Webpack section below).
-
-If you need to add special assets, for example an extra JavaScript library on the home page or the product page, there are a few ways to do so.
-
-Your theme have to print assets correctly in the smarty template, and it's explained
-in the [template section]({{< relref "/9/themes/reference/templates/head" >}}).
-
-## Registering assets
-
-In PrestaShop 1.7+, it's easy to register custom assets on each page. The major improvement is that you can easily manage them from your theme, without any modules.
-
-We introduced new methods to register assets, and especially new cool options.
-
-For instance, you can register your asset specifically in the head or bottom of your HTML code; you can load it with attributes like `async` or `defer`; and you can even inline it easily.
-
-One favorite option is the priority one, which makes it very easy to ensure everything is loaded in the order you need.
-
-{{% notice note %}}
- Backward compatibility is kept for the `addJS()`, `addCSS()`, `addJqueryUI()` and `addJqueryPlugin()` methods. Incidentally, now is the best time to update your libraries and use the new method.
-{{% /notice %}}
-
-Here is a list of options, and what they do.
-
-### Options
-
-PrestaShop's `FrontController` class provides 2 new methods to easily register new assets: `registerStylesheet()` and `registerJavascript()`.
-
-In order to have the most extensible signatures, these 2 methods take 3 arguments. The first one is the unique ID of the asset, the second one is the relative path, and the third one is an array of all other optional parameters, as described below.
-
-**ID**
-
-This unique identifier needed for each asset. Reusing the same ID is useful to either override or unregister something already loaded by the Core or a native module.
-
-However, avoid generic names when adding new JS and CSS files to avoid collision with other extensions. Prefixing with your module or theme name is a good start.
-
-**Relative path**
-
-This is the path of your asset. In order to make your assets fully overridable and compatible with the parent/child feature, you need to provide the path from the theme's root directory, or PrestaShop's root directory if it's a module.
-
-For example:
-
--   'assets/css/example.css' for something in your theme.
--   'modules/modulename/css/example.css' for something in your module.
-
-**Extra parameters for stylesheet registration**
-
-<table>
-<col width="10%" />
-<col width="33%" />
-<col width="56%" />
-<tbody>
-<tr class="odd">
-<td align="left">Name</td>
-<td align="left">Values</td>
-<td align="left">Comment</td>
-</tr>
-<tr class="even">
-<td align="left">media</td>
-<td align="left">all | braille | embossed | handheld | print | projection | screen | speech | tty | tv (default: all)</td>
-<td align="left">-</td>
-</tr>
-<tr class="odd">
-<td align="left">priority</td>
-<td align="left">0-999 (default: 50)</td>
-<td align="left">0 is the highest priority</td>
-</tr>
-<tr class="even">
-<td align="left">inline</td>
-<td align="left">true | false (default: false)</td>
-<td align="left">If true, your style will be printed inside the <code>&lt;style&gt;</code> tag in your HTML <code>&lt;head&gt;</code>. Use with caution.</td>
-</tr>
-<tr class="odd">
-  <td align="left">version</td>
-  <td align="left">version number (default: null)</td>
-  <td align="left">You can provide the version number, which will be added as a query string to the asset's URL</td>
-</tr>
-<tr class="even">
-  <td align="left">needRtl</td>
-  <td align="left">true | false (default: false)</td>
-  <td align="left">If true, the rtl version of the stylesheet will be loaded</td>
-</tr>
-</tbody>
-</table>
-
-**Extra parameters for JavaScript registration**
-
-<table>
-<col width="10%" />
-<col width="33%" />
-<col width="56%" />
-<tbody>
-<tr class="odd">
-<td align="left">Name</td>
-<td align="left">Values</td>
-<td align="left">Comment</td>
-</tr>
-<tr class="even">
-<td align="left">position</td>
-<td align="left">head | bottom (default: bottom)</td>
-<td align="left">JavaScript files should be loaded in the bottom as much as possible. Remember: core.js is loaded as a first thing in the bottom so jQuery won't be loaded in the &lt;head&gt; part.</td>
-</tr>
-<tr class="odd">
-<td align="left">priority</td>
-<td align="left">0-999 (default: 50)</td>
-<td align="left">0 is the highest priority</td>
-</tr>
-<tr class="even">
-<td align="left">inline</td>
-<td align="left">true | false (default: false)</td>
-<td align="left">If true, your JavaScript will be printed inside <code>&lt;script type=&quot;text/javascript&quot;&gt;</code> tags inside your HTML. Use with caution.</td>
-</tr>
-<tr class="odd">
-<td align="left">attributes</td>
-<td align="left">async | defer | none (default: none)</td>
-<td align="left">Load JavaScript file with the corresponding attribute (Read more: <a href="https://www.growingwiththeweb.com/2014/02/async-vs-defer-attributes.html">Async vs Defer attributes</a>)</td>
-</tr>
-<tr class="even">
-<td align="left">server</td>
-<td align="left">local | remote (default: local)</td>
-<td align="left">Define if the JS resource is a local or remote path</td>
-</tr>
-<tr class="odd">
-  <td align="left">version</td>
-  <td align="left">version number (default: null)</td>
-  <td align="left">You can provide the version number, which will be added as a query string to the asset's URL</td>
-</tr>
-</tbody>
-</table>
-
-### Registered by the Core
-
-Every page of every theme loads the following files:
-
--   theme.css
--   custom.css
--   rtl.css (if a right-to-left language is detected)
--   core.js
--   theme.js
--   custom.js
-
-<table>
-<col width="14%" />
-<col width="15%" />
-<col width="10%" />
-<col width="59%" />
-<tbody>
-<tr class="odd">
-<td align="left">Filename</td>
-<td align="left">ID</td>
-<td align="left">Priority</td>
-<td align="left">Comment</td>
-</tr>
-<tr class="even">
-<td align="left">theme.css</td>
-<td align="left">theme-main</td>
-<td align="left">50</td>
-<td align="left">Most (all?) of your theme's styles. Should be minified.</td>
-</tr>
-<tr class="odd">
-<td align="left">rtl.css</td>
-<td align="left">theme-rtl</td>
-<td align="left">900</td>
-<td align="left">Loaded only for Right-To-Left language</td>
-</tr>
-<tr class="even">
-<td align="left">custom.css</td>
-<td align="left">theme-custom</td>
-<td align="left">1000</td>
-<td align="left">Empty file loaded at the very end to allow user to override some simple style.</td>
-</tr>
-<tr class="odd">
-<td align="left">core.js</td>
-<td align="left">corejs</td>
-<td align="left">0</td>
-<td align="left">Provided by PrestaShop. Contains jQuery3, dispatches PrestaShop events and holds PrestaShop logic.</td>
-</tr>
-<tr class="even">
-<td align="left">theme.js</td>
-<td align="left">theme-main</td>
-<td align="left">50</td>
-<td align="left"><dl>
-<dt>Most of your theme's JavaScript. Should embed libraries</dt>
-<dd><p>required on all pages, and be minified.</p>
-</dd>
-</dl></td>
-</tr>
-<tr class="odd">
-<td align="left">custom.js</td>
-<td align="left">theme-custom</td>
-<td align="left">1000</td>
-<td align="left">Empty file loaded at the very end, to allow users to use their own custom JavaScript without modifying core files.</td>
-</tr>
-</tbody>
-</table>
-
-### Registering in themes
-
-By now you probably understood that this `theme.yml` file became the heart of PrestaShop themes.
-
-To register assets, create a new `assets` key at the top level of your `theme.yml`, and register your files according to your needs. Page identifiers are based on the `php_self` property of each controller ([example](https://github.com/PrestaShop/PrestaShop/blob/b2ba1c2ecd627e23993c9356165e0d1e842a2faa/controllers/front/ProductController.php#L35))
-
-For example, if you want to add an external library on each page and a custom library on the Product page:
-
-```yaml
-assets:
-  css:
-    product:
-      - id: product-extra-style
-        path: assets/css/product.css
-        media: all
-        priority: 100
-  js:
-    all:
-      - id: this-cool-lib
-        path: assets/js/external-lib.js
-        priority: 30
-        position: bottom
-    product:
-      - id: product-custom-lib
-        path: assets/js/product.js
-        priority: 200
-        attribute: async
-```
-
-In addition, if you want to include a library hosted in a different server you can use the following syntax:
-```yaml
-assets:
-  css:
-    all:
-      - id: custom-cdn-css
-        path: //cdn-url.com/external-lib.css
-        media: all
-        priority: 200
-        server: remote
-  js:
-    all:
-      - id: custom-cdn-js
-        path: //cdn-url.com/external-lib.js
-        priority: 200
-        server: remote
-```
-
-### Registering in modules
-
-When developing a PrestaShop module, you may want to add specific styles for your templates. The best way is to use the `registerStylesheet` and `registerJavascript` methods provided by the parent `FrontController` class.
-
-{{% notice note %}}
-  If you're developing a custom module that only works on your themes, don't put any style or JavaScript code inside the module: put it in the theme's files instead (`theme.js` and `theme.css`).
-{{% /notice %}}
-
-#### With a front controller module
-
-If you develop a front controller, simply extend the `setMedia()` method. For instance:
-
-```php
-public function setMedia()
-{
-    parent::setMedia();
-
-    if ('product' === $this->php_self) {
-        $this->registerStylesheet(
-            'module-modulename-style',
-            'modules/'.$this->module->name.'/css/modulename.css',
-            [
-              'media' => 'all',
-              'priority' => 200,
-              'version' => 'release-2021-11'
-            ]
-        );
-
-        $this->registerJavascript(
-            'module-modulename-simple-lib',
-            'modules/'.$this->module->name.'/js/lib/simple-lib.js',
-            [
-              'priority' => 200,
-              'attributes' => 'async',
-              'version' => 'release-2021-11'
-            ]
-        );
-    }
-}
-```
-
-#### Without a front controller module
-
-If you only have your module's class, register your code on the `actionFrontControllerSetMedia` hook, and add your asset on the go inside the hook:
-
-```php
-public function hookActionFrontControllerSetMedia($params)
-{
-    // Only on the product page
-    // You could also check if the current controller is an instance of the one you want to target
-    if ('product' instanceof $this->context->controller->php_self) {
-        $this->context->controller->registerStylesheet(
-            'module-'.$this->name.'-style',
-            'modules/'.$this->name.'/css/modulename.css',
-            [
-              'media' => 'all',
-              'priority' => 200,
-            ]
-        );
-
-        $this->context->controller->registerJavascript(
-            'module-'.$this->name.'-simple-lib',
-            'modules/'.$this->name.'/js/lib/simple-lib.js',
-            [
-              'priority' => 200,
-              'attributes' => 'async',
-            ]
-        );
-    }
-
-    // On every page
-    $this->context->controller->registerJavascript(
-        'module-'.$this->name.'-js',
-        'modules/'.$this->name.'/ga.js',
-        [
-          'position' => 'head',
-          'inline' => true,
-          'priority' => 10,
-          'version' => 'release-2021-10'
-        ]
-    );
-}
-```
-
-## Unregistering
-
-You can unregister assets! That's the whole point of an `id`. For example if you want to improve your theme/module's compatibility with a module, you can unregister its assets and handle them yourself.
-
-Let's say you want to be fully compatible with a popular navigation module. You could create a template override of course, but you could also remove the style that comes with it and bundle your specific style in your `theme.css` (since it's loaded on every page).
-
-To unregister an assets, you need to know its ID.
-
-### In themes
-
-As of today, the only way to unregister an asset without any module is to place an empty file where the module override would be.
-
-If the module registers a JavaScript file placed in `views/js/file.js`, you simply need to create an empty file in `modules/modulename/views/js/file.js`.
-
-It works for both JavaScript and CSS assets.
-
-### In modules
-
-Both `unregisterJavascript` and `unregisterStylesheet` methods take only one argument: the unique ID of the resource you want to remove.
-
-```php
-<?php
-// In a front controller
-public function setMedia()
-{
-    parent::setMedia();
-
-    $this->unregisterJavascript('the-identifier');
-}
-
-// In a module class
-public function hookActionFrontControllerSetMedia($params)
-{
-  $this->context->controller->unregisterJavascript('the-identifier');
-}
-```
diff --git a/themes/getting-started/asset-management/img/webpack.png b/themes/getting-started/asset-management/img/webpack.png
deleted file mode 100644
index 222672a51e..0000000000
Binary files a/themes/getting-started/asset-management/img/webpack.png and /dev/null differ
diff --git a/themes/getting-started/asset-management/webpack.md b/themes/getting-started/asset-management/webpack.md
deleted file mode 100644
index 4e47472692..0000000000
--- a/themes/getting-started/asset-management/webpack.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Webpack
----
-
-# About Webpack
-
->	[Webpack](https://webpack.github.io/) is a module bundler.
-	Webpack takes modules with dependencies and generates static assets representing those modules.
-
-The main interest of using Webpack is that it will compile all your styles - which we advise you to write using [Sass ](https://sass-lang.com/) - into a single CSS file.
-This way, your theme will make only one HTTP request for this single file, and since your browser will cache it for later re-use, it will even download this file only once.
-
-The same goes with your JavaScript code. Instead of loading jQuery along with its community plugins, your own custom plugins and any extra code you might need,
-Webpack compiles and minifies all this JavaScript code into a single file, which will be loaded once - and cached.
-
-
-{{% notice note %}}
-  Webpack is not at all required by PrestaShop, you are free to use your favorite tool!
-  The documentation explains Webpack since it's the tool we chose for the Classic theme.
-{{% /notice %}}
-
-![Webpack](../img/webpack.png)
-
-
-## Installing webpack
-
-If you want to compile your assets using Webpack (and we advise you to), follow these steps:
-
-1. Download and install [Node.js 20.x](https://nodejs.org/), which contains the npm tool.
-2. In your command line tool, open the `_dev` folder.
-3. Install npm: `npm install`.
-4. You then have a choice:
-  - To build your assets once, type `npm run build`.
-  - To rebuild your assets every time you change a file in the _dev folder, type `npm run watch`.
-
-## Webpack configuration
-
-The [Webpack configuration file for Classic Theme](https://github.com/PrestaShop/classic-theme/blob/develop/_dev/webpack.config.js) is thus:
-
-1. All CSS rules go to the `assets/css/theme.css` file.
-2. All JavaScript code go to the `assets/js/theme.js` file.
-
-It provides proper configuration for compile your Sass or CSS files into a single CSS file.
-
-JavaScript code is written in ES6, and compiled to ES5 with [esbuild](https://github.com/privatenumber/esbuild-loader).
diff --git a/themes/getting-started/environment-setup.md b/themes/getting-started/environment-setup.md
new file mode 100644
index 0000000000..34aee628ab
--- /dev/null
+++ b/themes/getting-started/environment-setup.md
@@ -0,0 +1,92 @@
+---
+title: Environment setup
+weight: 3
+---
+
+# Environment setup
+
+You need a running PrestaShop 9 instance to preview and test your theme during development.
+
+## Option 1: Docker (recommended)
+
+Hummingbird includes Docker Compose configurations that spin up a full PrestaShop environment (application, database, phpMyAdmin) with your theme mounted automatically. These configurations require **PrestaShop 9.1+**.
+
+Two images are available:
+
+| Image | Startup | Use case |
+|-------|---------|----------|
+| **[PrestaShop](https://github.com/PrestaShop/docker)** (`prestashop/prestashop`) | ~2–5 min | Full installation wizard, closest to production |
+| **[Flashlight](https://github.com/PrestaShop/prestashop-flashlight)** (`prestashop/prestashop-flashlight`) | ~10 sec | Pre-installed dump, ideal for fast iteration and testing |
+
+### Setup
+
+From the Hummingbird root directory:
+
+```bash
+cp docker/.env-example docker/.env
+```
+
+Edit `docker/.env` with your settings:
+
+```bash
+PS_TAG=9.1.0
+PLATFORM=linux/amd64       # or linux/arm64 for Apple Silicon Macs
+ADMIN_EMAIL=admin@prestashop.com
+ADMIN_PASSWORD=prestashop
+```
+
+### Start the environment
+
+```bash
+# Standard PrestaShop
+docker compose -f docker/docker-compose-prestashop.yml up -d
+
+# Or Flashlight (faster startup)
+docker compose -f docker/docker-compose-flashlight.yml up -d
+```
+
+| Service | URL |
+|---------|-----|
+| PrestaShop | `http://localhost:8887` |
+| Back Office | `http://localhost:8887/admin-dev` |
+| phpMyAdmin | `http://localhost:8889` |
+
+### Stop the environment
+
+Use the same compose file you started with:
+
+```bash
+# If you started with Standard PrestaShop
+docker compose -f docker/docker-compose-prestashop.yml down -v
+
+# If you started with Flashlight
+docker compose -f docker/docker-compose-flashlight.yml down -v
+```
+
+See the [Hummingbird Docker setup](https://github.com/PrestaShop/hummingbird#-run-hummingbird-with-docker) for full details.
+
+## Option 2: Local PHP stack
+
+If you prefer a traditional setup (XAMPP, MAMP, Laragon, or native PHP), install PrestaShop manually. Check the [system requirements]({{< relref "/9/basics/installation/system-requirements" >}}) for the PHP, MySQL, and web server versions needed, then follow the [installation guide]({{< relref "/9/basics/installation" >}}).
+
+Once installed, copy your theme folder into the `/themes/` directory of your PrestaShop installation, or upload it as a `.zip` from the Back Office under _Design > Theme & Logo_.
+
+## Configure for development
+
+Enable Developer Mode for template debugging and error reporting. You can either:
+
+- Set `_PS_MODE_DEV_` to `true` in `config/defines.inc.php`
+- Or toggle it from the Back Office under _Advanced Parameters > Performance > Debug mode_
+
+Additionally, disable caching and file merging so your changes appear immediately. In the Back Office under _Advanced Parameters > Performance_:
+
+- **Smarty:** set _Force compilation_ to **Yes** and _Cache_ to **No**.
+- **CCC (Combine, Compress, Cache):** disable all options to prevent PrestaShop from merging and minifying your CSS and JavaScript files.
+
+{{% notice tip %}}
+In Developer Mode, HTML comments show the source path of each rendered template — useful to confirm which file is actually being loaded. For example:
+{{% /notice %}}
+
+```html
+<!-- begin /var/www/html/themes/mytheme/templates/catalog/product.tpl -->
+```
diff --git a/themes/getting-started/guidelines.md b/themes/getting-started/guidelines.md
deleted file mode 100644
index b556c58de7..0000000000
--- a/themes/getting-started/guidelines.md
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: Guidelines and coding standards
-menuTitle: Guidelines
-weight: 1
----
-
-# Guidelines and coding standards
-
-## Compatibility
-
-##### PHP Code
-
-Your PHP code should be compatible with [PHP compatibility chart]({{< relref "8/basics/installation/system-requirements#php-compatibility-chart" >}})
-
-##### HTML / CSS / Javascript
-
-Your HTML/CSS/JS code should work with at least:
-
-- Edge
-- Firefox 45
-- Chrome 29.
-
-Mobile-wise:
- 
-- iOS 8.4
-- Android Browser 4.4
-
-## Standards
-
-##### General
-
-Use spaces for indentation in every language (PHP, HTML, CSS, etc.):<br>4 spaces for PHP files, 2 spaces for all other file types.
-
-Use our [.editorconfig](https://editorconfig.org/) file in order to easily configure your editor: https://github.com/PrestaShop/PrestaShop/blob/8.0.x/.editorconfig
-
-##### PHP files
-
-You should follow the [PSR-2 standard](https://www.php-fig.org/psr/psr-2/), just like PrestaShop does.
-
-In general, we tend to follow the [Symfony coding standards](https://symfony.com/doc/current/contributing/code/standards.html).
-
-##### HTML files
-
-Use HTML 5 tags:
-
-* `<br />` → `<br>`
-* `<nav>`
-* `<section>`
-* etc.
-
-All open tags must be closed in the same file (a `<div>` should not be opened in `header.tpl` then closed in `footer.tpl`). Subtemplates (templates meant to be included in another template) must reside inside a `/_partials/` folder.
-
-##### CSS files
-
-Use CSS3.
-
-We recommend that you follow the [RSCSS structure](https://github.com/rstacruz/rscss/tree/main/docs/)
-
-##### Javascript
-
-Make sure your linter tool follows our .eslint file: https://github.com/PrestaShop/PrestaShop/blob/8.0.x/js/.eslintrc.js
-
-If you wish to write ECMAScript 2015 (ES6) code, we recommend using the [Babel compiler](https://babeljs.io/) to maximize compatibility.
-
-A good JS practice consists in splitting files per use, and then compiling them into one.
-
-Learn more about the ES2015 standard: https://babeljs.io/docs/learn-es2015/
diff --git a/themes/getting-started/quick-start.md b/themes/getting-started/quick-start.md
new file mode 100644
index 0000000000..8c11bc2ce0
--- /dev/null
+++ b/themes/getting-started/quick-start.md
@@ -0,0 +1,75 @@
+---
+title: Quick start
+weight: 2
+---
+
+# Quick start
+
+Create your own custom theme in 5 minutes by cloning [Hummingbird]({{< relref "/9/themes/hummingbird" >}}), the default PrestaShop theme, and using it as a starting point.
+
+{{% notice info %}}
+Hummingbird requires **PrestaShop 9.1 or later**.
+{{% /notice %}}
+
+## Clone Hummingbird as a base
+
+Replace `mytheme` with your theme name:
+
+```bash
+git clone https://github.com/PrestaShop/hummingbird.git mytheme
+cd mytheme
+rm -rf .git && git init   # Remove Hummingbird's history and start your own
+```
+
+## Configure your theme
+
+Edit `config/theme.yml`:
+
+```yaml
+name: mytheme # The name must match the directory name
+display_name: My Theme
+version: 1.0.0
+author:
+  name: "Your Name"
+  email: "you@example.com"
+  url: "https://example.com"
+
+meta:
+  compatibility:
+    from: 9.1.0
+    to: ~9.1.0
+    framework: bootstrap-v5.3.3  # Informational, not parsed by PrestaShop
+```
+
+{{% notice info %}}
+The `name` field must match the theme's directory name exactly.
+{{% /notice %}}
+
+## Install dependencies and build
+
+From your theme's root directory, install dependencies and compile the source files into production-ready assets:
+
+```bash
+npm ci
+npm run build
+```
+
+## Activate the theme
+
+1. Place your theme folder in the `/themes/` directory of your PrestaShop installation.
+2. In the Back Office, go to _Design > Theme & Logo_.
+3. Select your theme and click _Use this theme_.
+
+Alternatively, you can upload your theme as a `.zip` file directly from the _Design > Theme & Logo_ page in the Back Office.
+
+{{% notice tip %}}
+See [Exporting your theme]({{< relref "/9/themes/distribution/exporting" >}}) for how to create a distributable ZIP file.
+{{% /notice %}}
+
+## Start developing
+
+```bash
+npm run watch
+```
+
+This watches for file changes and recompiles assets automatically. Edit SCSS files in `src/scss/`, JavaScript in `src/js/`, and templates in `templates/`.
diff --git a/themes/getting-started/requirements.md b/themes/getting-started/requirements.md
new file mode 100644
index 0000000000..369f16ff3d
--- /dev/null
+++ b/themes/getting-started/requirements.md
@@ -0,0 +1,61 @@
+---
+title: Requirements
+weight: 1
+aliases:
+  - /9/themes/getting-started/tools-for-theme-designers
+---
+
+# Requirements
+
+The tools listed below are **recommended** for theme development. A PrestaShop theme is ultimately a set of template, CSS, and JavaScript files — you can create one with just a text editor. However, working with Hummingbird's source code and modern tooling requires the following.
+
+## Tools
+
+| Tool | Status | Purpose |
+|------|--------|---------|
+| **Node.js 20.x + npm 8+** | Recommended | Asset compilation, dev workflow, linting |
+| **Git** | Recommended | Version control, cloning Hummingbird |
+| **Docker + Docker Compose** | Optional | Run a full PrestaShop environment without a local PHP/MySQL stack |
+
+{{% notice info %}}
+**Node.js** and **npm** are needed to compile Hummingbird's SCSS and JavaScript / TypeScript source files. If you are building a simple theme without a build pipeline, they are not strictly required.
+{{% /notice %}}
+
+### Node.js
+
+Install from [nodejs.org](https://nodejs.org/). To manage multiple Node.js versions, use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm).
+
+{{% notice tip %}}
+Hummingbird includes a **.nvmrc** file. If you use nvm, run `nvm use` in the theme directory to automatically switch to the correct Node.js version.
+{{% /notice %}}
+
+**Verify your installation:**
+
+```bash
+node -v   # Should output v20.x
+```
+
+### Git
+
+Install from [git-scm.com](https://git-scm.com/).
+
+**Verify your installation:**
+
+```bash
+git --version
+```
+
+### Docker
+
+Install from [docker.com](https://www.docker.com/). Docker is the easiest way to get a running PrestaShop instance if you don't already have a local PHP and MySQL setup. Hummingbird includes ready-to-use Docker Compose configurations.
+
+**Verify your installation:**
+
+```bash
+docker --version
+docker compose version
+```
+
+## Next step
+
+Once your tools are installed, follow the [Quick start]({{< relref "/9/themes/getting-started/quick-start" >}}) to get a working theme in minutes, or see [Environment setup]({{< relref "/9/themes/getting-started/environment-setup" >}}) for detailed configuration options.
diff --git a/themes/getting-started/setting-up-your-local-environment.md b/themes/getting-started/setting-up-your-local-environment.md
deleted file mode 100644
index a63673b733..0000000000
--- a/themes/getting-started/setting-up-your-local-environment.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: Setting up your local environment
-menuTitle: Set up your local environment
-weight: 10
----
-
-# Setting up your local environment
-
-Now that you intend to building a theme for PrestaShop, you are better off keeping all your development work on your machine. The main advantage is that it makes it possible for you to entirely bypass the process of uploading your files on your online server in order to test your changes. Another advantage is that a local test environment enables you to test code without the risk of breaking your production store. Having a local environment is the essential first step in the path of web development.
-
-{{% notice info %}}
-The following content assumes you’re a developer and you want to create a theme or a module.
-{{% /notice %}}
-
-## Installing PrestaShop
-
-We advise you to install PrestaShop using [Git](https://git-scm.com/) and [Composer](https://getcomposer.org/).
-
-Open a command line on your (empty) working directory, then:
-
-1. Clone PrestaShop
-    ```bash
-    git clone https://github.com/PrestaShop/PrestaShop.git
-    ```
-
-2. Install dependencies
-    ```bash
-    composer install
-    ```
-
-Using git you can choose your PrestaShop version:
-```bash
-git checkout 8.1.x
-```
-
-Also we would warn you to test your final result with a zip release, just for safety (since vendor version might be slightly different).
-
-{{% notice note %}}
-If you haven’t done it yet, we strongly recommend you to read our article [Set Up Your Git For Contributing](https://build.prestashop-project.org/howtos/misc/set-up-your-git-for-contributing/)
-{{% /notice %}}
-
-## Building your .gitignore file
-
-A gitignore file is a must-have for any Git-versioned project, as it specifies intentionally untracked files that Git should ignore.
-
-##### What to ignore
-
-Generally, you shouldn’t version the following types of files:
-
-* Temporary files (such as cache files)
-* Generated files (such as minified CSS or retrieved XML files)
-* Files with credentials or personal information (such as settings.inc.php)
-* OS and IDE-related files (such as .DS_Store or .idea/)
-* assets/css/*
-* assets/js/*
-* node_modules/
-
-We suggest that you build your own using https://gitignore.io.
-
-{{% notice note %}}
-If you are building a full project for a client, you can read our article on [building a gitignore for PrestaShop](https://build.prestashop-project.org/howtos/misc/prestashop-perfect-gitignore/).
-{{% /notice %}}
-
-## Create your theme from the Classic Theme
-
-When you want to create a theme, the best way is to use the Classic theme (included with PrestaShop) as a base.
-
-Create a new folder under `themes/`, and copy the contents of `classic` in it.
-
-##### Create your theme.yml file
-
-First of all, you need to rename `config/theme.dist.yml` to `config/theme.yml` and edit it according to the name of your theme.
-
-```yaml
-name: YOUR_THEME_DIRECTORY_NAME
-display_name: YOUR THEME NAME
-version: 1.0.0
-author:
-  name: "PrestaShop Team"
-  email: "pub@prestashop.com"
-  url: "https://www.prestashop-project.org"
- 
-meta:
-  compatibility:
-      from: 8.0
-      to: ~
-```
diff --git a/themes/getting-started/theme-organization.md b/themes/getting-started/theme-organization.md
deleted file mode 100644
index 36ade4754b..0000000000
--- a/themes/getting-started/theme-organization.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-title: Theme organization
-weight: 40
----
-
-# Theme organization
-
-## Directory structure
-
-A PrestaShop theme is a set of files which you can edit in order to change the look of your online shop.
-
-Here are a few important tidbits:
-
-- All themes have their files located in the /themes folder, at the root of PrestaShop's folder.
-- Each theme has its own sub-folder, in the main themes folder.
-- Each theme is made of template files (.tpl), image files (.jpg, .png and such), one or more CSS files (.css), and usually JavaScript files (.js).
-- Each theme has a preview.png image file in its folder, enabling the shop-owner to see what the theme looks like directly from the back office, and select the theme appropriately.
-
-The best way to learn how to create a theme for PrestaShop is to dive into the Classic Theme.
-
-Here is its organization, which is explained further below.
-
-```bash
-  .
-  ├── CONTRIBUTING.md
-  ├── README.md
-  ├── _dev
-  │   ├── css
-  │   │   └── ...
-  │   ├── js
-  │   │   └── ...
-  │   ├── package.json
-  │   └── webpack.config.js
-  ├── assets
-  │   ├── css
-  │   │   ├── ...
-  │   ├── img
-  │   │   └── ...
-  │   └── js
-  │       └── ...
-  ├── composer.json
-  ├── config
-  │   └── theme.yml
-  ├── modules
-  │   └── ...
-  ├── plugins
-  │   └── ...
-  ├── preview.png
-  └── templates
-      ├── _partials
-      │   └── ...
-      ├── catalog
-      │   ├── _partials
-      │   │   └── ...
-      │   ├── listing
-      │   │   └── ...
-      │   └── ...
-      ├── checkout
-      │   ├── _partials
-      │   │   └── ...
-      │   └── ...
-      ├── cms
-      │   ├── _partials
-      │   │   └── ...
-      │   └── ...
-      ├── contact.tpl
-      ├── customer
-      │   ├── _partials
-      │   │   └── ...
-      │   └── ...
-      ├── errors
-      │   ├── ...
-      │   └── static
-      │       └── ...
-      ├── index.tpl
-      ├── layouts
-      │   ├── layout-both-columns.tpl
-      │   ├── layout-content-only.tpl
-      │   ├── layout-error.tpl
-      │   ├── layout-full-width.tpl
-      │   ├── layout-left-side-column.tpl
-      │   └── layout-right-side-column.tpl
-      ├── page.tpl
-      └── wrapper.tpl
-```
-
-The folders are used this way:
-
-**/_dev/**
-: Contains the raw development files for your SCSS, JavaScript and image assets.  
-  They are to be compiled using Webpack, and turned into production assets.
-
-**/assets/**
-: Contains the production assets, compiled by Webpack from the _dev files.
-
-**/config/**
-: Contains configuration file. By default, it only has the theme.yml file.
-
-**/modules/**
-: Contains either theme-specific modules, or the theme's version of native modules' template files.  
-  For instance, the `themes/classic/modules/ps_categorytree/views/templates/front/ps_categorytree.tpl` file replaces the Category module's own `modules/ps_categorytree/views/templates/front/ps_categorytree.tpl`
-
-**/plugins/**
-: Your custom smarty plugins
-
-**/templates/**
-: Contains the template files themselves (.tpl), mostly in contextual subfolders (catalog, checkout, cms, etc.).  
-  The _partials folder contains "partial templates", which means parts
-  that can used by / included into several templates: header.tpl, breadcrumb.tpl, footer.tpl, etc.  
-  This prevents redundant code blocks, and makes themes easier to maintain.
-
-
-## Required templates and libraries
-
-#### Required templates
-
-When you install/enable a theme, PrestaShop checks if the theme is valid: it looks for the theme.yml file
-(and checks its content), its declared compatibility, and the existence of some files.
-
-There is a list of files that need to exists, even if they're empty. Please see dedicated documentation
-to know [what makes a theme valid]({{< relref "/9/themes/distribution/testing" >}}).
-
-It could be that you've built some sort of groundbreaking theme and it doesn't exactly work like the
-Classic Theme does. For instance, if you don't have a product page, then you don't need the product.tpl file.
-In that case, you just have to create an empty product.tpl file. Be nice to the next developer and
-add a comment indicating where the code related to products can be found ;)
-
-#### Required libraries
-
-jQuery v3.5 is loaded by the core (bundled in `core.js`) file.
-
-Read more about [assets management]({{< relref "/9/themes/getting-started/asset-management/" >}}).
diff --git a/themes/getting-started/theme-yml.md b/themes/getting-started/theme-yml.md
deleted file mode 100644
index aace8beed1..0000000000
--- a/themes/getting-started/theme-yml.md
+++ /dev/null
@@ -1,242 +0,0 @@
----
-title: Theme.yml
-weight: 50
----
-
-# Theme.yml
-
-The theme's theme.yml file defines all of the theme's configuration and meta information, such as its version number, layouts, compatibility range, hook configuration, etc.
-
-## Theme description
-
-The theme's name MUST match its directory name. For instance, if the theme is named "My Awesome Theme" and its 'name' value is set to "my-awesome-theme", then the folder MUST be /my-awesome-theme .
-
-Users will be able to choose the layout for each page from the theme's settings page. Layouts are automatically parsed from the theme's /templates/layouts folder, so this configuration key is optional, but it allows designers to provide some more user-friendly info than just a filename.
-
-```yaml
-  name: mysupertheme # The name must match the directory name
-  display_name: My Super Theme
-  version: 1.0.0
-  author:
-    name: "John Doe"
-    email: "pub@prestashop.com"
-    url: "https://www.prestashop-project.org"
-  meta:
-    compatibility:
-        from: 8.0
-        to: ~
-    available_layouts:
-      layout-full-width:
-        name: Full width layout
-        description: Ideal for product pages to maximize picture size
-      layout-left-side-column:
-        name: One small left column
-        description: Great for CMS pages to show advertisements on the side
-```
-
-## Parent / child settings
-
-{{% notice note %}}
-Find more information about [Theming inheritance - Parent/child themes]({{<relref "/9/themes/reference/template-inheritance/parent-child-feature">}})
-{{% /notice %}}
-
-To set the parent theme, set the parent key to the theme's name: 
-
-```yaml
-parent: classic
-```
-
-### use_parent_assets 
-
-Starting from {{< minver v="8.0" >}} , the setting `use_parent_assets` is now fully working and correctly loads assets from the parent theme.
-
-```yaml
-assets:
-  use_parent_assets: true
-```
-
-When set to `true`, some additional variables are changed for `Smarty` templates. 
-
-- `theme_assets` is replaced with the parent theme assets URI, 
-- `img_url`, `css_url`, `js_url` are replaced with the parent theme corresponding URIs,
-
-some other variables are available: 
-
-- `child_theme_assets` which is the child theme assets URI,
-- `child_img_url`, `child_css_url`, `child_js_url` which are the child theme corresponding URIs.
-
-When set to `false`, only `theme_assets`, `img_url`, `css_url` and `js_url` are available, and are the child theme corresponding URIs. 
-
-{{% notice note %}}
-To maintain the behavior of {{< minver v="1.7">}} and load the child theme's assets, `use_parent_assets` must be set to `false`.
-{{% /notice %}}
-
-## Global settings
-
-### Configuration
-
-You can have the theme change the configuration of PrestaShop when the theme is enabled.
-
-```yaml
-  global_settings:
-    configuration:
-      PS_QUICK_VIEW: false
-      NEW_PRODUCTS_NBR: 4
-      PS_PNG_QUALITY: 8
-```
-
-You can also add custom configuration variables here (to use on modules/themes).
-
-### Modules
-
-You can have the theme enable, disable or reset modules when the theme is enabled.
-
-```yaml
-  global_settings:
-    modules:
-      to_enable:
-        # All modules below are enabled when
-        # the theme is enabled (and installed if needed).
-        # They are disabled when the theme is disabled.
-        - my-custom-module
-        - yippeeslider
-      to_disable:
-        # All modules below are disabled when the theme is enabled.
-        # They are re-enabled when the theme is disabled.
-        - homeslider
-        - blockwishlist
-      to_reset:
-        # All modules below are reset when the theme is enabled.
-        - blockreassurance
-        - blockwishlist
-```
-
-You can also have the theme create hooks and attach modules to custom and existing hooks when the theme is enabled.
-
-```yaml
-  global_settings:
-    hooks:
-      custom_hooks:
-        - name: displayFooterBefore
-          title: displayFooterBefore
-          description: Add a widget area above the footer
-      modules_to_hook:
-        displayHeaderTop:
-          # displayHeaderTop will have exactly the following
-          # modules hooked to it, in the specified order.
-          # Each module in this list will be unhooked
-          # from all other display hooks it is hooked to.
-          - blocklanguages
-          - blockcurrencies
-          - blockuserinfo
-        displayHeaderMiddle:
-          # displayHeaderMiddle will have whatever is currently hooked to it
-          # kept hooked to it, and blocksearch will be appended
-          # to the list (or moved to the end if already hooked there).
-          - ~
-          - blocksearch
-        displayHeaderBottom:
-          # displayHeaderBottom will have blocktopmenu and blockcart
-          # prepended to it.
-          - blocktopmenu
-          - blockcart
-          - ~
-        displayFooter:
-          - blocknewsletter
-        displayLeftColumn:
-          # blockcategories is hooked on all pages on displayLeftColumn
-          - blockcategories
-          # blocktags is hooked on displayLeftColumn on all pages
-          # except "category" and "index"
-          - blocktags:
-              except_pages:
-                - category
-                - index
-```
-
-### Image settings
-
-Enabling the theme will remove all the existing image types.
-
-Therefore, themes MUST declare their image types, and what they apply to.
-
-```yaml
-  global_settings:
-    image_types:
-      cart_default:
-        width: 80
-        height: 80
-        scope: [products]
-      small_default:
-        width: 125
-        height: 125
-        scope: [products, categories, manufacturers, suppliers]
-      medium_default:
-        width: 300
-        height: 300
-        scope: [products, categories, manufacturers, suppliers]
-      large_default:
-        width: 500
-        height: 500
-        scope: [products]
-      home_default:
-        width: 250
-        height: 250
-        scope: [products]
-      category_default:
-        width: 960
-        height: 350
-        scope: [categories]
-      product_listing:
-        width: 220
-        height: 220
-        scope: [products, categories, manufacturers, suppliers]
-      large_banner:
-        width: 960
-        height: 400
-        scope: [categories]
-```
-
-### Theme settings
-
-All the settings below can be changed through an interface in the theme's back office interface, and only depend on the theme/shop combination.
-
-When the theme.yml file is parsed by PrestaShop, the 'theme_settings' configuration key is copied to a file named settings_n.yml, where 'n' is the id of the shop where the theme is installed (settings_123456.yml, for instance).
-
-When the configuration is changed through the back office interface, only the settings_n.yml file is updated - the theme.yml file remains unchanged.
-
-```yaml
-  global_settings:
-    theme_settings:
-      default_layout: layout-full-width
-      layouts:
-        # Specific layout for some pages
-        identity: layout-left-side-column
-        order-confirmation: layout-left-side-column
-```
-
-#### Disable loading of `core.js` file in your custom theme 
-{{< minver v="8.1.0" title="true">}}
-
-You can disable `core.js` loading and provide a custom implementation of the whole logic initially contained in `core.js`.
-To do this, use the `core_scripts` option, set to false, in `theme_settings` like in this example:
-
-```yaml
-theme_settings:
-    core_scripts: false
-```
-
-## Dependencies
-
-When making a theme you may want to add features with custom modules. It's important that these modules
-are installed with your theme. These modules should be declared as dependencies so you're sure prestashop
-will export them when creating your theme zipball.
-
-So far themes only have modules dependencies.
-
-```yaml
-  dependencies:
-    modules:
-      - xx_customslider
-      - xx_customproductpage
-```
diff --git a/themes/getting-started/tools-for-theme-designers.md b/themes/getting-started/tools-for-theme-designers.md
deleted file mode 100644
index 32608907b6..0000000000
--- a/themes/getting-started/tools-for-theme-designers.md
+++ /dev/null
@@ -1,217 +0,0 @@
----
-title: Tooling prerequisites for theme designers
-menuTitle: Required tools
-weight: 20
----
-
-# Tooling prerequisites for theme designers
-
-The way 1.7 themes are created is significantly different from the way they were with PrestaShop 1.6. By taking the freedom to rewrite the way themes work according to the latest best-practices, we chose to also work with modern tools. These tools are widely accepted as best-of-breed in the current web development; hence, learning to use them will not only make you more productive in PrestaShop development, but more importantly in web development in general.
-
-While those tools will help all designers and developers in the long run, there is a first step of knowing how to use them, particularly if you have never used such a chain of tools through the command line.
-
-This page is here to help! It will browse through the toolset, so that you know what the rest of the documentation is talking about :)
-
-
-## Which tools are we talking about?
-
-The PrestaShop developers chose to rely on these tools for the development of the Classic theme:
-
-* Git
-* Composer
-* npm
-* Webpack
-
-Along with these tools, PrestaShop 1.7 introduced frameworks and design tools that are must-know:
-
-* Bootstrap 4
-* Symfony and its Twig template engine
-* Sass
-* Bourbon
-
-This document presents each tool, and how they can get you to become a more productive web developer -- not just a more productive PrestaShop theme developer!
-
-
-## Before we get started: using the command line
-
-Many of the tools cited above are to be used through the command line -- launching commands in a text-based environment, line after line.
-While it has the advantage of being very powerful and easy to automate, it is also not intuitive and can be hard to grasp. Luckily, it only takes a handful of commands to understand the power of the command line, and to adopt it for your everyday processes.
-
-Now, as a web-designer, you might be more used to work with graphical interfaces, such as Dreamweaver (for the more WYSIWYG-inclined), or a full-featured text editor, such as Sublime Text, Atom or Brackets (among many other possibilities). Using the command line can supplement this.
-
-All operating systems give you access to a command line interface (CLI).
-
-* Windows: It is called the "command prompt".
-
-  * You can open it this way:
-
-    1. Open the Start menu, for instance by pressing the Windows key of your keyboard.
-    2. In the Search field, type `cmd` and press Enter. This will start the cmd.exe program.
-
-  * Try out a few basic commands:
-
-    * dir: lists the files in the current folder.
-    * cd: change the current directory. For instance, "cd Downloads" to enter a Downloads directory in the current folder; or `cd ..` to go to the parent folder.
-    * ping: to see the response time for a website. For instance, `ping google.com`.
-  * Note: Windows 10 also includes the Linux-
-
-* OS X: It is called the "terminal".
-
-  * You can open it this way:
-
-    1. Open Spotlight, for instance by pressing the Command key and Spacebar at the same time.
-    2. In the Search field, start typing "terminal" until the real "Terminal" is suggested, then press Enter. This will start the Terminal.app program.
-  * Try out a few basic commands:
-    * ls: displays the content of the current folder.
-    * cd: change the current directory. For instance, `cd Downloads` to enter a Downloads directory in the current folder; or `cd ..` to go to the parent folder.
-    * ping: to see the response time for a website. For instance, `ping google.com`.
-
-* Unix/Linux: Oh come on, don't tell me you don't already use bash, tcsh, zsh or any other POSIX variation of the concept! :)
-
-There are many default tools and commands which you can use and even combine, but we're going to use some non-standards tools: npm, Git, Composer and Webpack. Because they are non-standards, you will have to install and configure them first.
-
-Note that you do not HAVE TO use these exactly: you can choose alternatives such as Gulp or Grunt if you're more familiar with them. We simply use Webpack :)
-
-
-## Using Git to manage your project files
-
-Git is a version control system, designed to manage decentralized projects with speed and efficiency.
-In plain English: you can use Git to save the current state of your files (through individual snapshot), in order to return to a previous state should the need arise, among other things.
-
-As a theme designer, tracking all your CSS and JavaScript changes can help you return to a previous snapshot of a file or of the whole project, add new code without breaking the code that's already working, collaborate with others, and in general keep you from losing your project because of a bad Ctrl-S.
-
-If you have already used the Subversion system, think of Git as a decentralized Subversion (to keep it simple): any machine hosts all versions of all the files, and therefore there is no centralized repository. In effect, the PrestaShop project is mainly hosted on GitHub -- but developers also work on it on their own machine.
-
-
-### Why you should use it for your PrestaShop theme?
-
-The PrestaShop Open Source project makes heavy use of Git in order to keep versions of its files. The community can access the official public repository on GitHub: https://github.com/PrestaShop/PrestaShop
-
-As a theme designer, you will need Git in order to retrieve the latest version of PrestaShop 1.7 and its default theme, "Classic".
-
-Note: You do not need to install or use Git if you are not interested in the latest development of PrestaShop.
-
-
-### How can you install it?
-
-Simply download the archive for the latest version of Git (2.23 as of this writing) and install it just like you would do for any other software:
-
-* Windows: https://git-for-windows.github.io/
-
-  * User interfaces are available, for instance https://tortoisegit.org/ or https://www.gitkraken.com/
-* OS X: https://git-scm.com/download/mac
-
-  * User interfaces are available, for instance https://git-fork.com/ or https://www.gitkraken.com/
-* Linux: type `apt-get install git` (or your distribution's equivalent).
-
-You can then open your command line and type `git --version` to check that Git is indeed installed. It should display the version number. You're good to go!
-
-
-## Using Composer to manage your PHP dependencies
-
-The PHP ecosystem is made of code packages which can be embedded into bigger projects, or even into other code packages which, in turn, can be embedded, etc. These packages are called dependencies.
-
-Being able to rely on such code packages is great, because it prevents from having to reinvent the wheel every time a well-known feature is needed. On the other hand, dependencies can get problematic: the more a project depends on third-party package, the more it must manage dependency resolution (determining which package to use), autoloading solution (finding the right package and making it available automatically), and keeping all packages up to date (or not, if backward compatibility is an issue).
-
-In short, the modern PHP ecosystem can get complex quite quickly, and Composer is the main way PHP developers manage their dependencies.
-
-
-### Why you should use it for your PrestaShop theme?
-
-Now, why should you care about PHP files when working on a PrestaShop theme? Since you mostly work with theme files (.tpl, .css and .js), .php files are few in your editor, and "PHP dependencies" is something out there, and it seems you'd be better off avoiding them, right?
-
-Thing is, PrestaShop uses Composer to build its own package dependencies. While the Zip archive available for public download is packed with all the required dependencies, the Git-hosted files do not automatically download and install all those dependencies: PrestaShop developers rely on Composer for that, through a `composer.json` file located at the root of the official Git folder.
-
-In short, you need to use Composer when working with the latest development version from Github, in order to have a complete set of packages.
-
-Yes, that means that if you choose not to retrieve the latest PrestaShop files using Git, but to simply install the latest public archive, then you do not need to worry about Composer.
-But not using the latest Git version also means that you cannot work with the development version of PrestaShop, and that you rely on the Core developers to release upgraded packages, thus giving you no head start in developing with new features. Your call!
-
-
-### How can you install it?
-
-Download the archive for the latest version of Composer (1.9 as of this writing) and install it just like you would do for any other software:
-
-Note: you need to already have the PHP tool installed on your machine. You probably already have it if you're building websites locally. If not, install WampServer, EasyPHP, XAMPP or any other Windows Apache+PHP+MySQL package there is.
-
-* Windows: https://getcomposer.org/Composer-Setup.exe
-* OS X and Linux: in your command line, type these commands:
-
-  * `curl -s https://getcomposer.org/installer | php`
-  * `sudo mv composer.phar /usr/local/bin/composer`
- 
-Testing it requires using the command line; there is no graphical interface for this tool.
-Simply type `composer --version` to check that it is indeed installed.
-
-
-## Using npm to automate compilation from third-party package
-
-npm is a popular package manager, which originates from the JavaScript ecosystem -- most precisely, from the Node.js JS runtime environment.
-
-npm is both a command line tool and an online registry (located at https://www.npmjs.com/): you can use it to manage the dependencies (yes, just like Composer), or simply to work with useful packages. It is an extremely useful command to have when building websites, even if you do not use JavaScript or Node.js.
-
-
-### Why you should use it for your PrestaShop theme?
-
-In the context of building PrestaShop themes, npm is mostly used in order to automate tasks -- namely, building assets automatically so that you don't have to.
-
-PrestaShop 1.7 themes are built around "assets": CSS, JavaScript and image files, which are (or can be) generated from easier-to-manager formats:
-
-* CSS files are built from Sass files (.scss).
-* Some image files are built from SVG files (.svg).
-* JavaScript files are from several files (.js).
-
-All the source files are located in the theme's `_dev` folder. The generated files are built using Webpack, a JavaScript module bundler. See below for more information about Webpack.
-
-
-### How can you install it?
-
-npm cannot be directly downloaded and installed. It is an integral part of the Node.js tool, therefore you need to download and install Node.js, which in turn will install npm for you.
-
-To download Node.js, please refer to the [NodeJS versions table]({{< ref "/9/development/compile-assets" >}})
-
-So, install Node.js on your machine, then test that npm is available:
-
-* Open your command line interface.
-* Type `node -v` to check that Node.js is installed.
-* Type `npm -v` to check that npm is indeed available.
-
-npm is updated much more frequently that Node.js, so chances are that there's a more recent version available than the one from the Node.js package.
-
-To update your npm:
-
-* Open your command line interface.
-* Type `npm install npm -g`: this tells npm to install npm as global package.
-* Type `npm -v` to check if the version has indeed changed.
-
-
-## Using Webpack to compile and minify your asset files
-
-Modern website are getting more and more complex, and JavaScript becomes more prominent than ever in the web-development world. As a result there is a lot of code on the client side!
-
-Webpack was built in order to make your life easier, most notably by organizing your code into JavaScript modules. It takes a whole lot of work off your shoulders: you have better things to do than to edit configuration files in order to adjust media files, fonts or URLs.
-
-Before Webpack, many were using task-runners such as Grunt or Gulp in order to organize their code. That lead to a patchwork of configuration, and you had to pay a lot of attention to any change in order to not break everything. Webpack fixes this in an elegant way.
-
-### Why you should use it for your PrestaShop theme?
-
-Let’s see where we’re at. So far was have installed:
-
-* Git: A better way to make a snapshot of your codebase.
-* Composer: A better way to manage your PHP dependencies.
-* npm: A better way to automate tasks (among many other things).
-
-It’s all fine and dandy, but all of this remains very developer-centric, and there comes a time when you have to think about the user, and optimize for the browser.
-Fear not, for Webpack is here to save the day! Webpack is a “module bundler”, meaning that it turns your assets into JavaScript modules, and packs them into static assets.
-
-So, the main interest of using Webpack is that it will compile all your styles into a single CSS file. This way, your theme will make only one HTTP request for this single file, and since your browser will cache it for later re-use, it will even download this file only once.
-
-The same goes for your JavaScript code. Instead of loading jQuery along with its community plugins, your own custom plugins and any extra code you might need, Webpack compiles and minifies all this JavaScript code into a single file, which will be loaded once - and cached.
-
-
-### How can you install it?
-
-From the moment you have npm installed (see above), Webpack can be installed in a few seconds:
-
-* Open your command line interface.
-* Type `npm install webpack -g`
diff --git a/themes/guidelines/_index.md b/themes/guidelines/_index.md
new file mode 100644
index 0000000000..d5968d5b50
--- /dev/null
+++ b/themes/guidelines/_index.md
@@ -0,0 +1,24 @@
+---
+title: Guidelines
+weight: 25
+chapter: true
+showOnHomepage: true
+aliases:
+  - /9/themes/getting-started/guidelines
+---
+
+# Guidelines
+
+These guidelines define the quality bar for new PrestaShop theme development. They represent the **new standard** introduced with PrestaShop 9 and Hummingbird — existing themes are not required to comply, but new themes and contributions to the ecosystem are expected to follow them.
+
+Accessibility is treated as a first-class requirement, not an afterthought. The [European Accessibility Act (EAA)](https://ec.europa.eu/social/main.jsp?catId=1202) makes digital accessibility legally mandatory for e-commerce in EU member states from June 2025. Hummingbird is built to align with these requirements, and themes distributed on PrestaShop Marketplace are expected to do the same.
+
+| Page | What it covers |
+|------|----------------|
+| **[Coding standards]({{< relref "/9/themes/guidelines/coding-standards" >}})** | HTML semantics, BEM naming, vanilla JavaScript, `data-ps-*` attributes, file naming, and formatting rules |
+| **[Browser compatibility]({{< relref "/9/themes/guidelines/browser-compatibility" >}})** | Evergreen browser targets, Web Platform Baseline, no IE, progressive enhancement with `@supports` |
+| **[Accessibility]({{< relref "/9/themes/guidelines/accessibility" >}})** | EAA-aligned requirements (WCAG 2.2 AA) — semantic HTML, ARIA, keyboard navigation, focus management, contrast ratios, and validation tools |
+
+{{% notice tip %}}
+Building on Hummingbird? The [coding standards]({{< relref "/9/themes/guidelines/coding-standards" >}}) are the right starting point — they cover the patterns already in use in the codebase.
+{{% /notice %}}
diff --git a/themes/guidelines/accessibility.md b/themes/guidelines/accessibility.md
new file mode 100644
index 0000000000..24dafd09f2
--- /dev/null
+++ b/themes/guidelines/accessibility.md
@@ -0,0 +1,90 @@
+---
+title: Accessibility requirements
+menuTitle: Accessibility
+weight: 3
+---
+
+# Accessibility requirements
+
+Accessibility is a hard requirement for new PrestaShop themes, not an optional enhancement. The [European Accessibility Act (EAA)](https://ec.europa.eu/social/main.jsp?catId=1202) makes digital accessibility legally mandatory for e-commerce in EU member states from June 2025. These guidelines are aligned with **WCAG 2.2 AA** — the standard referenced by the EAA — and apply to all new themes and contributions to the ecosystem.
+
+This page covers the key requirements. Each project has its own specifics — use this as a baseline and adapt as needed.
+
+{{% notice tip %}}
+For Hummingbird's concrete implementation (focus management helpers, theme state), see [Hummingbird accessibility]({{< relref "/9/themes/hummingbird/accessibility" >}}).
+{{% /notice %}}
+
+## Semantic HTML
+
+Correct HTML semantics are the foundation of accessibility. See [Coding standards]({{< relref "/9/themes/guidelines/coding-standards#html" >}}) for the full HTML rules. Accessibility-specific additions:
+
+- `<h1>`–`<h6>` in order, no skipping levels — headings define the document outline for screen reader users
+- Provide text alternatives for all non-text content: `alt` on images, captions on video and audio
+
+## ARIA
+
+Use ARIA to fill gaps where semantic HTML alone is not sufficient — but prefer native HTML elements first:
+
+- Accessible names and descriptions: `aria-label`, `aria-describedby`
+- State attributes for dynamic content: `aria-expanded`, `aria-controls`, `aria-hidden`, `aria-live`
+- `role` only when no native element conveys the right meaning
+- Never duplicate information already expressed by the HTML element itself
+
+## Keyboard navigation
+
+All interactive elements must be reachable and operable without a mouse:
+
+- Provide a visible skip link at the top of the page to bypass repeated navigation
+- Maintain a logical tab order that matches the visual reading order
+- Never remove the focus outline without providing a visible replacement
+- Custom widgets (tabs, accordions, dropdowns) must have full keyboard support per [ARIA patterns](https://www.w3.org/WAI/ARIA/apg/)
+
+## Focus management
+
+When content updates without a full page reload — AJAX cart updates, filter results, modal opening — focus must be managed explicitly:
+
+- After opening a modal or overlay: move focus inside it and trap it there; support `Escape` to close and return focus to the trigger
+- After an AJAX update: restore focus to the element the user was interacting with, or to a logical fallback in the updated region
+- Never let focus get lost or reset to the top of the page unexpectedly
+
+## Forms
+
+- Every form control must have an associated `<label>`, or an ARIA equivalent (`aria-label`, `aria-labelledby`)
+- Required fields must be marked both visibly and programmatically (`aria-required="true"` or `required`)
+
+## Screen readers
+
+- Use `aria-live` regions to announce dynamic updates (cart count, filter results, notifications)
+- Provide screen-reader-only text when the visible context is insufficient (e.g. "Remove" buttons that need product name context)
+- Test with at least one screen reader: VoiceOver (macOS/iOS), NVDA or JAWS (Windows)
+
+## Contrast and visual design
+
+| Requirement | WCAG 2.2 AA threshold |
+|-------------|----------------------|
+| Normal text (below 18px regular or 14px bold) | 4.5:1 minimum contrast ratio |
+| Large text (18px+ regular or 14px+ bold) | 3:1 minimum contrast ratio |
+
+Never rely on color alone to convey information — always pair it with text or a universally recognizable visual element (icon, pattern, label).
+
+Additional requirements:
+- Minimum body text size: 14px — prefer `rem`/`em` units
+- Touch targets: minimum 24×24px (WCAG 2.2 AA) — aim for 32px or above for comfortable usability
+
+## Validation
+
+No single tool catches everything. Use a combination:
+
+| Tool | Type | What it catches |
+|------|------|-----------------|
+| [Lighthouse](https://developer.chrome.com/docs/lighthouse/) | Automated | ~30% of WCAG issues — good first pass |
+| [axe DevTools](https://www.deque.com/axe/devtools/) | Automated | More comprehensive than Lighthouse |
+| [Accessibility Insights](https://accessibilityinsights.io/) | Semi-automated | Guided manual checks for full WCAG coverage |
+| Keyboard navigation | Manual | Tab order, focus trapping, custom widget behavior |
+| Screen reader | Manual | Announcements, live regions, label quality |
+
+## Further reading
+
+- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/) — W3C Web Content Accessibility Guidelines
+- [ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) — W3C patterns and examples for accessible widgets
+- [European Accessibility Act — official page](https://ec.europa.eu/social/main.jsp?catId=1202)
diff --git a/themes/guidelines/browser-compatibility.md b/themes/guidelines/browser-compatibility.md
new file mode 100644
index 0000000000..2de13e2655
--- /dev/null
+++ b/themes/guidelines/browser-compatibility.md
@@ -0,0 +1,68 @@
+---
+title: Browser compatibility
+weight: 2
+---
+
+# Browser compatibility
+
+PrestaShop 9 themes target **evergreen browsers** — browsers that update automatically and stay current. This means modern versions, not a specific pinned release. The minimum floor is set by [Bootstrap 5.3](https://getbootstrap.com/docs/5.3/getting-started/browsers-devices/), which the entire theme stack is built on.
+
+## Supported browsers
+
+| Browser | Desktop | Mobile |
+|---------|---------|--------|
+| **Chrome** | Modern versions | Android |
+| **Firefox** | Modern versions | Android |
+| **Safari** | Modern versions | iOS |
+| **Edge** | Modern versions | — |
+
+{{% notice warning %}}
+Internet Explorer and other legacy browsers are **not supported**. This is consistent with the [Bootstrap 5.3 browser support policy](https://getbootstrap.com/docs/5.3/getting-started/browsers-devices/) and will not change.
+{{% /notice %}}
+
+## Web Platform Baseline
+
+[Web Platform Baseline](https://web.dev/baseline/) is a signal created by browser vendors (Google, Mozilla, Apple, Microsoft) that tells you when a web feature is safe to use across all major browsers. PrestaShop 9 themes use it as the reference for deciding whether a CSS or JavaScript feature can be used without fallbacks.
+
+Baseline divides features into three tiers:
+
+| Tier | Definition | Usage |
+|------|------------|-------|
+| **Widely Available** | Supported in all major browsers for 30+ months | Use freely — no fallback needed |
+| **Newly Available** | Just reached cross-browser support | Use with care — consider your audience's browser update frequency |
+| **Limited availability** | Not yet supported in all major browsers | Avoid, or use only with a `@supports` fallback |
+
+You can check any feature's Baseline status on [MDN](https://developer.mozilla.org/) (shown in the browser compatibility table) or [caniuse.com](https://caniuse.com/).
+
+## Progressive enhancement
+
+For features that are Newly Available or where you want to gracefully degrade, use `@supports`:
+
+```css
+/* Base layout — works everywhere */
+.product-list {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+}
+
+/* Container queries — Newly Available, @supports guards older browsers */
+@supports (container-type: inline-size) {
+  .product-list {
+    container-type: inline-size;
+  }
+
+  @container (max-width: 400px) {
+    .product-card {
+      flex-direction: column;
+    }
+  }
+}
+```
+
+## Testing
+
+Test your theme in modern versions of all supported browsers before release:
+
+- **Desktop:** Chrome, Firefox, Safari, Edge
+- **Mobile:** Safari on iOS, Chrome on Android
+- **Tools:** Browser DevTools device emulation for quick checks; [BrowserStack](https://www.browserstack.com/) or [Playwright](https://playwright.dev/) for systematic cross-browser testing
diff --git a/themes/guidelines/coding-standards.md b/themes/guidelines/coding-standards.md
new file mode 100644
index 0000000000..ec001c1d74
--- /dev/null
+++ b/themes/guidelines/coding-standards.md
@@ -0,0 +1,89 @@
+---
+title: Coding standards
+weight: 1
+---
+
+# Coding standards
+
+These standards apply to new themes and contributions targeting PrestaShop 9. They reflect the patterns used in [Hummingbird]({{< relref "/9/themes/hummingbird" >}}) and define what is expected in the ecosystem going forward.
+
+## HTML
+
+Use correct, semantic HTML5 — the right element for the right purpose:
+
+- Landmark elements for page structure: `<nav>`, `<main>`, `<header>`, `<footer>`, `<section>`, `<article>`, `<aside>`
+- `<button>` for actions, `<a>` for navigation
+- Self-closing syntax for void elements: `<br>`, `<img>`, `<input>`
+- All open tags must be closed within the same template file
+- Shared fragments (header, footer, partials) belong in a `_partials/` directory
+
+```smarty
+<nav aria-label="{l s='Main navigation' d='Shop.Mytheme'}">
+  <ul>
+    <li><a href="{$urls.pages.index}">{l s='Home' d='Shop.Theme.Global'}</a></li>
+    <li><a href="{$urls.pages.cart}">{l s='Cart' d='Shop.Theme.Global'}</a></li>
+  </ul>
+</nav>
+```
+
+## CSS
+
+### BEM naming convention
+
+All custom CSS classes follow the [BEM](https://getbem.com/naming/) convention — Block, Element, Modifier:
+
+```css
+/* Block — standalone component */
+.product-card { }
+
+/* Element — part of the block (double underscore) */
+.product-card__title { }
+.product-card__image { }
+
+/* Modifier — variant of a block or element (double hyphen) */
+.product-card--featured { }
+.product-card__title--small { }
+```
+
+Rules:
+- Block names: lowercase with hyphens
+- Select by class only — no tag selectors, no IDs
+- Never nest BEM selectors (`.product-card .product-card__title` is wrong)
+
+### SCSS
+
+- Write styles in SCSS, compiled to CSS via the build pipeline
+- Organize files modularly by component — one partial per component
+- Use SCSS variables and mixins for shared values; prefer Bootstrap variables before introducing new ones
+- Place new files in the appropriate `src/scss/` subdirectory
+
+{{% notice tip %}}
+See [CSS architecture]({{< relref "/9/themes/hummingbird/css-architecture" >}}) for the full `src/scss/` directory structure, `@layer` order, and guidance on where to add custom styles.
+{{% /notice %}}
+
+## JavaScript
+
+- Write **vanilla JavaScript** — do not use jQuery in new theme code (jQuery is loaded by `core.js` for module backward compatibility only)
+- Use modern ECMAScript syntax: `const`/`let`, arrow functions, template literals, `async`/`await`, native `import`/`export`
+- Use [`data-ps-*` attributes]({{< relref "/9/themes/hummingbird/javascript#semantic-data-ps--attributes" >}}) to target DOM elements from JavaScript — not CSS classes
+- Use the `prestashop` event system for cross-component communication
+
+{{% notice tip %}}
+See [JavaScript conventions]({{< relref "/9/themes/hummingbird/javascript" >}}) for the full `data-ps-*` attribute reference, the events map, and the selectors map.
+{{% /notice %}}
+
+## File naming
+
+| File type | Convention | Example |
+|-----------|------------|---------|
+| SCSS partials | Underscore prefix, lowercase with hyphens | `_product-card.scss` |
+| JavaScript / TypeScript | Lowercase with hyphens | `product-gallery.js` |
+| Smarty templates | Lowercase with hyphens | `product-list.tpl` |
+| Shared fragments | Placed in a `_partials/` directory | `_partials/header.tpl` |
+
+## Formatting
+
+- **2 spaces** for indentation in all front-end files (HTML, CSS, SCSS, JS, Smarty templates)
+- End every file with a newline; no trailing whitespace
+- Configure your editor with [EditorConfig](https://editorconfig.org/) — Hummingbird ships with an `.editorconfig` file
+- When working within Hummingbird or a fork of it, use the bundled linters and formatters: **ESLint**, **Stylelint**, and **Prettier**
diff --git a/themes/hummingbird/_index.md b/themes/hummingbird/_index.md
index 7d1f26ec40..56f626e0d8 100644
--- a/themes/hummingbird/_index.md
+++ b/themes/hummingbird/_index.md
@@ -1,20 +1,25 @@
 ---
-title: Hummingbird Theme
-weight: 5
+title: Hummingbird
+weight: 15
+chapter: true
+showOnHomepage: true
 ---
 
-# Hummingbird Theme
+# Hummingbird
 
-Hummingbird is a PrestaShop theme that aims to replace Classic as a new default theme for the PrestaShop. 
+Hummingbird is the default theme for PrestaShop 9.1+ and the reference implementation for modern theme development. It replaces the Classic theme, which is deprecated for new development in PrestaShop 9.
 
-Read more about Hummingbird [in the announcement of the new theme for PrestaShop](https://build.prestashop-project.org/news/2022/new-theme-announce/).
+- **Repository:** [github.com/PrestaShop/hummingbird](https://github.com/PrestaShop/hummingbird)
 
-Want to test it? Want to contribute to the project and share the feedback with the team? See [Hummingbird Github repository](https://github.com/PrestaShop/hummingbird).
+| Page | Description |
+|------|-------------|
+| [CSS Architecture]({{< relref "/9/themes/hummingbird/css-architecture" >}}) | [Bootstrap 5.3](https://getbootstrap.com/docs/5.3/getting-started/introduction/), [BEM](https://getbem.com/naming/), SCSS, `@layer`, dark mode via color modes |
+| [JavaScript]({{< relref "/9/themes/hummingbird/javascript" >}}) | jQuery-free theme code, semantic `data-ps-*` attributes, event system |
+| [Accessibility]({{< relref "/9/themes/hummingbird/accessibility" >}}) | EAA compliance, ARIA, keyboard navigation |
+| [Development Workflow]({{< relref "/9/themes/hummingbird/development-workflow" >}}) | README link, troubleshooting, dev environment tips |
+| [Bootstrap Compatibility]({{< relref "/9/themes/hummingbird/bootstrap-compatibility" >}}) | BS4→BS5 migration guide for modules |
+| [Hook mapping]({{< relref "/9/themes/hummingbird/hooks" >}}) | Visual map of front-office hooks per page |
 
-{{% notice info %}}
-Please note that the Hummingbird theme is still under development and is not considered production-ready.
+{{% notice note %}}
+Want to contribute to Hummingbird? See [CONTRIBUTING.md](https://github.com/PrestaShop/hummingbird/blob/develop/CONTRIBUTING.md) in the repository.
 {{% /notice %}}
-
-## Hook mapping project for the Hummingbird theme
-
-A visual map of hooks for the Hummingbird theme has been created, [find more information about the project here]({{<relref "/9/themes/hummingbird/hooks">}}).
\ No newline at end of file
diff --git a/themes/hummingbird/accessibility.md b/themes/hummingbird/accessibility.md
new file mode 100644
index 0000000000..d59b31a866
--- /dev/null
+++ b/themes/hummingbird/accessibility.md
@@ -0,0 +1,53 @@
+---
+title: Accessibility
+weight: 3
+---
+
+# Accessibility
+
+Accessibility is a baseline requirement in Hummingbird, not an optional enhancement. It is already mandatory in many countries (for example under the European Accessibility Act) and is increasingly treated as a standard for e‑commerce. The theme is built to comply with EAA-relevant standards. All theme contributions must maintain or improve accessibility compliance.
+
+{{% notice info %}}
+See [Accessibility requirements]({{< relref "/9/themes/guidelines/accessibility" >}}) for a detailed checklist that applies to every PrestaShop theme.
+{{% /notice %}}
+
+## What the theme implements
+
+The theme puts a strong focus on accessibility. When content is updated dynamically, focus is restored so keyboard and screen reader users keep their place. Dynamic updates are announced to assistive technology via live regions. Interactive elements are keyboard-operable, and overlays support focus trapping and closing via keyboard.
+
+## Accessibility helpers (`a11y.ts`)
+
+Hummingbird provides an `A11yHelpers` class (`src/js/helpers/a11y.ts`) with focus management utilities. Theme scripts use it to save and restore focus across AJAX updates — for example, after a cart refresh or product combination change, focus returns to the control the user was using (quantity input, remove button, voucher field, etc.).
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `storeFocus()` | `void` | Saves the currently focused element (`document.activeElement`) |
+| `restoreFocus(fallback?)` | `void` | Restores focus to the stored element — tries by ID first, then by element reference, then an optional fallback. Clears the store afterward |
+| `setFocus(element)` | `void` | Focuses a specific element and stores it |
+| `getStoredFocus()` | `HTMLElement \| null` | Returns the stored element |
+| `getStoredFocusId()` | `string \| null` | Returns the stored element's `id` |
+| `clearStoredFocus()` | `void` | Clears all stored focus data |
+
+## Theme state (`state.ts`)
+
+The accessibility helpers rely on a centralized `ThemeState` singleton (`src/js/state.ts`) that tracks runtime state for the current page. It exposes a simple `get()` / `set()` / `merge()` API. State is in-memory only and does not persist across full page navigations.
+
+Current state keys:
+
+| Key | Type | Purpose |
+|-----|------|---------|
+| `storedFocusElement` | `HTMLElement \| null` | The element stored by the a11y helpers for focus restoration |
+| `storedFocusElementId` | `string \| null` | The `id` of the stored element (used as primary lookup on restore) |
+| `lastUpdateAction` | `string \| null` | Tracks the last cart-related action so scripts know *what* triggered an update (e.g. quantity change, product removed, voucher submitted). The set of values is defined in the theme and may grow over time. |
+
+Theme scripts use `lastUpdateAction` to restore focus after a cart AJAX refresh: for example, focus returns to the quantity input after a quantity change, or to the voucher form after a voucher submission or removal.
+
+## Guidelines for contributions
+
+Customizations and contributions must follow web accessibility principles in line with EAA, RGAA, or other applicable accessibility rules. A detailed checklist is available in [Accessibility requirements]({{< relref "/9/themes/guidelines/accessibility" >}}).
+
+## Further reading
+
+- [Web Accessibility (MDN)](https://developer.mozilla.org/en-US/docs/Web/Accessibility) — Concepts, ARIA, and guides for building accessible web content
+- [ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) — Accessible patterns and widgets (W3C)
+- [Hummingbird CONTRIBUTING.md](https://github.com/PrestaShop/hummingbird/blob/develop/CONTRIBUTING.md) — Contribution workflow
diff --git a/themes/hummingbird/bootstrap-compatibility.md b/themes/hummingbird/bootstrap-compatibility.md
new file mode 100644
index 0000000000..dc48b494a9
--- /dev/null
+++ b/themes/hummingbird/bootstrap-compatibility.md
@@ -0,0 +1,89 @@
+---
+title: Bootstrap compatibility
+weight: 5
+aliases:
+  - /9/themes/reference/bootstrap-compatibility
+---
+
+# Bootstrap compatibility
+
+## Why this matters
+
+Hummingbird uses [Bootstrap 5.3](https://getbootstrap.com/docs/5.3/getting-started/introduction/), but the PrestaShop module ecosystem was largely built on Bootstrap 4 (Classic theme). Bootstrap 5 introduced breaking changes — renamed classes, namespaced data attributes (`data-bs-*`), and the removal of jQuery as a dependency. Without intervention, modules that rely on BS4 patterns render incorrectly or lose interactive behavior (modals, tooltips, dropdowns) when used with Hummingbird.
+
+## The Bootstrap Compatibility Layer
+
+The [Bootstrap Compatibility Layer](https://github.com/PrestaShop/bootstrap-compatibility-layer) is a standalone library — it is **not part of Hummingbird**. It is a lightweight runtime shim that maps BS4 data attributes, class names, and jQuery plugin calls to their BS5 equivalents. Module developers who need it must include it in their own modules.
+
+{{% notice warning %}}
+The compatibility layer is a **temporary patch**, not a long-term solution. Migrating your module's markup to Bootstrap 5.3 is always the better approach — it removes a runtime dependency, reduces page weight, and avoids subtle rendering differences. Use the layer only as a stopgap while you plan a proper migration.
+
+New modules targeting PrestaShop 9 must use Bootstrap 5.3 classes and attributes directly.
+{{% /notice %}}
+
+{{% notice note %}}
+For a full list of changes between Bootstrap 4 and 5, see the [Bootstrap migration guide](https://getbootstrap.com/docs/5.3/migration/).
+{{% /notice %}}
+
+## What the layer handles
+
+The library covers the three main breaking changes between Bootstrap 4 and 5:
+
+- **Data attributes** — Transforms BS4 attributes (`data-toggle`, `data-dismiss`, …) to their BS5 namespaced equivalents (`data-bs-toggle`, `data-bs-dismiss`, …).
+- **Class names** — Maps renamed utility classes (`.ml-*` → `.ms-*`, `.sr-only` → `.visually-hidden`, etc.).
+- **jQuery plugins** — Bridges jQuery-based plugin calls (`.modal()`, `.tooltip()`, …) to Bootstrap 5's vanilla JS API.
+
+## Installation
+
+### Package
+
+```bash
+npm install bootstrap-compatibility-layer
+```
+
+### CDN
+
+```html
+<link href="https://unpkg.com/bootstrap-compatibility-layer@1/dist/bootstrap-compatibility-layer.min.css" rel="stylesheet">
+<script src="https://unpkg.com/bootstrap-compatibility-layer@1"></script>
+```
+
+### From a module hook
+
+To load the compatibility layer from a module, use the `actionFrontControllerSetMedia` hook. Use `addCss()` and `addJs()` — these methods deduplicate by URL, so if multiple modules include the same asset it loads only once.
+
+```php
+public function hookActionFrontControllerSetMedia()
+{
+    $this->context->controller->addCss(
+        'https://unpkg.com/bootstrap-compatibility-layer@1/dist/bootstrap-compatibility-layer.min.css'
+    );
+    $this->context->controller->addJs(
+        'https://unpkg.com/bootstrap-compatibility-layer@1'
+    );
+}
+```
+
+## Usage
+
+### As a package
+
+```js
+import BSCompatibilityLayer from 'bootstrap-compatibility-layer';
+```
+
+The layer initializes automatically on import.
+
+### Via CDN
+
+The library auto-initializes for attribute and class transformations. For jQuery-based Bootstrap calls, wait for DOM ready:
+
+```html
+<script src="https://unpkg.com/bootstrap-compatibility-layer@1"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', function() {
+    $('[data-toggle="popover"]').popover();
+    $('[data-toggle="tooltip"]').tooltip();
+  });
+</script>
+```
diff --git a/themes/hummingbird/css-architecture.md b/themes/hummingbird/css-architecture.md
new file mode 100644
index 0000000000..e1795cb166
--- /dev/null
+++ b/themes/hummingbird/css-architecture.md
@@ -0,0 +1,111 @@
+---
+title: CSS architecture
+weight: 1
+---
+
+# CSS architecture
+
+Hummingbird's CSS is built on Bootstrap 5.3, organized in modular SCSS with CSS `@layer` for cascade control and [BEM](https://getbem.com/naming/) naming for custom components.
+
+## Bootstrap 5.3
+
+Hummingbird is built on [Bootstrap 5.3](https://getbootstrap.com/docs/5.3/getting-started/introduction/). Use Bootstrap utilities and components when they fit; extend with custom BEM-named components when they don't. Illustrative example:
+
+```html
+<!-- Bootstrap utilities: layout, spacing — no custom class needed -->
+<div class="d-flex justify-content-between p-3">...</div>
+
+<!-- Custom BEM: theme-specific structure that Bootstrap doesn't cover -->
+<div class="product-card product-card--featured">
+  <h3 class="product-card__title">...</h3>
+</div>
+```
+
+## BEM naming convention
+
+All custom CSS classes follow the [BEM (Block Element Modifier)](https://getbem.com/naming/) convention:
+
+```css
+/* Block */
+.product-card { }
+
+/* Element (double underscore) */
+.product-card__title { }
+.product-card__image { }
+.product-card__price { }
+
+/* Modifier (double hyphen) */
+.product-card--featured { }
+.product-card--out-of-stock { }
+.product-card__title--small { }
+```
+
+## SCSS architecture
+
+Source files live in `src/scss/` with a modular structure:
+
+```
+src/scss/
+├── abstract/               # Shared theme variables and mixins
+├── bootstrap/              # Bootstrap customization
+│   ├── overrides/
+│   │   └── variables/      # Bootstrap variable overrides
+│   │       └── components/ # Per-component variable overrides
+│   └── components/         # Bootstrap component restyling
+├── prestashop/             # PrestaShop-specific styles
+│   ├── base/               # Base element styles
+│   ├── components/         # Reusable UI components (product cards, buttons, etc.)
+│   ├── layout/             # Header, footer, grid structure
+│   ├── modules/            # Styles for core modules
+│   └── pages/              # Page-specific styles (product, checkout, etc.)
+├── vendors/                # Third-party CSS (Bootstrap imports, Material Icons, etc.)
+├── theme.scss              # Main entry point
+├── rtl.scss                # RTL overrides
+└── error.scss              # Error page styles
+```
+
+The entry point (`theme.scss`) defines the `@layer` order and imports abstractions, vendors, and PrestaShop styles:
+
+```scss
+@layer vendors, bs-base, bs-components, bs-custom-components, ps-base, ps-components, ps-pages, ps-modules, utilities;
+
+@import "abstract";
+@import "vendors";
+@import "prestashop";
+```
+
+### CSS `@layer`
+
+Hummingbird uses [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) to manage style priority. The layer order defined in `theme.scss` determines cascade precedence:
+
+| Layer | Purpose |
+|-------|---------|
+| `vendors` | Third-party libraries |
+| `bs-base` | Bootstrap base styles |
+| `bs-components` | Bootstrap components |
+| `bs-custom-components` | Bootstrap component overrides |
+| `ps-base` | PrestaShop base element styles |
+| `ps-components` | PrestaShop UI components |
+| `ps-pages` | Page-specific styles |
+| `ps-modules` | Module-specific styles |
+| `utilities` | Utility overrides (always win) |
+
+{{% notice warning %}}
+The layer order is intentional and carefully designed to separate Bootstrap, PrestaShop, and utility concerns. Do not modify it unless you fully understand the cascade impact. Instead, place your styles in the appropriate existing layer.
+{{% /notice %}}
+
+Unlayered CSS (e.g., from modules) retains higher cascade priority by design. This protects backward compatibility and allows gradual adoption of `@layer` across the ecosystem.
+
+For more context on the architecture decisions, see [Hummingbird v2: Architecture, Best Practices, and Contribution Guide](https://build.prestashop-project.org/news/2026/hummingbird-v2-architecture-best-practices-contribution/).
+
+## Adding custom styles
+
+Prefer configuration over overrides — adjust existing variables and use utility classes before writing custom CSS. When custom styles are needed, place them in the appropriate location:
+
+| What | Where |
+|------|-------|
+| Bootstrap variable overrides | `bootstrap/overrides/variables/` (per-component in `variables/components/`) |
+| Bootstrap component customization | `bootstrap/components/` |
+| New PrestaShop components | `prestashop/components/` → lands in `ps-components` layer |
+| Page-specific styles | `prestashop/pages/` → lands in `ps-pages` layer |
+| Shared theme variables and mixins | `abstract/` |
diff --git a/themes/hummingbird/development-workflow.md b/themes/hummingbird/development-workflow.md
new file mode 100644
index 0000000000..ee9b532b98
--- /dev/null
+++ b/themes/hummingbird/development-workflow.md
@@ -0,0 +1,65 @@
+---
+title: Development workflow
+weight: 4
+---
+
+# Development workflow
+
+{{% notice info %}}
+You need **Node.js 20.x** and **npm** to build Hummingbird. For the full list of tools, see [Requirements]({{< relref "/9/themes/getting-started/requirements" >}}). For setting up a local PrestaShop instance, see [Environment setup]({{< relref "/9/themes/getting-started/environment-setup" >}}).
+{{% /notice %}}
+
+## Build commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm ci` | Install exact dependency versions from the lockfile |
+| `npm run build` | Compile SCSS and TypeScript into production assets |
+| `npm run watch` | Watch for file changes and recompile automatically |
+| `npm run lint` | Run ESLint and Stylelint |
+| `npm run format` | Run Prettier |
+| `npm run storybook` | Launch Storybook component explorer |
+
+Run `npm ci` first to install dependencies, then `npm run build` to compile. During development, `npm run watch` recompiles on every file save.
+
+{{% notice tip %}}
+Hummingbird includes a `.nvmrc` file. If you use nvm, run `nvm use` in the theme directory to automatically switch to the correct Node.js version.
+{{% /notice %}}
+
+## Docker environment
+
+Hummingbird includes Docker Compose configurations that mount your theme directory automatically. See [Environment setup]({{< relref "/9/themes/getting-started/environment-setup" >}}) for setup instructions and available images.
+
+For the full Docker configuration details, see the [Hummingbird README](https://github.com/PrestaShop/hummingbird).
+
+## Storybook
+
+Hummingbird ships with [Storybook](https://storybook.js.org/) for isolated component development. Start it with:
+
+```bash
+npm run storybook
+```
+
+This opens a component explorer where you can develop and review UI components without a running PrestaShop instance.
+
+## Troubleshooting
+
+If styles or templates don't update during development:
+
+### PrestaShop cache
+
+In the Back Office under _Advanced Parameters > Performance_:
+
+- **Smarty:** set _Force compilation_ to **Yes** and _Cache_ to **No**
+- **CCC (Combine, Compress, Cache):** disable all options to prevent CSS/JS merging
+
+{{% notice info %}}
+For more development mode settings, see [Configure for development]({{< relref "/9/themes/getting-started/environment-setup#configure-for-development" >}}).
+{{% /notice %}}
+
+### Webpack watch not recompiling
+
+If `npm run watch` is running but compiled files are not updating:
+
+- Verify the watch process has no errors in its terminal output
+- Check that you are editing files inside `src/` — files in `assets/` are the compiled output and should not be edited directly
diff --git a/themes/hummingbird/hooks/_index.md b/themes/hummingbird/hooks/_index.md
index 9b9b00884c..6d8759af30 100644
--- a/themes/hummingbird/hooks/_index.md
+++ b/themes/hummingbird/hooks/_index.md
@@ -1,12 +1,23 @@
 ---
-title: Hooks on Hummingbird Theme
-weight: 3
+title: Hook mapping
+menuTitle: Hooks
+weight: 10
+aliases:
+  - /9/themes/reference/hooks
 ---
 
-# Hooks on Hummingbird Theme
+# Hook mapping
 
-Hummingbird theme introduced a brand new UI for the PrestaShop front office. 
+Visual maps of front-office hook locations in the Hummingbird theme, created by the PrestaShop Product Design team.
 
-A visual map of hook locations was created by the Product Design team at PrestaShop. 
+Each page below shows a Figma embed with hook positions and a reference table listing the page-specific hooks. Header and footer hooks are shared across all pages and are listed once on the [Home page]({{< relref "/9/themes/hummingbird/hooks/homepage" >}}).
 
-{{% children /%}}
\ No newline at end of file
+{{% notice note %}}
+The visual maps are embedded from Figma. If an embed does not load, refer to the hook table below it for the same information. The source Figma file is available in the [Hook Cartography project](https://www.figma.com/file/HKGzVBx5p2JaFrFocGe6p0/Hook-Cartography).
+{{% /notice %}}
+
+{{% notice info %}}
+For how hooks work in the PrestaShop theme system, see [Hooks]({{< relref "/9/themes/concepts/hooks" >}}). For the full list of available hooks, see the [hook reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks" >}}).
+{{% /notice %}}
+
+{{% children /%}}
diff --git a/themes/hummingbird/hooks/cartpage.md b/themes/hummingbird/hooks/cartpage.md
index 32ef500d02..aca4847546 100644
--- a/themes/hummingbird/hooks/cartpage.md
+++ b/themes/hummingbird/hooks/cartpage.md
@@ -1,16 +1,18 @@
 ---
 title: Cart page
-weight: 5
+weight: 4
 ---
 
 # Cart page
 
+Hooks available on the Hummingbird cart page.
+
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15450%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayShoppingCart` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayShoppingCart">}}) |
-| `displayCartExtraProductActions` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCartExtraProductActions">}}) |
-| `displayReassurance` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayReassurance">}}) |
-| `displayShoppingCartFooter` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayShoppingCartFooter">}}) |
-| `displayCrossSellingShoppingCart` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCrossSellingShoppingCart">}}) |
\ No newline at end of file
+| `displayShoppingCart` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayShoppingCart">}}) |
+| `displayCartExtraProductActions` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCartExtraProductActions">}}) |
+| `displayReassurance` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayReassurance">}}) |
+| `displayShoppingCartFooter` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayShoppingCartFooter">}}) |
+| `displayCrossSellingShoppingCart` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCrossSellingShoppingCart">}}) |
diff --git a/themes/hummingbird/hooks/categorypage.md b/themes/hummingbird/hooks/categorypage.md
index 53a8dfde35..a3e3255ed0 100644
--- a/themes/hummingbird/hooks/categorypage.md
+++ b/themes/hummingbird/hooks/categorypage.md
@@ -1,13 +1,16 @@
 ---
 title: Category page
-weight: 3
+weight: 2
 ---
+
 # Category page
 
+Hooks available on the Hummingbird category (product listing) page.
+
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15444%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayLeftColumn` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayLeftColumn">}}) |
-| `displayHeaderCategory` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayHeaderCategory">}}) |
-| `displayFooterCategory` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterCategory">}}) |
\ No newline at end of file
+| `displayLeftColumn` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayLeftColumn">}}) |
+| `displayHeaderCategory` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayHeaderCategory">}}) |
+| `displayFooterCategory` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterCategory">}}) |
diff --git a/themes/hummingbird/hooks/checkoutflow.md b/themes/hummingbird/hooks/checkoutflow.md
index 35537d846c..65c6eea0ae 100644
--- a/themes/hummingbird/hooks/checkoutflow.md
+++ b/themes/hummingbird/hooks/checkoutflow.md
@@ -1,23 +1,25 @@
 ---
 title: Checkout flow
-weight: 3
+weight: 5
 ---
 
 # Checkout flow
 
+Hooks available across the Hummingbird checkout steps: personal information, shipping, payment, and order confirmation.
+
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15452%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayPersonalInformationTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPersonalInformationTop">}}) |
-| `displayCustomerAccountForm` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccountForm">}}) |
-| `displayCheckoutSummaryTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCheckoutSummaryTop">}}) |
-| `displayReassurance` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayReassurance">}}) |
-| `displayBeforeCarrier` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayBeforeCarrier">}}) |
-| `displayAfterCarrier` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterCarrier">}}) |
-| `displayPaymentTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPaymentTop">}}) |
-| `displayPaymentByBinaries` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPaymentByBinaries">}}) |
-| `displayPaymentReturn` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPaymentReturn">}}) |
-| `displayOrderConfirmation` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayOrderConfirmation">}}) |
-| `displayRightColumn` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayRightColumn">}}) |
-| `displayOrderConfirmation2` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayOrderConfirmation2">}}) |
\ No newline at end of file
+| `displayPersonalInformationTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPersonalInformationTop">}}) |
+| `displayCustomerAccountForm` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccountForm">}}) |
+| `displayCheckoutSummaryTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCheckoutSummaryTop">}}) |
+| `displayReassurance` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayReassurance">}}) |
+| `displayBeforeCarrier` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayBeforeCarrier">}}) |
+| `displayAfterCarrier` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterCarrier">}}) |
+| `displayPaymentTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPaymentTop">}}) |
+| `displayPaymentByBinaries` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPaymentByBinaries">}}) |
+| `displayPaymentReturn` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayPaymentReturn">}}) |
+| `displayOrderConfirmation` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayOrderConfirmation">}}) |
+| `displayRightColumn` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayRightColumn">}}) |
+| `displayOrderConfirmation2` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayOrderConfirmation2">}}) |
diff --git a/themes/hummingbird/hooks/connexionpage.md b/themes/hummingbird/hooks/connexionpage.md
index b35c56be17..ed57ada8b2 100644
--- a/themes/hummingbird/hooks/connexionpage.md
+++ b/themes/hummingbird/hooks/connexionpage.md
@@ -1,14 +1,16 @@
 ---
-title: Connexion page
-weight: 3
+title: Login & account creation
+weight: 6
 ---
 
-# Connexion page
+# Login & account creation
+
+Hooks available on the Hummingbird login and account creation pages.
 
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15461%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayCustomerLoginFormAfter` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerLoginFormAfter">}}) |
-| `displayCustomerAccountFormTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccountFormTop">}}) |
-| `displayCustomerAccountForm` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccountForm">}}) |
\ No newline at end of file
+| `displayCustomerLoginFormAfter` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerLoginFormAfter">}}) |
+| `displayCustomerAccountFormTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccountFormTop">}}) |
+| `displayCustomerAccountForm` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccountForm">}}) |
diff --git a/themes/hummingbird/hooks/contactpage.md b/themes/hummingbird/hooks/contactpage.md
index 812754ce17..3099ef9216 100644
--- a/themes/hummingbird/hooks/contactpage.md
+++ b/themes/hummingbird/hooks/contactpage.md
@@ -1,15 +1,17 @@
 ---
 title: Contact page
-weight: 3
+weight: 8
 ---
 
 # Contact page
 
+Hooks available on the Hummingbird contact page.
+
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15459%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayContactLeftColumn` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContactLeftColumn">}}) |
-| `displayContactRightColumn` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContactRightColumn">}}) |
-| `displayContactContent` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContactContent">}}) |
-| `displayGDPRContent` |  |
\ No newline at end of file
+| `displayContactLeftColumn` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContactLeftColumn">}}) |
+| `displayContactRightColumn` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContactRightColumn">}}) |
+| `displayContactContent` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContactContent">}}) |
+| `displayGDPRContent` | *Undocumented* |
diff --git a/themes/hummingbird/hooks/homepage.md b/themes/hummingbird/hooks/homepage.md
index 4ccb3bae4b..beffe21182 100644
--- a/themes/hummingbird/hooks/homepage.md
+++ b/themes/hummingbird/hooks/homepage.md
@@ -1,27 +1,29 @@
 ---
 title: Home page
-weight: 3
+weight: 1
 ---
 
 # Home page
 
-<iframe style="border: 1px solid rgba(0, 0, 0, 0);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15442%26mode%3Ddesign%26t%3DIcCnIO2KXW3WErLh-1" allowfullscreen></iframe>
+Hooks available on the Hummingbird home page. The header and footer hooks listed here are shared across all pages.
 
-| Hook |  |
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15442%26mode%3Ddesign%26t%3DIcCnIO2KXW3WErLh-1" allowfullscreen></iframe>
+
+| Hook | Documentation |
 | --- | --- |
-| `displayAfterTitleTag` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterTitleTag">}}) |
-| `displayAfterBodyOpeningTag` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterBodyOpeningTag">}}) |
-| `displayBanner` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayBanner">}}) |
-| `displayNav1` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayNav1">}}) |
-| `displayNav2` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayNav2">}}) |
-| `displayTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayTop">}}) |
-| `displayNavFullWidth` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayNavFullWidth">}}) |
-| `displayWrapperTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayWrapperTop">}}) |
-| `displayContentWrapperTop` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContentWrapperTop">}}) |
-| `displayContentWrapperBottom` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContentWrapperBottom">}}) |
-| `displayWrapperBottom` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayWrapperBottom">}}) |
-| `displayFooterBefore` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterBefore">}}) |
-| `displayFooter` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooter">}}) |
-| `displayMyAccountBlock` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayMyAccountBlock">}}) |
-| `displayFooterAfter` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterAfter">}}) |
-| `displayBeforeBodyClosingTag` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayBeforeBodyClosingTag">}}) |
\ No newline at end of file
+| `displayAfterTitleTag` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterTitleTag">}}) |
+| `displayAfterBodyOpeningTag` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterBodyOpeningTag">}}) |
+| `displayBanner` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayBanner">}}) |
+| `displayNav1` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayNav1">}}) |
+| `displayNav2` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayNav2">}}) |
+| `displayTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayTop">}}) |
+| `displayNavFullWidth` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayNavFullWidth">}}) |
+| `displayWrapperTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayWrapperTop">}}) |
+| `displayContentWrapperTop` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContentWrapperTop">}}) |
+| `displayContentWrapperBottom` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayContentWrapperBottom">}}) |
+| `displayWrapperBottom` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayWrapperBottom">}}) |
+| `displayFooterBefore` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterBefore">}}) |
+| `displayFooter` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooter">}}) |
+| `displayMyAccountBlock` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayMyAccountBlock">}}) |
+| `displayFooterAfter` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterAfter">}}) |
+| `displayBeforeBodyClosingTag` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayBeforeBodyClosingTag">}}) |
diff --git a/themes/hummingbird/hooks/myaccount.md b/themes/hummingbird/hooks/myaccount.md
index 8c9e4513e9..83424239da 100644
--- a/themes/hummingbird/hooks/myaccount.md
+++ b/themes/hummingbird/hooks/myaccount.md
@@ -1,14 +1,16 @@
 ---
 title: My account
-weight: 3
+weight: 7
 ---
 
 # My account
 
+Hooks available on the Hummingbird customer account pages.
+
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15463%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayCustomerAccount` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccount">}}) |
-| `displayOrderDetail` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayOrderDetail">}}) |
-| `displayAdditionalCustomerAddressFields` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdditionalCustomerAddressFields">}}) |
+| `displayCustomerAccount` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayCustomerAccount">}}) |
+| `displayOrderDetail` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayOrderDetail">}}) |
+| `displayAdditionalCustomerAddressFields` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAdditionalCustomerAddressFields">}}) |
diff --git a/themes/hummingbird/hooks/productpage.md b/themes/hummingbird/hooks/productpage.md
index d0aeff5fb6..26d3cd62b8 100644
--- a/themes/hummingbird/hooks/productpage.md
+++ b/themes/hummingbird/hooks/productpage.md
@@ -5,17 +5,18 @@ weight: 3
 
 # Product page
 
+Hooks available on the Hummingbird product page.
+
 <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="100%" height="450" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FHKGzVBx5p2JaFrFocGe6p0%2FHook-Cartography%3Ftype%3Ddesign%26node-id%3D128%253A15447%26mode%3Ddev" allowfullscreen></iframe>
 
-| Hook |  |
+| Hook | Documentation |
 | --- | --- |
-| `displayProductActions` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayProductActions">}}) |
-| `displayProductAdditionalInfo` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayProductAdditionalInfo">}}) |
-| `displayAfterProductThumbs` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterProductThumbs">}}) |
-| `displayReassurance` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayReassurance">}}) |
-| `displayLeftColumnProduct` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayLeftColumnProduct">}}) |
-| `displayRightColumnProduct` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayRightColumnProduct">}}) |
-| `displayFooterProduct` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterProduct">}}) |
-| `displayCardModalContent` |  |
-| `displayCardModalFooter` |  |
-| `displayProductAdditionalInfo` | [Documentation]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayProductAdditionalInfo">}}) |
\ No newline at end of file
+| `displayProductActions` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayProductActions">}}) |
+| `displayProductAdditionalInfo` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayProductAdditionalInfo">}}) |
+| `displayAfterProductThumbs` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayAfterProductThumbs">}}) |
+| `displayReassurance` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayReassurance">}}) |
+| `displayLeftColumnProduct` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayLeftColumnProduct">}}) |
+| `displayRightColumnProduct` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayRightColumnProduct">}}) |
+| `displayFooterProduct` | [Reference]({{< relref "/9/modules/concepts/hooks/list-of-hooks/displayFooterProduct">}}) |
+| `displayCardModalContent` | *Undocumented* |
+| `displayCardModalFooter` | *Undocumented* |
diff --git a/themes/hummingbird/javascript.md b/themes/hummingbird/javascript.md
new file mode 100644
index 0000000000..ee517e9612
--- /dev/null
+++ b/themes/hummingbird/javascript.md
@@ -0,0 +1,111 @@
+---
+title: JavaScript conventions
+weight: 2
+---
+
+# JavaScript conventions
+
+Hummingbird's JavaScript is written in TypeScript, compiled with Webpack, and follows modern patterns: no jQuery in theme code, semantic `data-ps-*` attributes for DOM targeting, and a centralized event system.
+
+## No jQuery
+
+jQuery is loaded by `core.js` for backward compatibility with existing modules. **Theme code must not use jQuery.** Write vanilla JavaScript (or TypeScript) using modern ECMAScript syntax.
+
+## Semantic `data-ps-*` attributes
+
+Hummingbird decouples styling from behavior by introducing semantic `data-ps-*` attributes instead of CSS classes as JavaScript hooks:
+
+```html
+<!-- Styling class as JS hook — fragile, breaks on CSS refactors -->
+<button class="js-add-to-cart btn">Add to cart</button>
+
+<!-- Semantic behavior attribute — decoupled from styling -->
+<button class="btn" data-ps-action="add-to-cart">Add to cart</button>
+```
+
+### Available attributes
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `data-ps-ref` | References a DOM element for JS queries | `data-ps-ref="voucher-form"` |
+| `data-ps-action` | Marks an element that triggers a user action (click, toggle, submit) | `data-ps-action="toggle-password"` |
+| `data-ps-target` | Target area for content updates (inject/refresh HTML) | `data-ps-target="cart-summary"` |
+| `data-ps-component` | Identifies a JS component | `data-ps-component="product-gallery"` |
+| `data-ps-state` | Tracks element state | `data-ps-state="expanded"` |
+| `data-ps-context` | Defines component context | `data-ps-context="checkout"` |
+| `data-ps-observe` | Marks an element for MutationObserver | `data-ps-observe="cart-content"` |
+| `data-ps-data` | Carries data payloads | `data-ps-data='{"id": 42}'` |
+
+By separating styling from behavior, CSS refactors don't break JavaScript, behavioral intent is readable directly in the markup, and modules know exactly which attributes to target.
+
+{{% notice info %}}
+This convention is starting to be introduced in different places across Hummingbird. The codebase currently uses both `data-ps-*` attributes and legacy `.js-` prefixed class selectors. New code should use `data-ps-*`; legacy selectors will be migrated over time. The convention itself is still open for discussion — feedback and real-world testing are welcome on the [JavaScript conventions discussion](https://github.com/PrestaShop/hummingbird/discussions/934) and in the [detailed specification (PDF)](https://github.com/user-attachments/files/25360286/JavaScript_Framework_for_Themes.pdf).
+{{% /notice %}}
+
+## Event system
+
+Cross-component communication uses the `prestashop` global object as an event emitter:
+
+### Emit an event
+
+Use `prestashop.emit()` to trigger an event with optional data:
+
+```js
+prestashop.emit('myEvent', { myData: 'value' });
+```
+
+### Listen to an event
+
+Use `prestashop.on()` to react to an event. Data is passed directly as the first argument:
+
+```js
+prestashop.on('myEvent', (data) => {
+  console.log(data.myData);
+});
+```
+
+### Events map
+
+Hummingbird defines its events as constants accessible via the `Theme` global. Use these constants instead of string literals to avoid typos and benefit from autocompletion:
+
+```js
+const { prestashop, Theme: { events } } = window;
+
+prestashop.on(events.updatedProduct, () => {
+  // React to product update
+});
+```
+
+Key constants available in `Theme.events` (subset — see the [JavaScript events reference]({{< relref "/9/themes/reference/javascript-events" >}}) for the full list):
+
+| Constant | Event string | Description |
+|----------|-------------|-------------|
+| `events.updateCart` | `updateCart` | Cart updated via AJAX |
+| `events.updatedCart` | `updatedCart` | Cart DOM fully refreshed |
+| `events.updateProduct` | `updateProduct` | Combination changed, before AJAX call |
+| `events.updatedProduct` | `updatedProduct` | Product DOM updated after AJAX |
+| `events.updateProductList` | `updateProductList` | Product listing DOM reloaded |
+| `events.updateFacets` | `updateFacets` | Facet filters reloaded |
+| `events.clickQuickview` | `clickQuickview` | Quickview link clicked |
+| `events.quickviewOpened` | `quickviewOpened` | Quickview modal opened and ready |
+| `events.updatedDeliveryForm` | `updatedDeliveryForm` | Delivery form updated in checkout |
+| `events.handleError` | `handleError` | AJAX request failed |
+
+{{% notice info %}}
+Note: core `listing.js` emits `clickQuickView` (uppercase `V`), while Hummingbird's constants use `clickQuickview` (lowercase `v`). Always use `Theme.events` constants in Hummingbird code to avoid this discrepancy. For the complete list of events dispatched by `core.js`, see the [JavaScript events reference]({{< relref "/9/themes/reference/javascript-events" >}}).
+{{% /notice %}}
+
+### Selectors map
+
+Hummingbird also exports its selectors map via the `Theme` global:
+
+```js
+const { Theme: { selectors } } = window;
+
+document.querySelectorAll(selectors.listing.product).forEach((el) => {
+  // ...
+});
+```
+
+This centralizes all DOM selectors in one place, making them easier to override and maintain.
+
diff --git a/themes/img/choose-layouts.png b/themes/img/choose-layouts.png
new file mode 100644
index 0000000000..cb0558f378
Binary files /dev/null and b/themes/img/choose-layouts.png differ
diff --git a/themes/img/export-current-theme.png b/themes/img/export-current-theme.png
new file mode 100644
index 0000000000..22df2ca6c8
Binary files /dev/null and b/themes/img/export-current-theme.png differ
diff --git a/themes/img/inheritance-schema.png b/themes/img/inheritance-schema.png
new file mode 100644
index 0000000000..0ac0cd9e44
Binary files /dev/null and b/themes/img/inheritance-schema.png differ
diff --git a/themes/img/rtl-generate.png b/themes/img/rtl-generate.png
new file mode 100644
index 0000000000..e14aa524f0
Binary files /dev/null and b/themes/img/rtl-generate.png differ
diff --git a/themes/reference/_index.md b/themes/reference/_index.md
index 46c0e4c9b3..af1eaf9a5d 100644
--- a/themes/reference/_index.md
+++ b/themes/reference/_index.md
@@ -1,10 +1,18 @@
 ---
-title: Theme development reference
-menuTitle: Reference
-weight: 30
+title: Reference
+weight: 35
+chapter: true
 showOnHomepage: true
 ---
 
-# Theme development reference
+# Reference
 
-{{% children /%}}
+Quick lookup tables for PrestaShop theme development.
+
+| Page | Description |
+|------|-------------|
+| [Template variables]({{< relref "/9/themes/reference/template-variables" >}}) | Global Smarty variables available on every normal front-office page — cart, currency, customer, language, country, page, shop, URLs, configuration, and utilities |
+| [JavaScript events]({{< relref "/9/themes/reference/javascript-events" >}}) | All events dispatched by `core.js` via the `prestashop` event bus |
+| [Smarty helpers]({{< relref "/9/themes/reference/smarty-helpers" >}}) | Custom Smarty functions (`{l}`, `{url}`, `{hook}`, `{widget}`) and modifiers (`classname`, `classnames`) |
+
+For conceptual documentation, see [Concepts]({{< relref "/9/themes/concepts" >}}). For Hummingbird-specific details, see [Hummingbird]({{< relref "/9/themes/hummingbird" >}}).
diff --git a/themes/reference/bootstrap-compatibility.md b/themes/reference/bootstrap-compatibility.md
deleted file mode 100644
index 28ca4058c9..0000000000
--- a/themes/reference/bootstrap-compatibility.md
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: Bootstrap compatibility
----
-
-# Bootstrap compatibility
-
-Starting from PrestaShop 9.0 you can choose between two themes `classic` or `hummingbird`, the Hummingbird theme is based on more modern design and dependencies and gives better performance and SEO.
-
-However, Hummingbird uses [Bootstrap 5.2](https://getbootstrap.com/docs/5.2/getting-started/introduction/) as a base when Classic was based on [Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/). Since many modules developed these years are based on Bootstrap 4, switching to Hummingbird may cause some unexpected side effects.
-
-{{% notice note %}}
-If you want more details about the changes in Bootstrap 5 we invite you to read their [migration guide](https://getbootstrap.com/docs/5.2/migration/).
-{{% /notice %}}
-
-The ideal thing to do is for module developers to adapt their module to be compatible with Bootstrap 5, as ultimately the Classic theme will be deprecated and won't evolve anymore, the only remaining theme provided by PrestaShop will be based on Bootstrap 5.
-
-In the meantime, if you need a quick solution we provide a [compatibility layer library](https://github.com/PrestaShop/bootstrap-compatibility-layer) that you can include in your module or theme so that your code remains compatible even with Bootstrap 5 as a base.
-
-## Installation
-
-You can install the Bootstrap compatibility layer from your preferred package.
-
-### Package
-
-```yml
-npm install bootstrap-compatibility-layer
-# OR
-yarn add bootstrap-compatibility-layer
-# OR
-pnpm add bootstrap-compatibility-layer
-```
-
-### CDN
-
-Or use it directly through our CDN:
-
-```html
-[...]
-<link href="https://unpkg.com/bootstrap-compatibility-layer@1/dist/bootstrap-compatibility-layer.min.css" rel="stylesheet">
-[...]
-<script src="https://unpkg.com/bootstrap-compatibility-layer@1"></script>
-[...]
-```
-
-### Use a hook
-
-To integrate the compatibility layer from your module you can use the `actionFrontControllerSetMedia` hook for example, it is **very important** that you include the assets relying on the `addCss` and `addJs` methods, this way if other modules also include the same asset it prevents it from being loaded multiple times.
-
-```php
-class my_module extends Module {
-    ...
-
-    public function hookActionFrontControllerSetMedia()
-    {
-        $this->context->controller->addCss('https://unpkg.com/bootstrap-compatibility-layer@1/dist/bootstrap-compatibility-layer.min.css');
-        $this->context->controller->addJs('https://unpkg.com/bootstrap-compatibility-layer@1');
-    }
-}
-```
-
-## Usage
-
-### Package
-
-To use the library as a package you can load it in your script:
-
-```ts
-import BSCompatibilityLayer from 'bootstrap-compatibility-layer';
-```
-
-The compatibility layer initializes automatically; however, you can call the methods independently if you need to.
-
-```ts
-BSCompatibilityLayer.updateAllDataAttributes();
-```
-
-### CDN
-
-If you only want to use attribute modifiers, you can place the tag wherever you want in your code. However, if you want to use jQuery commands relating to Bootstrap, it is advisable to put it first in the list of your scripts and to wait for the DOM to be loaded before using them like the following code:
-
-```html
-[...]
-<link href="https://unpkg.com/bootstrap-compatibility-layer@1/dist/bootstrap-compatibility-layer.min.css" rel="stylesheet">
-[...]
-<script src="https://unpkg.com/bootstrap-compatibility-layer@1"></script>
-<script>
-  document.addEventListener('DOMContentLoaded', function() {
-    $('[data-toggle="popover"]').popover()
-
-    $('[data-toggle="tooltip"]').tooltip()
-  });
-</script>
-```
diff --git a/themes/reference/hooks/_index.md b/themes/reference/hooks/_index.md
deleted file mode 100644
index a7ff78f0dd..0000000000
--- a/themes/reference/hooks/_index.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Theme Hooks
-weight: 3
----
-
-# Create hooks available in Front Office
-
-This section of the documentation is only about front office hooks: [display and action]({{< relref "/9/development/components/hook/_index.md" >}}).
-
-## Creating a dynamic hook
-
-When your module or theme calls a hook, PrestaShop executes it.
-
-This is how it is called from a PHP file:
-
-```php
-<?php
-Hook::exec('MyCustomHook');
-```
-
-This is how it is called from a Smarty template:
-
-```html
-{hook h='MyCustomHook'}
-```
-
-## Register the hook to make it visible and reusable
-
-If you add a hook call, it is better to register it.
-
-This will enable Back Office user to:
-- see it in the hooks list
-- be able to plug some modules on it (in Position page)
-- allow other modules to listen to this hook being called and add some extra behavior
-
-You can register your hook from your theme's [theme.yml file]({{< relref "/9/themes/getting-started/theme-yml" >}}):
-
-```yaml
-global_settings:
-  hooks:
-    custom_hooks:
-      - name: displayFooterBefore
-        title: displayFooterBefore
-        description: Add a widget area above the footer
-```
-
-You can also register your hook from a module:
-
-```php
-<?php
-// Create the function for the MyCustomHook hook public function
-MyCustomHook($params) { // method body }
-
-// Register the MyCustomHook hook
-Hook::register('MyCustomHook');
-
-// Call it from PHP
-Hook::exec('MyCustomHook');
-```
diff --git a/themes/reference/javascript-events.md b/themes/reference/javascript-events.md
new file mode 100644
index 0000000000..1d25f28251
--- /dev/null
+++ b/themes/reference/javascript-events.md
@@ -0,0 +1,42 @@
+---
+title: JavaScript events
+weight: 2
+---
+
+# JavaScript events
+
+PrestaShop's front-office JavaScript uses a global event bus on the `prestashop` object. The event API (`on`, `emit`) is added by the theme's compiled `theme.js` — Classic and Hummingbird both include this during boot.
+
+{{% notice warning %}}
+`prestashop.on()` and `prestashop.emit()` are not available until the theme's `theme.js` has executed. Modules that register listeners before the theme boots will throw a runtime error.
+{{% /notice %}}
+
+## Core event reference
+
+| Event | When it fires | Key payload properties |
+|-------|--------------|----------------------|
+| `updateCart` | After a cart action (add, remove, quantity change, voucher) triggers an AJAX update | `reason` (action context), `resp` (full AJAX response including updated cart data) |
+| `updatedCart` | After the cart HTML has been refreshed in the DOM following `updateCart` | `eventType`, `resp` |
+| `updateProduct` | On the product page when a variant is selected, the page is navigated via browser history, or `.product-refresh` is clicked — **before** the AJAX call | `eventType`, `event` (original DOM event), `resp` (empty object, kept for compatibility), `reason.productUrl` |
+| `updatedProduct` | After the product combination AJAX call completes and the DOM has been updated | Two arguments: `data` (full AJAX response with HTML fragments) and `formData` (serialized form array) |
+| `updateProductList` | After a product listing page is updated via AJAX (filter, sort, paginate) | Full AJAX response — includes `current_url` and updated listing HTML |
+| `updateFacets` | Emitted by theme listing code (not core) when the user interacts with a facet filter, pagination, or search link — core's `facets.js` listens to this and triggers the AJAX request, then emits `updateProductList` | URL string for the new filter state |
+| `clickQuickView` | When a quick-view link is clicked on a product listing card | `dataset` — jQuery `.data()` of the product miniature (includes `id_product`, `id_product_attribute`) |
+| `updatedAddressForm` | After the address form is refreshed via AJAX following a country change | `target` (form jQuery object), `resp` (response with updated `address_form` HTML) |
+| `editAddress` | When the user clicks "edit addresses" on the checkout addresses step | — |
+| `editDelivery` | When the user clicks "edit delivery" on the checkout delivery step | — |
+| `updatedDeliveryForm` | After a delivery option is selected and the cart summary has been updated via AJAX | `dataForm` (serialized form array), `deliveryOption` (jQuery object of selected option), `resp` |
+| `changedCheckoutStep` | When the user navigates between checkout steps | `event` (original DOM click event) |
+| `orderConfirmationErrors` | When the pre-payment cart validation returns errors | `resp` (response with `errors` and `cartUrl`), `paymentObject` |
+| `termsUpdated` | When a terms and conditions checkbox changes or a payment option is selected | `isChecked` (boolean — whether all required terms are checked) |
+| `handleError` | After any core AJAX request fails | `eventType` (e.g. `updateCart`, `updateAddressForm`), `resp` (failed jqXHR object) |
+| `showErrorNextToAddtoCartButton` | Emitted by modules (not core) to display an error near the add-to-cart button — core only listens for it | `errorMessage` (string) |
+
+## Selector initialization events
+
+| Event | Object | Purpose |
+|-------|--------|---------|
+| `selectorsInit` | `prestashop.selectors` | Core JS selector map is ready |
+| `themeSelectorsInit` | `prestashop.themeSelectors` | Theme JS selector map is ready |
+
+See [Overrides]({{< relref "/9/themes/concepts/overrides#selector-overrides" >}}) for how to customize selector maps.
diff --git a/themes/reference/javascript-events/_index.md b/themes/reference/javascript-events/_index.md
deleted file mode 100644
index 8653c4c740..0000000000
--- a/themes/reference/javascript-events/_index.md
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: Javascript events
-weight: 4
----
-
-# JavaScript events
-
-## Javascript architecture
-
-{{% notice info %}}
-It's recommended to read more about [PrestaShop asset management]({{< relref "/9/themes/getting-started/asset-management/" >}}) before continuing.
-{{% /notice %}}
-
-A default store loads two important files on every page:
-
-  File      | Content
-  ----------| ------------------------------------------------------------------------------
-  `core.js` | Loads jQuery3, makes ajax calls, defines core methods that all frontend should use
-  `theme.js`| Bundles all theme specific code and libraries
-
-{{% notice tip %}}
-  jQuery is loaded by the core, so each theme will have jQuery v3 available. Do not redefine it.
-{{% /notice %}}
-
-## Events
-
-### Dispatch an event
-
-The best way to trigger an event is to use the `prestashop` object. Here is a simple example:
-
-```js
-prestashop.emit(
-  'myEventName',
-  {
-    myData1: 1,
-    myData2: 3
-  }
-);
-```
-
-### Listening to events
-
-You can also react to an event emitted by `prestashop.emit`. Here is a simple example:
-
-```js
-if (typeof prestashop !== 'undefined') {
-  prestashop.on(
-    'myEventName',
-    function (event) {
-      var eventDatas = {};
-      if (event && event.reason) {
-        eventDatas = {
-          my_data_1: event.reason.myData1,
-          my_data_2: event.reason.myData2
-        };
-      }
-    }
-  );
-}
-```
-
-### Dispatched events
-
-PrestaShop will dispatch many events from `core.js` so your code can rely on it:
-
-Event Name            | Description
-----------------------|------------------------------------------------------------------------------------------
- `updateCart`         | On the cart page, everytime something happens (change quantity, remove product and so on) the cart is reloaded by ajax call. After the cart is updated, this event is triggered.
- `updatedAddressForm`  | In the address form, some input will trigger ajax calls to modify the form (like country change), after the form is updated, this event is triggered.
- `updateDeliveryForm` | During checkout, if the delivery address is modified, this event will be trigged.
- `changedCheckoutStep` | Each checkout step **submission** will fire this event.
- `updateProductList`  | On every product list page (category, search results, pricedrop and so on), the list is updated via ajax calls if you change filters or sorting options. Each time the DOM is reloaded with new product list, this event is triggered.
- `clickQuickView`     | If your theme handles it, this event will be trigged when you click on the quickview link.
- `updateProduct`      | On the product page, selecting a new combination will reload the DOM via ajax calls. This event will fire after modifying the combination, but before the ajax call.
- `updatedProduct`      | On the product page, selecting a new combination will reload the DOM via ajax calls. After the update, this event is fired.
- `handleError`        | This event is fired after a fail of POST request. Have the `eventType` as first parameter.
- `updateFacets`        | On every product list page (category, search results, pricedrop and so on), the list is updated via ajax calls if you change filters or sorting options. Each time the facets is reloaded, this event is triggered.
- `responsive update`  | While browser is resized, this event is fired with a `mobile` parameter.
-
-### Triggering delegated events
-
-We use event delegation to make sure that the events are still attached
-after the DOM was modified (like after an ajax call).
-
-Here is a simple way to trigger a delegated event.
-
-```js
-const body = $('body'); // Our events are usually attached to the body
-
-const event = jQuery.Event('click');
-event.target = body.find('.js-theClassYouNeed');
-
-body.trigger(event);
-```
diff --git a/themes/reference/migration-from-16.md b/themes/reference/migration-from-16.md
deleted file mode 100644
index 77b32e239e..0000000000
--- a/themes/reference/migration-from-16.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: Migrating from PrestaShop 1.6
-menuTitle: Migrating from 1.6
----
-
-# Migrating from PrestaShop 1.6
-
-PrestaShop 1.7 introduces a totally reworked theme system from version 1.6, with the goal of making PrestaShop upgrades easier, and making it easier and faster to create a brand new theme.
-
-The huge change to the theme system means that there is no easy way to migrate your PrestaShop 1.6 theme to PrestaShop 1.7.
-
-When using the automatic upgrade from PrestaShop 1.6 to 1.7, your theme will be switched to the new default theme, called "Classic". We therefore recommend working on your 1.7 theme before you make the switch to PrestaShop 1.7.
-
-Some features have been dropped with PrestaShop 1.7. They were either already deprecated in 1.6, or proved too problematic to maintain.
diff --git a/themes/reference/overriding-modules.md b/themes/reference/overriding-modules.md
deleted file mode 100644
index 58dd796373..0000000000
--- a/themes/reference/overriding-modules.md
+++ /dev/null
@@ -1,138 +0,0 @@
----
-title: Overriding modules
----
-
-# Overriding modules
-
-When you write a theme, you often need to override the templates and assets coming from a module so that they match your theme's specific markup needs.
-Themes can override modules' assets (CSS and JavaScript only) by placing the corresponding file at a specific location.
-
-All module overriding code goes to the `modules` directory (in your module's own directory).
-
-{{% notice note %}}
-  If your asset override is empty, PrestaShop will load nothing (neither the module one nor your override). This is useful
-  if you want to fully remove this module style and add your own to your compiled `theme.css`.
-{{% /notice %}}
-
-Examples in this page are based on this sample module directory structure:
-
-```
-.
-├── css
-│   ├── external-lib.css
-│   └── style.css
-├── js
-│   └── app.js
-├── moduledemo.php
-└── views
-    └── templates
-        └── front
-            ├── included-template.tpl
-            └── moduledemo.tpl
-
-5 directories, 6 files
-```
-
-## Overriding templates and assets
-
-Here are the folder paths to create in order to override templates and assets:
-
-```
-.
-└── modules
-    ├── css
-    │   ├── external-lib.css
-    │   └── style.css
-    ├── js
-    │   └── app.js
-    └── views
-        └── templates
-            └── front
-                ├── included-template.tpl
-                └── moduledemo.tpl
-
-6 directories, 5 files
-```
-
-Compared to what was needed in PrestaShop 1.6, it is much simpler:
-
-```
-.
-├── css
-│   └── modules
-│       └── css
-│           ├── external-lib.css
-│           └── style.css
-├── js
-│   └── modules
-│       └── js
-│           └── app.js
-└── modules
-    └── views
-        └── templates
-            └── front
-                ├── included-template.tpl
-                └── moduledemo.tpl
-
-10 directories, 5 files
-```
-
-## Overriding with the 'include' method
-
-There is one very important issue that you should be aware of.
-When loading a template file (for instance 'moduledemo.tpl'), PrestaShop will look for overriding first, in the following order:
-
-1. /themes/THEME_NAME/modules/MODULE_NAME/views/templates/front/moduledemo.tpl
-2. /modules/MODULE_NAME/views/templates/front/moduledemo.tpl
-
-But if your `moduledemo.tpl` file includes the `included-template.tpl` file, you will have to override 'included-template.tpl' as well, even if you don't want to modify it (nor to edit the path). This means that every file that an overridden file includes needs to be copy-pasted as-is in order for your override to work properly.
-
-The issue goes both ways: if you want to modify the `included-template.tpl` file, you will have to override the `moduledemo.tpl` file that includes it.
-
-```smarty
-{include file='./included-template.tpl'}
-```
-
-PrestaShop 1.7 introduced a way to include files in module templates. By using this method, all the expected rules will be followed:
-
-```smarty
-{include file='module:MODULE_NAME/views/templates/front/included-template.tpl'}
-```
-
-## SmartyDev helps you debug!
-
-PrestaShop 1.7 also introduced our own SmartyDev tool, a Smarty extension which allows you to see the template's name within your generated HTML markup. This will help debugging a lot, especially because of template override.
-
-Here an example of generated markup with SmartyDev activated:
-
-```html
-[...]
-      <a href="http://prestashop.ps/en/" class="dropdown-item">English</a>
-    </li>
-  </ul>
-</div>
-<!-- end /var/www/html/PrestaShop/themes/classic/modules/ps_languageselector/ps_languageselector.tpl -->
-
-<!-- begin /var/www/html/PrestaShop/themes/classic/modules/ps_customersignin/ps_customersignin.tpl -->
-<div class="user-info">
-  <a class="logout hidden-sm-down" href="http://prestashop.ps/en/?mylogout=" rel="nofollow">
-    <i class="material-icons">&#xE7FF;</i>
-    Sign out
-  </a>
-  <a class="account" href="http://prestashop.ps/en/my-account" title="View my customer account" rel="nofollow" >
-    <i class="material-icons hidden-md-up logged">&#xE7FF;</i>
-    <span class="hidden-sm-down">Julien Bourdeau</span>
-  </a>
-</div>
-
-<!-- end /var/www/html/PrestaShop/themes/classic/modules/ps_customersignin/ps_customersignin.tpl -->
-
-<!-- begin /var/www/html/PrestaShop/themes/classic/modules/ps_shoppingcart/ps_shoppingcart.tpl -->
-<div class="blockcart cart-preview " data-refresh-url="http://prestashop.ps/en/module/ps_shoppingcart/ajax">
-  <div class="header">
-    <i class="material-icons shopping-cart">shopping_cart</i>
-
-[...]
-```
-
-To use it, simply set the `_PS_MODE_DEV_` constant to `true` in your installation's `/config/defines.inc.php` file: add the `define('_PS_MODE_DEV_', true);` line to that file in order to turn the PrestaShop Developer Mode on, which features SmartyDev.
diff --git a/themes/reference/overriding-selectors.md b/themes/reference/overriding-selectors.md
deleted file mode 100644
index 32907aaee7..0000000000
--- a/themes/reference/overriding-selectors.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Overriding selectors
----
-
-# Overriding selectors
-
-When you write a theme, you often need to change the markup, but if you do this, you'll encounter some problems because core's and classic's javascript use some class in order to work.
-
-Two selectors maps are available, one on the core side `(/themes/_core/js/selectors.js)` and another one inside the classic theme `(/themes/classic/_dev/js/selectors.js)`.
-
-That means that almost every selectors we use inside every JS files are inside these two files.
-
-You can easily update these mapping because these 2 files send an event on dom ready : `selectorsInit` for the core mapping file, and `themeSelectorsInit` for the classic theme.
-Also, if you place your file without these events, you need place it after the core/theme js bundle, it will work as it would with the event.
-
-These selectors are mapped inside the `prestashop` object. That means that if you attach a method which override the `prestashop.selectors` or `prestashop.themeSelectors` object, you'll be able to change a lot of markup if you manage to override every selectors properly.
diff --git a/themes/reference/rtl.md b/themes/reference/rtl.md
deleted file mode 100644
index d61c8b3360..0000000000
--- a/themes/reference/rtl.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-title: RTL support
----
-
-# RTL support
-
-PrestaShop supports RTL (Right-to-left) themes natively.
-
-## RTL stylesheets
-
-There are two ways of customizing your theme for RTL: either by adding an override file that is only loaded for RTL languages, or by using completely different version of the theme's stylesheets.
-
-### CSS override file
-
-PrestaShop will try to load a css file named `rtl.css` after your theme's ones when displayed in an RTL language. You can use this file to place any style override you need for RTL.
-
-### RTL version
-
-When the shop is displayed in an RTL language, PrestaShop will automatically try and load RTL versions of the theme's stylesheets if they are available, instead of the "normal" ones.
-
-RTL versions are automatically "discovered" by PrestaShop using a simple convention: to obtain the RTL version name, you just need to add `_rtl` to the end of the standard file name.
-
-Example:
-
-| Original name | RTL version name
-|---------------|----------
-|`theme.css`    | `theme_rtl.css`
-|`theme-custom.css` | `theme-custom_rtl.css`
-
-#### Stylesheet generation
-
-PrestaShop can also automagically generate an RTL version of your theme's stylesheets based on the original CSS files.
-
-Follow this steps to generate RTL stylesheets for your theme:
-
-* Open your shop's Back Office.
-* Go to the "Design > Theme & Logo" page.
-* Scroll down to the "Adaptation to right-to-left languages" section.<br>
- **Note:** this is only visible if you have an RTL language installed on your shop.
-* Choose the theme you want to generate stylesheets for.
-* Toggle "Generate RTL stylesheet" to "Yes".
-* Press "Save".
-
-{{< figure src="../img/RTL-generation-screen.png" title="RTL generation in the back office" >}}
-
-This process will generate `_rtl.css` files for every `.css` file in the theme.
-
-{{% notice info %}}
-**PrestaShop won't generate a file if one with the same name already exists.**<br>
-If you want to regenerate a file, you have to delete it first.
-{{% /notice %}}
-
-##### Polishing it up
-
-Sometimes the automatic transformation won't be enough to get your theme exactly how you want it.
-
-**You should never modify generated `_rtl.css` files** – they are generated automatically by PrestaShop.
-
-If you need to add some specific css to fix your RTL transformed files, use `.rtlfix` files. The content of those files is appended to the RTL version of that file after it's transformed.
-
-This is what PrestaShop does for each `.css` file in the theme:
-
-1. Take a file (let's say it's called `my-file.css`)
-2. If `my-file_rtl.css` exists, move on to the next file.
-3. Transform `my-file.css` to RTL and save its contents to `my-file_rtl.css`
-4. If a file named `my-file.rtlfix` exists, append its contents to `my-file_rtl.css`.
diff --git a/themes/reference/smarty-helpers.md b/themes/reference/smarty-helpers.md
index 5438ddec1d..6ebf653476 100644
--- a/themes/reference/smarty-helpers.md
+++ b/themes/reference/smarty-helpers.md
@@ -1,8 +1,47 @@
 ---
-title: Smarty helper functions
-menuTitle: Smarty helpers
+title: Smarty helpers
+weight: 3
 ---
 
-# Helpers: functions and modifiers
+# Smarty helpers
+
+PrestaShop provides custom Smarty functions and modifiers for use in front-office templates. For full parameter documentation, see [Smarty extensions]({{< relref "/9/development/components/smarty-extensions" >}}).
+
+## Functions
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `{l}` | Translate a string — see [Translation]({{< relref "/9/themes/concepts/translation" >}}) for domain naming rules and placeholders | `{l s='Add to cart' d='Shop.Theme.Actions'}` |
+| `{url}` | Generate a URL for any entity | `{url entity='product' id=$product.id}` |
+| `{hook}` | Invoke a hook and display its output | `{hook h='displayFooterBefore'}` |
+| `{render}` | Render a template file with variables | `{render file='customer/_partials/login-form.tpl' ui=$login_form}` |
+| `{form_field}` | Render a form field with consistent markup | `{form_field field=$field}` |
+| `{widget}` | Display a module's content directly | `{widget name='ps_contactinfo'}` |
+| `{widget_block}` | Display a module with an inline template override | `{widget_block name='ps_linklist'}...{/widget_block}` |
+
+## Modifiers
+
+| Modifier | Purpose | Example |
+|----------|---------|---------|
+| `classname` | Sanitize a string into a valid CSS class name | `{$value\|classname}` |
+| `classnames` | Convert a key/boolean array into a space-separated class string | `{$page.body_classes\|classnames}` |
+
+## `{url}` entities
+
+The `{url}` function generates URLs for any front-office entity. Pass the entity type and its required parameters. All entities also accept `id_lang`, `id_shop`, `ssl`, and `params` (extra query string) as optional parameters.
+
+| Entity | Required parameters | Example |
+|--------|--------------------|---------|
+| `product` | `id` | `{url entity='product' id=$product.id}` |
+| `category` | `id` | `{url entity='category' id=$category.id}` |
+| `categoryImage` | `id`, `name` | `{url entity='categoryImage' id=$category.id name=$category.name}` |
+| `manufacturer` | `id` | `{url entity='manufacturer' id=$manufacturer.id}` |
+| `manufacturerImage` | `id` | `{url entity='manufacturerImage' id=$manufacturer.id}` |
+| `supplier` | `id` | `{url entity='supplier' id=$supplier.id}` |
+| `supplierImage` | `id` | `{url entity='supplierImage' id=$supplier.id}` |
+| `cms` | `id` | `{url entity='cms' id=$cms.id}` |
+| `module` | `name`, `controller` | `{url entity='module' name='ps_cart' controller='cart'}` |
+| `language` | `id` | `{url entity='language' id=$lang.id}` |
+| `sf` | `route` | `{url entity='sf' route='my_route'}` — generates a URL from a Symfony route name; only available in Symfony context |
+| *(any page name)* | — | `{url entity='contact'}` — falls back to `Link::getPageLink()` |
 
-PrestaShop provides several smarty helper functions and modifiers. See [Smarty extensions]({{< ref "/9/development/components/smarty-extensions/" >}}) for a full reference.
diff --git a/themes/reference/template-inheritance/_index.md b/themes/reference/template-inheritance/_index.md
deleted file mode 100644
index 39707b06a9..0000000000
--- a/themes/reference/template-inheritance/_index.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-title: Template inheritance
----
-
-# Template inheritance
-
-PrestaShop relies a lot on template inheritance in order to create the most consistent theme possible, while heavily reducing the amount of duplicated code.
-
-
-## The principle
-
-Template inheritance allow you to extend a parent template and only redefine the block you need.
-
-The picture below illustrates the example of a specific product page extending a generic one. Say
-you have three files: `product-pack.tpl` extending `product.tpl`, itself extending `page.tpl`.
-
-{{< figure src="img/template-inheritance.png" title="Schema for template inheritance" >}}
-
-The `product-pack.tpl` file will **only** contain the product description part. Everything else
-will be exactly the same as product page. Even better, the product page will only define the main
-content of the page, everything else will be taken from its own parent template (ie page.tpl).
-
-The wrong way of doing this would be to extract header, footer and reusable part of the template
-and _include_ them in each file.
-
-The [official Smarty documentation](https://www.smarty.net/inheritance) has a nice and simple example. In their own words:
-
-> Template inheritance is an approach to managing templates that resembles object-oriented programming techniques.
-  Instead of the traditional use of {include ...} tags to manage parts of templates, you can inherit the
-  contents of one template to another (like extending a class) and change blocks of content therein (like
-  overriding methods of a class.) This keeps template management minimal and efficient, since each template
-  only contains the differences from the template it extends.
-
-## PrestaShop real life example
-
-In a PrestaShop theme, many pages are very similar, for example template listing products: categories, new products, search results, and so on. All of them display a list of products, so they all extend `catalog/listing/product-list.tpl` (which extends the main layout).
-
-```smarty
-  {extends file=$layout}
-
-  {block name='content'}
-    <section id="main">
-
-      {block name='product_list_header'}
-        <h2 class="h2">{$listing.label}</h2>
-      {/block}
-
-      {block name='product_list'}
-        {include file='catalog/_partials/products.tpl' listing=$listing}
-      {/block}
-
-    </section>
-  {/block}
-```
-
-The template will show a title and a list of products underneath. For category page, we want a nice
-description with an cover image. So we can simply override the *product_list_header*
-
-```smarty
-  {extends file='catalog/listing/product-list.tpl'}
-
-  {block name='product_list_header'}
-
-    <h1>{$category.name}</h1>
-    <div class="category-cover">
-      <img src="{$category.image.large.url}" alt="{$category.image.legend}">
-    </div>
-    <div id="category-description">{$category.description nofilter}</div>
-
-  {/block}
-```
-
-This reduce code to the minimum, without any repetition.
diff --git a/themes/reference/template-inheritance/img/template-inheritance.png b/themes/reference/template-inheritance/img/template-inheritance.png
deleted file mode 100644
index cdb8d05687..0000000000
Binary files a/themes/reference/template-inheritance/img/template-inheritance.png and /dev/null differ
diff --git a/themes/reference/template-inheritance/parent-child-feature.md b/themes/reference/template-inheritance/parent-child-feature.md
deleted file mode 100644
index 7e46accd6e..0000000000
--- a/themes/reference/template-inheritance/parent-child-feature.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-title: Parent/child theme
----
-
-# Parent/child theme
-
-PrestaShop relies a lot on template inheritance in order to create the most consistent theme possible, while heavily reducing the amount of duplicated code.
-
-We took it even further introducing the Parent Child theme feature. The point to is to avoid modifying the main theme, so you can update it!
-
-{{% notice note %}}
-  This feature is only useful if you want to slightly modify a theme (to add a block for example).
-  If you need to modify the markup more deeply, modify the theme, don't create a child theme.
-{{% /notice %}}
-
-## The principle
-
-So far we talked about extending template within the same theme. But you can also extend templates from another theme.
-
-{{% notice tip %}}
-  As a theme developer, you want to create as many blocks as possible so your user can
-  override the minimum amount of code.
-{{% /notice %}}
-
-## How to create a child theme
-
-First you need to have the theme you want to use as parent in your store `/themes` folder.
-
-Then you can create a very minimal theme, containing only the following files:
-
-```bash
-  .
-  ├── config
-  │   └── theme.yml
-  └── preview.png
-```
-
-{{% notice tip %}}
-  It's recommended to copy these files from the Parent theme.
-{{% /notice %}}
-
-Once you have this, you will specify in your child theme `theme.yml` which theme should be used as a parent.
-The value must be the theme technical name (ie: the theme folder name).
-
-```yaml
-parent: classic
-name: childtheme
-display_name: My first child Theme
-version: 1.0.0
-assets:
-  use_parent_assets: true
-```
-
-{{% notice note %}}
-Find more information about [`use_parent_assets` behavior here]({{<relref "/9/themes/getting-started/theme-yml#parent--child-settings">}})
-{{% /notice %}}
-
-Go ahead, select this theme in your backoffice and you're all set.
-
-### Overriding templates
-
-Without any further modification the child theme will use every template from the parent theme.
-
-In the following example we'll modify the category template.
-
-### Re-defining the whole template
-
-Create the category template in your child theme `templates/catalog/listing/category.tpl`. At this point you
-can do anything you want in this template but most likely you still want to extend product-list template. If so,
-you don't have to copy product-list template to your child theme, PrestaShop will use the parent file.
-
-Extend product-list the normal way and override the block you need.
-
-```smarty
-  {extends file='catalog/listing/product-list.tpl'}
-```
-
-### Extending the same template
-
-Another way to overriding the category template would be to extend the parent template and define just the
-block you need. There is a little difference if you want to override the same template, you need to add
-the parent resource (note the parent keyword in the example below).
-
-```smarty
-  {extends file='parent:catalog/listing/category.tpl'}
-```
diff --git a/themes/reference/template-variables.md b/themes/reference/template-variables.md
new file mode 100644
index 0000000000..43ea6dfd29
--- /dev/null
+++ b/themes/reference/template-variables.md
@@ -0,0 +1,249 @@
+---
+title: Template variables
+weight: 1
+aliases:
+  - /9/themes/reference/templates/variables
+---
+
+# Template variables
+
+PrestaShop exposes global variables to all front-office Smarty templates via [`FrontController.php`](https://github.com/PrestaShop/PrestaShop/blob/9.0.x/classes/controller/FrontController.php). All variables listed on this page are available on every normal front-office page. The maintenance page and the restricted-country page are exceptions — they bypass the normal controller lifecycle and only receive `{$urls}` and `{$shop}`.
+
+## Cart
+
+`{$cart}` is a lazy-loaded object (`CartLazyArray`). Properties are only computed when accessed. Most keys use snake_case — `minimalPurchase` and `minimalPurchaseRequired` are the only camelCase exceptions.
+
+{{% notice warning %}}
+On the order-confirmation page, `{$cart}` is an empty unsaved cart — the cart cookie is cleared after purchase. Use `{$order}` to display order data on that page.
+{{% /notice %}}
+
+| Variable | Description |
+|----------|-------------|
+| `{$cart.products}` | Products in the cart with quantities, attributes, and prices |
+| `{$cart.products_count}` | Total number of product items |
+| `{$cart.totals}` | Total amounts — includes `total` and `total_excluding_tax` keys, each a formatted amount array |
+| `{$cart.subtotals}` | Breakdown by line: products, discounts, shipping, wrapping, taxes |
+| `{$cart.vouchers}` | Applied cart rules and reductions |
+| `{$cart.discounts}` | Additional cart discounts |
+| `{$cart.summary_string}` | Localized item count string (e.g., "3 items") |
+| `{$cart.labels}` | Tax notation labels (e.g., `tax_short`: "Tax incl.") |
+| `{$cart.is_virtual}` | Whether all products in the cart are virtual (no shipping required) |
+| `{$cart.id_address_delivery}` | Delivery address ID |
+| `{$cart.id_address_invoice}` | Invoice address ID |
+| `{$cart.minimalPurchase}` | Minimum required order amount converted to the current currency — `0` if disabled (`PS_PURCHASE_MINIMUM`) |
+| `{$cart.minimalPurchaseRequired}` | Translated error message when the cart total (tax excl.) is below the minimum — empty string if the threshold is met or disabled |
+
+## Currency
+
+| Variable | Description |
+|----------|-------------|
+| `{$currency.id}` | Currency ID |
+| `{$currency.name}` | Currency name (e.g., "Euro") |
+| `{$currency.iso_code}` | ISO 4217 alphabetic code (e.g., `EUR`) |
+| `{$currency.iso_code_num}` | ISO 4217 numeric code (e.g., `978`) |
+| `{$currency.sign}` | Currency symbol (e.g., `€`) |
+
+## Customer
+
+All keys are present on every page. String keys are empty and `id` is `null` when the customer is not logged in — always check `{$customer.is_logged}` before using personal data.
+
+| Variable | Description |
+|----------|-------------|
+| `{$customer.id}` | Customer ID — `null` when not logged in |
+| `{$customer.firstname}` | First name |
+| `{$customer.lastname}` | Last name |
+| `{$customer.email}` | Email address |
+| `{$customer.is_logged}` | Whether the customer is authenticated |
+| `{$customer.is_guest}` | Whether the customer is a guest |
+| `{$customer.active}` | Whether the customer account is active |
+| `{$customer.birthday}` | Birthday in `YYYY-MM-DD` format |
+| `{$customer.gender}` | Gender — array with `id`, `type` (0=male, 1=female, 2=other), and translated `name` |
+| `{$customer.company}` | Company name |
+| `{$customer.website}` | Website URL |
+| `{$customer.siret}` | SIRET number |
+| `{$customer.ape}` | APE code |
+| `{$customer.newsletter}` | Whether the customer is subscribed to the newsletter |
+| `{$customer.newsletter_date_add}` | Newsletter subscription date |
+| `{$customer.optin}` | Whether the customer opted in to partner offers |
+| `{$customer.outstanding_allow_amount}` | Allowed outstanding credit amount (B2B) |
+| `{$customer.max_payment_days}` | Maximum payment period in days (B2B) |
+| `{$customer.id_default_group}` | Default customer group ID |
+| `{$customer.id_shop}` | Associated shop ID |
+| `{$customer.id_shop_group}` | Associated shop group ID |
+| `{$customer.date_add}` | Account creation date |
+| `{$customer.date_upd}` | Account last modification date |
+| `{$customer.risk}` | Risk level — array with `id`, `name`, `color`, `percent` (B2B) |
+| `{$customer.addresses}` | Saved addresses keyed by address ID — empty when not logged in |
+
+## Language
+
+| Variable | Description |
+|----------|-------------|
+| `{$language.id}` | Language ID |
+| `{$language.name}` | Language name (e.g., "English") |
+| `{$language.iso_code}` | ISO 639-1 code (e.g., `en`) |
+| `{$language.locale}` | BCP 47 locale (e.g., `en-US`) |
+| `{$language.language_code}` | IETF language tag, lowercase (e.g., `en-us`) |
+| `{$language.is_rtl}` | Whether the language reads right-to-left |
+| `{$language.active}` | Whether the language is enabled |
+| `{$language.date_format_lite}` | Short date format as a PHP `date()` pattern (e.g., `Y-m-d`) |
+| `{$language.date_format_full}` | Long date and time format as a PHP `date()` pattern (e.g., `Y-m-d H:i:s`) |
+
+## Country
+
+| Variable | Description |
+|----------|-------------|
+| `{$country.id}` | Country ID |
+| `{$country.name}` | Country name (translated to the current language) |
+| `{$country.iso_code}` | ISO 3166-1 alpha-2 code (e.g., `FR`) |
+| `{$country.call_prefix}` | International dialing prefix (e.g., `33`) |
+| `{$country.display_tax_label}` | Whether tax labels should be shown for this country |
+| `{$country.contains_states}` | Whether the country is subdivided into states or provinces — controls state field visibility in address forms |
+| `{$country.need_zip_code}` | Whether a postal code field should appear in address forms |
+| `{$country.need_identification_number}` | Whether an ID number field (DNI/NIF/NIE) is required in address forms |
+
+## Page
+
+| Variable | Description |
+|----------|-------------|
+| `{$page.title}` | Empty string on successful pages — only set on 404 and error states. Use `{$page.meta.title}` for the `<title>` tag and page-specific variables (e.g., `{$product.name}`) for the visible H1 |
+| `{$page.canonical}` | Canonical URL for SEO — set by each controller; `null` if the controller does not define one |
+| `{$page.meta.title}` | SEO meta title — always non-empty at runtime (falls back to shop name) |
+| `{$page.meta.description}` | SEO meta description — may be empty if not configured in the Back Office |
+| `{$page.meta.robots}` | Robots directive — `"index"` by default; `"noindex"` on search results and some CMS pages |
+| `{$page.page_name}` | Internal page identifier (e.g., `product`, `category`, `index`, `search`) |
+| `{$page.body_classes}` | Key/bool pairs for building the body class attribute — use with the `classnames` modifier |
+| `{$page.password-policy}` | zxcvbn strength feedback strings — present on every page, consumed by the JS password-strength meter. Requires bracket notation: `{$page['password-policy']}` |
+
+## Shop
+
+| Variable | Description |
+|----------|-------------|
+| `{$shop.id}` | Shop ID |
+| `{$shop.group_id}` | Shop group ID |
+| `{$shop.name}` | Shop name |
+| `{$shop.email}` | Shop contact email |
+| `{$shop.registration_number}` | Legal registration number (`PS_SHOP_DETAILS`) — empty string if not configured |
+| `{$shop.logo}` | Logo as a full absolute URL — empty string if no logo is uploaded |
+| `{$shop.logo_details}` | Logo with dimensions — array with `src`, `width`, and `height` keys — empty array if no logo |
+| `{$shop.favicon}` | Favicon as a full absolute URL — empty string if not configured |
+| `{$shop.favicon_update_time}` | Favicon cache-busting timestamp (`PS_IMG_UPDATE_TIME`) |
+| `{$shop.stores_icon}` | Store locator icon as a full absolute URL — empty string if not configured |
+| `{$shop.phone}` | Phone number — `false` if not configured |
+| `{$shop.fax}` | Fax number — `false` if not configured |
+| `{$shop.address.formatted}` | Full shop address as HTML with `<br>` line breaks |
+| `{$shop.address.address1}` | Street address line 1 |
+| `{$shop.address.address2}` | Street address line 2 |
+| `{$shop.address.postcode}` | Postal code |
+| `{$shop.address.city}` | City |
+| `{$shop.address.state}` | State or region name |
+| `{$shop.address.country}` | Country name (translated to the current language) |
+
+## URLs
+
+### Base URLs
+
+All values are absolute URLs.
+
+| Variable | Description |
+|----------|-------------|
+| `{$urls.base_url}` | Shop base URL including language prefix (e.g., `https://example.com/en/`) |
+| `{$urls.current_url}` | Current page full URL |
+| `{$urls.shop_domain_url}` | Shop domain without language prefix (e.g., `https://example.com/`) |
+| `{$urls.img_ps_url}` | PrestaShop core images (`/img/`) |
+| `{$urls.img_prod_url}` | Product images (`/img/p/`) |
+| `{$urls.img_cat_url}` | Category images (`/img/c/`) |
+| `{$urls.img_lang_url}` | Language flag images (`/img/l/`) |
+| `{$urls.img_manu_url}` | Manufacturer images (`/img/m/`) |
+| `{$urls.img_sup_url}` | Supplier images (`/img/su/`) |
+| `{$urls.img_ship_url}` | Carrier images (`/img/s/`) |
+| `{$urls.img_store_url}` | Store images (`/img/st/`) |
+| `{$urls.img_col_url}` | Color and attribute images (`/img/co/`) |
+| `{$urls.img_url}` | Theme image assets |
+| `{$urls.css_url}` | Theme CSS assets |
+| `{$urls.js_url}` | Theme JavaScript assets |
+| `{$urls.theme_assets}` | Theme assets root |
+| `{$urls.theme_dir}` | Theme root directory |
+| `{$urls.pic_url}` | Customer-uploaded files (`/upload/`) |
+| `{$urls.no_picture_image}` | Placeholder image — array with `bySize` (named sizes), `small`, `medium`, and `large` keys, each with `url`, `width`, and `height` |
+| `{$urls.actions.logout}` | Logout action URL |
+| `{$urls.alternative_langs}` | Equivalent page URLs keyed by language code (e.g., `fr-fr`) — empty array on single-language shops |
+
+### Page URLs
+
+Pre-built URLs for standard front-office pages. All values are absolute URLs.
+
+| Variable | Page |
+|----------|------|
+| `{$urls.pages.index}` | Home |
+| `{$urls.pages.cart}` | Cart |
+| `{$urls.pages.authentication}` | Login |
+| `{$urls.pages.registration}` | Registration |
+| `{$urls.pages.register}` | Registration (alias) |
+| `{$urls.pages.my_account}` | Customer account |
+| `{$urls.pages.identity}` | Account information |
+| `{$urls.pages.addresses}` | Saved addresses |
+| `{$urls.pages.address}` | Add / edit address |
+| `{$urls.pages.history}` | Order history |
+| `{$urls.pages.order}` | Checkout |
+| `{$urls.pages.order_confirmation}` | Order confirmation |
+| `{$urls.pages.order_detail}` | Order detail |
+| `{$urls.pages.order_follow}` | Order tracking |
+| `{$urls.pages.order_return}` | Order return |
+| `{$urls.pages.order_slip}` | Credit slips |
+| `{$urls.pages.order_login}` | Checkout with login forced |
+| `{$urls.pages.discount}` | Vouchers |
+| `{$urls.pages.search}` | Search |
+| `{$urls.pages.contact}` | Contact |
+| `{$urls.pages.sitemap}` | Sitemap |
+| `{$urls.pages.stores}` | Stores |
+| `{$urls.pages.cms}` | CMS pages |
+| `{$urls.pages.category}` | Categories |
+| `{$urls.pages.product}` | Products |
+| `{$urls.pages.manufacturer}` | Brands |
+| `{$urls.pages.brands}` | Brands (alias) |
+| `{$urls.pages.supplier}` | Suppliers |
+| `{$urls.pages.prices_drop}` | Sales / price drops |
+| `{$urls.pages.new_products}` | New products |
+| `{$urls.pages.guest_tracking}` | Guest order tracking |
+| `{$urls.pages.password}` | Password reset |
+| `{$urls.pages.pagenotfound}` | 404 page |
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `{$configuration.display_taxes_label}` | Whether to show tax labels next to prices (based on current country settings) |
+| `{$configuration.display_prices_tax_incl}` | Whether prices are displayed tax-inclusive (based on `PS_TAX` and the customer group tax method) |
+| `{$configuration.taxes_enabled}` | Whether taxes are enabled in the shop (`PS_TAX`) |
+| `{$configuration.low_quantity_threshold}` | Stock quantity below which "low stock" is displayed — default `3` (`PS_LAST_QTIES`) |
+| `{$configuration.is_b2b}` | Whether the shop is in B2B mode (`PS_B2B_ENABLE`) |
+| `{$configuration.is_catalog}` | Whether the shop is in catalog mode — prices and cart are hidden (`PS_CATALOG_MODE` or geolocation override) |
+| `{$configuration.show_prices}` | Whether prices are visible to the current customer group |
+| `{$configuration.voucher_enabled}` | Whether vouchers and cart rules are active |
+| `{$configuration.return_enabled}` | Whether merchandise returns are enabled (`PS_ORDER_RETURN`) |
+| `{$configuration.number_of_days_for_return}` | Number of days allowed to request a return — default `14` (`PS_ORDER_RETURN_NB_DAYS`) |
+| `{$configuration.opt_in.partner}` | Whether the partner opt-in checkbox appears on the registration form (`PS_CUSTOMER_OPTIN`) |
+| `{$configuration.quantity_discount.type}` | How quantity discounts are displayed — `"price"` (unit price) or `"discount"` (`PS_DISPLAY_DISCOUNT_PRICE`) |
+| `{$configuration.quantity_discount.label}` | Translated label for the quantity discount column — `"Unit price"` or `"Unit discount"` |
+| `{$configuration.password_policy.minimum_length}` | Minimum password length — default `8` |
+| `{$configuration.password_policy.maximum_length}` | Maximum password length — default `72` |
+| `{$configuration.password_policy.minimum_score}` | Minimum zxcvbn strength score required, from `0` (any password) to `4` (very strong) |
+
+## Utilities
+
+| Variable | Description |
+|----------|-------------|
+| `{$breadcrumb.links}` | Breadcrumb steps — each item has a `title` and a `url`. Always contains at least the Home entry |
+| `{$breadcrumb.count}` | Number of breadcrumb steps — at least `1` |
+| `{$field_required}` | Array of required field validation errors |
+| `{$time}` | Current Unix timestamp |
+| `{$static_token}` | CSRF token — stable across requests for the same session (`Tools::getToken(false)`) |
+| `{$token}` | CSRF token — changes per page/controller (`Tools::getToken()`) |
+| `{$debug}` | Whether developer mode is enabled (`_PS_MODE_DEV_`) |
+
+## Page-specific variables
+
+The variables above are available on every front-office page. Controllers also inject page-specific variables — for example `$product` on the product page, `$listing` on category and search pages, `$order` on the order confirmation page.
+
+See the source controllers in [`classes/controller/`](https://github.com/PrestaShop/PrestaShop/blob/9.0.x/classes/controller/) and the relevant `.tpl` templates for the full list of variables available on each page.
diff --git a/themes/reference/templates/_index.md b/themes/reference/templates/_index.md
deleted file mode 100644
index 6c3e0b017e..0000000000
--- a/themes/reference/templates/_index.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Templates
-chapter: true
----
-
-# Templates
-
-The following section describes the purpose of each template and how to use them.
-
-PrestaShop front office is based on Smarty template engine, for this part it's very important
-you understood well how Smarty works, especially [template inheritance]({{< relref "/9/themes/reference/template-inheritance/_index.md" >}}).
-
-{{% children /%}}
diff --git a/themes/reference/templates/head.md b/themes/reference/templates/head.md
deleted file mode 100644
index 9329baf69d..0000000000
--- a/themes/reference/templates/head.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: Head
-weight: 20
----
-
-# Head
-
-The head part is very important in terms of SEO and performance.
-
-Have look at Classic's head part to see real life examples.
-
-
-## Assets
-
-PrestaShop 1.7 changed the way asset work, and it means the way they are added
-inside the `<head>` tag of your page changed a bit too.
-
-There are 2 important files to use:
-
-* `_partials/stylesheets.tpl`
-* `_partials/javascript.tpl`
-
-These 2 files are used to take full advantage of the features like async
-loading for javascript or automatic inline for CSS.
-
-{{% notice warning %}}
-  The `_partials/javascript.tpl` has to be included at the bottom of your page as well.
-{{% /notice %}}
-
-```smarty
-  {block name='stylesheets'}
-    {include file="_partials/stylesheets.tpl" stylesheets=$stylesheets}
-  {/block}
-
-  {block name='javascript_head'}
-    {include file="_partials/javascript.tpl" javascript=$javascript.head vars=$js_custom_vars}
-  {/block}
-```
-
-Those 2 subtemplates are very simple, they loop and print each provided assets.
-
-
-### SEO
-
-A lot of meta and SEO information belong here, there is a special block for it
-so template which extend this layout can easily redefine the page title or
-description.
-
-```smarty
-  {block name='head_seo'}
-
-    <title>{block name='head_seo_title'}{$page.meta.title}{/block}</title>
-    <meta name="description" content="{block name='head_seo_description'}{$page.meta.description}{/block}">
-    <meta name="keywords" content="{block name='head_seo_keywords'}{$page.meta.keywords}{/block}">
-
-    {if $page.meta.robots !== 'index'}
-      <meta name="robots" content="{$page.meta.robots}">
-    {/if}
-
-    {if $page.canonical}
-      <link rel="canonical" href="{$page.canonical}">
-    {/if}
-
-  {/block}
-```
diff --git a/themes/reference/templates/img/configure-layout.png b/themes/reference/templates/img/configure-layout.png
deleted file mode 100644
index c4f68dabce..0000000000
Binary files a/themes/reference/templates/img/configure-layout.png and /dev/null differ
diff --git a/themes/reference/templates/listing.md b/themes/reference/templates/listing.md
deleted file mode 100644
index a2a9b6754d..0000000000
--- a/themes/reference/templates/listing.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: Listing pages
-weight: 40
----
-
-# Listing pages
-
-Your catalog is mostly 2 things: a list of products and a detailed product page.
-
-This section covers the listing pages, which includes: category, search result,
-products per brand, best seller list, new product list and so on.
-
-In order to reduce code duplication, the only necessary template is the file
-`catalog/listing/product-list.tpl`.
-
-
-## Extending product-list template
-
-We already covered [how PrestaShop chooses the right template to use]({{< ref "templates-layouts" >}})
-so we know that the category template extends the product-list template.
-
-We already covered how the [template inheritance]({{< relref "/9/themes/reference/template-inheritance/" >}}) allows you to redefine only a
-small part of bigger template.
-
-So basically you are all set to create a category template or a search result template
-that make much more than the product-list template!
-
-
-## AJAX page update
-
-Your product list will change as the customer filters the result with
-faceted navigation or sorting options for instance.
-
-One of the golden rules is: **No presentation code duplication**.
-Hence we didn't want to return json data about the result and let javascript
-reconstitute the page.
-
-We made the core generate the sub template part and return it to the client. In the
-end javascript is only used to replace the content of HTML placeholders.
-
-Each ajax call will regenerate the following templates:
-
-* `catalog/_partials/products-top.tpl`
-* `catalog/_partials/products.tpl`
-* `catalog/_partials/products-bottom.tpl`
-
-### How to update the view
-
-PrestaShop will emit JavaScript events to let you know what to do something.
-
-Example:
-
-```js
-import $ from 'jquery';
-import prestashop from 'prestashop';
-import 'velocity-animate';
-
-$(document).ready(() => {
-  prestashop.on('updateProductList', (data) => {
-    updateProductListDOM(data);
-  });
-});
-
-function updateProductListDOM (data) {
-  $('#search_filters').replaceWith(data.rendered_facets);
-  $('#js-active-search-filters').replaceWith(data.rendered_active_filters);
-  $('#js-product-list-top').replaceWith(data.rendered_products_top);
-  $('#js-product-list').replaceWith(data.rendered_products);
-  $('#js-product-list-bottom').replaceWith(data.rendered_products_bottom);
-}
-```
diff --git a/themes/reference/templates/notifications.md b/themes/reference/templates/notifications.md
deleted file mode 100644
index 4cc120d72f..0000000000
--- a/themes/reference/templates/notifications.md
+++ /dev/null
@@ -1,116 +0,0 @@
----
-title: Notifications
-weight: 30
----
-
-# Notifications
-
-Throughout the whole front office, the customer can receive notification messages
-from PrestaShop, to inform about successes or errors for instance.
-Your theme can also send notifications when certain events occur.
-
-The notification messages are not hard-coded in the template files, but are sent
-from the controller, so that you have consistency in case you update/change your theme.
-Thus, this way there is a better chance that all notification messages are already
-translated into your language!
-
-
-## Types of notifications
-
-An array of notification is passed to the templates, containing at least one of these:
-
-**success**
-: An action was performed and everything went well.
-
-**error**
-: Something went wrong.
-
-**warning**
-: Important notice the merchant should know about.
-
-**info**
-: "just so you know".
-
-## How to display notifications
-
-In the "Classic" Theme, [notifications are implemented as a partial template file](https://github.com/PrestaShop/classic-theme/blob/2.0.1/templates/_partials/notifications.tpl):
-
-```smarty
-<aside id="notifications">
-
-  {if $notifications.error}
-    {block name='notifications_error'}
-      <article class="notification notification-danger" role="alert" data-alert="danger">
-        <ul>
-          {foreach $notifications.error as $notif}
-            <li>{$notif nofilter}</li>
-          {/foreach}
-        </ul>
-      </article>
-    {/block}
-  {/if}
-
-  {if $notifications.warning}
-    {block name='notifications_warning'}
-      <article class="notification notification-warning" role="alert" data-alert="warning">
-        <ul>
-          {foreach $notifications.warning as $notif}
-            <li>{$notif nofilter}</li>
-          {/foreach}
-        </ul>
-      </article>
-    {/block}
-  {/if}
-
-  {if $notifications.success}
-    {block name='notifications_success'}
-      <article class="notification notification-success" role="alert" data-alert="success">
-        <ul>
-          {foreach $notifications.success as $notif}
-            <li>{$notif nofilter}</li>
-          {/foreach}
-        </ul>
-      </article>
-    {/block}
-  {/if}
-
-  {if $notifications.info}
-    {block name='notifications_info'}
-      <article class="notification notification-info" role="alert" data-alert="info">
-        <ul>
-          {foreach $notifications.info as $notif}
-            <li>{$notif nofilter}</li>
-          {/foreach}
-        </ul>
-      </article>
-    {/block}
-  {/if}
-
-</aside>
-```
-
-...and are then [included in the template file](https://github.com/PrestaShop/classic-theme/blob/2.0.1/templates/customer/page.tpl#L32-L34):
-
-```smarty
-{block name='notifications'}
-  {include file='_partials/notifications.tpl'}
-{/block}
-```
-
-## Add your own message in your front controller
-
-Your front controller holds [the 4 following variables](https://github.com/PrestaShop/PrestaShop/blob/8.0.x/classes/controller/FrontController.php#L637-L640):
-
-* ``$this->errors``
-* ``$this->success``
-* ``$this->warning``
-* ``$this->info``
-
-They are PHP arrays, and they hold messages as a string.
-
-Here is how you can [redirect the customer AND display a message after an action](https://github.com/PrestaShop/PrestaShop/blob/8.0.x/classes/controller/FrontController.php#L634-L653):
-
-```php
-$this->success[] = $this->l('Information successfully updated.');
-$this->redirectWithNotifications($this->getCurrentURL());
-```
diff --git a/themes/reference/templates/templates-layouts.md b/themes/reference/templates/templates-layouts.md
deleted file mode 100644
index 2ba0ca5ad4..0000000000
--- a/themes/reference/templates/templates-layouts.md
+++ /dev/null
@@ -1,214 +0,0 @@
----
-title: Templates & layouts
-weight: 10
-useMermaid: true
----
-
-# Templates & layouts
-
-PrestaShop template files are based on the [Smarty 4 template engine](https://smarty-php.github.io/smarty/).
-
-{{% notice note %}}
-On PrestaShop `1.7.x`, template files were based on [Smarty 3 template engine](https://www.smarty.net/v3_overview).
-{{% /notice %}}
-
-All template files must be stored in the theme's `templates/` subfolder. For instance, the default theme
-has its template files in the following folder: `/themes/classic/templates`.
-
-## Directory structure
-
-Templates are then split between various subfolders.
-
-**/_partials/**
-: Code shared accross the whole site like header, footer or notifications.
-
-**/catalog/**
-: Product page, product/brand/supplier listing, search result and such.
-
-**/checkout/**
-: Cart, delivery options, payment options, order confirmations and such.
-
-**/cms/**
-: All the static content: contact, sitemap, CMS pages and such.
-
-**/customer/**
-: Everything about the customer's account and its data.
-
-**/errors/**
-: All the error templates: not found, server error, forbidden and such.
-
-**/layouts/**
-: The theme layouts: 1, 2 or more columns, full width, everything is possible.
-
-Template files should be written so that a single .tpl can generate a whole HTML page -- unless they are
-inside a `_partials` folder or subfolder (see our coding standard, linked from the Prologue chapter
-of this documentation).
-
-## Templates
-
-We make a **clear difference between templates and layout**.
-
-* A template extends a layout
-* The layout holds the global organization of the page
-* A template is specific to a feature: the product page for example
-
-There are many templates in a PrestaShop theme, the main ones includes:
-
-* **index.tpl** for the home page
-* **catalog/product.tpl** for the product page
-* **catalog/listing/product-list.tpl** for any product list page
-* **checkout/cart.tpl** for the detailed cart
-* **checkout/checkout.tpl** for the checkout process
-
-### Specific templates
-
-If you're working on a big store in many languages you may need to change the layout
-of the page depending on the language.
-
-For example you want a different product page for american customers and japanese ones.
-In this case you simply have to create new template `product.tpl` and place it in
-the right folder.
-
-When searching for a template, PrestaShop will check many location to determine
-which file should be used. It make it very easy to have different template for a
-given locale or a specific entity id.
-
-More details in [TemplateFinder.php](https://github.com/PrestaShop/PrestaShop/blob/8.0.x/classes/Smarty/TemplateFinder.php#L71-L117).
-
-#### Product page example
-
-With the product page, the core will check the following locations (in order) and
-return the first template found:
-
-<div class="mermaid">
-graph TD;
-    A(Lookup for template catalog/product with : locale + entity id)
-    A-->B(Lookup for template catalog/product with : entity id);
-    B-->C(Lookup for template catalog/product with : locale);
-    C-->D(Lookup for template catalog/product);
-</div>
-
-Example for the product with ID = 3 and locale = en-US:
-
-1. `en-US/catalog/product-3.tpl`
-2. `catalog/product-3.tpl`
-3. `en-US/catalog/product.tpl`
-4. `catalog/product.tpl`
-
-#### Category page example
-
-<div class="mermaid">
-graph TD;
-    A(Lookup for template catalog/listing/category with : locale + entity id)
-    A-->B(Lookup for template catalog/listing/category with : entity id);
-    B-->C(Lookup for template catalog/listing/category with : locale);
-    C-->D(Lookup for template catalog/listing/category);
-    D-->E(Lookup for template catalog/listing/product-list with locale);
-    E-->F(Lookup for template catalog/listing/product-list);
-    
-</div>
-
-Example for the category with ID = 9 and locale = en-US:
-
-1. `en-US/catalog/listing/category-9.tpl`
-2. `catalog/listing/category-9.tpl`
-3. `en-US/catalog/listing/category.tpl`
-4. `catalog/listing/category.tpl`
-5. `en-US/catalog/listing/product-list.tpl`
-6. `catalog/listing/product-list.tpl`
-
-This feature is mostly made for developer working on a custom template for a customer.
-
-## Layouts
-
-The layout is the organisation of the page: how the parts of your design are arranged.
-
-The typical example is the sidebar: is there a sidebar on your category page or is your product listing taking the whole space?
-
-In PrestaShop, users are given the ability to change the layout of each page independently. 
-As a template developer, it's your role to ensure your theme is compatible.
-
-![Configure layout](../img/configure-layout.png)
-
-### What's in a layout file
-
-The layout is the very top level of the [template inheritance]({{< relref "/9/themes/reference/template-inheritance/" >}})
-tree. Basically it hold the opening and closing `<html>` tags.
-
-Typical layout files look like the following snippet. This one is a full one:
-
-{{% notice note %}}
-  Remember to define as many blocks as possible.
-{{% /notice %}}
-
-```smarty
-    <!doctype html>
-    <html lang="{$language.iso_code}">
-
-    <head>
-      {block name='head'}
-        {include file='_partials/head.tpl'}
-      {/block}
-    </head>
-
-    <body id="{$page.page_name}" class="{$page.body_classes|classnames}">
-
-      {hook h='displayAfterBodyOpeningTag'}
-
-      <main>
-
-        <header id="header">
-          {block name='header'}
-            {include file='_partials/header.tpl'}
-          {/block}
-        </header>
-
-        <section id="wrapper">
-          <div class="container">
-
-            {block name='breadcrumb'}
-              {include file='_partials/breadcrumb.tpl'}
-            {/block}
-
-            {block name="left_column"}
-              <div id="left-column">
-                {if $page.page_name == 'product'}
-                  {hook h='displayLeftColumnProduct'}
-                {else}
-                  {hook h="displayLeftColumn"}
-                {/if}
-              </div>
-            {/block}
-
-            {block name="content_wrapper"}
-              <div id="content-wrapper">
-                {block name="content"}
-                  <p>Hello world! This is HTML5 Boilerplate.</p>
-                {/block}
-              </div>
-            {/block}
-
-          </div>
-        </section>
-
-        <footer id="footer">
-          {block name="footer"}
-            {include file="_partials/footer.tpl"}
-          {/block}
-        </footer>
-
-      </main>
-
-      {hook h='displayBeforeBodyClosingTag'}
-
-      {block name='javascript_bottom'}
-        {include file="_partials/javascript.tpl" javascript=$javascript.bottom}
-      {/block}
-
-    </body>
-
-    </html>
-```
-
-From there, each part of the theme will do its job and replace content inside these
-bricks, keeping the same organization.
\ No newline at end of file
diff --git a/themes/reference/templates/variables.md b/themes/reference/templates/variables.md
deleted file mode 100644
index bc632643f6..0000000000
--- a/themes/reference/templates/variables.md
+++ /dev/null
@@ -1,206 +0,0 @@
----
-title: Global variables for templates
-menuTitle: Template variables
-weight: 50
----
-# Global variables for templates
-PrestaShop offers preset global variables for the front office Smarty templates.
-
-The variables are set in [`classes/FrontController.php`](https://github.com/PrestaShop/PrestaShop/blob/8.1.x/classes/controller/FrontController.php):
-
-```php
-$templateVars = [
-    'cart' => $this->cart_presenter->present($cart),
-    'currency' => $this->getTemplateVarCurrency(),
-    'customer' => $this->getTemplateVarCustomer(),
-    'language' => $this->objectPresenter->present($this->context->language),
-    'page' => $this->getTemplateVarPage(),
-    'shop' => $this->getTemplateVarShop(),
-    'core_js_public_path' => $this->getCoreJsPublicPath(),
-    'urls' => $this->getTemplateVarUrls(),
-    'configuration' => $this->getTemplateVarConfiguration(),
-    'field_required' => $this->context->customer->validateFieldsRequiredDatabase(),
-    'breadcrumb' => $this->getBreadcrumb(),
-    'link' => $this->context->link,
-    'time' => time(),
-    'static_token' => Tools::getToken(false),
-    'token' => Tools::getToken(),
-    'debug' => _PS_MODE_DEV_,
-];
-```
-
-*You can dig into the code to get more information about what the variables do. Here is the list with a short description:*
-
-## List of variables
-
-### User Cart
-
-| Variable | Description |
-| --- | --- |
-| `{$cart}` | Array containing useful data from the current user's cart. |
-
-### Currency (actual shop currency)
-
-| Variable | Description |
-| --- | --- |
-| `{$currency.id}` | Currency ID in PrestaShop database |
-| `{$currency.name}` | Name of the currency |
-| `{$currency.iso_code}` | Currency ISO code |
-| `{$currency.iso_code_num}` | Currency ISO code number |
-| `{$currency.sign}` | Currency symbol |
-
-### Customer logged-in information 
-
-| Variable | Description |
-| --- | --- |
-| `{$customer.lastname}` | Customer last name  |
-| `{$customer.firstname}` | Customer first name  |
-| `{$customer.email}` | Customer email |
-| `{$customer.last_passwd_gen}` | The last date customer password was changed  |
-| `{$customer.birthday}` | Customer birthday |
-| `{$customer.newsletter}` | Receives newsletter |
-| `{$customer.newsletter_date_add}` | Newsletter registration date |
-| `{$customer.ip_registration_newsletter}` | Newsletter ip registration |
-| `{$customer.optin}` | Opt-in subscription |
-| `{$customer.website}` | User web site |
-| `{$customer.company}` | User company  |
-| `{$customer.siret}` | User SIRET |
-| `{$customer.ape}` | User APE |
-| `{$customer.outstanding_allow_amount}` | Outstanding allow amount (B2B opt)  |
-| `{$customer.max_payment_days}` | Max payment day  |
-| `{$customer.note}` | Protected note  |
-| `{$customer.is_guest}` | Is guest (not registered)  |
-| `{$customer.id_shop}` | User Shop ID  |
-| `{$customer.id_shop_group}` | Shop Group ID  |
-| `{$customer.id_default_group}` | Default group ID  |
-| `{$customer.date_add}` | User creation date  |
-| `{$customer.date_upd}` | User last modification date  |
-| `{$customer.reset_password_token}` | Unique token for forgot password feature  |
-| `{$customer.reset_password_validity}` | Token validity date for forgot password feature  |
-| `{$customer.id}` | Customer ID  |
-| `{$customer.is_logged}` | Is logged in the Shop |
-| `{$customer.gender}` | Gender array information |
-| `{$customer.risk}` | Risk array information |
-| `{$customer.addresses}` | Addresses array information |
-
-### Language store
-
-
-| Variable | Description |
-| --- | --- |
-| `{$language}` | An array containing useful data from the current shop language. |
-
-### Actual Page information
-
-| Variable | Description |
-| --- | --- |
-| `{$page.title}` | Title information |
-| `{$page.canonical}` | Friendly-Url |
-| `{$page.meta}` | Array with page meta information |
-| `{$page.page_name}` | Internal page name |
-| `{$page.body_classes}` | Array body page information |
-| `{$page.admin_notifications}` | Array admin notifications |
-| `{$page.password-policy}` | Array password policy |
-
-### Shop information
-
-| Variable | Description |
-| --- | --- |
-| `{$shop.id}` | Shop ID |
-| `{$shop.name}` | Shop name |
-| `{$shop.email}` | Shop email |
-| `{$shop.registration_number}` | Shop legal information |
-| `{$shop.logo}` | Logo url |
-| `{$shop.logo_details}` | Array with logo image information |
-| `{$shop.stores_icon}` | Icon image url |
-| `{$shop.favicon}` | Favicon image url |
-| `{$shop.favicon_update_time}` | Favicon timestamp |
-| `{$shop.address}` | Array of full address information |
-| `{$shop.phone}` | Shop phone number |
-| `{$shop.fax}` | Shop fax number |
-
-### Urls 
-
-| Variable | Description |
-| --- | --- |
-| `{$urls.base_url}` | Web site url base |
-| `{$urls.current_url}` | Actual page url |
-| `{$urls.shop_domain_url}` | Shop url |
-| `{$urls.img_ps_url}` | Url path for images |
-| `{$urls.img_cat_url}` | Url path for category images |
-| `{$urls.img_lang_url}` | Url path for language images |
-| `{$urls.img_prod_url}` | Url path for product images |
-| `{$urls.img_manu_url}` | Url path for manufacturer images |
-| `{$urls.img_sup_url}` | Url path for all “No image available” images in different languages |
-| `{$urls.img_ship_url}` | Url path for shipping images |
-| `{$urls.img_store_url}` | Url path for store images |
-| `{$urls.img_col_url}` | Url path for attributes (colors) pictures |
-| `{$urls.img_url}` | Url path for theme images assets |
-| `{$urls.css_url}` | Url path for theme styles assets |
-| `{$urls.js_url}` | Url path for theme javascript assets |
-| `{$urls.pic_url}` | Url path for files that would be uploaded by clients for customizable products |
-| `{$urls.theme_assets}` | Url path for theme assets |
-| `{$urls.alternative_langs}` | An array variable that contains URLs of the current shop's alternative languages. |
-| `{$urls.actions}` | An array of URLs representing available actions in the shop. |
-| `{$urls.no_picture_image}` | An array variable that contains the dimensions and URLs of all the "no picture" images used in the PrestaShop shop. |
-| `{$urls.pages}` | An array of URLs for different pages in PrestaShop (Home Page, Cart, Category, Search, etc.) |
-
-### Configuration
-
-The values set for shop configuration.
-
-| Variable | Description |
-| --- | --- |
-| `{$configuration.display_taxes_label}` |
-| `{$configuration.display_prices_tax_incl}` |
-| `{$configuration.taxes_enabled}` |
-| `{$configuration.low_quantity_threshold}` |
-| `{$configuration.is_b2b}` |
-| `{$configuration.is_catalog}` |
-| `{$configuration.show_prices}` |
-| `{$configuration.opt_in}` |
-| `{$configuration.quantity_discount}` |
-| `{$configuration.voucher_enabled}` |
-| `{$configuration.return_enabled}` |
-| `{$configuration.number_of_days_for_return}` |
-| `{$configuration.password_policy}` |
-
-### field_required 
-
-| Variable | Description |
-| --- | --- |
-| `{$field_required}` | Array of errors indicating the fields that are required. |
-
-### breadcrumb
-
-| Variable | Description |
-| --- | --- |
-| `{$breadcrumb}` | Array containing the description and URL of all the paths that the user has browsed from the home page. |
-
-### link
-
-
-| Variable | Description |
-| --- | --- |
-| `{$link}` | Array that contains the main information of the Link Class, including the URL protocol used. |
-
-### time
-
-| Variable | Description |
-| --- | --- |
-| `{$time}` | Current Unix timestamp|
-
-### token
-
-Retrieve the shop token data used to prevent CSRF (Cross-Site Request Forgery) attacks.
-
-| Variable | Description |
-| --- | --- |
-| `{$static_token}` | |
-| `{$token}` | (generated token, including the PHP page.) |
-
-### debug 
-
-| Variable | Description |
-| --- | --- |
-| `{$debug}` | Boolean value indicating whether the shop's debug mode is turned on (true) or off (false). |
diff --git a/themes/reference/theme-translation.md b/themes/reference/theme-translation.md
deleted file mode 100644
index 277269904b..0000000000
--- a/themes/reference/theme-translation.md
+++ /dev/null
@@ -1,77 +0,0 @@
----
-title: Theme translation
----
-
-# How to translate your theme
-
-PrestaShop provides a way to translate your theme to any language.
-
-## 1. Add new or customize existing wordings in a theme
-
-Adding new wordings is easy when building your theme. You simply need to edit the `.tpl` file of your choice and add (or customize) a wording. All wordings must always be written in english.
-
-For example:
-
-```smarty
-{l s='Read more' d='Shop.Yourthemename'}
-```
-
-Change "Yourthemename" to your own theme's name.
-
-{{% notice warning %}}
-The theme name must start in a capital letter and have no other upper case letter (eg. "YourThemeName" won't work).
-{{% /notice %}}
-
-## 2. Add the desired languages in your shop
-
-It is best to perform the following steps only after your shop is ready to be exported (ie. you're done developing it).
-
-1. On your shop, go to International > Translations
-
-	![Translations section in the menu](../img/translations-menu.png)
-	
-2. Then go to the "Add / Update a language" section and choose the languages that you wish to support in your theme.
-
-	![Add / Update a language](../img/translations-add-update-language.png)
-
-## 3. Translate your theme's custom translations
-
-Again, on the same "Translations" page as in the previous step, go to the "Modify translations section" and choose:
-
-* Theme translations
-* The theme you wish to translate (in this example, we are translating "lifestyle")
-* Language to translate to (eg. "French")
-
-![Modify translations](../img/translations-modify.png)
-
-When you click on "Modify", a new page opens up that allows you to translate your theme's wordings. On the left column, go to "Shop" and "your theme name" ("Lifestyle" in this example).
-
-![Translation tree](../img/translations-tree.png)
-
-A form appears on the right, showing all the customized wordings that you added in the `.tpl` files. 
-
-![Translation form](../img/translations-form.png)
-
-At this point, all you need to do is translate them, then redo the process for each one of the languages you want to translate your theme in.
-
-## 4. Export languages
-
-Once all translations are done, you now need to export all of the wordings that you want to include in your theme. For this, go back to the "Translations" page, then scroll to the "Export a language" section:
-
-![Export a language](../img/translations-export-language.png)
-
-Once the .zip file has been downloaded, extract it and add this folder to your theme's translations folder. This way, when you will export your theme, translations will be included with it.
-
-## 5. Export your theme
-
-After all the previous steps have been performed, all that's left to do is export your theme.
-
-1. On your shop, go to Design > Theme & logo.
-
-	![Theme and logo in the menu](../img/translations-theme-and-logo.png)
-
-2. In this page, on the top right corner, click on the "Export current theme" button.
-
-	![Export current theme button](../img/translations-export-current-theme.png)
-
-After this step, the theme will be zipped an ready, and will include the translations that we added before. To verify it, just unzip the zip file and check that all the files are present.