Green Bag Developer logo Green Bag Developer
Sections, Blocks, and Schema Design Beginner 8 min read

Theme Editor UX: Naming and Settings Hygiene

Learn how to create merchant-friendly sections with clear naming, organized settings, helpful labels, and intuitive structure.

Your sections might be technically perfect, but if merchants can’t figure out how to use them, they’re not useful. Good theme editor UX means clear naming, logical organization, and helpful guidance. Let’s learn how to make your sections a joy to customize.

🛠 Try the Schema Builder: Our Schema Builder helps you organize settings with headers, add helpful info text, and preview how your schema will appear—all before writing any code.

Naming Sections and Blocks

Section Names

The name property is what merchants see in the editor:

{
  "name": "Featured Collection"
}

Good Names:

  • Featured Collection
  • Image with Text
  • Testimonials
  • Newsletter Signup
  • Product Recommendations

Bad Names:

  • Section 1
  • My Section
  • fcol-v2
  • Image Banner (Full Width with Parallax and Overlay)

Keep names:

  • Descriptive: What does it do?
  • Concise: 2-4 words maximum
  • User-focused: Use terms merchants understand

Block Names

{
  "blocks": [
    {
      "type": "slide",
      "name": "Slide"
    },
    {
      "type": "testimonial",
      "name": "Testimonial"
    }
  ]
}

Name blocks after what they represent, not their technical type.

Organizing Settings

{
  "settings": [
    {
      "type": "header",
      "content": "Content"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    },
    {
      "type": "richtext",
      "id": "text",
      "label": "Text"
    },
    {
      "type": "header",
      "content": "Button"
    },
    {
      "type": "text",
      "id": "button_text",
      "label": "Button text"
    },
    {
      "type": "url",
      "id": "button_link",
      "label": "Button link"
    },
    {
      "type": "header",
      "content": "Layout"
    },
    {
      "type": "select",
      "id": "alignment",
      "label": "Text alignment",
      "options": [...]
    },
    {
      "type": "header",
      "content": "Colors"
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Background"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text"
    }
  ]
}

Common header groups:

  • Content: Text, images, products
  • Button/CTA: Button text, links
  • Layout: Alignment, columns, spacing
  • Colors: Background, text, accent colors
  • Spacing: Padding, margins

Logical Setting Order

Put settings in the order merchants will think about them:

  1. Content first: What will be displayed
  2. Layout second: How it’s arranged
  3. Style third: How it looks
  4. Advanced last: Less common options
{
  "settings": [
    { "type": "header", "content": "Content" },
    { "type": "text", "id": "heading" },
    { "type": "richtext", "id": "text" },
    { "type": "collection", "id": "collection" },


    { "type": "header", "content": "Layout" },
    { "type": "range", "id": "products_to_show" },
    { "type": "select", "id": "columns" },


    { "type": "header", "content": "Style" },
    { "type": "color", "id": "background_color" },
    { "type": "color", "id": "heading_color" },


    { "type": "header", "content": "Spacing" },
    { "type": "range", "id": "padding_top" },
    { "type": "range", "id": "padding_bottom" }
  ]
}

Writing Clear Labels

Be Specific

// Good
{ "label": "Heading" }
{ "label": "Button text" }
{ "label": "Products to show" }


// Bad
{ "label": "Text" }
{ "label": "Content" }
{ "label": "Number" }

Use Consistent Terminology

Pick terms and stick with them:

// Consistent
{ "label": "Heading" }
{ "label": "Subheading" }
{ "label": "Button text" }
{ "label": "Button link" }


// Inconsistent
{ "label": "Title" }
{ "label": "Subtitle" }
{ "label": "CTA Label" }
{ "label": "Link URL" }

Avoid Technical Jargon

// Good
{ "label": "Background color" }
{ "label": "Show vendor name" }


// Bad
{ "label": "bg_color hex value" }
{ "label": "Enable vendor boolean" }

Using Info Text

The info property adds help text below an input:

{
  "type": "range",
  "id": "overlay_opacity",
  "label": "Overlay darkness",
  "info": "Higher values make text more readable",
  "min": 0,
  "max": 100,
  "default": 40,
  "unit": "%"
}

When to Use Info

  • Explain non-obvious settings: What does this actually do?
  • Provide recommendations: “Recommended: 4-8 products”
  • Warn about consequences: “Enabling this may slow down page load”
  • Give formatting hints: “Use format: HH:MM AM/PM”
{
  "type": "text",
  "id": "video_url",
  "label": "YouTube video URL",
  "info": "Paste the full URL, e.g., https://www.youtube.com/watch?v=..."
}
{
  "type": "range",
  "id": "products_to_show",
  "label": "Products to show",
  "info": "Showing more products may slow page load on mobile",
  "min": 2,
  "max": 24,
  "default": 8
}

Don’t Overuse Info

Not every setting needs explanation:

// Unnecessary info
{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "info": "Enter the heading text that will be displayed"
}

The label “Heading” is self-explanatory.

Using Paragraphs for Context

Paragraphs provide longer explanatory text:

{
  "settings": [
    {
      "type": "paragraph",
      "content": "This section displays products from a selected collection. Choose a collection and customize how products are displayed."
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    }
  ]
}

Use paragraphs sparingly, typically at the start of a settings group.

Placeholder Text

Placeholders appear inside empty inputs:

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "placeholder": "Enter a catchy headline"
}

Good Placeholder Uses

{
  "type": "text",
  "id": "email",
  "label": "Email address",
  "placeholder": "[email protected]"
}


{
  "type": "text",
  "id": "phone",
  "label": "Phone number",
  "placeholder": "+1 (555) 123-4567"
}


{
  "type": "url",
  "id": "video_url",
  "label": "Video URL",
  "placeholder": "https://www.youtube.com/watch?v=..."
}

Don’t Use Placeholders as Labels

// Bad - placeholder disappears when typing
{
  "type": "text",
  "id": "heading",
  "label": "",
  "placeholder": "Heading"
}


// Good - label is always visible
{
  "type": "text",
  "id": "heading",
  "label": "Heading"
}

Select Options

Write clear option labels:

{
  "type": "select",
  "id": "image_ratio",
  "label": "Image ratio",
  "options": [
    { "value": "portrait", "label": "Portrait (2:3)" },
    { "value": "square", "label": "Square (1:1)" },
    { "value": "landscape", "label": "Landscape (3:2)" }
  ]
}

Include dimensions or descriptions when helpful:

{
  "type": "select",
  "id": "columns",
  "label": "Desktop columns",
  "options": [
    { "value": "2", "label": "2 columns" },
    { "value": "3", "label": "3 columns" },
    { "value": "4", "label": "4 columns" }
  ]
}

Complete Example: Well-Organized Section

{% schema %}
{
  "name": "Featured Collection",
  "tag": "section",
  "settings": [
    {
      "type": "paragraph",
      "content": "Showcase products from a collection with customizable layout and styling."
    },
    {
      "type": "header",
      "content": "Content"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Featured Products"
    },
    {
      "type": "richtext",
      "id": "description",
      "label": "Description"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    },
    {
      "type": "header",
      "content": "Layout"
    },
    {
      "type": "range",
      "id": "products_to_show",
      "label": "Products to show",
      "info": "On mobile, products display in 2 columns",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4
    },
    {
      "type": "select",
      "id": "columns_desktop",
      "label": "Desktop columns",
      "options": [
        { "value": "2", "label": "2 columns" },
        { "value": "3", "label": "3 columns" },
        { "value": "4", "label": "4 columns" }
      ],
      "default": "4"
    },
    {
      "type": "header",
      "content": "Product Card"
    },
    {
      "type": "checkbox",
      "id": "show_vendor",
      "label": "Show vendor",
      "default": false
    },
    {
      "type": "checkbox",
      "id": "show_rating",
      "label": "Show rating",
      "default": true,
      "info": "Requires a product reviews app"
    },
    {
      "type": "select",
      "id": "image_ratio",
      "label": "Image ratio",
      "options": [
        { "value": "portrait", "label": "Portrait (2:3)" },
        { "value": "square", "label": "Square (1:1)" },
        { "value": "landscape", "label": "Landscape (4:3)" }
      ],
      "default": "portrait"
    },
    {
      "type": "header",
      "content": "Call to Action"
    },
    {
      "type": "checkbox",
      "id": "show_view_all",
      "label": "Show 'View all' button",
      "default": true
    },
    {
      "type": "text",
      "id": "view_all_label",
      "label": "Button label",
      "default": "View all"
    },
    {
      "type": "header",
      "content": "Colors"
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Background",
      "default": "#ffffff"
    },
    {
      "type": "color",
      "id": "heading_color",
      "label": "Heading",
      "default": "#000000"
    },
    {
      "type": "header",
      "content": "Spacing"
    },
    {
      "type": "range",
      "id": "padding_top",
      "label": "Top padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "default": 40,
      "unit": "px"
    },
    {
      "type": "range",
      "id": "padding_bottom",
      "label": "Bottom padding",
      "min": 0,
      "max": 100,
      "step": 4,
      "default": 40,
      "unit": "px"
    }
  ],
  "presets": [
    {
      "name": "Featured Collection"
    }
  ]
}
{% endschema %}

Testing Your UX

The “Mom Test”

Could someone unfamiliar with web development customize this section? Show your settings panel to a non-technical person and watch where they struggle.

Checklist

  • Section name is clear and descriptive
  • Settings are grouped logically with headers
  • Labels are specific and jargon-free
  • Important settings come first
  • Info text explains non-obvious options
  • Select options have clear labels
  • Defaults make the section look good immediately
  • Nothing requires technical knowledge to use

Practice Exercise

Review this schema and identify UX improvements:

{
  "name": "Banner v2",
  "settings": [
    { "type": "color", "id": "bg", "label": "bg" },
    { "type": "text", "id": "txt", "label": "text" },
    { "type": "range", "id": "p", "min": 0, "max": 100, "label": "padding" },
    { "type": "checkbox", "id": "cta", "label": "cta" },
    { "type": "image_picker", "id": "img", "label": "image" },
    { "type": "text", "id": "btn", "label": "btn txt" },
    { "type": "url", "id": "url", "label": "link" }
  ]
}

Improved version:

{
  "name": "Hero Banner",
  "settings": [
    { "type": "header", "content": "Content" },
    { "type": "image_picker", "id": "image", "label": "Background image" },
    { "type": "text", "id": "heading", "label": "Heading" },
    { "type": "header", "content": "Button" },
    { "type": "checkbox", "id": "show_button", "label": "Show button", "default": true },
    { "type": "text", "id": "button_text", "label": "Button text", "default": "Shop Now" },
    { "type": "url", "id": "button_link", "label": "Button link" },
    { "type": "header", "content": "Style" },
    { "type": "color", "id": "background_color", "label": "Background color", "default": "#000000" },
    { "type": "range", "id": "padding", "label": "Vertical padding", "min": 20, "max": 100, "step": 10, "default": 60, "unit": "px" }
  ]
}

Key Takeaways

  1. Name sections clearly with 2-4 descriptive words
  2. Group settings with headers for logical organization
  3. Order settings by importance: content → layout → style
  4. Write specific labels without technical jargon
  5. Use info text sparingly for non-obvious settings
  6. Provide good defaults so sections look great immediately
  7. Test with non-developers to find UX issues

What’s Next?

The final lesson in this module covers Reusable Patterns with Snippets, helping you build a component library that makes section development faster and more consistent.

Finished this lesson?

Mark it complete to track your progress.

Discussion

Loading comments...