Skin and formula data

Derma's signature features read structured data you keep in Shopify: two metaobject definitions (Ingredient and Clinical study) and a set of product metafields in the derma namespace. Nothing here is required. Every feature hides itself cleanly when its data is missing, and in the theme editor a dashed note says what it needs.

The tables below say which feature reads each field.

Step 1: create the Ingredient definition

In Shopify admin go to Settings › Custom data › Metaobjects › Add definition. Name it Ingredient; its type must be exactly ingredient. Add these fields (the key is what the theme reads, so match it exactly):

Under Access, turn on Storefronts. Under Features, turn on Web pages and give it a URL handle, such as ingredient, so each entry gets its own page (/pages/ingredient/niacinamide) using Derma's metaobject/ingredient template. Then add entries in Content › Metaobjects › Ingredient.

Step 2: create the Clinical study definition

Add a second definition named Clinical study, type exactly clinical_study, with Storefronts access on:

Step 3: create the product metafields

Go to Settings › Custom data › Products › Add definition. For each one, set the namespace and key exactly as shown (type derma.formula in the "Namespace and key" field), choose the type, and turn on Storefronts access. For the fields marked "choices", use the Limit to preset choices validation so every product uses the same spelling; filters and the quiz match values exactly.

Variant metafields (Settings › Custom data › Variants):

Blog post metafields: derma.reviewed_by (single line text) and derma.reviewed_on (date) for the "Medically reviewed by" line (chapter 5).

Writing the values

• derma.inci: the full list in label order, separated by commas: Aqua, Niacinamide, Glycerin, Zinc PCA, …. Tokens that match a key active are highlighted; tokens that match an Ingredient entry link to it.
• derma.facts: one row per line as name, amount and daily value separated by |: Vitamin D3 (as cholecalciferol) | 25 µg | 125%. Leave the daily value empty to print "†". Start a line with ## for a sub-heading, or with - to indent it under the row above.
• derma.active_strengths: keep the order of derma.actives. An active without a strength shows a drop icon in place of the figure.

Step 4: add the Search & Discovery filters

Install Shopify's free Search & Discovery app. In Filters › Add filter, add these product metafield filters (the app lists a metafield once its definition exists with Storefronts access):

Collection and search pages then show them, and links can use them: the format is filter.p.m.<namespace>.<key>=<value>. Different filters combine with AND; repeating one filter's parameter combines its values with OR (?filter.p.m.derma.strength=Gentle&filter.p.m.derma.strength=Moderate). The skin quiz builds exactly these links.

While you're in the app, set up Product recommendations › Complementary products for your hero products. The Routine section's "Build from the product", the cart's "Complete your routine" and "Complementary products" recommendations use them.

Step 5: set up the skin quiz page

1. Online Store › Pages › Add page. Title it, for example, "Skin quiz". In Theme template, choose skin-quiz. Save.
2. Theme settings › Skin and formula › Skin quiz page: choose it. Every "Take the skin quiz" and "Change" link now goes there; with no page chosen those links are hidden.
3. Open the page in the theme editor. The Skin finder section comes with five Skin type answers, six Concern answers and three Reaction answers. Each Concern answer points at a collection by handle (breakouts, dark-spots, fine-lines, redness, dryness, dullness). Create those collections, or choose your own for each answer. Until then, the template's "Fallback collection" (All products) stands in, so the quiz works on a new store: it shows your full range and says that nothing is matched to that concern yet.
4. Check that each Skin type answer's "Filter value" matches the value on your products exactly (Oily, not oily).

How it works: question 1 filters by skin type, question 2 picks the collection the results come from, and question 3 filters by strength. The results show up to "Products to show" matches and a "See all" link to the filtered collection. If nothing matches, the quiz drops question 3's filter, then question 1's, and says so ("Nothing in Breakouts is marked for your sensitivity yet, so we've left that answer out."). The answers also go in the page address (#skin=oily,breakouts,often), so a result can be shared. Without JavaScript, the concern answers work as plain links to their collections.

Skin finder settings

Answer blocks:

• Skin type (up to 6): "Label", "Filter value" (the value as it's entered on your products), "Description", "Image", "Icon" (Drop, Sun, Leaf, Sparkle or Shield, shown when there's no image).
• Concern (up to 9): "Label", "Collection" (shoppers who pick this answer see this collection, filtered by their other answers), "Description", "Image" (uses the collection's image when empty).
• Reaction (up to 4): "Label", "Description", "Filter values" (separated by commas; products with any of them match; leave empty to show every strength). The defaults are Rarely (empty: any strength), Sometimes (Gentle, Moderate) and Often (Gentle).

The quiz isn't only for skin. The Bloom preset asks about skin type and then what the shopper is shopping for (Skin tint, Concealer, Blush…); Daily asks "How do you eat?" (filtering on derma.suitable_for) and a health goal. You can use tags instead of metafields with filter.p.tag.

The skin profile

With Theme settings › Skin and formula › "Remember skin profile" on, a finished quiz saves the answers on the shopper's device (browser storage, not their customer account) and says "Saved to your skin profile". Then:

• The header shows a chip with the profile, such as "oily, breakouts" (Header › "Show skin profile"); on phones it's a bar under the header.
• Suits your skin on the product page highlights the skin types and concerns that match, with "Matches your skin profile". Without a profile it reads "Not sure? Take the skin quiz" (when a quiz page is chosen).
• Collection pages offer "Filter for oily skin" in place of the quiz prompt, when the collection has that filter.
• "Change" goes back to the quiz page.

Step 6: set up the glossary and ingredient pages

1. Online Store › Pages › Add page, titled for example "Ingredients", with the theme template ingredients.
2. Theme settings › Skin and formula › Ingredient glossary page: choose it. The home page teaser's "Browse A to Z" link goes there.
3. Each Ingredient entry's own page uses the Ingredient section: image, name, also known as, category, typical strength, the long explainer, the concerns it's good for, and a grid of the entry's products (or a "See products with niacinamide" button that opens your catalogue filtered by the Key ingredient filter).

The full glossary shows an A to Z letter rail, a search field and concern chips that filter the cards, with entries grouped by letter. Glossary cards link to "4 products" when the entry's products field is filled, or to "See products" (the Key ingredient filter) when it isn't. Until the store has at least one Ingredient entry, glossary sections are hidden from shoppers and the editor shows a note.

The product page blocks that read this data

All four live in the Formula and use section (product pages only).

Formula: the strength card and formula notes, the key active cards (each a big percentage, name, also known as, summary and an "About niacinamide" link), and the full ingredient list with a search ("Check for an ingredient": "Glycerin is in this formula, 3rd of 14.") and a Copy list button.

How to use: "When" chips, a routine track with this product's step lit and a sentence such as "After cleansing and toning, before moisturiser.", Amount, How often, Pairs well with, Don't layer with, the directions, the patch test callout and the SPF reminder. Settings: "Label" (default "How to use"), "Heading" (default "Use it after cleansing, morning and night"), "Show routine track" (on), "Show patch test note" (on; uses derma.patch_test, or the theme setting). With no routine data it shows only the patch test note, and with that off, nothing. The patch test note alone doesn't make a band: a Formula and use band whose other blocks have nothing for this product isn't shown.

Clinical results: results from the product's derma.studies, with footnotes. Settings: "Label" (default "Clinical results"), "Heading" (default "What people saw"), "Show before and after" (off; needs both images and a caption on the study).

Supplement facts: chips for the daily amount, servings and how long a container lasts (when derma.amount and derma.serving_size both start with a number), the facts panel, then other ingredients, allergens, warnings and the supplement disclaimer from theme settings. Settings: "Title" (default "Supplement facts"; use the name your regulator requires, such as Nutrition information), "Daily value column" (default "% Daily value"; "%NRV" in the EU and Australia), "Footnote" (default "† Daily value not established."). Without derma.facts the block renders nothing, disclaimer included.

Details (spec table) can also go in this band for rows such as texture, size and where it's made.

Suits your skin sits in the main Product section and has no settings. It renders nothing for products without derma.skin_types or derma.concerns.

Known limits

• 50 items per loop. Shopify Liquid reads at most 50 items in a loop. The glossary page shows 50 entries per page and paginates past that; the glossary search and concern chips filter the entries on the current page. Ingredient-list links reach the first 50 Ingredient entries (key actives are always linked, through derma.actives).
• No reverse lookup. Liquid can't find "every product that contains this ingredient". Fill the entry's products field for a count and grid, or rely on the Key ingredient filter link.
• Search & Discovery limits. Filters don't show on collections with more than 5,000 products, so point quiz answers at smaller collections. Metafield list values are capped at 128 entries.
• Exact matching. Filter values match exactly. "Oily" on a product doesn't match an answer whose filter value is "oily skin". Preset choices on the definitions prevent drift.
• The profile lives on one device. It's stored in the browser, so it doesn't follow a shopper to another device and is cleared with their browser data.
• Accordion rows need connecting. The product template's metafield rows ship empty because a theme can't connect to metafields before your store defines them (chapter 6).