---
title: "Change a section"
space: "Commera"
url: "https://docs.bwh.tech/commera/build-a-section-theme/change-a-section"
updated: "2026-11-07"
---

Change the hero for Diwali, give it a Background setting, and set the Diwali colours and fonts.

By the end, the hero says something about Diwali, the merchant can pick its background, and the whole store has a deep red button and a serif heading.

## Before you start

Finish [Get the starter theme](/commera/build-a-section-theme/get-the-starter-theme).

Run the commands on this page from your app folder, `apps/acme_themes`, with `bench start` running.

## Change the words

The hero is two files in `apps/acme_themes/acme_themes/themes/diwali/sections/`:

- `hero.html` is the page. It prints `{{ section.settings.heading }}` where the heading goes.
- `hero.json` lists the settings, and the `default` text for each.

1. Open `hero.json`. Change the `default` of the four text settings:

   ```json
   { "id": "badge", "type": "text", "label": "Badge", "default": "Diwali 2026" },
   { "id": "heading", "type": "text", "label": "Heading", "default": "Light up the festival in something new." },
   {
   	"id": "text",
   	"type": "textarea",
   	"label": "Text",
   	"default": "Silk, cotton and zari for every evening of the festival."
   },
   ```

   and the button label further down:

   ```json
   { "id": "primary_label", "type": "text", "label": "Button label", "default": "Shop the festive edit" },
   ```

2. Add your photos. This guide uses `hero.webp` here and `suit.webp` on the next page. Any portrait photos work. Copy them into your theme's images folder:

   ```bash
   cp hero.webp suit.webp acme_themes/public/themes/diwali/images/
   ```

   The home page layout, `themes/diwali/layouts/index.json`, says which photo each slide shows. Commera Starter has three slides. Keep one, and point it at your photo:

   ```json
   {
   	"id": "hero",
   	"type": "hero",
   	"hidden": false,
   	"settings": { "background": "warm" },
   	"blocks": [
   		{ "id": "slide-1", "type": "slide", "settings": { "image": "images/hero.webp", "alt": "A model in a floral dress against a yellow wall" } }
   	]
   }
   ```

   `images/hero.webp` is a path inside `public/themes/diwali/`. The `background` line is for the next step.

## Add a Background setting

You want the merchant to pick the hero's background. A merchant cannot write CSS, so you give them a short list.

1. In `hero.json`, add a `select` setting. Put it after `text`:

   ```json
   {
   	"id": "background",
   	"type": "select",
   	"label": "Background",
   	"options": ["plain", "warm", "blush"],
   	"default": "warm"
   },
   ```

   The editor shows it as a drop-down called **Background** with Plain, Warm and Blush.

2. In `hero.html`, turn each option into a Tailwind class, and put the class on the outer tag. Add this line at the top:

   ```jinja
   {% set backgrounds = {"plain": "bg-surface-base", "warm": "bg-surface-amber-3", "blush": "bg-surface-red-2"} %}
   ```

   and add the class to the `<section>` tag:

   ```jinja
   <section x-data="hero({{ slides | length }})" class="{{ backgrounds[section.settings.background] }} grid items-center gap-10 px-5 pb-20 pt-4 md:grid-cols-2 md:px-12">
   ```

   The class names are written out in full on purpose. Tailwind finds them by reading the file as text.

3. Rebuild the CSS. `bg-surface-amber-3` is a new class, so the stylesheet does not have it yet. Check:

   ```bash
   grep -o "\.bg-surface-amber-3{" acme_themes/public/themes/diwali/tailwind.output.css | wc -l
   ```

   ```
   0
   ```

   Build, and check again:

   ```bash
   npm run build:diwali
   grep -o "\.bg-surface-amber-3{" acme_themes/public/themes/diwali/tailwind.output.css | wc -l
   ```

   ```
   1
   ```

:::caution[Forget the rebuild and the colour is missing]
If you skip `npm run build:diwali`, the new class is not in the stylesheet. The page loads with no error, and the hero has no background.
:::

## Set the Diwali colours and fonts

The colours and fonts of the whole store are not in a section. They live in the theme's settings, the **Diwali Settings** doctype that the command made.

On the **Style** tab of that doctype, every field becomes a CSS variable on the page. A field called `brand_color` becomes `--theme-brand-color`. The starter's templates already use these four:

| Field | Label in the editor | Used for |
| --- | --- | --- |
| `brand_color` | Brand Colour | Main buttons and the cart count |
| `brand_text_color` | Text on Brand Colour | Text on those buttons |
| `font` | Font | All text. A Google Fonts name. |
| `heading_font` | Heading Font | Headings. A Google Fonts name. |

You want these to be right on day one, and to come with the app when you move it. So set a `default` in the doctype file, instead of typing them into a form.

1. Open `apps/acme_themes/acme_themes/acme_themes/doctype/diwali_settings/diwali_settings.json`. Add a `default` to each of the four fields:

   ```json
   {
    "fieldname": "brand_color",
    "fieldtype": "Color",
    "label": "Brand Colour",
    "default": "#9a1b2f"
   },
   {
    "fieldname": "brand_text_color",
    "fieldtype": "Color",
    "label": "Text on Brand Colour",
    "default": "#fff7e6"
   },
   ```

   ```json
   {
    "fieldname": "font",
    "fieldtype": "Data",
    "label": "Font",
    "default": "Poppins"
   },
   {
    "fieldname": "heading_font",
    "fieldtype": "Data",
    "label": "Heading Font",
    "default": "Playfair Display"
   }
   ```

   Each field keeps its other keys. Only the `default` line is new.

2. Run migrate, so the site reads the new defaults:

   ```bash
   bench --site dev.localhost migrate
   ```

3. Check that the variables are on the page:

   ```bash
   curl -s http://127.0.0.1:8000/en | grep -o -- '--theme-[a-z-]*: [^;]*'
   ```

   ```
   --theme-brand-color: #9a1b2f
   --theme-brand-text-color: #fff7e6
   --theme-font: Poppins
   --theme-heading-font: Playfair Display
   ```

Reload the store. The hero is the Diwali hero.

<img src="/files/commera-01-what-you-will-build-after-07cec249.png" alt="The Diwali hero: warm yellow background, serif heading, a deep red button" width="944">

A default shows until the merchant saves a value of their own. They can change all four in the editor, under **Theme settings**, on the **Style** part of the panel.

<img src="/files/commera-03-change-a-section-theme-settings-style-5a21d45b.png" alt="The Theme settings panel, Style part, with Brand Colour, Text on Brand Colour, Font and Heading Font filled in" width="320">

:::note[Fonts are Google Fonts names]
Type a family name exactly as Google Fonts writes it, for example `Playfair Display`.
:::

## Next steps

- [Add sections](/commera/build-a-section-theme/add-sections)
- [Section reference](/commera/build-a-section-theme/section-reference)
