Theme-derived Bundle

Merchants can let the system derive a color + icon bundle from their published Shopify theme, snapshot-locked to the widget. This makes the widget visually fuse with the native theme — no manual color tuning needed.

Derivation flow

In the Widget creation wizard Step 3 “Color scheme”, if the current theme is recognized as supported, a “From your theme” group appears:

1. System reads the published theme (GraphQL OnlineStoreTheme.files)
2. Parses settings_data.json to extract color / icon settings
3. Derives 2-4 candidate bundles (different intensity / style variants)
4. Merchant picks one → projected onto widget config (hex flat values)
5. Bundle structure also persisted to widgets.editor_state_json.style.bundle
   (so reopening the editor restores the picker selection)

Derivation is lazy on wizard open — no caching (single GraphQL call 100-300ms is acceptable).

Per-axis snapshot contract

Different axes behave differently when the merchant later switches themes:

Axis	Creation	After theme switch	Merchant override
color	bundle → resolved hex into widget config	❌ Unchanged (snapshot)	Override goes into snapshot
icon	bundle → iconStyle / iconWeight	❌ Unchanged (snapshot)	Override goes into snapshot
typography	Default fontFamily: "inherit", no derived value written	✅ Follows new theme (CSS inherit)	Explicit override goes into snapshot
shape	Uses template default	❌ Unchanged (template doesn’t follow theme)	Override goes into snapshot

Key principle: snapshot only locks values the merchant actively chose. CSS inheritance / template defaults are pass-through mechanisms, not part of the snapshot.

Three support detection gates

Not all themes can derive bundles. The system runs three sequential checks; any failure makes the entire group disappear:

1. OS 2.0 structure check — does settings_data.json conform to OS 2.0 schema?
2. Required token check — do color tokens cover all 8 required positions (surface / surfaceMuted / text / textMuted / textInverse / accent / accentMuted / border)?
3. Vintage exclusion — vintage themes (e.g. Brooklyn) are explicitly unsupported

Unsupported themes don’t show “From your theme” in the wizard, but the 5 internal presets remain available.

Theme switch doesn’t affect existing widgets

After creating a widget, switching the Shopify theme later does not affect existing widgets:

• color + icon are snapshot — locked at creation time
• typography follows the new theme (CSS inherit)
• shape follows template default (doesn’t follow theme)

After switching themes, reopening the editor lets the wizard derive the new theme’s bundles for “switching” — but this is an explicit choice, not an automatic overwrite.

Related concepts

• Theme-derived bundles and the 5 internal presets are the same Layer 1 object kind, just different sources. Projection logic is identical. See Multi-axis Token Bundle
• Merchant operation flow: Import theme colors