Build themes without rebuilding commerce.

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.

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.

{
  "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.

• 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/<type>.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.

{% render 'snippet-name' %}
{% content_for 'blocks' %}
{% content_for 'block', id: block.id %}

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.

<a href="{{ product.url }}">{{ product.title }}</a>
<span>{{ product.price | money }}</span>
<img src="{{ product.featured_image | image_url: width: 800 }}" alt="{{ product.title }}">

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.

Required routes

/
/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 <kind>.<suffix>.json, e.g. product.special.json or collection.editorial.json.

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).

• 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.

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.

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:

comflo marketplace login --token <cfmk_…>
comflo theme submit . --theme <slug> --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.

• 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.