# LaysanX Theme Designer Guide

LaysanX custom themes are normal HTML, CSS, and JavaScript packages with LaysanX template placeholders for dynamic data. Designers do not need to write .NET code.

## Quick Start

1. Download or clone the TheLiaison reference theme.
2. Edit normal HTML, CSS, and JavaScript.
3. Keep placeholders and loops.
4. Zip the theme folder.
5. Upload it from Client Admin theme customization.
6. Preview it.
7. Publish it.

Reference theme download:

`/downloads/theliaison-reference-theme.zip`

Reference theme Git repository:

`https://github.com/laysanx/theliaison-reference-theme`

Clone command:

```bash
git clone https://github.com/laysanx/theliaison-reference-theme.git
```

## Package Structure

```txt
theme.zip
  theme.json
  README.md
  templates/
    home.html
    page.html
    contact.html
    service-list.html
    service-detail.html
    product-list.html
    product-detail.html
    project-list.html
    project-detail.html
    blog-list.html
    blog-detail.html
    news-list.html
    news-detail.html
    notification-list.html
    event-list.html
    event-detail.html
    gallery.html
    faq-list.html
    pricing-list.html
    job-list.html
    job-detail.html
    team-list.html
    custom-section-detail.html
  sections/
    header.html
    footer.html
    hero.html
    services.html
    products.html
    projects.html
    blogs.html
    news.html
    events.html
    gallery.html
    pricing.html
    jobs.html
    faqs.html
    notifications.html
    team.html
    testimonials.html
    clients.html
    partners.html
    marketing.html
    auxiliaries.html
    trust-badges.html
    detail-faqs.html
    product-gallery.html
    related-services.html
    related-products.html
    related-projects.html
    logos.html
    contact-form.html
  assets/
    css/style.css
    js/main.js
    images/placeholder.svg
```

## Allowed Files

- `.html`
- `.css`
- `.js`
- `.json`
- `.md`
- images such as `.jpg`, `.jpeg`, `.png`, `.webp`, `.svg`, `.gif`
- fonts such as `.woff`, `.woff2`, `.ttf`

## Not Allowed

- `.cshtml`, `.cs`, `.dll`, `.exe`, `.php`, `.py`, `.sh`
- server-side scripts
- files outside the uploaded theme folder
- hidden executable payloads

## Common Placeholders

```liquid
{{ site.name }}
{{ site.logo }}
{{ site.email }}
{{ site.phone }}
{{ site.address }}
{{ page.title }}
{{ page.subheading }}
{{ page.content }}
{{ seo.title }}
{{ seo.description }}
{{ seo.keywords }}
{{ settings.primary_color }}
{{ 'assets/css/style.css' | asset_url }}
```

## Common Loops

```liquid
{% for item in menus.header %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

{% for service in services limit: section_controls.services.count %}
  <article>
    <img src="{{ service.image }}" alt="{{ service.title }}">
    <h3>{{ service.title }}</h3>
    <p>{{ service.short_description }}</p>
    <a href="{{ service.url }}">View More</a>
  </article>
{% endfor %}

{% for item in news limit: section_controls.news.count %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

{% for plan in pricing_plans limit: section_controls.pricing_plans.count %}
  <h3>{{ plan.title }}</h3>
  <strong>{{ plan.primary_price_formatted | default: plan.price_formatted | default: plan.price }}</strong>
  <a href="{{ plan.checkout_url | default: plan.checkoutUrl | default: plan.direct_checkout_url | default: plan.directCheckoutUrl }}">
    {{ plan.cta_text | default: 'Buy Now' }}
  </a>
{% endfor %}
```

Other list objects available to designers: `products`, `projects`, `blogs`, `events`, `notifications`, `gallery`, `faqs`, `jobs`, `team`, `testimonials`, `clients`, and `partners`.

## Ecommerce, Currency, And Pricing Placeholders

Uploaded themes receive storefront ecommerce context when commerce is enabled:

```liquid
{{ ecommerce.enabled }}
{{ ecommerce.cart_count }}
{{ ecommerce.urls.cart }}
{{ ecommerce.urls.checkout }}
{{ ecommerce.urls.orders }}
{{ ecommerce.urls.returns }}
{{ ecommerce.urls.account }}
{{ ecommerce.urls.login }}
{{ ecommerce.urls.wishlist }}
```

Currency context:

```liquid
{{ currency.code }}
{{ currency.symbol }}
{{ currency.switch_url }}

{% for item in currencies %}
  <option value="{{ item.code }}" {% if currency.code == item.code %}selected{% endif %}>{{ item.symbol }} {{ item.code }}</option>
{% endfor %}
```

Header currency selector example:

```liquid
{% if currencies.size > 0 %}
  <form class="currency-switcher" method="post" action="{{ currency.switch_url | default: '/currency' }}">
    <input type="hidden" name="returnUrl" value="{{ routes.current | default: routes.home | default: '/' }}">
    <select name="currencyCode" onchange="this.form.submit()" aria-label="Currency">
      {% for item in currencies %}
        <option value="{{ item.code }}" {% if currency.code == item.code %}selected{% endif %}>{{ item.symbol }} {{ item.code }}</option>
      {% endfor %}
    </select>
  </form>
{% endif %}
```

Product prices should prefer formatted symbol-first fields:

```liquid
{{ product.primary_price_formatted | default: product.selling_price_formatted | default: product.price_formatted | default: product.price }}
{{ product.compare_at_price_formatted | default: product.compare_at_price }}
```

Pricing plans also expose formatted prices and direct checkout:

```liquid
{{ plan.primary_price_formatted | default: plan.selling_price_formatted | default: plan.price_formatted | default: plan.price }}
{{ plan.checkout_url | default: plan.checkoutUrl | default: plan.direct_checkout_url | default: plan.directCheckoutUrl }}
{{ plan.cart_line_type | default: plan.cartLineType }}
```

For product cards:

```liquid
{% if ecommerce.enabled %}
  {% if product.has_variants %}
    <a href="{{ product.url }}">Choose Options</a>
  {% else %}
    <form method="post" action="{{ ecommerce.urls.cart }}?handler=Add">
      <input type="hidden" name="productId" value="{{ product.id }}">
      <input type="hidden" name="quantity" value="1">
      <button type="submit">Add to Cart</button>
    </form>
  {% endif %}
{% endif %}
```

## Product Detail Expectations

- Product gallery should include the main image, gallery images, and variant images.
- Variant selection should switch the main gallery image instead of showing a separate small image near quantity.
- Wishlist actions should use the runtime customer wishlist route and return to the current page.
- Keep quantity, add-to-cart, and wishlist controls compact on mobile and desktop.

## AI Website Builder Themes

AI Website Builder-generated uploaded theme ZIPs now preserve the exact copied sample theme templates, CSS, JavaScript, and image assets. Generated fallback files only fill missing templates. Designers can therefore treat `sample-projects/*-theme` as the canonical design source for AI theme output.

## Dynamic Forms

Do not hard-code contact form fields. Render the assigned form:

```liquid
{% render 'sections/contact-form.html', form: forms.contact %}
```

The platform controls required fields, file uploads, captcha, and button CTA text.

## Responsive Rules

- Design for mobile, tablet, and desktop.
- Do not allow horizontal scrolling.
- Keep buttons at 10px border radius unless the brand requires less.
- Service cards should include image, title, short description, and View More.
- Menus with more than 10 child items may use two columns, but must stay inside the viewport.

## Upload Flow

When the custom theme upload feature is enabled:

1. Open Client Admin.
2. Go to Themes.
3. Upload ZIP.
4. Validate package.
5. Preview theme.
6. Publish theme.

Publishing should not require an app restart because theme assets and templates are runtime files.