Global settings

Overview

There are two surfaces. The primary one is the in-sidebar Global Settings panel (settings/GlobalSettingsPanel.tsx) — when no element is selected in the right sidebar, this panel replaces the "No element selected" empty state with a category list. Eight categories drill in inline within the sidebar (Branding, Theme Colour, Typography, Fonts, Color, Button, Product, Global SEO); two "wide" categories (Global Code, Breakpoints) instead pop a floating SettingsExpandedPanel to the left so the Monaco code editor and breakpoint cards have enough room.

The legacy surface is the Global Settings modal (settings/Settings.tsx) — a full Antd Modal with tabs for the same categories. Both share the same draft / save plumbing via useEditorSettingsStore and useSaveSettings, so the data model and validation are identical.

All persisted settings are typed by the EditorSettings interface in common/components/commmerce-editor/types/settings.types.ts. The breakpoint sub-shape lives in types/breakpoint.types.ts. Every default value documented below traces back to a DEFAULT_* constant in those two files — if a field shows — in the Default column, the source did not seed it and the renderer falls back to its own internal default.

How it works

The committed settings payload lives in useEditorSettingsStore.settings (typed as EditorSettings). Each sub-section maintains its own local draft and emits changes via onSettingsChange; GlobalSettingsPanel wires those into setDraftField('branding' | 'themeColour' | 'typography' | ...) on the store. While a draft is non-empty, hasUnsavedDraft() returns true and a sticky Save / Discard footer appears at the bottom of the panel.

Save flow (GlobalSettingsPanel.handleSave / Settings.handleSave): it is intentionally server-first. useSaveSettings inspects the URL params and dispatches to the Dev Portal settings save flow or the Store Editor settings save flow depending on the active project. On success, importSettings(draft) commits the payload into useEditorSettingsStore and runs syncSettingsToWindow() as a side effect so web components and CSS variables pick up the new values immediately. Then importBreakpointSettings(draft.breakpoints) mirrors breakpoint changes into useBreakpointStore and copyBreakpointStyles(from, to) seeds any newly added breakpoints with styles copied from an existing one. Finally, saveThemeBreakpoints(breakpointStorageKey) persists the breakpoint config to local storage as a hot-restart fallback, and clearDraft() wipes the draft.

Persisted vs transient. Two distinct stores back this UI. Persisted theme settings (EditorSettings) ship to the server with every version and live forever — this is what end users see on the live store. Transient editor UI state lives in useCommmerceEditorSetupStore (store/useCommmerceEditorSetupStore.ts), persisted to sessionStorage under the key commmerce-editor-setup-store, with a partialize that explicitly drops isInitializing, initializingMessage, placementMode and quickEditElementId so a stale rehydrate never leaves the canvas in crosshair mode or with a panel pinned to an element that no longer exists.

UI state for the panel itself (which section is drilled in, which sub-view of Fonts / Colors / Buttons is active) lives in a separate transient store useGlobalSettingsUIStore (settings/useGlobalSettingsUIStore.ts) so the right sidebar can swap between Element Inspector and Global Settings without losing or leaking drilled-in state. resetUIState() is called whenever the sidebar swaps to the Element Inspector.

Key features

• In-sidebar panel (GlobalSettingsPanel.tsx) — renders inline when no element is selected; eight categories drill in within the 320px sidebar, two open a floating expanded panel to the left.
• Legacy modal (Settings.tsx) — same tabs in an Antd Modal with width: min(60rem, 90vw); destroyOnHidden so each open starts with a fresh draft from committed settings.
• Draft / commit semantics — every sub-section maintains a local draft (seeded from storeSettings.*) and emits via onSettingsChange. Nothing applies to the canvas or to web components until Save.
• Server-first save — the API call happens before the store mutation, so a failed save leaves the runtime untouched and the user can retry without local drift.
• Project-aware save dispatch — useSaveSettings reads URL params (app_id / app_version_code vs store_theme_id / store_theme_version_code) and picks the right endpoint with no prop drilling.
• Reusable slot registries — Fonts, Color and Button each expose a list / add / edit sub-view inside their inline section, persisted under settings.fonts, settings.colors, settings.buttons. The Button section also has a patterns shape-gallery sub-view that returns to the edit form it was opened from.
• Dynamic breakpoint config (BreakpointSettings.tsx) — manage up to MAX_CUSTOM_BREAKPOINTS (10) custom breakpoints in addition to the four defaults. Each row controls minWidth, containedWidth, label and icon; max-width and canvas-width are auto-calculated by recalculateBreakpointRanges. Adding a new breakpoint can optionally copy every element style from an existing source breakpoint.
• Custom attribute registry — theme-wide list of typed HTML attribute definitions (text, number, value-unit, dropdown, radio, checkbox, range, seeker) that elements can opt into via the Element Inspector. Reserved structural keys (id, class, style, src, href, etc.) are blocked by the picker form.
• Global Code editor — Monaco editor with four tabs (Header HTML, Body HTML, CSS, JavaScript). Header HTML and CSS are injected into <head>; Body HTML and JavaScript are injected before </body>.
• Global SEO defaults — defaultTitle, prefixTitle, suffixTitle, defaultDescription, defaultKeywords, defaultMetaImage. Page-level Block Settings override these per page.
• Snap settings for smart guides — managed on useCommmerceEditorSetupStore.snapSettings: enabled, threshold (5px default), showDistances, snapToElements, snapToContainer. The bottom toolbar has a one-click toggle (toggleSnap).
• Default device mode — the canvas always boots at deviceMode: 'xl' in useCommmerceEditorSetupStore; the topbar's device switcher calls toggleDeviceMode(id) to switch between any default or custom breakpoint id.
• Settings re-seed — sub-components remount on draftResetVersion change (incremented after Save / Discard), re-seeding from committed storeSettings. Otherwise their useEffect seed would refire on every keystroke and steal focus.

EditorSettings reference

Top-level keys of the EditorSettings object in types/settings.types.ts. Each key is owned by one sub-section UI; the onSettingsChange from each component writes into setDraftField(key, value) on the store. The rest of this page expands each key into a dedicated section with every leaf field documented.

Branding

Owned by BrandingSettings.tsx. Controls the merchant's primary logo and favicon (raw URL strings) plus a structured brandLogo block that the header web component renders directly — either as an <img> (logoType 'image') or as styled text (logoType 'text'). Merchants edit this once when launching a new theme and then return to it whenever they rebrand, add a wordmark, or swap their favicon for a holiday variant.

BrandingSettings (top level)

BrandLogoSettings (brandLogo)

branding: {
  primaryLogo: '',
  faviconIcon: 'https://cdn.example.com/favicon.svg',
  brandLogo: {
    logoType: 'text',
    logoText: 'ATELIER',
    logoTextFontFamily: 'Playfair Display, serif',
    logoTextFontWeight: '700',
    logoTextFontSize: 28,
    logoTextFontSizeUnit: 'px',
    logoTextLetterSpacing: 2,
    logoTextLetterSpacingUnit: 'px',
    logoTextColor: '#111111',
    logoTextTransform: 'uppercase'
  }
}

Theme Colour

Owned by ThemeColourSettings.tsx. These are the colour tokens consumed by the production mmm-* web components — not individual element styles but the system-wide tokens that every PDP, cart, checkout and header reads. Merchants set these once when locking in their brand palette; the renderer wires them to CSS custom properties so a single change repaints buttons, links, inputs and checkboxes everywhere.

text

button

addToCartButton

seeOrSelectVariantButton

border

inputBox

hyperlink

checkbox

radioButton

Typography

Owned by TypographySettings.tsx. Eleven role-keyed styles that the web components pick up by role — e.g. the PDP heading reads heading; the cart's selling price reads sellingPrice; the link rendered inside a description reads link. Merchants tune these to set the editorial voice of the store. Every style shares the shape below; per-style defaults vary so each role starts in a sensible place.

TypographyStyle shape (applies to every role key)

Role-key defaults

All eleven role keys exist on TypographySettings. Their seeded defaults from DEFAULT_TYPOGRAPHY_SETTINGS are listed below (anything omitted from the source remains undefined). Use the role list to decide which control to tune for a given UX outcome.

Product

Owned by ProductSettings.tsx. Theme-wide defaults for how a product is presented — the framing colour around media, the dimensions of product images, and the typography used for short and long descriptions. Adjust these once when designing the look of every product card / PDP, then let element-level overrides handle one-off cases.

Product display

shortDescription (ProductDescriptionStyle)

description (ProductDescriptionStyle)

Fonts

Owned by FontsSettings.tsx. A merchant-managed list of named font slots. Each slot is a fully configured typography preset (family, weight, size, colour, line-height, transform, custom CSS). Once registered, the slot can be referenced anywhere a typography control accepts a slot id — so every element using "Primary Heading" picks up future edits automatically. The default list is empty (DEFAULT_FONTS_SETTINGS.fonts = []); merchants populate it as they design the theme.

FontEntry shape (one per font slot)

Colors

Owned by ColorsSettings.tsx. Mirrors the Fonts pattern: a merchant-managed list of named colour slots. Define the palette once (Primary, Secondary, Universal, etc.) and reuse the colour by id from anywhere a colour input accepts a slot. Rebrands then ripple through the entire theme by editing one slot. Defaults to an empty list (DEFAULT_COLORS_SETTINGS.colors = []); merchants populate it as they curate the palette.

ColorEntry shape

Buttons

Owned by ButtonsSettings.tsx. The button registry mirrors the Fonts / Colors pattern but is far richer: each entry encodes a complete visual button design (shape, colour, border, radius, padding, font, interaction). Mark one entry isPrimary to use it as the theme-wide primary button; consumers pick the first isPrimary entry when resolving "primary". Defaults to an empty list (DEFAULT_BUTTONS_SETTINGS.buttons = []).

Button shapes

The shape field drives the rendered silhouette. The first four honour the corner-radius controls; tab uses asymmetric corners; chevron and hexagon use clip-paths and ignore border rendering entirely.

Button interaction

The interaction field controls the hover / press transition. Stored as a free-form string so future patterns can be added without a type migration; unknown values fall back to none.

ButtonEntry shape (one per button slot)

Custom Attributes

Theme-wide registry of typed HTML attributes that elements can opt into. The picker form (rendered from the Element Inspector) consumes this registry to offer a curated set of attributes the user can apply to a node; each definition declares the attribute key, the input flavour, the validation ranges, and an optional default value. Defaults to an empty list (DEFAULT_CUSTOM_ATTRIBUTES_SETTINGS.list = []).

Custom attribute types

CustomAttributeDefinition shape

Global SEO

Owned by SEOSettings.tsx. Theme-wide SEO defaults applied to every page that doesn't override them at the page level. Page-level Block Settings always win — these defaults fill in the gaps so a freshly created page still has a sensible title / description / image without manual setup.

Global Code

Owned by GlobalCodeSettings.tsx. Free-form code snippets the SSR pipeline injects on every rendered page. Use these for third-party scripts, theme-wide CSS overrides, and additional <head> tags — never hand-edit the rendered HTML in a way that bypasses the theme editor.

Breakpoints

Owned by BreakpointSettings.tsx. The ordered list of responsive breakpoints used by the canvas device switcher and by every responsive style write. Four immutable defaults ship with the theme (xl, desktop, tablet, mobile); merchants can add up to MAX_CUSTOM_BREAKPOINTS (10) more. Custom breakpoint ids are custom_{counter} — the counter is monotonic so deleting and re-adding "the same" breakpoint produces a new id.

BreakpointSettings (top level)

BreakpointConfig shape (one per breakpoint)

Default breakpoint values

Constants from breakpoint.types.ts: MAX_CUSTOM_BREAKPOINTS = 10, MIN_BREAKPOINTS = 1, MIN_ALLOWED_WIDTH = 300, validateBreakpointConfig.canvasWidth bounds 320-3840.

App-wide editor UI state

Fields on useCommmerceEditorSetupStore that are truly app-wide — not per-block, not per-element, not part of the theme settings payload. The store is persisted to sessionStorage minus isInitializing, initializingMessage, placementMode and quickEditElementId (these are transient by design — see the partialize in useCommmerceEditorSetupStore.ts).

Validation rules

Validation is implemented in types/settings.types.ts and types/breakpoint.types.ts. Most checks produce warnings (the save still proceeds — the user is informed inline) rather than hard errors.

validateSEOSettings

• defaultTitle.length > 60 — warning: "Default Title should be under 60 characters for optimal SEO".
• defaultDescription.length > 160 — warning: "Default Description should be under 160 characters for optimal SEO".
• defaultKeywords split by , > 20 entries — warning: "Consider limiting keywords to 20 or fewer".
• defaultMetaImage non-empty and not a valid URL — warning: "Default Meta Image should be a valid URL".

validateBrandingSettings

• primaryLogo set but not a valid URL — warning: "Primary Logo should be a valid URL".
• faviconIcon set but not a valid URL — warning: "Favicon should be a valid URL".
• primaryLogo empty — recommendation: "Primary Logo is recommended for better branding".
• faviconIcon empty — recommendation: "Favicon is recommended for browser tab identification".

validateGlobalCodeSettings

Currently a no-op — Monaco handles syntax errors and there are no length / pattern checks. The function exists as a hook for future hardening.

Breakpoint validation

• validateBreakpointOverlap — flags any pair of breakpoints with overlapping [minWidth, maxWidth] ranges.
• validateBreakpointConfig — requires minWidth < maxWidth when both are set, canvasWidth between 320 and 3840, and a non-empty label.
• validateNewBreakpointMinWidth — requires minWidth ≥ MIN_ALLOWED_WIDTH (300) and forbids duplicate minWidths.

Reserved custom attribute keys

RESERVED_ATTRIBUTE_KEYS blocks these keyName values in the custom attribute picker form to prevent shadowing structural attributes: id, class, style, src, href, alt, title, name, type, value, data-block-id, data-block-name, data-block-type, data-block-version.

Workflows

Tips & gotchas

• The Save button is intentionally hidden until a draft exists. If you change a value and the button doesn't appear, the change didn't reach setDraftField — usually because the sub-component's useEffect seed re-ran (check that the section is keyed by draftResetVersion like the others).
• The modal (Settings.tsx) and the in-sidebar panel (GlobalSettingsPanel.tsx) share the same store and save hook — opening the modal while a sidebar draft is pending will read from the same draft, not from committed settings.
• Breakpoint deletion is destructive — styles for the deleted breakpoint are lost; BreakpointSettings shows a Popconfirm before calling deleteBreakpoint. There is no undo for this through the editor history slice.
• The Mobile breakpoint (minWidth: null) cannot be edited — it is always the "lowest" breakpoint and its row hides the InputNumber. Don't rely on a numeric minWidth for mobile.
• Custom breakpoint ids are assigned as custom_{counter} in BreakpointSettings.handleAddBreakpoint; the counter is monotonic and never recycles, so deleting and re-adding "the same" custom breakpoint produces a new id.
• The setup store is persisted to sessionStorage, not localStorage — closing the browser drops zoom, snap settings, and sidebar collapse state. The persisted theme settings are server-side and survive forever.
• If useSaveSettings returns "Cannot determine save context — URL is missing version params.", the panel is being rendered outside of a Dev Portal or Store Editor route (e.g. inside a preview iframe with no version params). Wrap consumers in a route that provides them.
• Layout settings (layoutSettings on the setup store) are distinct from the containedWidth field on each breakpoint in settings.breakpoints — the breakpoint containedWidth drives the saved theme's responsive output; layoutSettings drives the editor's canvas frame only.
• Fonts / Colors / Buttons all default to empty lists. Element-level controls fall back to inline values when no slot id is referenced, so an empty registry is not a runtime error — it just means no theme-wide reuse is wired up yet.
• Custom attribute defaultValue is always a string. For 'checkbox' persist "true" / "false"; for 'range' persist the pair as "low,high"; consumers must parse on read.
• Typography optional fields (letterSpacing, lineHeight, textTransform, textDecoration, textDecorationHover) are unset for some roles by design — the renderer falls back to user-agent defaults when absent. Only set what you need to override.
• Breakpoint canvasWidth is auto-calculated from maxWidth (or minWidth + 200 for the topmost breakpoint) and clamped to [320, 3840] by validateBreakpointConfig — don't try to edit it directly.