# Comflo Theme Developer Guide Theme API: 1 · Node.js 20+ · Updated 2026-10-12 This guide is designed for human developers and AI coding assistants. It documents the contracts enforced by the Comflo theme engine, CLI, store uploader and marketplace validator. ## Starter prompt for an AI coding assistant > Build a complete, responsive Comflo e-commerce theme using the attached developer guide. Follow the required folder structure, component contracts, and configuration schema. Do not reimplement products, cart, checkout, payments, or other core business logic. Focus on creating a unique, professional storefront UI/UX using Comflo's supported theme APIs and components. Ensure the theme passes the Comflo CLI validation process. ## Platform boundary **Comflo owns** products, collections, variants, inventory, carts, checkout, payments, customers, orders, shipping, tax and store settings. **A theme never:** - calls a payment gateway; - changes stock or creates orders; - stores customer credentials; - runs server code. **A theme owns presentation:** layouts, sections, blocks, typography, colours, product presentation, progressive enhancement and responsive behaviour. It consumes the drops and data attributes documented below. JavaScript may enhance the interface, but the Comflo runtime remains the source of truth for commerce actions. ## Required structure ~~~text config/theme.json config/settings_schema.json layout/theme.comflo templates/index.json templates/product.json templates/collection.json templates/page.json templates/search.json templates/404.json templates/header-group.json templates/footer-group.json sections/*.comflo blocks/*.comflo snippets/*.comflo assets/*.{css,js,svg,png,jpg,jpeg,webp,gif,ico,woff,woff2} locales/*.json ~~~ Only these folders are packaged. Limits: 1,000 files, 500 KB per file, 10 MB uncompressed theme, and a 10 MB ZIP. File names are lowercase letters, numbers, dots, underscores and hyphens. ## Manifest and settings ~~~json { "name": "My Theme", "version": "0.1.0", "api": 1, "author": "Studio name", "description": "A clear description of at least 20 characters." } ~~~ Raise the semantic version for every marketplace submission. `config/settings_schema.json` is a list of groups whose settings use supported types: text, textarea, richtext, inline_richtext, html, image, url, video_url, color, color_scheme, font, range, number, select, radio, checkbox, text_alignment, product, collection, link_list, header and paragraph. Every non-display setting needs a unique id. ## Layouts, sections and blocks - `layout/theme.comflo` is the HTML shell. It must output the requested template's content and include theme assets with the `asset_url`, `stylesheet_tag` and `script_tag` filters. - **JSON templates** (`templates/*.json`) contain an ordered map of sections. - **Sections** live in `sections/.comflo` and declare editor settings, allowed blocks and presets inside one `{% schema %}` JSON block. - **Theme blocks** live in `blocks/` and can nest up to four levels (section → block → block → block). - **Snippets** hold reusable markup. ~~~liquid {% render 'snippet-name' %} {% content_for 'blocks' %} {% content_for 'block', id: block.id %} ~~~ ## Storefront data contracts **Product** - `id`, `title`, `handle`, `url`, `created_at` - `description`: sanitised HTML - `price`, `compare_at_price`: LKR cents; `available` - `featured_image`, `images`: `[{src, alt}]` - `variants`: `[{id, title, price, available, options, option1, option2, option3, image, sku}]` (only variants on sale); `selected_or_first_available_variant` - Options: `options_with_values`: `[{name, position, values}]` (Size: S, M, L); `has_only_default_variant` when sold one way. A variant\'s `options` are its values in the same order. - Bundles: `is_bundle`, `bundle_size`, `flavour_options`: `[{id, title, image}]` - `collections` **Collection:** `id`, `title`, `handle`, `url`, `description`, `image`, `products`, `products_count`, `sort_by`. **Page:** `title`, `handle` and sanitised `content`. **Search:** `performed`, `terms`, `results`, `results_count`. **Also available everywhere:** `settings`, `shop`, `routes`, `request`, `linklists`, `collections`. Prices must use the `money` filter; images should use `image_url` and `image_srcset`. ~~~liquid {{ product.title }} {{ product.price | money }} {{ product.title }} ~~~ ## Cart and checkout integration Do not implement cart or checkout requests yourself. Use these stable hooks: - Cart trigger: `data-comflo-cart-open`; count target: `data-comflo-cart-count`. - Quick add: `data-comflo-add` plus `data-variant-id`. - Product form: `data-comflo-product-form`; a selected variant id; optional `data-buy-now`. - Bundles: `data-bundle-url`, `data-bundle-size`, `data-flavours`, and `data-flavour-slot`. - Lead forms: `data-comflo-lead-form` with `data-form-error` and `data-form-status`. The runtime owns storage, cart lines, checkout, COD, bank transfer, PayHere, Payments.lk and preview-mode mock responses. Always render unavailable variants and sold-out states accurately; never assume stock from price or option names. ## Collections, search and sorting **Required routes** ~~~text / /products/:handle /collections/:handle /collections/all /pages/:handle /search?q= 404 fallback (any other path) ~~~ **Collection sorting** (`?sort_by=`): `manual`, `created-descending`, `price-ascending`, `price-descending`, `title-ascending`. - Render links from drop `url` values; never build them by hand. - Search results are supplied by Comflo. A theme provides the form and the result presentation, not a separate search index. - Alternate templates are named `..json`, e.g. `product.special.json` or `collection.editorial.json`. ## Customers and accounts Theme API 1 does not expose customer authentication or account drops. - Do not create custom login, password, session or order-history logic. - Account components will arrive in a later theme API version, together with validator support. - Contact and proposal capture use the central lead-form hooks (`data-comflo-lead-form`). ## Responsive, accessible and secure UI - **Mobile-first:** start at 320 px; test mobile, tablet and desktop. - **Accessible:** semantic landmarks, visible focus, labelled controls, usable keyboard order, sufficient contrast, responsive images and reduced-motion fallbacks. - **Works without JavaScript:** core content stays usable without the theme's scripts. - **Not allowed:** `eval`, `new Function`, cookies, trackers or outbound data collection. - **Assets:** remote fonts only from Google Fonts; package every other asset locally. - Merchant rich text is sanitised by the engine. ## Develop, validate and package ~~~bash comflo theme init my-theme --from aurora --name "My Theme" cd my-theme comflo theme dev comflo theme validate comflo theme package ~~~ `comflo theme dev` previews at `http://localhost:9292` with demo products, variants, sold-out inventory, a bundle, collections, pages and search. Validation checks paths, bytes, manifest, required templates, JSON, schemas, references, Liquid compilation and a render of every page kind. `comflo theme package` runs validation first. ## Publish to the marketplace 1. Create a developer account and a theme listing, and confirm your email. 2. Submit a version in one of three ways: - **Dashboard:** upload the ZIP made by `comflo theme package`. - **GitHub:** connect a repository to the theme; each published release is submitted. - **CLI:** create a marketplace token on the dashboard, then run: ~~~bash comflo marketplace login --token comflo theme submit . --theme --notes "What changed" ~~~ **After submitting** - The first version and every major version go to staff review. - Minor and patch versions that pass the checks publish automatically. - Submitting a package identical to one already submitted (same checksum) changes nothing. ## Troubleshooting - **Missing required file:** compare your folder with Required structure. - **Unknown section or block:** add the matching file, or correct the `type`. - **Schema error:** keep exactly one valid JSON `{% schema %}` block, with unique setting ids. - **Render error:** go to the file and line the CLI prints, then open the failing page in `comflo theme dev` (it lists the pages it checks, e.g. `/products/ceylon-black-tea`). - **Cart does nothing:** check the exact `data-comflo-*` hook and that the variant id is valid. - **Marketplace rejection:** fix every reported problem and run `comflo theme validate` before resubmitting.