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

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
`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',
  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

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

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' });

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

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 ​

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

Showcase Default Factories

Complete Example