Colour-theme packs

Bottle shop themes are data packages, not executable website code. Bottle renders their settings with its own components and supplies the shop’s products, prices and shopping behaviour.

This guide describes the simpler .bottle-theme.json format, which uses Yard or Flame. For a completely independent shopfront using HTML, CSS and JavaScript in a ZIP, read Build a custom shop template.

Create one UTF-8 JSON file named your-design.bottle-theme.json. Version 1 supports a base design, global styling choices, optional homepage sections and optional bundled pictures. Custom shop pages remain editable in the normal shop editor.

Start with a working file

Download the starter pack from Shop → Design → Look → Browse templates, or use the example below. Every field is case-sensitive. Unknown fields are rejected, including unknown fields inside sections and link targets.

{
  "format": "bottle-theme",
  "schemaVersion": 1,
  "name": "My Bottle shop",
  "description": "A clean shop with warm colours.",
  "template": "yard",
  "theme": {
    "primary": "#1F3A5F",
    "accent": "#E4572E",
    "background": "#FAF7F2",
    "fontPair": "modern",
    "radius": 12
  },
  "design": {
    "spacing": "balanced",
    "container": "wide",
    "headingScale": "balanced",
    "productCards": "outlined"
  },
  "assets": []
}

Supported styling

Field	Allowed values
template	yard, flame
theme.primary, theme.accent, theme.background	Six-digit hex colours, such as #155EEF
theme.fontPair	classic, modern, friendly, editorial
theme.radius	Whole numbers from 0 to 28; Flame caps rounded corners at 4
design.spacing	compact, balanced, relaxed
design.container	narrow, wide, full
design.headingScale	compact, balanced, bold
design.productCards	plain, outlined, raised

Styling applies to public shop content and product displays. Authentication, basket and checkout forms retain Bottle’s supported layout and behaviour. The business’s logo and browser icon are preserved; set those in the shop editor.

Homepage sections

Leave out homeSections to preserve the shop’s current homepage. Include it only when the design should replace that layout. The user must confirm the replacement before applying the theme.

For example, add this field to the starter pack:

"homeSections": [
  { "id": "main-banner", "type": "banners" },
  { "id": "assurances", "type": "strip" },
  { "id": "products", "type": "products" },
  { "id": "about", "type": "about" },
  { "id": "delivery", "type": "delivery" },
  { "id": "questions", "type": "faq" }
]

Each section needs a unique id: 1–40 lower-case letters, digits or hyphens. There can be at most 30 sections. banners, strip, categories, delivery, about, faq and contact appear at most once. Existing words and banner content are reused.

Section type	Additional settings
banners, strip, categories, delivery, about, faq, contact	No additional settings required
products	Optional settings: source (featured, all, category, kind), count (1–12), sort, heading, seeAll; category or kind when needed
text	heading, html
textPicture	heading, html, imageKey, imageAlt, side (left, right)
picture	imageKey, imageAlt, caption, shape (natural, wide)
callToAction	heading, body, buttonLabel, colour (primary, accent, plain), optional target
blogPosts	heading, count (1–6)
spacer	size (small, medium, large), line (boolean)

Product kind values are cylinder, accessory, appliance, fuel, consumable and other. Product sort values are featured, price-low, price-high, name and newest. A category is its public shop slug, never a database ID.

You can omit a product section’s settings to use the shop’s current choices. If you include it, provide all five fields: source, count, sort, heading and seeAll. Use an empty heading to keep the shop’s default heading. Add category for a category source or kind for a product-kind source.

For example:

{
  "id": "shop-products",
  "type": "products",
  "settings": {
    "source": "all",
    "count": 8,
    "sort": "featured",
    "heading": "Our products",
    "seeAll": true
  }
}

Leave out width to use the full available width. On a phone, sections stack vertically. The validator rejects a width that the section cannot use.

Section type	Supported width values
text, picture	full, threeQuarters, twoThirds, half, third, quarter
textPicture	full, threeQuarters, twoThirds, half
callToAction	full, twoThirds, half, third
All other sections	full only

Theme button targets can use built-in pages, public category slugs or HTTPS links:

{ "kind": "builtin", "page": "products" }

Built-in page names are home, products, delivery, about, help, contact, terms, privacy and blog.

{ "kind": "category", "slug": "bottled-gas" }

{ "kind": "url", "url": "https://example.com/" }

Do not embed product, customer or custom-page IDs. Text sections support limited rich HTML—paragraphs, headings, lists and emphasis—which Bottle sanitises. Script tags, event handlers, embedded forms and styles are not rendered. Whole HTML websites and CSS files are not theme packs.

Bundled pictures

Use JPEG, PNG or WebP. SVG, scripts and external image URLs are not accepted. An asset has a unique local name and a base64 data URL:

"assets": [
  { "name": "delivery-picture", "dataUrl": "data:image/jpeg;base64,REPLACE_WITH_REAL_BASE64" }
]

Reference it from a picture or text-and-picture section using "imageKey": "asset:delivery-picture". Include meaningful imageAlt text. Do not put S3 keys or another business’s asset IDs in a pack.

A pack can contain up to eight pictures, each about 1 MB or less. The whole file must be no larger than 7 MB, and non-picture configuration is limited to 256 KB. Bottle also limits image dimensions and processing time. Optimise large photos before packaging them.

Each picture is limited to four million pixels. Picture bytes must match their JPEG, PNG or WebP label. Bottle re-encodes public pictures and removes their metadata; the original theme package remains private.

Each business may upload up to 50 MB in a rolling 24-hour period. Accepted upload attempts count even if picture processing fails. Deleting a saved theme does not reset this allowance. The saved-theme allowance is separate: up to 20 revisions and 40 MB of source packages.

Checking your file

Save the JSON as a .bottle-theme.json file. Pictures belong in the assets array using the format above; reference each one with its matching asset: handle.

Upload the file through Shop → Design → Look → Browse templates. Bottle checks it before offering Use in draft. If a check fails, correct the file and upload it again. You do not need Bottle’s source code or internal tools.

Prompt for Claude or ChatGPT

Give your AI this guide and the starter pack, then ask:

Create a Bottle theme pack using schemaVersion 1. Return valid JSON, not HTML, CSS, JavaScript or a React project. Use only the fields and section types in this guide. Preserve existing homepage content unless I ask for a new homepage. Do not invent product IDs, image URLs, credentials or unsupported styling values. Use the shop’s product sections for live prices and products. Describe any changes that require a bundled picture. Validate the file against the Bottle theme format before calling it complete.

You can use your own AI account; Bottle does not need access to it. Do not put API keys, passwords, customer data or other secrets in a theme file.

Previewing and publishing

Applying a theme changes the draft only. Check it in the shop preview, then select Publish to make it visible to shoppers. Saved themes let you restore an earlier design to the draft, review it and publish it again.

The uploaded file is private to your business. JSON colour-theme packs do not run custom JavaScript; Bottle displays their approved colours and sections.