Design Editors

Design editors define the styling options merchants can adjust in the Instant Site Editor. Each editor maps to a specific design widget — color pickers, font selectors, background controls, and more.

Overview

All design editors are created using factory functions from @lightspeed/crane-api:

import { design } from '@lightspeed/crane-api';

Type	Factory	Purpose
TEXT	design.text()	Text styling (font, size, color, bold, italic, visibility)
BUTTON	design.button()	Button appearance, size, shape, color, font
IMAGE	design.image()	Image overlay (color, gradient, or none)
TOGGLE	design.toggle()	Boolean design toggle
SELECTBOX	design.selectbox()	Design dropdown selection
BACKGROUND	design.background()	Background color or gradient
COLOR_PICKER	design.colorPicker()	Standalone color selection
LOGO	design.logo()	Logo styling (font, spacing, frame, capitalization)
DIVIDER	design.divider()	Visual separator in the editor
INFO	design.info()	Informational text in the editor
ACCORDION	design.accordion()	Collapsible group of design editors

Color Values

Several design editors accept color values. Colors can be:

• Hex colors: '#RGB', '#RRGGBB', or '#RRGGBBAA' format

• Global colors: Reference the store's global color palette:

  • 'global.color.title'

  • 'global.color.body'

  • 'global.color.button'

  • 'global.color.link'

  • 'global.color.background'

Color Configuration Options

Several editors support these optional properties for controlling color selection:

Property	Type	Description
colors	string[]	Restricts the color picker to a specific set of colors
enableAlphaColor	boolean	Enables transparency (alpha channel) in the color picker
enableAutoColor	boolean	Enables the "auto" color option (uses global color)

Global Text Sizes

Text size defaults can be a specific integer (pixels) or a reference to a global text size:

• 'global.textSize.title'

• 'global.textSize.subtitle'

• 'global.textSize.body'

TEXT

Text styling for headings, paragraphs, and other text content.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
colors	string[]	No	Restrict available colors
sizes	integer[]	No	Restrict available font sizes (each >= 1)
enableAlphaColor	boolean	No	Enable transparency in color picker
enableAutoColor	boolean	No	Enable auto color option
hideVisibleToggle	boolean	No	Hide the visibility toggle in the editor
hideSize	boolean	No	Hide the size selector in the editor
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
font	string	No	Font family
size	integer | string	No	Font size in pixels, or a global text size reference
bold	boolean	No	Bold text
italic	boolean	No	Italic text
color	string	No	Hex color or global color reference
visible	boolean	No	Whether the element is visible

Factory

design.text({
  label: '$label.design.title_style',
  defaults: {
    font: 'global.fontFamily.heading',
    size: 'global.textSize.title',
    bold: true,
    italic: false,
    color: 'global.color.title',
    visible: true,
  },
})

BUTTON

Button styling including appearance, size, shape, color, and font.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
colors	string[]	No	Restrict available colors
enableAutoColor	boolean	No	Enable auto color option
enableAlphaColor	boolean	No	Enable transparency in color picker
hideVisibleToggle	boolean	No	Hide the visibility toggle
hideSize	boolean	No	Hide the size selector
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
appearance	string	No	"SOLID", "OUTLINE", or "TEXT"
size	string	No	"SMALL", "MEDIUM", or "LARGE"
shape	string	No	"ROUND_CORNER", "RECTANGLE", or "PILL"
font	string	No	Font family
color	string	No	Hex color or global color reference
visible	boolean	No	Whether the button is visible

Factory

design.button({
  label: '$label.design.button_style',
  defaults: {
    appearance: 'SOLID',
    size: 'MEDIUM',
    shape: 'ROUND_CORNER',
    color: 'global.color.button',
    visible: true,
  },
})

IMAGE

Image design controls for overlay effects.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
static	boolean	No	Must match the content IMAGE editor's static value
colors	string[]	No	Restrict available colors (hex only)
enableAlphaColor	boolean	No	Enable transparency in color picker
hideVisibleToggle	boolean	No	Hide the visibility toggle
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
overlay	string	No	"COLOR", "GRADIENT", or "NONE"
color	string | string[]	No	Overlay color(s) — see rules below
visible	boolean	No	Whether the image is visible

Overlay Color Rules

Overlay	Color Requirement
"COLOR"	color is required and must be a single color value
"GRADIENT"	color is required and must be an array of exactly 2 colors
"NONE" or not set	color must not be defined

Factory

design.image({
  label: '$label.design.hero_image',
  defaults: { overlay: 'COLOR', color: '#00000066' },
})

Validation

• The static flag must match between content and design IMAGE editors for the same field. Mismatch produces: "Both content and design editor need to have same value for attribute static."

• Invalid color/overlay combinations produce specific errors. For example, providing a single color when overlay is GRADIENT produces: "color must be an array when overlay is GRADIENT."

TOGGLE

Boolean design toggle for enabling or disabling design features.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
enabled	boolean	No	Default toggle state

Factory

design.toggle({
  label: '$label.design.enable_animation',
  defaults: { enabled: true },
})

SELECTBOX

Dropdown selection for design options.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
description	string	No	Translation key for description text
options	array	No	Array of selectable options
defaults	object	No	Default values

Each option:

Property	Type	Required	Description
value	string	No	Option value
label	string	No	Translation key for option label

Defaults

Property	Type	Required	Description
value	string	No	Default selected value

Factory

design.selectbox({
  label: '$label.design.layout_style',
  description: '$label.design.layout_style_desc',
  options: [
    { value: 'compact', label: '$label.options.compact' },
    { value: 'spacious', label: '$label.options.spacious' },
  ],
  defaults: { value: 'compact' },
})

BACKGROUND

Background color or gradient controls.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
colors	string[]	No	Restrict available colors
enableAlphaColor	boolean	No	Enable transparency in color picker
enableAutoColor	boolean	No	Enable auto color option
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
style	string	No	"COLOR" or "GRADIENT"
color	string | string[]	No	Background color(s) — see rules below

Background Color Rules

Style	Color Requirement
"COLOR"	color is required and must be a single color value
"GRADIENT"	color is required and must be an array of exactly 2 colors

Factory

// Solid color
design.background({
  label: '$label.design.section_background',
  defaults: { style: 'COLOR', color: '#FFFFFF' },
})

// Gradient
design.background({
  label: '$label.design.section_background',
  defaults: { style: 'GRADIENT', color: ['#FF0000', '#0000FF'] },
})

Validation

Invalid color/style combinations produce errors:

• "color is required when style is GRADIENT"

• "color must be an array when style is GRADIENT"

• "color array must have exactly 2 items when style is GRADIENT"

• "color must be a single value when style is COLOR"

COLOR_PICKER

Standalone color picker for custom color settings that don't fit into other editor types.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
colors	string[]	No	Restrict available colors
enableAlphaColor	boolean	No	Enable transparency in color picker
enableAutoColor	boolean	No	Enable auto color option
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
color	string	No	Hex color or global color reference

Factory

design.colorPicker({
  label: '$label.design.accent_color',
  defaults: { color: '#FF5733' },
})

LOGO

Logo styling controls, including text formatting, spacing, frame, and capitalization. This editor is specific to logo elements.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the editor label
colors	string[]	No	Restrict available colors
sizes	integer[]	No	Restrict available font sizes (each >= 1)
defaults	object	No	Default values

Defaults

Property	Type	Required	Description
font	string	No	Font family
size	integer | string	No	Font size in pixels, or a global text size reference
bold	boolean	No	Bold text
italic	boolean	No	Italic text
color	string	No	Hex color or global color reference
visible	boolean	No	Whether the logo is visible
spacing	integer	No	Letter spacing (1–9)
frame	object	No	Logo frame configuration
capitalization	string	No	"none", "all", or "small"

The frame object:

Property	Type	Required	Description
visible	boolean	Yes	Whether the frame is visible
width	integer	No	Frame width (1–49)
color	string	No	Hex color or global color reference

Factory

design.logo({
  label: '$label.design.logo_style',
  defaults: {
    font: 'global.fontFamily.heading',
    size: 24,
    bold: true,
    color: 'global.color.title',
    visible: true,
    spacing: 2,
    capitalization: 'none',
    frame: { visible: false },
  },
})

Mandatory for Headers

The LOGO design editor is mandatory for sections with type HEADER. It must be defined with the key logo. See Sections

DIVIDER

Visual separator in the design editor UI. Does not affect storefront rendering.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the divider label
defaults	object	No	Default values (empty, type only)

Factory

design.divider({
  label: '$label.design.advanced_options',
})

INFO

Informational text displayed in the design editor UI. Like DIVIDER, this does not affect storefront rendering — it provides guidance or contextual help to merchants within the design panel.

Properties

Property	Type	Required	Description
label	string	Yes	Translation key for the info title
description	string	Yes	Translation key for the info description
button	object	No	Optional link button in the editor

The button object:

Property	Type	Required	Description
label	string	Yes	Translation key for button text
link	string	Yes	URL (must be a valid URL)

Defaults

Property	Type	Required	Description
description	string	No	Default info text (translation key)
button	object	No	Default button configuration (optional)
button.label	string	No	Default button text (translation key)
button.link	string	No	Default button URL (must be a valid URL)

Factory

design.info({
  label: '$label.design.help_info',
  description: '$label.design.help_description',
  button: {
    label: '$label.design.learn_more',
    link: 'https://docs.example.com',
  },
})

ACCORDION

Groups multiple design editors into collapsible accordion sections in the Instant Site Editor. Each accordion item has a label and contains a set of nested design editors. This is purely an organizational tool for the editor UI — it does not affect storefront rendering directly. The nested editors within the accordion are what control the actual styling. This is useful for organizing complex design panels with many settings into logical, expandable categories.

Properties

Property	Type	Required	Description
items	object	Yes	Map of accordion items keyed by unique item identifier
sortable	boolean	No	If true, merchants can reorder items within this accordion group; when enabled, each item must define its own positionFieldName

Each accordion item:

Property	Type	Required	Description
label	string	Yes	Translation key for the accordion item header
positionFieldName	string	Conditional	Key of the editor within this item that stores the sort position for that item (required when the accordion's sortable property is true)
editors	object	Yes	Map of design editors within this accordion item

Within an accordion item, the editors object can contain standard design editors such as TEXT, BUTTON, IMAGE, TOGGLE, SELECTBOX, BACKGROUND, COLOR_PICKER, LOGO, and DIVIDER (for example, design.selectbox(), design.toggle(), design.divider(), design.text(), etc.), but it cannot contain another ACCORDION or an INFO editor.

Nested Editor Access Use the useAccordionElementDesign composable to access nested editor values from within your Vue component. See UI Composables for details.

Factory

design.accordion({
  sortable: true,
  items: {
    page_settings: {
      label: '$label.accordion.page_settings',
      positionFieldName: 'sortPosition',
      editors: {
        sortPosition: design.selectbox({
          label: '$label.sort_position.label',
          options: [
            { value: '1', label: '$label.sort_position.first' },
            { value: '2', label: '$label.sort_position.second' },
          ],
          defaults: { value: '1' },
        }),
        layout: design.selectbox({
          label: '$label.layout_style.label',
          options: [
            { value: 'GRID', label: '$label.layout_style.grid' },
            { value: 'LIST', label: '$label.layout_style.list' },
          ],
          defaults: { value: 'GRID' },
        }),
        showFilters: design.toggle({
          label: '$label.show_filters.label',
          defaults: { enabled: true },
        }),
      },
    },
    card_settings: {
      label: '$label.accordion.card_settings',
      positionFieldName: 'sortPosition',
      editors: {
        sortPosition: design.selectbox({
          label: '$label.sort_position.label',
          options: [
            { value: '1', label: '$label.sort_position.first' },
            { value: '2', label: '$label.sort_position.second' },
          ],
          defaults: { value: '1' },
        }),
        cardSize: design.selectbox({
          label: '$label.card_size.label',
          options: [
            { value: 'SMALL', label: '$label.card_size.small' },
            { value: 'LARGE', label: '$label.card_size.large' },
          ],
          defaults: { value: 'LARGE' },
        }),
        showBorder: design.toggle({
          label: '$label.show_border.label',
          defaults: { enabled: false },
        }),
      },
    },
  },
})

Showcase Default Factories

When defining showcase configurations, the design.default.*() factories create standalone default values:

import { design } from '@lightspeed/crane-api';

design.default.text({ font: 'Arial', size: 18, bold: false, color: '#333333', visible: true });
design.default.button({ appearance: 'SOLID', size: 'MEDIUM', shape: 'PILL', color: '#000000', visible: true });
design.default.background({ style: 'COLOR', color: '#F5F5F5' });
design.default.image({ overlay: 'NONE' });
design.default.colorPicker({ color: '#FF0000' });
design.default.logo({ font: 'Arial', size: 20, color: '#000000', visible: true });
design.default.toggle({ enabled: true });
design.default.selectbox({ value: 'default' });
design.default.info({ description: '$label.showcase.info_text' });
design.default.accordion({
  items: {
    page_settings: {
      editors: {
        layout: design.default.selectbox({ value: 'GRID' }),
      },
    },
    card_settings: {
      editors: {
        showBorder: design.default.toggle({ enabled: false }),
      },
    },
  },
});

See Showcases for usage in showcase files.

Complete Example

// settings/design.ts
import { design } from '@lightspeed/crane-api';

export default {
  title_style: design.text({
    label: '$label.design.title_style',
    defaults: {
      font: 'global.fontFamily.heading',
      size: 'global.textSize.title',
      bold: true,
      italic: false,
      color: 'global.color.title',
      visible: true,
    },
  }),
  description_style: design.text({
    label: '$label.design.description_style',
    defaults: {
      font: 'global.fontFamily.body',
      size: 'global.textSize.body',
      bold: false,
      color: 'global.color.body',
      visible: true,
    },
  }),
  button_style: design.button({
    label: '$label.design.button_style',
    defaults: {
      appearance: 'SOLID',
      size: 'MEDIUM',
      shape: 'ROUND_CORNER',
      color: 'global.color.button',
      visible: true,
    },
  }),
  section_background: design.background({
    label: '$label.design.background',
    defaults: { style: 'COLOR', color: '#FFFFFF' },
  }),
  hero_image: design.image({
    label: '$label.design.hero_image',
    defaults: { overlay: 'NONE' },
  }),
  help_info: design.info({
    label: '$label.design.help_info',
    description: '$label.design.help_description',
    button: {
      label: '$label.design.learn_more',
      link: 'https://docs.example.com',
    },
  }),
  styling: design.accordion({
    items: {
      page_settings: {
        label: '$label.accordion.page_settings',
        editors: {
          layout: design.selectbox({
            label: '$label.layout_style.label',
            options: [
              { value: 'GRID', label: '$label.layout_style.grid' },
              { value: 'LIST', label: '$label.layout_style.list' },
            ],
            defaults: { value: 'GRID' },
          }),
          showFilters: design.toggle({
            label: '$label.show_filters.label',
            defaults: { enabled: true },
          }),
        },
      },
    },
  }),
};