Darkroom documentation

Everything in Darkroom is set in the Shopify theme editor. You will not need to touch code, and you do not need any apps to run the storefront. This page follows the order you will actually work in: install, replace the demo, set your brand, then tune each section.

Install the theme

1. Add Darkroom from the Shopify Theme Store. It lands in Online Store → Themes under Theme library. If you received a .zip file instead, use Add theme → Upload zip file on the same screen.
2. Click Customize to open the theme editor. The homepage loads with demo content so you can see how each section is meant to be used.
3. Work through the setup below while the theme is still unpublished. Your live store keeps running on your current theme the whole time.
4. When you are happy, go back to Themes and click Publish on Darkroom.

Theme settings and section content belong to the theme, not to your store. Nothing you configured on a previous theme carries over, and nothing you do here changes your products, collections or pages.

First setup

Do these five things first. They affect every page at once.

1. Logo. In the editor, open the Header section (top of the section list) and set Logo image, then Logo width. A transparent PNG or SVG works best. With no logo uploaded, the header falls back to your store name as text.
2. Favicon. Theme settings → Brand → Favicon. Square, at least 32 by 32 pixels.
3. Social sharing image. Theme settings → Brand → Social sharing image, at 1200 by 630 pixels. It is used when a page that has no image of its own is shared.
4. Colors and fonts. See Color schemes and Typography.
5. Menus. Menus are store data, not theme data. Build them in Online Store → Navigation, then point the header and footer at them. See Header, menus and footer.

Demo content and how to replace it

The demo is a worked example of a skincare brand, not content you should keep. Every headline, image, ingredient and testimonial in it is a placeholder.

• Images. Every image sits behind a picker in the section or block that uses it. Click the section in the editor, click the image, then Change to upload your own. The demo photography ships with the theme so the layout is visible; you are responsible for the rights to any image you publish, so replace all of it before going live.
• Text. Headings, eyebrows and body copy are plain fields on each section. Empty a field to hide that piece of the layout rather than leaving placeholder words in place.
• Products. The demo points at whatever products exist in your store. Open Featured collection and pick a real collection of yours; do the same for any Linked product in the ingredient story.
• Links. Every button has its own link field. Buttons that still point at a demo URL are the most common thing merchants forget, so click through the homepage once in the preview before publishing.
• Sections you do not want. Use the eye icon in the section list to hide a section, or the three-dot menu to remove it. Drag to reorder. Nothing in the homepage order is fixed.

Theme settings

Customize → Theme settings (the gear icon at the bottom of the left sidebar). These apply to the whole store.

• Brand. Favicon and social sharing image.
• Typography. Fonts and type scale. See Typography.
• Colors. The four color schemes. See Color schemes.
• Social media. Instagram, TikTok, Facebook, YouTube, X (Twitter), Pinterest and LinkedIn URLs. Paste the full address including https://. Only the ones you fill in appear in the footer, and only when the footer’s Show social icons is on.
• Layout. Page width (Standard or Wide), Page margin, Space between sections, Card corner radius and Button & input radius. Sections sit flush against each other by default; raise Space between sections if you want visible gaps. Set both radius controls to 0 for a hard editorial look, or raise them for something softer.

Color schemes

Darkroom ships four schemes. Every section has its own Color scheme setting, which is how the homepage alternates between dark and light without any custom code. In the editor the schemes are listed as Scheme 1 to Scheme 4:

To rebrand, edit the swatches instead of adding new schemes. Open Theme settings → Colors, pick a scheme and set:

• Background and Background gradient (the gradient overrides the solid color when set, so leave it empty for a flat surface).
• Text, Accent (links, active states, the highlighted word in headings) and Secondary (supporting details).
• Primary button background and label, Secondary button label, and Border for hairlines and dividers.

To run the whole store light, set every section to Scheme 2 (Paper) or Scheme 4 (Sage). To run it dark, use Scheme 1 (Ink) or Scheme 3 (Ember). Mixing per section is what gives the demo its rhythm.

Typography

Theme settings → Typography. Fonts come from Shopify’s font library, which is a Shopify requirement; Darkroom defaults to Archivo for headings and DM Sans for body.

• Heading font and Body font. Pick any two from the library. A high-contrast display face for headings plus a plain grotesque for body reads closest to the demo.
• Base body size. 14 to 20 pixels, default 16. Everything else scales from it.
• Heading scale. 100 to 150 percent. Raise it for a louder editorial cover, lower it if your headlines are long.
• Heading letter-spacing. Negative by default, which tightens large headings. Set it back toward 0 if your chosen font already sits tight.
• Label (eyebrow) letter-spacing. Controls the wide-tracked uppercase labels above each section heading. Reduce it if you use a condensed font.

Motion

The hero and every narrative section has its own Motion setting with three options:

• Off. Content appears with no animation.
• Subtle. Short, small movements. The safe choice for a busy page.
• Cinematic. The demo setting. Longer reveals with more travel.

Motion is per section, so you can keep the hero cinematic and turn everything below it down. All motion respects a visitor’s operating system reduce motion setting automatically, with no setting for you to configure. If animations are not playing for you, check that setting on your own machine before assuming something is broken.

Homepage sections

Customize → the Home page template. The demo order is hero, manifesto, ingredient story, routine, before and after, featured collection, testimonials and press, UGC, founder note. Each one can be reordered, hidden, removed or added again from Add section. Every section starts with a Color scheme picker.

Several sections have an Index number field (01, 02, 03). It prints a small numeral beside the heading so the page reads as a sequence. Leave it empty to hide it, or renumber after you reorder sections.

Hero

The cover. One full-bleed image with a headline over it. Settings are grouped: Media (Image, Image alt text, Image caption), Masthead (Wordmark, Kicker), Content (Eyebrow, Heading, Highlighted word, Body text), Buttons, and Layout & motion.

• Heading. A multi-line field, and the line breaks you type are kept. That is how the demo art-directs the headline into three short lines.
• Highlighted word. Type one word that also appears in the heading and it is picked out in the accent color. It must match the spelling in the heading exactly, including case.
• Image alt text. Describe the image for screen readers and for anyone whose image fails to load. Do not leave it empty on the hero.
• Buttons. A primary button plus an optional secondary one (Show secondary button). A button with an empty label is hidden.
• Section height. Medium, Large or Full screen. Full screen is the most dramatic and pushes everything else below the fold, which is a trade you should make deliberately.
• Meta item blocks. Add short strings such as “1% Bakuchiol” or “Fragrance free”. They render as a small strip under the hero content.

Manifesto

One large brand statement. Fill Eyebrow, Statement (line breaks are kept, as in the hero), Highlighted word and Supporting text, then choose Alignment: Left or Center. Keep the statement to a sentence or two; this section is a pause, not a paragraph.

Ingredient story

An ingredient to benefit timeline. Set the Eyebrow, Heading and Intro paragraph, then choose Layout (Alternating timeline or Stacked) and Image shape (Portrait, Square or Landscape).

Add an Ingredient block per item: Image, Image alt text, Ingredient name, Benefit, Detail (a short line such as a concentration or origin), plus an optional Linked product and Link label so the ingredient sells the product it belongs to. Three to five ingredients reads best. There is a Show default intro when empty checkbox; turn it off if you want no intro at all.

Routine

A step-by-step ritual. Set Eyebrow, Heading and Intro, then add a Step block for each step with a Time tag (AM, PM, “2 minutes”), a Step name and a Description. Use two of these sections if you want a separate morning and evening routine.

Before / after

A results comparison. Upload the Before image and After image, and set Before label, After label plus optional captions such as “Day 0” and “Week 8”. Shoot both frames in the same light, at the same distance, with the same crop. Anything else looks like a trick and costs you trust. Keep the claim you can actually support.

Featured collection

The product showcase. Pick a Collection, then set Products to show, Columns on desktop and Image shape (Portrait, Square or Adapt to image). Under Card: Show vendor, Show quick add (adds to cart without leaving the page) and Show “view all” link with its own label. Products come from the collection in its own sort order, which you set on the collection in the Shopify admin.

Testimonials and press

Social proof plus an “as seen in” strip. Add a Testimonial block per quote (Quote, Author, Detail) and a Press logo block per publication. A press block shows the uploaded Logo, or falls back to the Name as text if you have no logo file, so you can ship the strip before you have the assets. Press strip label renames the row.

UGC / Instagram

A community grid. Set Handle and Handle link, then add a Post block per image with an optional Link to the original post. Images are uploaded, not pulled from Instagram, so nothing breaks when a social API changes and the grid costs you no page weight. Update it when you have new content worth showing.

Founder note

The human close. Add a Portrait, the Note, an optional Signature image (a transparent PNG of a handwritten signature), plus Name and Role. Write it in first person and keep it under about 80 words.

The product page

Customize → template picker at the top of the editor → Products → Default product. The page is built from blocks you can reorder and toggle, so you can put the conversion pieces exactly where your buyer needs them. The demo order is: vendor, title, rating, price, variant picker, quantity, buy buttons, trust badges, description, ingredients, how to use, before and after, shipping, reviews, share.

The section itself (click Product above the blocks) holds Enable image zoom, Image fit (Contain or Cover) and Show sticky add-to-cart bar on mobile.

Variant and shade picker

The Variant picker block renders swatch chips instead of plain buttons when an option reads as a color. It does that when the option is named Color, Colour, Shade, Tone or Hue, or when its values carry Shopify swatch data. Everything else (Size, Volume, Scent) renders as pills. Swatch shape is Round or Square.

Where the chip color comes from, in order:

1. A Shopify swatch metaobject on the option value (a color or an uploaded image). This is the accurate route: Content → Metaobjects → Color swatch in your admin.
2. A built-in map of common cosmetic shade names (Ivory, Porcelain, Sand, Honey, Amber, Caramel, Bronze, Espresso and similar), so a shade selector works before you configure anything.
3. The value name read as a CSS color, then a neutral chip if none of the above match.

Ingredients

The Ingredients block has an Eyebrow, Heading, Intro, up to five key actives, and a full list. Each active takes a name, what it does and concentration or origin. Leave an active’s name empty to hide that row, so a product with two hero ingredients simply shows two. Put the complete INCI list in Ingredient list under your own List label. Keep every claim to what you can substantiate.

How to use

Up to five steps, each with a title, description and an icon (Number only, Droplet, Leaf, Sun, Moon, Sparkle or Heart). Leave a step title empty to hide it. Steps that name the amount and the moment (“two to three drops, on damp skin”) cut returns and support email.

Before and after

A draggable comparison on the product page. Set the Heading, both images with their alt text, the Before label and After label, and Start position, which is where the handle sits when the page loads. You can add this block twice, for example for two skin concerns.

Rating and reviews

The Rating block near the title shows a star summary read from your product review metafields, which means you need a reviews app (Shopify Product Reviews or a compatible one) to be collecting them. Until real reviews exist it shows an honest prompt, which you can turn off with Show a prompt when there are no reviews yet. Link to reviews anchor defaults to #reviews and jumps to the Reviews block lower down. If your app provides its own app block, add it directly after the Reviews block to render individual reviews.

Trust badges

Up to five short signals, each an icon (Cruelty-free, Vegan / botanical, Tested / safe, Clean, Science-backed, Hydrating, Kind) and a label you write. Leave a label empty to hide that badge. Only claim what your product actually meets; badge claims are regulated in most markets.

Shipping and returns

This is a Collapsible row block, so you can add as many as you need (returns, subscription terms, a size guide). Each one takes a Heading and either Content typed in place or Content from page, which pulls the body of an existing Shopify page so you maintain the policy once. Open by default controls whether it starts expanded.

Complete the routine

The Complete the routine section below the product details is the cross-sell. With Use Shopify product recommendations on, it shows the complementary products you set up in the free Shopify Search & Discovery app (Apps → Search & Discovery → Recommendations). Set a Fallback collection so the row is never empty while you configure them. Products to show, Columns on desktop and Image shape control the layout.

Sticky buy bar

On mobile, a bar with the product, price and add-to-cart follows the visitor down the page so the buy action is never more than a thumb away. Turn it off in the Product section under Buy buttons → Show sticky add-to-cart bar on mobile. Leave it on unless it clashes with something else fixed to the bottom of your screen.

Header, menus and footer

Menus themselves are built in Online Store → Navigation, not in the theme editor. Create the menu first, then select it here.

• Announcement bar. At the top of the section list. Add a Message block per line (Text and optional Link). Turn Scroll messages (marquee) off for a static bar, and use Marquee duration to slow the scroll down. Two or three short messages is the limit before it turns into noise.
• Header. Logo image and Logo width, Menu (defaults to your main menu), Enable sticky header, Show predictive search (the results that appear as a visitor types) and a Customer account menu. Dropdowns come from nesting items inside your menu in Navigation.
• Cart drawer. The cart slides in from the side instead of taking the visitor to a separate page. It only carries a color scheme; there is nothing to configure.
• Footer. Add a Menu block per column (each with its own Heading and menu), one Brand text block (heading, image and rich text) and one Newsletter block, which signs visitors up to your Shopify customer list. Toggles: Show social icons (from Theme settings → Social media), Show payment icons, Show language selector, Show country and currency selector, plus a Copyright note. The language and currency selectors only appear once you have added extra languages or markets in Shopify.

Other templates

Switch templates from the picker at the top of the theme editor. Every template below is styled and editable.

• Collection. Show breadcrumb, Show collection description, Show collection image banner, Enable filtering and Enable sorting, plus Products per page, Columns on desktop, Columns on mobile (1 or 2), Image shape, Show vendor and Show quick add. Which filters appear is controlled by Shopify, in the free Search & Discovery app under Filters.
• Collections list. The grid of all collections, with an eyebrow, heading, description, column count, image shape and Show product count.
• Search. Results for products, pages and articles, matching the collection grid.
• Cart. The full cart page, used when a visitor opens the cart URL directly.
• Page. The default layout for About, FAQ and policy pages.
• Contact. A separate template with a working form. Assign it in Online Store → Pages → your contact page → Theme template → contact. Submissions arrive at your store’s customer contact email, set in Shopify Settings → Store details.
• 404 and password. Both styled. The password page is what visitors see while your store is password protected, so set its content before a launch.

You can also add a Custom section to most templates for a block of your own text over an optional background image.

Blog and articles

Posts are written in Online Store → Blog posts. The theme controls how they look.

• Blog posts (the listing). Eyebrow (Journal by default), Heading and Description; Feature the first post gives the newest post a full-width card; Show topic filter builds a filter row from your post tags; plus Posts per page, Columns on desktop, Image shape, Show excerpt, Show author and Show estimated read time.
• Blog post (the article). Toggles for Show breadcrumb, Show featured image, Show author, Show estimated read time, Show topic tags, Show share links and Show related posts with a count. Related posts are drawn from the same blog.

Excerpts come from the post’s own excerpt field in the admin. If you leave it empty, the card falls back to the start of the post, which is rarely the sentence you would have chosen.

Translations and RTL

Every piece of text the theme itself provides (buttons, labels, empty states, form errors) is translatable. Edit it in Online Store → Themes → the three-dot menu → Edit default theme content, or use Shopify’s free Translate & Adapt app to manage full languages. Text you typed into sections is translated in Translate & Adapt alongside your products and pages.

Right-to-left languages (Arabic, Hebrew, Farsi, Urdu and others) mirror the entire layout automatically when the visitor is on that language. There is no setting to turn on, and no separate RTL theme to install.

Performance and accessibility

Darkroom is built to stay light, and these are the parts a theme can actually control. The motion runs on CSS scroll-driven animation, so there is no JavaScript framework anywhere in the theme. The build gate fails if any single page ships more than 16 KB of minified theme JavaScript, which means the theme cannot quietly get heavier between updates. Every image the theme renders carries explicit width and height, so the page does not jump around while it loads.

What we deliberately do not do is quote you a load time or a Core Web Vitals verdict. Core Web Vitals is measured on your real visitors over 28 days; it is a property of your store, not of a theme, and a number from our demo would tell you nothing useful about yours. Measure your own before and after you switch. Four things move that number more than the theme does:

• Size your images. Upload at roughly twice the size they display, not at 6000 pixels wide. The hero image is usually the single biggest factor in how fast your homepage feels.
• Be selective with apps. Every app that injects a script runs on every page. Sliders, popups and chat widgets are the usual culprits behind a score dropping after launch.
• Keep the homepage focused. Nine sections tell a complete story. Twenty do not tell it better.
• Write alt text on every image you upload. It is required for screen reader users and it is the field most often left empty.

The theme is keyboard operable, has visible focus states, meets AA contrast in its shipped color schemes, and honours reduce-motion. The two ways to undo that are custom colors that fail contrast and images without alt text, both of which are in your hands.

Troubleshooting

Shade swatches show as plain buttons

The option is not being read as a color. Rename the product option to Color, Colour, Shade, Tone or Hue in the product admin, or attach Shopify swatch metaobjects to its values. See Variant and shade picker.

No stars on my product page

The Rating and Reviews blocks read review metafields, so they stay empty until a reviews app has collected real reviews. Install a review app, or hide the blocks until you have reviews to show.

No filters on my collection page

Enable filtering only tells the theme to render whatever filters Shopify provides. Add them in the free Search & Discovery app under Filters.

Complete the routine is empty

Complementary products are configured per product in Search & Discovery. Until they are, set a Fallback collection on the section so the row still shows something.

My contact page has no form

The page is still on the default page template. Assign the contact template in Online Store → Pages → your page → Theme template.

An ingredient, step or badge is missing

Those blocks hide any row whose name, title or label is empty. Fill the name field and the row comes back.

Nothing animates

Check the section’s Motion setting, then check whether reduce motion is on in your own system settings. Darkroom respects it, so the page will be still by design.

Two sections run into each other

They share a color scheme. Give one of them a different Color scheme, or raise Space between sections in Theme settings → Layout.

The highlighted word is not highlighted

Highlighted word has to match the word in the heading exactly, including capitals and any punctuation attached to it.

My settings disappeared

Check which theme you are editing. Settings and section content belong to a single theme, so a duplicate or an updated copy starts from its own saved state. Duplicate a theme before any large change and you always have a way back.

Get support

If your question is not answered here, read the FAQ next; it covers licensing, apps, speed and language support. For anything else, use Darkroom support. Include your store URL, your theme version and a screenshot, and we reply within 2 business days.