Theme playbook

Anatomy

Six words that describe the whole site, and the question that wastes the most time: where does a given piece of text actually live?

What the site is made of

Level	What it is	Example here
Theme	The whole design. One is live; others are drafts.	dev-leo-v1
Layout	The frame every page sits in — header, footer, fonts.	Main, password, gift card
Template	The recipe for one kind of page.	Home, Product, Collection
Section	A horizontal band on a page.	Hero slider, Trust row
Block	One repeating item inside a band.	A slide, a tile, a question
Setting	A single field you can type in.	A heading, a link, a colour

Where a given string actually lives

This is the question that wastes the most time. A piece of text on the site is in exactly one of four places, and only the first three are in this theme at all.

Theme settings — affects every page. Colours, fonts, the cart style. Rare.
Section settings — affects one band on one page. A section heading, a background image, a toggle.
Blocks — one of several repeating items. A hero slide, a footer link, a FAQ question. If there is more than one of a thing, it is a block.
Store content — not in the theme. Product names, prices, descriptions, images, and page body text live in Products and Pages. Editing the theme will never change them, and swapping themes will never lose them.

Rule of thumb. If it would still be true on a completely different design — a price, a product name, a policy — it is store content. If it only makes sense on this design, it is a theme setting.

Page map

Every surface on the store and the bands it is built from, top to bottom.

Every surface

Bands are listed top to bottom, as they appear. The header and footer are on every page and are edited once, not per page.

Page	Bands, in order
Every page	Announcement marquee, Site header … Site footer
Home	Hero slider, Intro + tiles, Trust row, Product grid, Feature split (flagship), Feature split (story), Quote grid, Newsletter
Product	Breadcrumbs, Product main, Bought together, Product reviews
Collection	Collection hero, Collection listing
Our story	Page intro, Media band, Feature split, Trust row, Text columns, CTA panel
FAQ	Page intro, Anchor chips, six FAQ groups, CTA panel
Reviews	Page intro, Video wall, Review wall, CTA panel
Routine finder	Guided finder (the quiz)
Contact	Contact split
Shipping / Returns / RMA / Privacy / Terms	Doc layout
Journal	Page intro, Blog grid
Cart	Cart items, Cart footer
Search · Account · 404	One band each
Password gate	Password gate — its own layout, seen before login

Making a change

The four-step loop, and how to undo a publish in thirty seconds.

The loop

Duplicate first. Always. Themes → the live theme → Duplicate, named with today's date. This is the undo button, and it takes ten seconds.
Edit the duplicate, not the live one. Open the customizer on the copy.
Check it at phone width before anything else. Most breakage shows up narrow, not wide.
Publish the copy when it is right. The old theme stays in the list as the way back.

If something goes wrong after publishing, publish yesterday's duplicate. That is a thirty-second fix and it is why step one exists.

Adding and reordering

To add a repeating item — a slide, a tile, a footer link, a FAQ question — select its band and use Add block. There is no cap.
To reorder, drag in the sidebar. Order on screen follows order in the list.
To remove, delete the block. To hide temporarily, use the eye icon instead so the content is still there.
New blocks arrive with placeholder text like "Headline for this slide". That is deliberate — it is obviously not real copy, so it cannot ship by accident unnoticed.

Section catalogue

What each band is for, and the one thing about it most likely to catch you out.

What each band is for, and its one gotcha

Band	For	Watch out
Announcement marquee	The scrolling strip at the very top.	The list is rendered twice so the loop is seamless. You still only edit it once.
Site header	Logo, nav, concern links, mobile menu.	Every link shows in both the desktop bar and the phone menu. Edit once, appears twice.
Hero slider	The big rotating images on the home page.	Adding a slide adds its dot automatically. Autoplay speed is a section setting.
Intro + tiles	Headline, buttons and the four category tiles.	Buttons and tiles are both blocks in one list. The grid is four wide — a fifth tile starts a new row.
Trust row	The four short promises.	Columns follow the number of items, up to four.
Product grid	Best sellers.	Pick a product and the card fills itself. The text fields are overrides — leave them blank to follow the product.
Feature split	Image beside copy. Used for the flagship and the story.	Paragraphs, chips and buttons are all blocks. Give a button a product and it becomes a real add-to-cart.
Quote grid / Review wall	Customer quotes.	Each quote has a Mark as sample toggle. Placeholder quotes must carry it.
Product reviews	Rating summary and quotes on the product page.	The 5–1 star bars are percentages you type; they are not calculated.
Bought together	Cross-sell under the product.	Driven by the product's own cross-sell data, not by this band.
Collection listing	The product grid and its filters.	A filter's key must match what the products carry, or it will match nothing.
Guided finder	The routine finder quiz.	Rules are checked top to bottom and the first match wins. Put specific rules above general ones.
FAQ group	One accordion. The FAQ page has six.	Each group is a separate band with its own questions.
Doc layout	Policy and returns pages.	The side nav links are blocks, shared across those pages — edit them on each.
Password gate	What everyone sees while the store is locked.	It has its own layout. Check it logged out, in a private window.
Site footer	Logo, blurb, socials, three link columns.	Each column holds its own links as nested blocks.

Images

What to upload, how big, in what format, and what to write in the alt field.

Sizes

Where	Shape	Upload at least
Hero slide	Fills the screen, crops both ways	2400 × 1600
Category tile	Tall, 3:4	1200 × 1600
Feature split	Square or 4:5	1600 × 1600
Product card	Square	1200 × 1200
Logo	Any, SVG preferred	—

Upload larger than you need, never smaller. The store makes the smaller versions itself. It cannot invent detail that was not there, and an undersized hero looks soft on a laptop.

Format, weight, alt text

JPG for photographs, PNG only for cut-outs that need a transparent background, SVG for the logo.
Keep files under about 500KB. A 5MB hero is the single easiest way to make the site feel slow on a phone.
Alt text describes the picture to someone who cannot see it. "John DeBerry, founder" — not "image1" and not a list of keywords. Decorative images can be left blank.

What not to do

Short, and every item is here because it has gone wrong somewhere before.

Do not edit the live theme directly. Duplicate, edit, publish.
Do not invent reviews, ratings or star counts. If a quote is not from a real customer it must carry the sample marker, or come off the site.
Do not make medical claims. These are cosmetics. Nothing treats, heals or cures.
Do not paste styled text from Word or Google Docs. It carries hidden formatting that fights the design. Paste as plain text.
Do not type your own colours or font sizes into a text field. Use the pickers; the design system keeps everything consistent.
Do not delete a band because it looks empty in the editor — some only fill in once there is content behind them.
Do not rename a product's URL handle casually. Links elsewhere on the site point at it.
Do not remove the password gate until launch day is agreed. It is the only thing keeping the store private.

Before you publish

Nine checks. They take about five minutes and catch nearly everything.

Before you publish

You duplicated the live theme first, named with today's date.
You looked at the changed pages on a phone, not only a laptop.
Nothing scrolls sideways on the phone.
No placeholder text is left — search the page for "Headline", "Eyebrow", "Lorem".
Every new image has alt text, and none is over about 500KB.
Every button you added goes somewhere. Click each one.
Any new quote is either real or marked as a sample.
You added an item to the cart and the drawer opened correctly.
If you touched the header or footer, you checked a second page too — they are on all of them.

When to call a developer

Where the line is, and what to send so the answer comes back first time.

Call a developer when

You need a new kind of band that does not exist in the list.
Something is broken on one screen size only, and it is not content you can fix.
A change needs to apply to every product or every page at once.
You want to add an app that renders on the storefront.
Anything to do with checkout, payment or shipping logic.
The site is slow and it is not an oversized image.

What to send

A good report takes two minutes and saves an hour of back-and-forth.

The link to the exact page.
A screenshot, with the problem visible.
Phone or computer, and which browser.
What you expected versus what happened.
Whether it is on the live theme or a draft, and the theme's name.

If you have just published and something is wrong, do not wait for a reply. Publish yesterday's duplicate to put the site back, then report it.

Cart