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:

typescript

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

typescript

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

typescript

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

typescript

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

typescript

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

typescript

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

typescript

// 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
`description`	`string`	No	Translation key for optional helper copy the site editor shows with this color picker (placement and styling are defined by the editor, not the theme)
`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

typescript

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

TIP

Use design.colorPicker() from @lightspeed/crane-api so section design config stays aligned with validation and types.

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

typescript

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

typescript

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

typescript

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.

Factory

typescript

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 },
        }),
      },
    },
  },
})

💡 Nested Editor Access

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

Showcase Default Factories

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

typescript

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

typescript

// 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 },
          }),
        },
      },
    },
  }),
};

Layouts

Settings

Design Editors ​

Overview ​

Color Values ​

Color Configuration Options ​

Global Text Sizes ​

TEXT ​

Properties ​

Defaults ​

Factory ​

BUTTON ​

Properties ​

Defaults ​

Factory ​

IMAGE ​

Properties ​

Defaults ​

Overlay Color Rules ​

Factory ​

TOGGLE ​

Properties ​

Defaults ​

Factory ​

SELECTBOX ​

Properties ​

Defaults ​

Factory ​

BACKGROUND ​

Properties ​

Defaults ​

Background Color Rules ​

Factory ​

COLOR_PICKER ​

Properties ​

Defaults ​

Factory ​

LOGO ​

Properties ​

Defaults ​

Factory ​

DIVIDER ​

Properties ​

Factory ​

INFO ​

Properties ​

Defaults ​

Factory ​

ACCORDION ​

Properties ​

Factory ​

Showcase Default Factories ​

Complete Example ​

Design Editors

Overview

Color Values

Color Configuration Options

Global Text Sizes

TEXT

Properties

Defaults

Factory

BUTTON

Properties

Defaults

Factory

IMAGE

Properties

Defaults

Overlay Color Rules

Factory

TOGGLE

Properties

Defaults

Factory

SELECTBOX

Properties

Defaults

Factory

BACKGROUND

Properties

Defaults

Background Color Rules

Factory

COLOR_PICKER

Properties

Defaults

Factory

LOGO

Properties

Defaults

Factory

DIVIDER

Properties

Factory

INFO

Properties

Defaults

Factory

ACCORDION

Properties

Factory

Showcase Default Factories

Complete Example