@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/schema-types.md

@@ -0,0 +1,926 @@
+---
+title: "Schema Types"
+weight: 13
+---
+
+# Schema Types
+
+Schema defines how sections and settings are customized in the Zoho Commerce admin panel. Each setting type has specific properties, default value formats, and output behavior.
+
+## Schema Structure
+
+```json
+{
+  "name": "t:sections.hero_banner.name",
+  "category": "Banner",
+  "tag": "section",
+  "class": "section",
+  "available_in": {"templates": ["index", "category", "collection"]},
+  "settings": [
+    {
+      "type": "text",
+      "id": "section_title",
+      "label": "t:sections.hero_banner.settings.title.label",
+      "default": "Welcome",
+      "meta": "desktop"
+    }
+  ],
+  "blocks": [
+    {
+      "type": "button",
+      "name": "t:sections.hero_banner.blocks.button.name",
+      "limit": 2,
+      "settings": [
+        {
+          "type": "text",
+          "id": "button_text",
+          "label": "t:sections.hero_banner.blocks.button.settings.text.label",
+          "default": "Shop Now"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Core Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | Yes | Display name in admin (use `t:` prefix for translations) |
+| `category` | string | No | Section category for grouping in admin |
+| `tag` | string | No | HTML element for wrapper (default: `div`) |
+| `class` | string | No | CSS class for section wrapper |
+| `available_in` | object | No | Templates where section can be used |
+| `settings` | array | Yes | Array of setting definitions |
+| `blocks` | array | No | Repeatable content blocks |
+| `limit` | number | No | Maximum instances of this section per page |
+
+### available_in Property
+
+Controls where a section can be added:
+
+```json
+{
+  "available_in": {
+    "templates": ["index", "category", "collection", "product", "search", "header-group", "footer-group"]
+  }
+}
+```
+
+---
+
+## Setting Types
+
+### Setting Meta Property
+
+Use the `meta` property to group settings for desktop/mobile views in the admin UI:
+
+```json
+{
+  "type": "range",
+  "id": "desktop_padding",
+  "label": "Desktop Padding",
+  "default": 10,
+  "min": 0,
+  "max": 50,
+  "step": 1,
+  "meta": "desktop"
+},
+{
+  "type": "range",
+  "id": "mobile_padding",
+  "label": "Mobile Padding",
+  "default": 5,
+  "min": 0,
+  "max": 30,
+  "step": 1,
+  "meta": "mobile"
+}
+```
+
+For theme-level settings in `settings/schema.json`, use `meta` to group as component or global settings:
+
+```json
+{
+  "name": "t:settings_schema.colors.name",
+  "settings": [...],
+  "meta": "global_settings"
+}
+```
+
+---
+
+### header
+
+Visual divider to group related settings in the admin panel. Does not produce any output value.
+
+```json
+{
+  "type": "header",
+  "content": "Layout Settings",
+  "meta": "desktop"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"header"` | Yes | Setting type |
+| `content` | string | Yes | Header label text |
+| `meta` | string | No | Grouping (`desktop`, `mobile`, `global_settings`, `component_settings`) |
+
+**Output:** None — used only for admin UI organization.
+
+---
+
+### text
+
+Single-line text input.
+
+```json
+{
+  "type": "text",
+  "id": "heading",
+  "label": "t:sections.hero.settings.heading.label",
+  "placeholder": "Enter heading text",
+  "default": "Welcome to our store",
+  "meta": "desktop"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"text"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `placeholder` | string | No | Hint text |
+| `default` | string | Yes | Initial value |
+| `meta` | string | No | Grouping for admin UI |
+
+**Output:** `{{ section.settings.heading | escape }}` → `"Welcome to our store"`
+
+> **Use for:** headings (`<h1>`–`<h6>`), titles, eyebrows, badges, button/CTA labels — any short plain text.
+> **Do not use for:** multi-line body copy — use `richtext` instead.
+
+---
+
+### richtext
+
+Multi-line rich text editor with HTML formatting.
+
+```json
+{
+  "type": "richtext",
+  "id": "description",
+  "label": "t:sections.hero.settings.description.label",
+  "default": "<p>Enter your description here</p>"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"richtext"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `default` | string (HTML) | Yes | Initial HTML content |
+
+**Output:** `{{ section.settings.description }}` → `"<p>Enter your description here</p>"`
+
+> The output contains raw HTML. Use `{{ section.settings.description | raw }}` in templates.
+>
+> **When to use:** `richtext` for paragraphs, descriptions, answers, and multi-line body copy only.
+> **When NOT to use:** headings, titles, eyebrows, badges, or button labels — use `text` instead (see `text` type above).
+
+---
+
+### color
+
+Color picker returning a hex color value.
+
+```json
+{
+  "type": "color",
+  "id": "primary_color",
+  "label": "t:sections.hero.settings.primary_color.label",
+  "default": "#854d0e"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"color"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `default` | string (hex) | Yes | Hex color code (e.g., `#854d0e`) |
+
+**Output:** `{{ section.settings.primary_color }}` → `"#854d0e"`
+
+**With filters:**
+```liquid
+{{ section.settings.primary_color | color_component: "red" }}
+```
+**Output:** `133`
+
+---
+
+### select
+
+Dropdown menu with predefined options.
+
+```json
+{
+  "type": "select",
+  "id": "layout_style",
+  "label": "t:sections.hero.settings.layout_style.label",
+  "options": [
+    { "value": "grid", "label": "t:sections.hero.settings.layout_style.options.grid" },
+    { "value": "list", "label": "t:sections.hero.settings.layout_style.options.list" },
+    { "value": "carousel", "label": "t:sections.hero.settings.layout_style.options.carousel" }
+  ],
+  "default": { "display_name": "t:sections.hero.settings.layout_style.default", "value": "grid" }
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"select"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `options` | array | Yes | Array of `{ value, label }` objects |
+| `default` | object | Yes | Object with `display_name` and `value` |
+
+**Output:** `{{ section.settings.layout_style.value }}` → `"grid"`
+
+---
+
+### radio
+
+Radio button group for selecting one option from a set. Similar to select but displayed as radio buttons.
+
+```json
+{
+  "type": "radio",
+  "id": "text_alignment",
+  "label": "t:sections.hero.settings.text_alignment.label",
+  "options": [
+    { "value": "left", "label": "t:sections.hero.settings.text_alignment.options.left" },
+    { "value": "center", "label": "t:sections.hero.settings.text_alignment.options.center" },
+    { "value": "right", "label": "t:sections.hero.settings.text_alignment.options.right" }
+  ],
+  "default": { "display_name": "t:sections.hero.settings.text_alignment.default", "value": "center" }
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"radio"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `options` | array | Yes | Array of `{ value, label }` objects |
+| `default` | object | Yes | Object with `display_name` and `value` |
+
+**Output:** `{{ section.settings.text_alignment.value }}` → `"center"`
+
+---
+
+### preview_layout
+
+Layout selector that renders options as visual layout previews in the admin panel. Functionally identical to `select` and `radio`, but displays each option as a clickable layout thumbnail rather than a dropdown or radio button. Use this when the setting controls visual placement or alignment and a preview aids the user.
+
+```json
+{
+  "type": "preview_layout",
+  "id": "content_alignment",
+  "label": "t:sections.banner.settings.content_alignment.label",
+  "options": [
+    { "value": "left",   "label": "t:sections.banner.settings.content_alignment.options.left" },
+    { "value": "center", "label": "t:sections.banner.settings.content_alignment.options.center" },
+    { "value": "right",  "label": "t:sections.banner.settings.content_alignment.options.right" }
+  ],
+  "default": { "display_name": "t:sections.banner.settings.content_alignment.default", "value": "left" },
+  "meta": "desktop"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"preview_layout"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `options` | array | Yes | Array of `{ value, label }` objects |
+| `default` | object | Yes | Object with `display_name` and `value` |
+| `meta` | string | No | Grouping (`desktop`, `mobile`) |
+
+**Output:** `{{ section.settings.content_alignment.value }}` → `"left"`
+
+```liquid
+<div class="banner-content
+  {% if section.settings.content_alignment.value == 'center' %}justify-center
+  {% elsif section.settings.content_alignment.value == 'right' %}justify-end
+  {% endif %}">
+  ...
+</div>
+```
+
+> Use `preview_layout` instead of `select` or `radio` when the setting controls layout or alignment — it helps admins visualize the effect before applying it.
+
+---
+
+### checkbox
+
+Boolean toggle (true/false).
+
+```json
+{
+  "type": "checkbox",
+  "id": "show_price",
+  "label": "t:sections.product.settings.show_price.label",
+  "default": true
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"checkbox"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `default` | boolean | Yes | `true` or `false` |
+
+**Output:** `{{ section.settings.show_price }}` → `true`
+
+```liquid
+{% if section.settings.show_price %}
+  <p class="price">{{ product.price }}</p>
+{% endif %}
+```
+
+---
+
+### range
+
+Numeric slider with min, max, and step constraints.
+
+```json
+{
+  "type": "range",
+  "id": "products_per_row",
+  "label": "t:sections.collection.settings.products_per_row.label",
+  "min": 1,
+  "max": 6,
+  "step": 1,
+  "unit": "cols",
+  "default": 4,
+  "meta": "desktop"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"range"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `min` | number | Yes | Minimum value |
+| `max` | number | Yes | Maximum value |
+| `step` | number | Yes | Increment value |
+| `unit` | string | No | Display unit (e.g., `px`, `%`, `cols`, `rem`) |
+| `default` | number | Yes | Must be within `min`–`max` range |
+| `meta` | string | No | Grouping (`desktop`, `mobile`) |
+
+**Output:** `{{ section.settings.products_per_row }}` → `4`
+
+---
+
+### image_picker
+
+Image upload and selection. Returns an object with `url` and `enable_customisation` properties. When `enable_customisation` is true, the runtime value also includes `alt_text` and `filters` for image transformations.
+
+**Schema definition** (only `url` and `enable_customisation` are needed):
+
+```json
+{
+  "type": "image_picker",
+  "id": "banner_image",
+  "label": "t:sections.banner.settings.banner_image.label",
+  "default": {
+    "url": "home_banner.webp",
+    "enable_customisation": true
+  },
+  "meta": "desktop"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"image_picker"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `default` | object | Yes | Object with `url` and `enable_customisation` |
+| `default.url` | string | Yes | Default image filename (just the filename, not full path) or empty string |
+| `default.enable_customisation` | boolean | Yes | Allow admin users to customize the image with filters and transformations |
+| `meta` | string | No | Grouping (`desktop`, `mobile`) |
+
+**Runtime output value** (when `enable_customisation` is true):
+
+```json
+{
+  "url": "https://cdn.example.com/uploads/example-image.webp",
+  "enable_customisation": true,
+  "alt_text": "",
+  "filters": {
+    "scale_y": 1,
+    "rotate": 0,
+    "scale_x": 1,
+    "filter": "brightness(70%) contrast(120%)",
+    "position_x": 0,
+    "position_y": 0,
+    "opacity": 100
+  }
+}
+```
+
+**Output:**
+```liquid
+{{ section.settings.banner_image.url }}
+```
+**Output:** `"home_banner.webp"` for theme assets (use `| asset_url` for resolution), or a full CDN URL when the admin uploads a custom image
+
+**Accessing filters:**
+```liquid
+{{ section.settings.banner_image.filters.opacity }}
+{{ section.settings.banner_image.filters.filter }}
+{{ section.settings.banner_image.filters.rotate }}
+{{ section.settings.banner_image.alt_text }}
+```
+
+> **Important:**
+> - The schema definition only requires `url` and `enable_customisation`. The `alt_text` and `filters` are part of the runtime output value.
+> - For theme asset images, use just the filename (e.g., `"home_banner.webp"`). Always pipe through the `asset_url` filter for full URL resolution: `{{ img.url | asset_url }}`. When users upload a custom image through admin, the URL will be a full CDN URL.
+
+---
+
+### Applying Image Filters (Customisation)
+
+When `enable_customisation` is true on an `image_picker` setting, the runtime output includes a `filters` object with transformation data. Apply these as inline CSS:
+
+#### Filters Object Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `opacity` | number | Image opacity (0–100) |
+| `filter` | string | CSS filter chain — supports preset filters and individual functions: `blur()`, `grayscale()`, `brightness()`, `contrast()`, `sepia()`, `saturate()` |
+| `position_x` | number | Horizontal translate offset (percentage) |
+| `position_y` | number | Vertical translate offset (percentage) |
+| `scale_x` | number | Horizontal scale factor (negative values flip the image) |
+| `scale_y` | number | Vertical scale factor (negative values flip the image) |
+| `rotate` | number | Rotation in degrees |
+
+**Usage as `<img>` element (always center the image):**
+```liquid
+{% assign img = section.settings.banner_image %}
+{% if img.url != blank %}
+  <img
+    src="{{ img.url | asset_url }}"
+    alt="{{ img.alt_text }}"
+    loading="lazy"
+    style="
+      transform: rotate({{ img.filters.rotate }}deg) scale({{ img.filters.scale_x }}, {{ img.filters.scale_y }}) translate({{ img.filters.position_x }}%, {{ img.filters.position_y }}%);
+      transform-origin: center center;
+      filter: {{ img.filters.filter }};
+      opacity: {{ img.filters.opacity }};
+      object-fit: cover;
+      object-position: center;
+    ">
+{% endif %}
+```
+
+**Usage as background image (always center the background):**
+```liquid
+{% assign img = section.settings.banner_image %}
+{% if img.url != blank %}
+  <div style="
+    background-image: url('{{ img.url | asset_url }}');
+    background-position: center center;
+    background-size: cover;
+    transform: rotate({{ img.filters.rotate }}deg) scale({{ img.filters.scale_x }}, {{ img.filters.scale_y }}) translate({{ img.filters.position_x }}%, {{ img.filters.position_y }}%);
+    transform-origin: center center;
+    filter: {{ img.filters.filter }};
+    opacity: {{ img.filters.opacity }};
+  "></div>
+{% endif %}
+```
+
+> **Important:** Always set `transform-origin: center center` so transformations align with the editor. Always center images (`object-position: center` for `<img>`, `background-position: center` for backgrounds) to keep the view stable and properly editable in the admin editor.
+
+---
+
+### url
+
+URL input field.
+
+```json
+{
+  "type": "url",
+  "id": "cta_link",
+  "label": "t:sections.hero.settings.cta_link.label",
+  "default": { "display_name": "t:sections.hero.settings.cta_link.default", "handle": "collections/all-products" }
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"url"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+| `default` | object | Yes | Object with `display_name` (translation key) and `handle` (URL path) |
+
+**Output:** `{{ section.settings.cta_link.handle }}` → `"collections/all-products"`
+
+> **Note:** For URL settings, the recommended default is `collections/all-products` which points to the all-products collection page. Use the `handle` property to access the URL path.
+
+---
+
+### category
+
+Zoho Commerce product category selector. Returns the selected category object.
+
+```json
+{
+  "type": "category",
+  "id": "featured_category",
+  "label": "t:sections.featured.settings.category.label"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"category"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+
+**Output:** Returns category object — access properties:
+```liquid
+{{ section.settings.featured_category.title }}
+{{ section.settings.featured_category.url }}
+{{ section.settings.featured_category.products }}
+{{ section.settings.featured_category.products_count }}
+```
+
+---
+
+### collection
+
+Product collection selector. Returns the selected collection object.
+
+```json
+{
+  "type": "collection",
+  "id": "featured_collection",
+  "label": "Featured Collection"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"collection"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+
+**Output:** Returns collection object — access properties:
+```liquid
+{{ section.settings.featured_collection.title }}
+{{ section.settings.featured_collection.url }}
+{{ section.settings.featured_collection.products }}
+{{ section.settings.featured_collection.products_count }}
+```
+
+---
+
+### blog
+
+Blog selector. Returns the selected blog object.
+
+```json
+{
+  "type": "blog",
+  "id": "featured_blog",
+  "label": "Featured Blog"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"blog"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+
+**Output:** Returns blog object — access properties:
+```liquid
+{{ section.settings.featured_blog.title }}
+{{ section.settings.featured_blog.url }}
+{{ section.settings.featured_blog.articles }}
+```
+
+---
+
+### menu
+
+Navigation menu selector. Returns the selected menu object.
+
+```json
+{
+  "type": "menu",
+  "id": "main_menu",
+  "label": "Main Navigation"
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `"menu"` | Yes | Setting type |
+| `id` | string | Yes | Unique identifier |
+| `label` | string | Yes | Display label |
+
+**Output:** Returns menu object — access properties:
+```liquid
+{% for link in section.settings.main_menu.links %}
+  <a href="{{ link.url }}">{{ link.title }}</a>
+{% endfor %}
+```
+
+---
+
+## Conditional Visibility
+
+Use `visible_if` to show or hide settings based on other setting values. This is a powerful feature that helps keep the admin UI clean by only showing relevant options.
+
+### Syntax
+
+The `visible_if` property uses a Liquid-like conditional expression:
+
+```json
+{
+  "settings": [
+    {
+      "type": "checkbox",
+      "id": "show_subtitle",
+      "label": "t:sections.hero.settings.show_subtitle.label",
+      "default": false
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "label": "t:sections.hero.settings.subtitle.label",
+      "default": "Your tagline here",
+      "visible_if": "{{ section.settings.show_subtitle }}"
+    }
+  ]
+}
+```
+
+### Complex Conditions
+
+You can use more complex conditions to compare values:
+
+```json
+{
+  "settings": [
+    {
+      "type": "image_picker",
+      "id": "desktop_banner_img",
+      "label": "Desktop Banner Image",
+      "default": { "url": "home_banner.webp", "enable_customisation": true },
+      "meta": "desktop"
+    },
+    {
+      "type": "color",
+      "id": "desktop_bg_color",
+      "label": "Background Color (Fallback)",
+      "default": "#FFFAF3",
+      "visible_if": "{{ section.settings.desktop_banner_img.url == null or section.settings.desktop_banner_img.url == '' }}",
+      "meta": "desktop"
+    }
+  ]
+}
+```
+
+### Best Practices for visible_if
+
+- **Use for dependent settings** — Show subtitle text field only when "Show Subtitle" is checked
+- **Reduce clutter** — Hide advanced options unless a feature is enabled
+- **Group related settings** — Combine with `meta` to organize desktop/mobile specific options
+- **Keep conditions simple** — Complex conditions can be hard to debug
+
+### Common Use Cases
+
+| Scenario | visible_if Expression |
+|----------|----------------------|
+| Show when checkbox is true | `"{{ section.settings.show_feature }}"` |
+| Show when checkbox is false | `"{{ section.settings.show_feature == false }}"` |
+| Show when image is empty | `"{{ section.settings.image.url == null or section.settings.image.url == '' }}"` |
+| Show when select has value | `"{{ section.settings.layout.value == 'custom' }}"` |
+
+---
+
+## Translation Keys
+
+Use `t:` prefix in labels for multi-language admin interfaces:
+
+```json
+{
+  "type": "text",
+  "id": "title",
+  "label": "t:sections.hero.settings.title.label",
+  "default": "Welcome"
+}
+```
+
+The translation is defined in `i18n/en.schema.json`:
+
+```json
+{
+  "sections": {
+    "hero": {
+      "settings": {
+        "title": {
+          "label": "Section Title"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Complete Section Example
+
+A full section using multiple setting types and blocks:
+
+```liquid
+<section class="hero-banner" style="background-color: {{ section.settings.bg_color }}">
+  {% if section.settings.bg_image.url != blank %}
+    {% assign img = section.settings.bg_image %}
+    <img 
+      src="{{ img.url }}" 
+      alt="{{ img.alt_text }}" 
+      class="hero-bg"
+      style="
+        object-fit: cover;
+        object-position: center;
+        transform: rotate({{ img.filters.rotate }}deg) scale({{ img.filters.scale_x }}, {{ img.filters.scale_y }}) translate({{ img.filters.position_x }}%, {{ img.filters.position_y }}%);
+        transform-origin: center center;
+        filter: {{ img.filters.filter }};
+        opacity: {{ img.filters.opacity }};
+      ">
+  {% endif %}
+  
+  <div class="hero-content" style="text-align: {{ section.settings.text_align.value }}">
+    <h1>{{ section.settings.heading }}</h1>
+    
+    {% if section.settings.show_subtitle %}
+      <p>{{ section.settings.subtitle }}</p>
+    {% endif %}
+    
+    {% for block in section.blocks %}
+      {% if block.type == 'button' %}
+        <a href="{{ block.settings.link.handle }}" class="btn" {{ block.zcommerce_attributes }}>
+          {{ block.settings.label }}
+        </a>
+      {% endif %}
+    {% endfor %}
+  </div>
+</section>
+
+{% schema %}
+{
+  "name": "t:sections.hero_banner.name",
+  "category": "Banner",
+  "tag": "section",
+  "class": "section hero-section",
+  "available_in": {"templates": ["index", "category", "collection"]},
+  "settings": [
+    { 
+      "type": "header", 
+      "content": "t:sections.hero_banner.settings.content_header",
+      "meta": "desktop"
+    },
+    {
+      "type": "text",
+      "id": "heading",
+      "label": "t:sections.hero_banner.settings.heading.label",
+      "default": "Welcome to Our Store"
+    },
+    {
+      "type": "checkbox",
+      "id": "show_subtitle",
+      "label": "t:sections.hero_banner.settings.show_subtitle.label",
+      "default": true
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "label": "t:sections.hero_banner.settings.subtitle.label",
+      "default": "Discover amazing products",
+      "visible_if": "{{ section.settings.show_subtitle }}"
+    },
+    { 
+      "type": "header", 
+      "content": "t:sections.hero_banner.settings.appearance_header",
+      "meta": "desktop"
+    },
+    {
+      "type": "color",
+      "id": "bg_color",
+      "label": "t:sections.hero_banner.settings.bg_color.label",
+      "default": "#1a1a2e"
+    },
+    {
+      "type": "image_picker",
+      "id": "bg_image",
+      "label": "t:sections.hero_banner.settings.bg_image.label",
+      "default": {
+        "url": "hero_banner.webp",
+        "enable_customisation": true
+      },
+      "meta": "desktop"
+    },
+    {
+      "type": "select",
+      "id": "text_align",
+      "label": "t:sections.hero_banner.settings.text_align.label",
+      "options": [
+        { "value": "left", "label": "t:sections.hero_banner.settings.text_align.options.left" },
+        { "value": "center", "label": "t:sections.hero_banner.settings.text_align.options.center" },
+        { "value": "right", "label": "t:sections.hero_banner.settings.text_align.options.right" }
+      ],
+      "default": { "display_name": "t:sections.hero_banner.settings.text_align.default", "value": "center" }
+    },
+    {
+      "type": "range",
+      "id": "desktop_padding",
+      "label": "t:sections.hero_banner.settings.padding.label",
+      "min": 0,
+      "max": 100,
+      "step": 10,
+      "unit": "px",
+      "default": 50,
+      "meta": "desktop"
+    },
+    {
+      "type": "range",
+      "id": "mobile_padding",
+      "label": "t:sections.hero_banner.settings.padding.label",
+      "min": 0,
+      "max": 60,
+      "step": 5,
+      "unit": "px",
+      "default": 20,
+      "meta": "mobile"
+    }
+  ],
+  "blocks": [
+    {
+      "type": "button",
+      "name": "t:sections.hero_banner.blocks.button.name",
+      "limit": 2,
+      "settings": [
+        {
+          "type": "text",
+          "id": "label",
+          "label": "t:sections.hero_banner.blocks.button.settings.label.label",
+          "default": "Shop Now"
+        },
+        {
+          "type": "url",
+          "id": "link",
+          "label": "t:sections.hero_banner.blocks.button.settings.link.label",
+          "default": { "display_name": "t:sections.hero_banner.blocks.button.settings.link.default", "handle": "collections/all-products" }
+        }
+      ]
+    }
+  ]
+}
+{% endschema %}
+```
+
+---
+
+## Quick Reference
+
+| Type | Default Format | Output Type | Admin UI |
+|------|---------------|-------------|----------|
+| `header` | N/A | None | Section divider |
+| `text` | `"string"` | string | Text input |
+| `richtext` | `"<p>html</p>"` | HTML string | Rich editor |
+| `color` | `"#hexcode"` | string | Color picker |
+| `select` | `{ "display_name": "...", "value": "..." }` | object | Dropdown |
+| `radio` | `{ "display_name": "...", "value": "..." }` | object | Radio buttons |
+| `preview_layout` | `{ "display_name": "...", "value": "..." }` | object | Visual layout picker |
+| `checkbox` | `true` / `false` | boolean | Toggle |
+| `range` | `number` | number | Slider |
+| `image_picker` | `{ "url": "filename.webp", "enable_customisation": true }` | object (`url`, `enable_customisation`, `alt_text`, `filters`) | Image uploader |
+| `url` | `{ "display_name": "...", "handle": "collections/all-products" }` | object | URL input |
+| `category` | N/A | object | Category picker |
+| `collection` | N/A | object | Collection picker |
+| `blog` | N/A | object | Blog picker |
+| `menu` | N/A | object | Menu picker |