ZG Size & Fit APP

ZG Size & Fit — Merchant Guide

A practical walkthrough of every feature shipped in the current build, written for merchants setting the app up on their Shopify store.

App type: Embedded Shopify admin app + Theme App Extension
Storefront surface: App Proxy endpoint at /apps/size-chart/chart
Data: stored per shop in the app's own PostgreSQL database, with fast storefront shadow copies written to Shopify product metafields

1. Overview

The app lets you build, assign, and display size guides on product pages, plus an optional "Find my size" wizard that recommends a size based on the shopper's measurements.

Core capabilities:

Build size charts as a measurement table, a chart image, or a mix of both
Add fit metadata (fit type, stretch, fit notes, model size, care note)
Show a segmented fit indicator on the storefront
Offer a "Find my size" stepped wizard with your bands and inputs
Assign charts to products using a priority hierarchy (product → tag → type → category → collection → vendor → gender → region → global)
Display multiple charts as tabs (for example "Regular" vs "Oversized" of the same garment)
Let shoppers toggle between cm and inches on the storefront with their choice persisted
Check which chart would render for any product before publishing

2. Getting started

2.1 Install the app

Install the app from the Shopify App Store. After the OAuth handshake you land on the admin dashboard where you can create your first chart.

2.2 Add the theme blocks

There is one primary block in the theme app extension:

Block	What it does
Size Chart	Renders the Size & Fit trigger and, when enabled, a separate "Find my size" trigger beside it.

To add it, open your theme in the Shopify theme editor, navigate to any product page, and click Add block. Pick Size Chart, save, and preview.

The block enables itself automatically on product templates. The "Find my size" trigger remains hidden unless the matched chart has a configured calculator.

2.3 Create your first chart

In the admin app, click Create chart. Give it a title, pick a base unit (cm or in), and you are ready to fill in the details.

3. Creating a size chart

3.1 Chart formats

Every chart has a format that controls what the shopper sees:

Format	Uses
Table	A measurement table with headers and rows
Image	A chart image only (useful for brand-approved assets)
Mixed	Both an image at the top and a table below

You can switch formats at any time; the app only renders the pieces the format requires.

3.2 Units (cm or in)

Pick the base unit the chart is authored in. The storefront shows a cm/in toggle in the chart header, so shoppers can view the numbers in whichever system they prefer — the numbers are converted live, and the preference is remembered across pages and visits.

Tip: pick whichever unit you measure and source in. The conversion rounds to one decimal for inches and zero decimals for cm, so authoring in your native unit is slightly more precise.

3.3 Building the measurement table

The table editor supports:

Add row / Add column buttons to grow the table
Remove row / remove column icons on each header and leading cell
Autofill from a template dropdown with common presets:
- Tops product measurements for men, women, and unisex products
- Tops body measurements for men, women, and unisex products
- Bottoms product measurements for men, women, and unisex products
- Bottoms body measurements for men, women, and unisex products
- Blazers, jackets, T-shirts, dress shirts, dresses, and bikini charts
- Shoes for men and women
- Kids' apparel and simple alpha sizes

The new-chart starting template picker also includes image-based and mixed image + table chart formats. Selecting a table template replaces the existing headers and rows with preset values after a Shopify confirmation modal. Alpha-size apparel templates include XS by default, and the size calculator's default measurement bands also start with XS. You can then edit any cell, add rows, or remove sizes you do not sell. When a template is active, the editor shows a template badge; after table edits, the badge marks the template as edited.

Cells can contain ranges (80-84), single numbers (36.5), comparators (>40), or plain labels (XS, One size). The storefront conversion is numeric-only — non-numeric cells pass through unchanged.

3.4 Uploading a chart image

Under Chart image, use the file picker to upload a PNG, JPG, or WebP. The picker also lets you reuse images from your Shopify Files library. Uploaded images are served from Shopify's CDN.

3.5 Fit notes, stretch, model size, care

These are optional free-text and dropdown fields:

Fit notes — free text about how the garment fits (for example "Cropped length, true to size")
Stretch level — none / slight / medium / high
Model size — free text like "Model is 5'10" wearing size M"
Care note — free text care instructions

All of these render below the chart body on the storefront when present.

4. Fit indicator

The segmented fit indicator is a six-stop bar that shows where a garment sits on a tight-to-loose scale.

4.1 Fit types

Pick one of six fit types:

Key	Default marker position
slim	0%
fitted	20%
regular	40%
relaxed	60%
loose	80%
oversized	100%

Labels render under the bar, the active label sits above the marker.

4.2 Custom marker position

Each fit type has a default position, but you can override it with the Fit indicator % field (0–100). Useful for nudging off-center — for example a "Relaxed" shirt that runs slightly closer to "Regular" could be set to 50 instead of 60.

Leave blank to use the default position for the selected fit type.

5. Find my size (size calculator)

The size calculator powers a stepped "Find my size" wizard that recommends a size from the shopper's measurements.

5.1 Enabling it

Open the Size calculator section on the chart editor and tick Enabled. The wizard only appears on the storefront when the chart has a calculator enabled with at least one input and one band.

5.2 Inputs

Pick which inputs to ask for:

chest — circumference at the fullest part of the chest
waist — natural waistline
hips — fullest part of the hips
height — standing height without shoes
weight — in kilograms (unit-invariant)
inseam — inside leg, for trousers
age_group — context only (not used for matching in v1)
gender — context only (not used for matching in v1)

Tip: fewer inputs usually convert better. Chest/waist/hips is a reliable baseline for tops; waist/hips/inseam for bottoms.

5.3 Fit preference step

Toggle Ask fit preference to add a step where the shopper picks slim / regular / oversized. When two sizes both match the entered measurements, the preference breaks the tie:

slim — picks the smaller size
regular — picks the central match
oversized — picks the larger size

5.4 Size bands

Bands map size labels (S, M, L) to measurement ranges (for example, chest 88–94 cm). You have two ways to fill them in:

Generate from your table — the editor can populate bands by parsing your measurement rows. Ranges like 88-94 become { min: 88, max: 94 }. Works best when every row has clear numeric ranges.
Manual — type min/max for each size, row by row.

Bands are stored in the chart's base unit. If the shopper has toggled the storefront to the other unit, the wizard labels the inputs in the shopper's unit and converts values back before matching — the merchant never has to duplicate data.

5.5 Recommendation output

The wizard shows:

The recommended size
A confidence label (Great fit / Good fit / Closest match / Approximate)
A short reason explaining the match

Confidence drops as the shopper's measurements land further from any band's range.

6. Assigning charts to products

6.1 Rule hierarchy

A chart can have one or more assignment rules. When a product page loads, the resolver walks all rules on every active chart and picks the chart with the highest-priority match.

Priority from most specific to most general:

#	Rule type	What it matches
1	product	A specific product (paste GID or handle, or use the product picker)
2	tag	Any product with this tag
3	product_type	Shopify product type (for example "T-Shirt")
4	category	Shopify Standard Product Taxonomy — category ID or name
5	collection	Specific collection (GID or handle)
6	vendor	Shopify vendor field
7	gender	Product metafield `zg_size_chart.gender` or a `gender:...` tag
8	region	Product metafield `zg_size_chart.region`, or the shop region param
99	global	Matches every product — used as the fallback

Lower number wins. If two active charts match at the same rule priority, the merchant-controlled Chart priority on the chart itself breaks the tie (lower wins, default 100). If still tied, the most recently updated chart wins.

6.2 Adding a rule

On the chart editor, scroll to Assignment rules and pick a rule type. Depending on the type, the second field either:

Opens the Shopify Resource Picker (for product and collection rules) — pick one with the native product chooser
Accepts free text (for tag, product type, vendor, gender, region, category name/ID)
Accepts no value (for global — matches everything)

Click Add rule to save it. You can add multiple rules to the same chart.

6.3 Setting a global default

The simplest possible setup: create one chart and mark it as the default in Settings → Default chart. Every product falls through to that chart unless a more specific rule on another chart wins.

6.4 Gender and region metafields

For gender/region rules, set either:

A product metafield (namespace zg_size_chart, key gender or region), or
A tag in the form gender:women or gender:men

Region rules also honour an optional region query param on the app proxy request (useful if your theme passes one).

7. Multi-chart display (tabs)

When a product needs more than one guide — for example Regular / Petite / Tall, Full length / Cropped / Shorts, or a Length Guide alongside the main Size Guide — the app can render matching charts side-by-side as tabs.

7.1 When tabs appear

Tabs appear when two or more matching active charts each carry a Storefront tab label. The label is the text that appears on the tab itself, for example "Regular", "Petite", "Tall", or "Length Guide".

If only one of the matching charts has a label, or none of them do, the storefront falls back to single-chart display — the highest-priority one wins.

This opt-in design means merchants who don't intend multi-chart mode never see tabs accidentally.

7.2 Chart priority

When multiple charts match the same product and tab mode doesn't apply, Chart priority decides the winner. Lower wins, default is 100.

Typical pattern: set Regular at priority 100 (the default) and Oversized at priority 90, so Oversized wins the tiebreak if only one can render.

7.3 Multiple matching charts

If two active charts have rules targeting the same product, tag, or collection, the rule builder shows an Other charts also match these rules banner listing the matching charts and their priority/tab labels. Each rule row also has an Also matches N badge.

Multiple matches are allowed. The banner is there so you can consciously decide to use tabs, re-order priority, or remove a rule.

7.4 Wizard + tabs

The Find my size wizard uses the first (highest priority) chart's bands, even in tabs mode. This avoids opening the wizard multiple times.

8. Storefront unit switching

Every rendered chart shows a cm / in pill toggle in the header.

Initial state matches the chart's base unit (set by the merchant)
Clicking switches every table cell, the unit hint, and the wizard's input labels
The shopper's choice is saved in localStorage and remembered across products and visits

Numeric tokens are converted (ranges, decimals, comparators all work). Non-numeric cells like "XS" or "One size" pass through untouched.

9. Settings

Settings are shop-wide.

Setting	What it does
Default chart	The chart that shows when no rule matches. Feeds the same priority 99 fallback.
Button label	The label on the theme block trigger ("Size Guide" by default).
Display mode	How the chart appears on click: modal (popup over the page), drawer (slide-in from the side), or inline (expands in place below the trigger).

10. Theme blocks

10.1 Size Chart block

The primary block. Renders the trigger button and on click loads the chart HTML via the app proxy.

Configurable in the theme editor:

Show Find my size toggle
Size chart icon and Find my size icon
Alignment (left / center / right)
Display mode (modal / drawer / inline — overrides the global setting for this block)
Color, radius, and font settings for matching the merchant theme

10.2 Find my size trigger

The Size Chart block can render a second "Find my size" trigger next to the chart trigger. Useful when a merchant wants the wizard close to the size selector without making shoppers open the full chart first. Clicking the button fetches the chart payload, reads the calculator config, and opens the wizard directly.

Configurable:

Show Find my size toggle
Find my size icon
Alignment follows the block alignment setting

The trigger does not show itself if the matched chart has no calculator configured.

11. Testing your setup

11.1 Check a product preview

On the Charts list page there's a Check a product panel. Click Pick a product, choose any product from your catalogue, and the app runs the same resolver the storefront uses and tells you:

The chart (or charts) that would render
The mode (single or tabs)
The priority and storefront tab label of each

Use this after a rule change to confirm the right chart wins.

11.2 Storefront preview

After adding the theme block, preview the product page in the Shopify theme editor or a private browser tab. The block fetches /apps/size-chart/chart?productId=<gid> and inlines the HTML — no JavaScript errors should appear in the browser console.

If the block is hidden, the resolver returned no chart and no default is set. Add a rule or pick a default chart in Settings.

12. Managing charts

On the Charts list page, each chart has:

Edit — open the editor
Duplicate — copy everything except rules into a new chart
Archive / Restore — an archived chart is preserved but never rendered on the storefront (stops matching rules too)
Delete — permanently removes the chart and its rules (confirmation required)

13. Troubleshooting

The "Size Guide" button doesn't appear on the product page

Check the theme editor: the Size Chart block must be added to the product template.
If the block is added but invisible, the resolver returned no match and no default. Add a matching rule or set a default chart.

The wrong chart is showing

Open the Check a product panel on the charts list and pick the product. The summary will name the winning chart.
Inspect rules on competing charts. A more-specific rule beats a less-specific one. Same rule type? Lower Chart priority wins.

Tabs aren't appearing when I expected them

Both charts must be active, both must match the product via rules, and both must have a non-empty Storefront tab label.
Confirm with the Check a product panel — the mode will read "Tabs mode — N charts".

The cm/in toggle looks stuck

The preference is stored in the browser's localStorage. Clearing site data or switching browsers resets it to the chart's base unit.

Find my size says "No size bands configured"

Open the chart editor, go to the Size calculator section, and either generate bands from the table or add them manually.

Chart image doesn't load

Confirm the image was uploaded successfully via the file picker (the preview appears after upload).
If the URL is correct but fails, check the file in Shopify Content → Files and reselect it from the chart editor.

14. Glossary

Chart — a single size guide with a title, format, and optional fit/calculator metadata
Rule — the condition that binds a chart to one or more products (product, tag, collection, etc.)
Priority (rule) — built-in ordering of rule types, 1 being the most specific
Priority (chart) — merchant-controlled tiebreak between charts matching the same product
Storefront tab label — the short label shown on a tab when multiple charts render for one product
App proxy — the storefront-facing endpoint at /apps/size-chart/chart that returns chart HTML
Theme app extension — the package of theme blocks the merchant installs via the theme editor

Appendix A — Example setups

A.1 Single global chart

Create one chart, pick your format, fill it in.
Go to Settings → Default chart and pick it.
Add the Size Chart block to the product template.

Every product shows the same chart.

A.2 Women's vs Men's

Create a "Women's sizing" chart and a "Men's sizing" chart.
On each, add a rule: gender = women (or men).
Tag your products with gender:women or gender:men, or set the zg_size_chart.gender metafield on each product.

The right chart renders per product automatically.

A.3 Regular vs Oversized tabs

Duplicate an existing chart; rename the copy "Oversized".
On both charts, fill in the Storefront tab label ("Regular" and "Oversized").
Add the same rule to both — for example a shared tag "oversized-tee-collection".
The storefront shows both as tabs.

A.4 One chart per collection

Create a chart per collection (for example "T-shirts", "Dresses", "Jeans").
On each, add a collection rule pointing to the Shopify collection.
The resolver picks the right chart based on the product's collections.

15. Import & export

CSV/Excel import and export are Pro features. Template downloads remain available from the chart list and import page so merchants can prepare data before upgrading.

15.1 Importing a chart

From the chart list, open More actions → Import from file.
Download the CSV template or Excel template to see the expected layout. The template ships pre-filled with a women's tops example, XS-XXL placeholder rows, and Find-my-size calculator metadata, so the format is self-documenting.
Edit the template with your chart data and save it.
Back in the import page, choose your file and click Import. The page shows upload, read, validation, and chart creation progress before sending you to the imported chart.

What gets imported: title, unit, format, fit type, fit notes, stretch, model size, care note, priority, storefront tab label, image URL, and the measurement table (headers + rows). If the calculator metadata is present, the importer also creates the calculator and derives its measurement bands from columns such as Bust/Chest, Waist, Hips, Height, Weight, and Inseam. What doesn't: assignment rules and per-locale translations — those are best done in the editor after the chart exists.

The importer always creates a new chart rather than overwriting an existing one. That removes any risk of a mis-mapped header silently rewriting good data. If you want to update an existing chart, edit in-app or delete + re-import.

15.2 Exporting a chart

Export requires Pro.

Open a chart in the editor.
Click Export in the page header → choose Export CSV or Export Excel.
The file downloads with the chart's title as its filename.

Exports cover the same field set as imports, including calculator setup where present. Assignment rules and translations stay in the admin.

16. How-to-measure illustrations

When the Find-my-size wizard asks shoppers for measurements, each input shows a small How to measure disclosure underneath. Clicking it expands a panel with a labelled illustration and a one-line technique note ("Wrap the tape around the fullest part of your chest…").

16.1 What ships out of the box

Six bundled SVG illustrations cover chest, waist, hips, height, weight, and inseam. They're included in the theme app extension and translate automatically — instruction copy is provided in all 9 supported languages (English, French, German, Spanish, Italian, Dutch, Brazilian Portuguese, Japanese, Arabic). No setup needed for most merchants.

16.2 Overriding with your own image

If you have brand-specific measurement diagrams:

Open the chart editor.
Scroll to the Size calculator section. Inside, expand How-to-measure illustrations (it starts collapsed).
For each measurement you want to override, click Upload and pick an image from your Shopify Files library.
Save the chart.

The wizard prefers your override and falls back to the bundled SVG where you don't override. Remove clears an override and reverts to the default.

The override list only shows measurements you've enabled on the calculator's Shopper inputs above — fewer rows when you're using fewer measurements.

17. Analytics

The Analytics page (in the app's left nav) shows engagement on the size guide and Find-my-size wizard. All data is anonymous aggregates — no shopper IDs, IP addresses, or PII.

17.1 Headline metrics

Four top-line counters across the available plan window. Free shows 7 days. Pro can switch between 7, 30, and 90 days:

Size chart opens — modal/drawer/inline views
Find my size starts — wizard launches
Find my size completes — wizard completions, with completion rate
Recommended size selected — shoppers who clicked "Select this size & continue" after receiving a recommendation

17.2 Per-chart breakdown

A table with one row per chart showing opens, wizard starts, completes, size-select clicks, and completion rate. Useful for spotting charts that get heavy traffic but low calculator engagement (often a sign of confusing labels) or high starts but low completes (often a sign of too many inputs or unclear measurements).

17.3 Recommended-size distribution

A breakdown of which sizes the wizard recommended most often. Useful when planning inventory or spotting bias in the size bands (e.g. if the algorithm always recommends "M", your bands may be too generous on either side).

17.4 The recent-views badge on the chart list

Each chart row on the list shows a recent-views badge so you can see at a glance which charts customers actually use, without opening the analytics page. Free uses 7 days; Pro uses 30 days for the chart-list glance.

18. Translations

The app supports two layers of translation:

Wizard chrome / chart UI labels ("Find my size", "Step 1 of 4", "Chest", "How to measure", etc.) — bundled in the theme app extension. Ships in 9 languages.
Your chart content (title, column headers, fit notes, care note, model-is-wearing text, tab labels) — managed via Shopify's Translate & Adapt app.

18.1 Layer 1: chrome (no setup)

If your storefront is multi-locale, the wizard and chart UI render in the shopper's language automatically. No work for you.

18.2 Layer 2: chart content via Translate & Adapt

The first time you save a chart, the app mirrors its translatable fields into a Shopify metaobject called Size chart translations. Translate & Adapt picks these up automatically.

To translate a chart:

Save the chart at least once. The "Translations" section on the chart editor will show an Edit translations in Shopify button.
Click it. You'll land directly on the Translate & Adapt editor for that chart, with your shop's first alternate language pre-selected.
Translate each field. Translate & Adapt's auto-translate works here — the same auto-translate you use for product descriptions.
Save in T&A. Your storefront picks up the translations within ~30 seconds (the proxy caches briefly).

Which fields are translatable:

Chart title
Column headers
Fit notes
Care / shrinkage note
Model is wearing
Tab label (only relevant in multi-chart "tabs" mode)

Which aren't:

Stretch level and fit type are dropdown selections — their displayed labels ("Slim", "Medium stretch", etc.) are part of the wizard chrome layer above.
Calculator data (band ranges, brand offsets) is numeric or fixed-list.
Size names in the table rows (S, M, L) — usually don't translate, but if you need to, edit them in the merchant editor and they'll mirror through to the metafield.

18.3 If you don't have Translate & Adapt

It's a free Shopify app and ships with most stores. If yours doesn't have it, install it from the Shopify App Store. The integration uses Shopify's standard metaobject translation API, so any compatible translation tool will work — T&A is just the official one.